Agent Memory

エージェントメモリー用ファイルシステム MCP

agent-memory-daemon を、あらゆる MCP 互換クライアント（Kiro（CLI と IDE）、Claude Desktop、Cursor など）に公開する MCP サーバーです。

デーモンが処理（統合＋抽出）を行い、このサーバーはエージェントが Model Context Protocol を通じてメモリーの読み取り、追記、検索を行うための軽量なファイルシステムブリッジです。

連携の仕組み

 ┌──────────────┐     MCP/stdio     ┌────────────────────┐     filesystem      ┌────────────────────────┐
 │ Kiro / Claude│ ◄───────────────► │ mcp-server-memory  │ ◄─────────────────► │ agent-memory-daemon    │
 │   / Cursor   │                   │  (this package)    │   ~/.agent-memory/   │  (runs in background)  │
 └──────────────┘                   └────────────────────┘                     └────────────────────────┘

• MCP サーバーは ~/.agent-memory/ 配下のファイルを読み書きします
• デーモンは同じディレクトリを監視し、統合＋抽出の処理を実行します
• 両者が直接通信することはありません。ファイルシステムが連携の取り決めです

公開されるツール

memory_read

エージェントのメモリーインデックス（MEMORY.md）を読み取り、必要に応じて特定のトピックファイルも読み込みます。引数なしで呼び出すと、軽量なインデックスのみを読み込みます（低コストです）。特定のトピックファイルの内容全体が必要な場合にのみ、topics を渡してください。

パラメーター	型	必須	説明
topics	string[]	いいえ	内容全体を読み込むトピックファイル名（例：["preferences", "projects"]）。省略すると、インデックスのみを返します。

memory_append_session

セッションの要約をセッションディレクトリに追記します。デーモンは後で、ここから長期的に保持すべきメモリーを抽出します。意義のあるやり取りの終わりに呼び出してください。要約は逐一の経過ではなく、長期的に有用な知見や決定事項に絞ってください（目安は300～800トークンです）。要約が長いほど、統合時のコストが増えます。

パラメーター	型	必須	説明
content	string	はい	Markdown 形式のセッション要約。抽出しやすくするため、構造化された見出しと箇条書きを使い、冗長な文章は避けてください。
source	string	いいえ	発生元を示すタグ（例："kiro"、"claude-desktop"）

memory_search

メモリーファイル内の部分文字列を検索します。すべてを読み込まずに特定の事実を思い出す場合に使います。

パラメーター	型	必須	説明
query	string	はい	すべてのメモリーファイルを対象に検索する部分文字列。

インストール

npm install -g mcp-agent-memory

クイックスタート（対話型ウィザード）

メモリーディレクトリ、デーモン、クライアント設定、ログ、自動起動サービス（macOS の LaunchAgent または Linux の systemd ユーザーサービス）をまとめて設定する最も手軽な方法は、セットアップウィザードです。

mcp-agent-memory --setup

ウィザードでは、次の7つの質問に回答します。

1. メモリーディレクトリ — .agent-memory/ の保存場所（デフォルトは ~/.agent-memory）
2. 統合デーモンをインストールしますか？ — MCP のみのモード（エージェントによるメモリーの読み取り／書き込み／検索は可能ですが、自動統合は行われません）にする場合は、「いいえ」と答えてください
3. LLM バックエンド — bedrock、openai、または kiro（デーモンをインストールしない場合はスキップされます）
4. 統合の設定 — min_hours、min_sessions、抽出間隔、最大文字数
5. 実行モード — standalone（手動で起動）、launchagent（ログイン時に自動起動、macOS）、または systemd（systemd ユーザーサービス、Linux）。Linux では systemctl --user にアクセスできる場合のみ、ウィザードに systemd が表示されます。アクセスできない場合は standalone に切り替わり、その理由が表示されます。
6. ログディレクトリ＋TTL — ログの保存場所と、ログを保持する日数（0 = 無期限）
7. クライアントの登録 — Kiro、Claude Desktop、Cursor の設定に MCP サーバーを自動登録します（既存の MCP エントリーは保持されます）

kiro バックエンドを選択すると、ウィザードはトークン使用量を約7分の1に削減する軽量なエージェントも ~/.kiro/agents/memconsolidate.json にコピーします（Kiro バックエンドを参照）。

launchagent または systemd を選択すると、ウィザードは agent-memory-daemon がインストールされているか確認します。インストールされていない場合は、npm install -g でのインストールを提案してから、plist／ユーザーユニットを登録して起動します。

CLI リファレンス

mcp-agent-memory                       # run as an MCP server (normal mode — clients spawn it)
mcp-agent-memory --setup               # first-time interactive setup
mcp-agent-memory --configure           # re-run most steps; can add/remove the daemon later
mcp-agent-memory --remove              # interactive uninstall (backup memory, clean configs)

# Auto-start service control (macOS LaunchAgent / Linux systemd user service):
mcp-agent-memory --daemon status       # is the daemon running?
mcp-agent-memory --daemon start        # install and start
mcp-agent-memory --daemon stop         # stop (keeps the plist / unit)
mcp-agent-memory --daemon restart      # stop + start
mcp-agent-memory --daemon remove       # stop and delete the plist / unit

--remove は、クライアントの MCP 設定にある他のエントリを保持し、memory キーのみを削除します。デフォルトでは、復元できるように ~/.agent-memory/ をタイムスタンプ付きの .bak-* ディレクトリにバックアップします。

手動インストール

ウィザードを使わずに手動で設定する方法を説明します。

デーモンをインストールする（任意）

MCP サーバーは単独で動作し、~/.agent-memory/ 以下のファイルを読み書きします。メモリは保持されますが、デーモンを追加するまでは、セッションからメモリが統合または抽出されません。

npm install -g agent-memory-daemon@^2.8.0

# copy the example config
mkdir -p ~/.agent-memory
cp examples/memconsolidate.toml ~/.agent-memory/memconsolidate.toml

# start the daemon
agent-memory-daemon start ~/.agent-memory/memconsolidate.toml

この MCP サーバーが想定するディレクトリ構成に合った、すぐに使える設定については、examples/memconsolidate.toml を参照してください。

ログイン時にデーモンを実行する（macOS）

デーモンを手動で起動する代わりに、LaunchAgent として登録します。

./scripts/daemon.sh start          # install plist, load it, start at login
./scripts/daemon.sh status         # check if it's running
./scripts/daemon.sh stop           # unload (keeps the plist)
./scripts/daemon.sh remove         # unload and delete the plist

カスタム設定ファイルのパスは、2 番目の引数として渡します：./scripts/daemon.sh start /path/to/config.toml。ログは ~/.agent-memory/logs/daemon.{out,err}.log に出力されます。remove を実行しても、設定ファイルとメモリファイルはそのまま残ります。

ログイン時にデーモンを実行する（Linux / systemd）

Linux では、systemd のユーザーサービスとして登録します。

./scripts/daemon-systemd.sh check      # is a systemd user manager reachable?
./scripts/daemon-systemd.sh start      # write unit, enable, start
./scripts/daemon-systemd.sh status     # check if it's running
./scripts/daemon-systemd.sh stop       # stop (keeps the unit)
./scripts/daemon-systemd.sh remove     # disable and delete the unit

ユニットファイルは ~/.config/systemd/user/agent-memory-daemon.service に書き込まれます。ログは macOS と同じ場所に出力されます。ユーザーサービスはログイン時に起動します。ログインセッションなしで起動時にデーモンを開始するには、linger を有効にします：sudo loginctl enable-linger $USER。

ホストによっては（コンテナ、サンドボックス環境、SSH 専用マシンなど）、systemctl --user に到達できない場合があります。その場合、check／start はコード 2 と説明を返して終了します。代わりに、デーモンを単独で実行してください。

Kiro を LLM バックエンドとして使用する

Kiro クレジットがあれば、Bedrock や OpenAI の API 呼び出しに料金を支払う代わりに、kiro-cli 経由でデーモンを実行できます。これには kiro バックエンドを追加する agent-memory-daemon ≥ 2.7（ブランチ feat/kiro-backend）が必要です。

[llm_backend]
name = "kiro"
# optional overrides:
# binary = "/custom/path/to/kiro-cli"
# agent = "memconsolidate"          # set to "" to use Kiro's default session context (not recommended)
# model = "claude-sonnet-4-20250514"
# timeoutMs = 300000

軽量エージェントを使って、トークン使用量を約 7 分の 1 に削減できます。 デフォルトでは、kiro-cli chat の呼び出しごとに、Kiro のシステムプロンプト全体とグローバル設定にあるすべての MCP ツールスキーマが読み込まれます。呼び出しごとに、入力トークンが約 12～18K 余分に必要です。これらをすべて省略する最小限のエージェントを作成します。

cp examples/kiro-agent-memconsolidate.json ~/.kiro/agents/memconsolidate.json

Kiro バックエンドは自動的に --agent memconsolidate を渡すため、追加の設定は不要です。簡単なプロンプトで測定したところ、出力品質は同じで、軽量エージェントでは 0.01 クレジット、デフォルトでは 0.07 クレジットでした。

examples/kiro-agent-memconsolidate.json を参照してください。このエージェントは mcpServers: {}、tools: []、useLegacyMcpJson: false を設定しているため、グローバルの Kiro 設定を引き継ぎません。

クライアントを手動で設定する

--setup と --configure のウィザードを使えば、この設定を自動で行えます。このセクションでは、手動で接続を設定したいユーザー向けに説明します。

Kiro（CLI と IDE）

~/.kiro/settings/mcp.json を編集します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "disabled": false,
      "timeout": 30000,
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

autoApprove を設定する理由は？ すべてのメモリツールはローカルのファイルシステムのみを操作し、~/.agent-memory/ 以下の Markdown ファイルを読み書きするだけで、ネットワーク呼び出しは行いません。これらを autoApprove に追加すると、毎回確認を求められることなく Kiro がツールを呼び出せるため、「セッション開始時にメモリを読み込む」というシームレスな体験に不可欠です。

続いて、Kiro に 「メモリのインデックスを読んで」、または 「これを覚えておいて：npm より pnpm が好きです」 と頼みます。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

Claude Desktop を再起動すると、memory_* ツールが表示されます。

Cursor

同じサーバーブロック（autoApprove を含む）を ~/.cursor/mcp.json に追加します。

環境変数

変数	デフォルト値	説明
MEMORY_DIRECTORY	~/.agent-memory/memory	デーモンが統合済みメモリファイルを保存する場所
SESSION_DIRECTORY	~/.agent-memory/sessions	エージェントが書き込むセッション要約の保存先

両方のパスは、agent-memory-daemon の設定で使用しているものと一致している必要があります。

推奨エージェントプロンプト

会話の開始時に memory_read を、終了時に memory_append_session を呼び出すよう、エージェントに指示してください。Kiro のステアリングルールの例（~/.kiro/steering/memory.md）：

At the start of every session, call memory_read (no arguments) to load my memory
index. Only pass `topics` when the task genuinely needs the full content of a
specific topic file.

When you learn something durable about me, my projects, or my preferences, call
memory_append_session with a concise markdown summary. Target 300-800 tokens,
use structured headers and bullets (not prose), and focus on durable findings
and decisions — not play-by-play. Verbose summaries cost more during the
daemon's consolidation pass.

トークン使用量のヒント

3 つのツールはそれぞれコスト特性が異なります。いくつかの方法で、推論と統合にかかるコストを抑えられます。

• 引数なしの memory_read は MEMORY.md のインデックスのみを返します（通常 1 KB 未満）。全内容が必要な場合を除き、topics よりこちらを優先してください。
• memory_search は部分文字列ベースで、ファイルごとに一致する行を最大 3 行返します。トピックファイル全体を読み込むより低コストです。
• memory_append_session の呼び出し時にはコストがかかりませんが、統合時に各セッションがデーモンの LLM によって処理されます。要約は簡潔で構造化されたものにしてください。
• 古いトピックファイルは、定期的に統合するか削除してください。mcp-agent-memory --configure を実行してください。メモリディレクトリが 25 ファイルまたは 200 KB を超えると、警告が表示されるようになりました。
• 抽出後のセッションの整理は MCP サーバーではなくデーモンが行います。処理後にセッションをアーカイブまたは削除するオプションについては、agent-memory-daemon の設定を参照してください（デーモンが古いセッションを延々と再スキャンするのを防げます）。

ライセンス

MIT