agentmemory徹底解説｜Claude Code・CursorのAIエージェントに永続メモリを与えるMCPサーバー

AIコーディングエージェントを使うほど痛感するのは、毎セッション冒頭の「再説明コスト」だ。認証はjose、テストはVitest、Edge Runtimeに合わせてjsonwebtokenではなくjoseを採用——そんな前提を毎回貼り直さなければ、エージェントは平気でjsonwebtokenを呼び出してくる。

Claude CodeのCLAUDE.mdもCursorのnotepadも、200行を超えたあたりから腐り始める。書きすぎれば毎セッションのトークン消費が膨れ、書かなければ判断が再現しない。これがAIコーディング現場の地味な摩耗だ。

rohitg00/agentmemory（★5075、2026年5月11日最終push）はそこを「永続メモリのMCPサーバー」というレイヤで解消する。Claude CodeのフックでもCursorのMCPでもCodex CLIでも、同じ1台のメモリサーバーが裏で文脈を吸い上げ、必要なときだけ注入する。

AIエージェント基盤の全体像と他フレームワーク比較は AIエージェントフレームワーク比較ガイド2026 をご覧ください。

1. agentmemoryとは：AIエージェント向け永続メモリMCPサーバーの全体像

agentmemoryは公式READMEで「#1 Persistent memory for AI coding agents based on real-world benchmarks」と自称している。日本語に直すと「実測ベンチマークに基づくAIコーディングエージェント向け永続メモリの第1選択」となる。

公式の位置付けは「メモリエンジン＋MCPサーバー」だ。AutoGPTやLettaのようなエージェントランタイムではなく、Claude CodeやCursorといった既存ハーネスの背後にレイヤとして差し込まれる。

GitHubトピックにはmemory・agents・ai・claude・claudecode・cursor・codex・copilot・harness・hermes・openclawが並ぶ。コーディング系のメジャーなAIエージェントを横断するスコープが公式に表明されている。

メモリ抽出のアイデアはAndrej Karpathyの「LLM Wiki」パターンが起点になっており、agentmemoryはそこに信頼度スコア、ライフサイクル、知識グラフ、ハイブリッド検索を加えた実装版だと位置付けられている。

派生元のデザインドキュメント（GitHub Gist）は1050スター・150フォークを記録しており、設計思想に対する評価が一定数固まっている。

agentmemoryのリポジトリ基本情報

Apache 2.0ライセンスで、社内利用や商用統合の制約が緩いのも普及を後押ししている。iii-engineへのバージョンピン（v0.11.2）はリポジトリREADMEに明記されており、v0.11.6のサンドボックスモデル移行は意図的に保留中だ。

2. なぜAIコーディングエージェントに永続メモリが必要か：CLAUDE.mdの200行壁

agentmemoryが解こうとしている問題は、AIコーディングエージェントの「セッション再起動コスト」に集約される。公式READMEはこの体験を「Session 1にJWT認証を組み、Session 2でレート制限を頼むときに再説明が要らない」と要約する。

実際の挙動は素朴だ。Session 1で書いた認証コードがsrc/middleware/auth.tsにあること、テストがtoken validationを覆っていること、Edge互換性のためにjoseを選んだこと——その三つを次セッションのエージェントが最初から「知っている」。

2.1 内蔵メモリの限界

各種AIコーディングエージェントは独自のメモリ機構を持つ。Claude CodeのMEMORY.md、Cursorのnotepad、ClineのMemory Bank、そしてプロジェクト直下のCLAUDE.mdや.cursorrulesだ。

問題はスケールしない点にある。READMEのベンチマーク表によれば、内蔵メモリは200行で上限に達し、240観測時点で22000トークン以上をコンテキストにロードしてしまう。常時22Kトークンが消えていく状態で、Opus 4.7のコスト感を保つのは難しい。

agentmemoryは同じ240観測前提でセッション平均1,900トークンに抑えると公開している。トークン削減率は約92％で、READMEは年間コストを19.5M超→約170K→約10ドル（ローカルエンベディングなら0ドル）と表現する。

2.2 「永続」と「想起」の分離

agentmemoryの設計上のキモは、永続化（書き込み）と想起（読み出し）を分けたことだ。永続化はバックグラウンドで自動的に走り、想起はBM25とベクトルとグラフの3チャネル融合で、必要な数K件だけをコンテキストに戻す。

これにより「全部読み込む built-in」「都度API呼び出しでaddする mem0」「ランタイム内蔵の archival memory のLetta」のいずれとも違う形に着地している。比較表は後の章で示す。

3. アーキテクチャ：12フック自動キャプチャと4層メモリ消費パイプライン

agentmemoryのアーキテクチャは、Claude Codeのフックエコシステムに合わせて設計されている。SessionStartからSessionEndまでの12フックを利用し、ツール呼び出しの観察とセッション要約を自動化する。

3.1 ハイブリッド検索とフック連動パイプライン

公式READMEの「Memory Pipeline」セクションを噛み砕くと、書き込みと読み出しは下の図のように分岐する。

PostToolUseがツール出力を捕まえると、まず5分窓のSHA-256デデュプを通す。短時間で同じ観測を二重に保存しないための施策だ。

その後、API鍵・シークレットを除去するプライバシーフィルタを通り、raw observationが書き込まれる。続いてLLMが「事実・概念・ナラティブ」の3層に圧縮し、ベクトル埋め込みを生成する。

SessionEndでは追加で要約・知識グラフ抽出・スロットリフレクションが走る。SessionStart時にはプロジェクトプロファイルが先に読まれ、その上でBM25とベクトルとグラフを統合した検索が、既定2000トークンの予算内で結果を返す。

3.2 4層メモリ消費（Working/Episodic/Semantic/Procedural）

agentmemoryは人間の睡眠中の記憶整理に着想を得た4層モデルを採用している。READMEの「4-Tier Memory Consolidation」表をそのまま引くと、層ごとの役割は次のとおりだ。

各層は時間とともに減衰する（エビングハウスの忘却曲線がベース）。アクセス頻度が高いメモリはweightが強化され、古くて使わないメモリは自動的に淘汰される。

公式の説明には「Contradictions are detected and resolved」とあり、新旧で矛盾する事実は検出されて統合・上書きされる。これは長期運用での衛生上、必須の機能だ。

3.3 検索ストリームの三本柱

検索は3つのストリームの結合だ。BM25は語幹マッチと類義語展開で、必ず動く。ベクトルはエンベディングが構成されている場合のみで、+8ppの再現率を上乗せする。グラフは検索クエリからエンティティが検出された場合だけ走り、知識グラフのBFSで隣接ノードを引く。

3チャネルはReciprocal Rank Fusion（RRF、k=60）で融合される。さらに「max 3 results per session」のセッション多様化を行うので、同じセッション由来の観測がトップを独占しない作りだ。

エンベディングは6種類から選べる（OpenAI・Gemini・Voyage・Cohere・OpenRouter・ローカル）。ローカルはall-MiniLM-L6-v2で、APIキー不要・無料・オフライン動作のため、年間コスト0円ルートになる。

4. ベンチマーク：LongMemEval-Sで95.2% R@5、92％のトークン削減

agentmemoryのアドバンテージは数字で裏打ちされている。benchmark/LONGMEMEVAL.mdに格納された結果は次のとおりだ。

4.1 LongMemEval-S（ICLR 2025、500問）

ICLR 2025で発表されたLongMemEvalは、長期記憶のAIエージェント評価用ベンチマークだ。500問のクエリに対してR@5（上位5件の再現率）で95.2％という数字は、BM25-onlyの86.2％を約9ポイント上回る。

公式の比較表によれば、mem0（53Kスター）はLoCoMoベンチで68.5％、Letta（22Kスター）は83.2％、内蔵CLAUDE.mdはgrep相当で計測不能、と整理されている。LoCoMoとLongMemEval-Sは異なるベンチマークなので単純比較はできないが、永続メモリ製品のレンジ感の把握には役立つ。

4.2 トークンとコスト

READMEは年間トークンとコストの試算も載せている。

「全文をペーストする運用は実質不可能、LLMサマリ方式は性能とコストが釣り合わない、agentmemoryは1桁オーダ低い」という主張は、現場のAIコーディング運用感覚とも合致する。

4.3 ベンチマーク以外の指標

READMEの上部バッジには「95.2% retrieval R@5」「92% fewer tokens」「51 MCP tools」「12 auto hooks」「0 external DBs」「827 tests passing」が並ぶ。

特に「827 tests passing」は、Apache 2.0ライセンス＋外部DB不要という前提と合わせて、社内・OSS両面でのリスク評価をしやすくする。テスト本数は信頼性の絶対指標ではないが、品質保証へのスタンスを示す。

5. インストール：Claude Code・Cursor・OpenCodeへの導入

agentmemoryのインストールは「メモリサーバー起動」と「各エージェント側のMCP設定」の2段構えだ。サーバーはnpx一発で立つ。

5.1 サーバー起動とデモ

# ターミナル1: メモリサーバー起動（REST 3111、WebSocket 3112、ビューワ 3113）
npx @agentmemory/agentmemory

# ターミナル2: サンプルデータ投入と意味検索デモ
npx @agentmemory/agentmemory demo

demoコマンドはJWT認証、N+1クエリ修正、レート制限という3セッションを投入し、「database performance optimization」というクエリで「N+1 query fix」が引けることを示す。キーワードマッチでは到達できない動きを最短で実感できるサンプルだ。

ビューワはhttp://localhost:3113で開ける。ライブ観測ストリーム、セッションエクスプローラ、メモリブラウザ、知識グラフ可視化、ヘルスダッシュボードが揃う。

5.2 Claude Codeでの導入

Claude Code向けは公式プラグインが用意されている。READMEの推奨パスは次の通りだ。

# 別ターミナルでメモリサーバーを起動した状態で
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
# 動作確認
curl http://localhost:3111/agentmemory/health

このプラグインは12フックと4スキル、そして.mcp.json経由の@agentmemory/mcp stdioサーバーを自動配線する。memory_smart_search・memory_save・memory_sessions・memory_governance_deleteなど51のMCPツールが追加設定なしで使えるようになる。

Claude Codeとフック設計の関係をもう一段掘りたい場合は、別記事の Claude Code開発者Thariqが語るエージェント設計の全貌 を読むと、なぜフックがメモリレイヤと相性が良いかが立体的に把握できる。

5.3 Cursor・OpenCode・Codex CLIでの導入

CursorやClaude DesktopなどmcpServersスキーマを採るホストは、~/.cursor/mcp.jsonに下記JSONブロックを追記すれば完了する。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

OpenCodeはトップレベルキーがmcpになっており、コマンドが配列型だ。OpenCode用の形は次のスニペットになる。

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

Codex CLIはTOMLで、codex mcp add agentmemory -- npx -y @agentmemory/mcpを実行するか、[mcp_servers.agentmemory]を手書きする。Gemini CLIはgemini mcp add agentmemory npx -y @agentmemory/mcp --scope userで~/.gemini/settings.jsonに自動マージされる。

MCPサーバーの仕組みを根本から確認したい場合は、別記事 MCPサーバーの作り方完全ガイド を参照してほしい。プロトコル全体の流れを把握すると、agentmemoryのMCPツール群の設計意図がよく見える。

6. 51 MCPツールと/recall・/rememberスキルの実用

agentmemoryのコアバリューは「51のMCPツール、6リソース、3プロンプト、4スキル」というツールキットの厚みにある。各エージェントから同じインターフェースで触れるので、フレームワーク横断の運用が現実的になる。

6.1 Coreツール（常に有効）

memory_recall          : 過去観測を検索
memory_save            : 洞察・判断・パターンを保存
memory_smart_search    : ハイブリッド意味＋キーワード検索
memory_file_history    : 特定ファイルの過去観測
memory_sessions        : 直近セッション一覧
memory_timeline        : 時系列観測ビュー
memory_profile         : プロジェクトプロファイル
memory_export          : メモリデータをエクスポート
memory_relations       : リレーションシップグラフを問い合わせ
memory_patterns        : 繰り返し出現するパターン検出
memory_compress_file   : 構造を保ったままファイル圧縮

このCore11個があれば、Claude CodeのSkillsから「/recall」「/remember」「/session-history」「/forget」を呼び出してメモリを直接操作できる。

6.2 Extended（AGENTMEMORY_TOOLS=all設定時）

AGENTMEMORY_TOOLS=allを環境変数で渡すと、memory_consolidate・memory_claude_bridge_sync・memory_action_create・memory_lease・memory_routine_run・memory_signal_send・memory_checkpoint・memory_mesh_sync・memory_sentinel_createなど、エージェント間調停系のツールが追加で開かれる。

特にmemory_leaseはマルチエージェント時の排他制御、memory_signal_sendは受信レシート付きのエージェント間メッセージング、memory_sentinel_createはイベント駆動の監視ウォッチャーになる。Ruflo型のマルチエージェント運用にも乗りやすい構成だ。

6.3 MEMORY.md双方向同期

Claude Codeを使うチームには重要な機能として「Claude bridge（MEMORY.mdとの双方向同期）」がある。memory_claude_bridge_syncを呼ぶと、agentmemoryの構造化メモリとリポジトリ直下のMEMORY.mdが整合する形にミラーされる。

これはチームで「Gitに乗るメモリ」と「エージェントが裏で蓄えるメモリ」の二系統が乖離するのを防ぐためのレールだ。Gitに残るドキュメントはレビュー対象、agentmemory側は実装プロセスの暗黙知、という分離設計に近い。

6.4 セッションリプレイ

Replayタブを使うと、agentmemoryが記録したセッションをタイムラインでスクラブできる。プロンプト、ツール呼び出し、結果、応答が個別のイベントとして並び、再生・一時停止・速度（0.5×〜4×）・キーボードショートカット（space・矢印キー）で操作する。

既存のClaude Code JSONLトランスクリプトを取り込む手段も用意されている。

# ~/.claude/projects 配下を全インポート
npx @agentmemory/agentmemory import-jsonl

# 単一ファイル
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

取り込んだセッションはReplayピッカーにそのまま並ぶ。mem::replay::load・mem::replay::sessions・mem::replay::import-jsonlというiii関数経由でルーティングされ、サイドチャンネルのサーバーを別に立てないという設計上のクリーンさがある。

7. mem0・Letta・built-in memoryとの違いとagentmemoryの選び方

agentmemoryの強みは比較表で見えてくる。READMEの「vs Competitors」セクションは、永続メモリ製品のポジション整理として実用的な資料だ。

7.1 機能比較表

mem0は「軽量なメモリAPI」「Qdrant等を別途用意して使う」「LLMが自己呼び出しで add する」前提だ。汎用カスタマーサポート用途で広く採用されるが、エージェント側に責任が寄る。

Lettaはランタイム同梱型で、archival memory・core memory・recall memoryなどの概念が明確だが、Lettaフレームワークの中でしか使えない。エージェント実装をLettaに合わせる必要があるため、Claude CodeやCursorをそのまま使いたいケースには向かない。

内蔵CLAUDE.mdは無料・即時で導入できる一方、240観測あたりで22000トークン以上を毎回ロードする構造上、長期運用と相性が悪い。

7.2 どれを選ぶか

agentmemoryが特に効くのは、次のような状況だ。

・Claude CodeとCursorを併用しており、同じプロジェクトのメモリを両方で使いたい
・本番のサポートチャットではなく、コーディングエージェントの長期セッションを伸ばしたい
・Qdrant・Postgres・Pineconeなど外部メモリインフラを増やしたくない
・MEMORY.mdをGit管理しつつ、それと整合する裏側の構造化メモリを欲しい
・ベクトルだけでなくBM25・グラフを統合したRRF検索が必要

反対に、運用上1台のグローバルメモリAPIを多数のアプリから叩く構成や、エージェントが本当に「自己編集メモリ」を持つ設計を試したい場合は、mem0やLettaが選択肢になる。agentmemoryはあくまでコーディング系エージェントに最適化された永続メモリ層だ。

8. 運用時の注意点：iii-engineのバージョン、Windows、セキュリティ

agentmemoryは「メモリエンジン＋MCPサーバー」というレイヤを薄く保つ代わりに、iii-engineというRust製ランタイムに強く依存する。運用上の留意点はここに集中する。

8.1 iii-engineのバージョンピン

agentmemoryは現時点でiii-engineをv0.11.2にピンしている。v0.11.6で導入された「サンドボックスをiii worker add経由に統一する」新モデルへの追随がまだリファクタ待ちになっているためだ。

このため、AGENTMEMORY_III_VERSION環境変数で意図的に上書きしない限り、ローカルのiiiバイナリも0.11.2系を使う前提になる。macOS arm64なら次のように導入できる。

mkdir -p ~/.local/bin
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
  | tar -xz -C ~/.local/bin
chmod +x ~/.local/bin/iii
iii --version  # 0.11.2 と表示されればOK

Linux x64／arm64、macOS x64も同じパターンで、aarch64-apple-darwin部分を該当ターゲットに差し替える。Dockerを使う場合はバンドルされるdocker-compose.ymlがiiidev/iii:0.11.2を引く。

8.2 Windows

agentmemoryはWindows 10/11でも動くが、iii-engineは別バイナリで必要だ。公式アップストリームのインストーラはshスクリプトだけなので、Windowsでは「プリビルトバイナリを%USERPROFILE%\.local\bin\iii.exeに置く」か「Docker Desktopを起動した状態でnpx @agentmemory/agentmemoryを走らせる」の二択になる。

REST・WebSocket・ビューワ・cronジョブが要らず、MCPツールだけで足りる場合は次のスタンドアロン経路で動かせる。

npx -y @agentmemory/agentmemory mcp
# または
npx -y @agentmemory/mcp

これはエンジンを使わないモードで、Cursor・Claude Desktop・Cline・Goose・Windsurfなど純粋なMCPクライアントから利用するのに向く。

8.3 セキュリティと監査

ビューワは127.0.0.1にバインドされ、/agentmemory/viewerはAGENTMEMORY_SECRETベアラトークンで保護される。CSPヘッダーはレスポンスごとのscript nonceを発行し、script-src-attr 'none'でインラインイベントハンドラを無効化する設計だ。

監査ポリシーはmemory_governance_deleteを中心にあらゆる削除パスへ広がっており、削除イベントがすべて監査トレイルに残る。チームでの導入時、最初に確認すべきはこのmemory_audit／memory_governance_delete周りだ。

プライバシーフィルタはAPIキー・シークレットを正規表現で検出して剥がし、<private>タグで囲んだ範囲は最初から保存しない。サンプルとしてapi_key=やBearerトークン形式が捕まる前提になっている。

9. まとめ：永続メモリは「エージェント」ではなくレイヤとして持つ

AIコーディングエージェントの永続メモリは、Claude CodeやCursorといった上流エージェントの「内蔵機能」として閉じ込めるより、独立した1枚のレイヤとして切り出した方が摩擦が少ない。

agentmemoryはその選択肢の中で、外部DB不要・MCP横断・自動キャプチャ・LongMemEval-Sで95.2％・年間コスト約10ドルという数字を揃えた現実解だ。Apache 2.0ライセンス、827テスト、リアルタイムビューワ込みで、社内導入評価のテーブルにのせやすい。

長期的にはmem0やLettaのような他のメモリ製品と相互運用できる方向に進む可能性が高い。今のうちにMCP経由でメモリレイヤを切り出しておけば、エージェントを後から差し替えてもメモリ資産は手元に残るという含意もある。

Claude CodeとCursorを併用しているチーム、あるいは「同じプロジェクトを複数のAIコーディングエージェントから触る」運用を取っているチームは、まずnpx @agentmemory/agentmemory demoから触り始めるのが速い。

参照ソース

• rohitg00/agentmemory（GitHubリポジトリ・README）
• agent-memory.dev（公式サイト）
• agentmemory CHANGELOG.md（v0.9.0リリースノート含む）
• iii-hq/iii（依存ランタイム iii-engine）
• 設計ドキュメント Gist（1050★／150 fork）