Agent Memory MCP

agent-memory-mcp

エンジニアリングエージェント向けのメモリ、ドキュメント、リポジトリコンテキストレイヤーです。

agent-memory-mcp は、エージェントが孤立したメモだけでなく、実際のエンジニアリングコンテキストを活用できるようにします。型付きメモリ、ドキュメント検索、リポジトリを考慮したツールを組み合わせ、Claude、Cursor、Codex、その他の MCP クライアントが、セッションをまたいで決定事項を思い出し、運用手順書を検索し、プロジェクトドキュメントを調べ、運用に関する知識を再利用できるようにします。

次のようなエンジニアリングワークフロー向けに設計されています。

• DevOps とプラットフォーム運用
• インフラストラクチャの変更とロールバック計画
• 運用手順書、変更履歴、RFC、事後分析
• リポジトリに紐づいたままのプロジェクト単位のメモリ

対象ユーザー

• 実際のコードベース、ドキュメント、運用ワークフローで AI エージェントを利用しているチーム
• チャット履歴以上の情報を必要とする DevOps、プラットフォーム、インフラエンジニア
• まずはローカルファーストのメモリを使い、将来的には共有サービスへ移行したいプロジェクト

単なるメモリツールでは不十分な理由

多くのメモリ MCP サーバーは、「メモを保存して、メモを呼び出す」ことに重点を置いています。

agent-memory-mcp は、より広いエンジニアリングコンテキストレイヤーを目指しています。

• 決定事項、事実、パターン、作業コンテキストのための型付きメモリ
• プロジェクトドキュメント、変更履歴、ナレッジファイルの RAG インデックス作成
• 許可されたプロジェクトパスの読み取りと検索を行うリポジトリ／ファイルツール
• 現在は stdio を使ったローカル SQLite ストレージ、共有が必要になった場合は HTTP/JSON-RPC

エージェントが次のような質問に答える必要がある場合、より適しています。

• 「このサービスで HPA を無効にした理由は何ですか？」
• 「このリグレッションの原因になりそうな、最近の変更は何ですか？」
• 「このインシデントに該当する運用手順書または RFC はどれですか？」

目次

• 対象ユーザー
• 単なるメモリツールでは不十分な理由
• 機能
• ユーザーにとっての改善点
• 3 分でローカル環境を開始
• ローカル専用モード
• 2 つのコマンドでリポジトリにインデックスを作成
• 後からチームサービスに移行
• インストール方法 — Homebrew、バイナリ、ソース、Docker
• CLI モード
• MCP クライアントの設定 — Claude Desktop、Cursor、Codex
• おすすめのワークフロースニペット — CLAUDE.md / .cursorrules に貼り付ける内容
• CLI コマンド
• MCP ツールのリファレンス — docs/MCP_TOOLS.md の JSON 例も参照してください
• 設定 — 環境変数、ホットリロード、インデックス作成の安全性
• セキュリティと運用
• アーキテクチャ
• macOS サービスのインストール
• トラブルシューティング／FAQ
• 開発

リファレンスドキュメント：HOOKS · MCP_TOOLS · SHARED_SERVICE · STEWARDSHIP · SEDIMENTATION · BACKUP_RESTORE · SECURITY · THREAT_MODEL · CONTRIBUTING · CHANGELOG

機能

• セッションの自動記録 — Claude Code フックにより、セッション終了時に知識を自動記録し、コンテキスト圧縮前にチェックポイントを保存し、セッション開始時に保留中の要約を作成します
• 型付きの永続メモリ（エピソード記憶、意味記憶、手続き記憶、作業記憶の4種類）
• ハイブリッド検索 — 埋め込みとキーワード／BM25風のランキングを組み合わせます
• RAG インデックス作成 — プロジェクトのドキュメント、変更履歴、ナレッジアーカイブを対象とします（stdio／CLI モードではデフォルトで有効、Homebrew サービスのプリセットではデフォルトで無効です。詳しくはインストールオプションをご覧ください）
• リポジトリを認識するファイルツール — 許可リストに登録されたパスの一覧表示、読み取り、検索に対応します
• 知識の管理 — 重複の検出、競合の解決、古い情報の検出、ドリフトのスキャン、レビュー受信箱などのメンテナンスを自動化します
• 時間的知識モデル — 知識が有効だった時期を追跡し、置き換えの連鎖を構築して、「時点 T では何が真実だったか」を照会できます
• デュアルトランスポート：MCP クライアント向けの stdio と、API および共有セットアップ向けの HTTP/JSON-RPC
• メモリとベクトルインデックスの両方に SQLite ストレージを使用 — 外部データベースは不要です
• 自動インデックス作成 — 長時間稼働するローカルモードまたはサービスモードでファイルウォッチャーを使用します

ユーザー向けの改善点

• メモリ使用量の削減：メモリストアがすべてを RAM に読み込むのではなく、SQLite から直接読み込むようになりました。大規模なメモリバンクでも、OOM のリスクがなくなります。
• ローカル単独利用に適したセットアップ：推奨レイアウトは 1 つ、データディレクトリは 1 つ、手軽なスモークテスト手順も 1 つです。
• .env の自動読み込み：環境変数を手動で読み込まずに、プロジェクトのルートディレクトリから実行できます。
• ローカル限定の埋め込みモード：ホスト型プロバイダーを無効にしたまま、テキストをローカルの Ollama エンドポイントにのみ送信できます。
• セマンティック検索の安全性向上：異なる埋め込みモデルで作成されたメモリが、誤解を招く一致を返さなくなりました。
• 明示的な移行フロー：メモリの移行には agent-memory-mcp reembed、モデルの切り替え後に RAG を再構築するには agent-memory-mcp index を使用します。
• 可視性の向上：stats と memory_stats では、各埋め込みモデルに属するメモリの数と、セマンティック検索では見つからない項目の名前が表示されます。エンコーダーが完全に拒否したレコードや、冒頭部分のみから埋め込まれたレコードも確認できます。
• すぐに使える MCP クライアント設定：Claude Desktop、Cursor、Codex 用のコピー＆ペースト可能なスニペットを生成できます。
• より安全なインデックス作成のデフォルト設定：組み込みのディレクトリ除外、パスごとの除外 glob（任意）、インデックス作成前のドキュメント内シークレットのマスキングに対応しました。
• ソースを考慮した検索：ドキュメント、ADR、RFC、変更履歴、運用手順書、ポストモーテム、CI 設定、Helm、Terraform、K8s ファイルを分類し、ソースメタデータとともに提示します。
• 検索のハイブリッドランキング：セマンティック類似度だけでなく、キーワードの一致、新しさ、ソースを考慮した重み付けも組み合わせるようになりました。
• 信頼性を考慮した検索：メモリとドキュメントの結果に source_type、confidence、freshness、owner、last_verified_at が追加され、類似度だけでなく信頼性や鮮度に基づいてランキングされます。
• 説明可能な検索：オプトインのデバッグ出力で、すべての結果についてフィルター、スコアの内訳、適用されたブーストを確認できます。
• DevOps 向けツール：汎用的なメモリ呼び出しではなく、ドメイン固有の MCP ツールで決定事項、インシデント、運用手順書、ポストモーテムを保存できます。
• メモリのライフサイクル：メモリは active、outdated、superseded、canonical の各ステータスを移行します。古い知識は検索を汚染するのではなく、自動的にランキングが下がります。
• 手動の統合ワークフロー：履歴を削除せずに、重複を統合し、古いメモに印を付け、正規エントリーに昇格させ、競合グループを調査できます。
• 明示的な正規知識レイヤー：確認済みの知識を生のメモリとは分けて一覧表示・検索でき、プロジェクトの要約では正規のコンテキストを優先して提示します。
• プロジェクトバンクのビュー：管理対象の知識を、決定事項、運用手順書、インシデント、注意事項、移行、レビュー待ちといったカテゴリ別に表示できます。フラットなメモリ一覧ではありません。
• セッション終了時のパイプライン：セッション終了時にメモリを分析、分類し、既存の知識と統合します。無条件に追記することはありません。
• 説明可能な統合：セッション終了レポートには、追加、統合、古い項目への変更、昇格の内容が、各アクションの判断トレースとリスクレベルとともに表示されます。
• DevOps セッションモード：セッション終了処理はセッションの種類に応じて動作を調整します。インシデントや移行のセッションではレビュー優先のより厳格なポリシーが適用され、コーディングセッションではリスクの低い更新が自動適用されます。
• 共有サービス向けパッケージ：動作する Docker Compose レシピ、共有環境変数テンプレート、nginx リバースプロキシの例、専用の共有デプロイガイドが含まれます。
• 組み込みの検索コンソール：/console の軽量 HTTP UI で、ハイブリッドランキング、信頼性、通常の検索とデバッグ検索を確認できます。
• より安全な HTTP のデフォルト設定：HTTP モードはデフォルトで 127.0.0.1 にバインドされます。ループバック以外へのバインドには認証が必要です。ただし、認証なしの安全でないアクセスを明示的に選択した場合を除きます。
• CLI と MCP の動作の一貫性：メモリタイプの検証、タグの正規化、クエリとコンテンツの上限、信頼性の要約で、両方のインターフェースに同じポリシーが適用されるようになりました。
• 知識の管理：steward_run を実行すると、重複の検出、競合の解決、古いエントリーのスキャン、正規エントリーへの昇格候補の抽出を含むメンテナンスサイクル全体を、1 つのコマンドで実行できます。
• 管理用受信トレイ：メンテナンス実行、ドリフトスキャン、セッション統合で要レビューとされたアクションが、黙って適用されたり失われたりせず、1 つの実行可能なキューに集約されます。
• ドリフト検出：drift_scan はメモリエントリーをリポジトリ内の実ファイルやドキュメントと比較し、古い参照、欠落した参照、変更された参照を特定します。
• 検証モデル：verify_entry と verification_candidates を使って、知識が最後に検証された時期と、対応が必要な項目をエージェントやユーザーが追跡できます。
• 正規知識の健全性診断：スチュワードの実行結果に、古い、未検証、競合あり、裏付けが不十分といった正規エントリーの健全性サマリーが含まれるようになりました。
• ポリシーに基づく自動化：スチュワードシップのしきい値、自動適用ルール、スケジュールを、steward_policy と環境変数で設定できます。
• 時間的な知識：メモリに valid_from / valid_until のタイムスタンプを付与でき、recall_as_of で特定の時点に有効だった知識を取得できます。
• 後継関係のチェーン：後継エントリーを指定して mark_outdated を実行すると、双方向リンク（superseded_by / replaces）が自動的に作成され、時間的な境界が設定されます。
• 知識のタイムライン：knowledge_timeline で、あるトピックに関する知識の変遷を時系列で確認できます。
• 経過時間を考慮した検索（オプトイン）：検索スコアに指数関数的な経年減衰を適用すると、古いメモリの順位を下げる一方、正規知識やキャラクター／アイデンティティ情報は維持できます。T121 の測定では、従来の 30 日設定で Hit@5 が 0.7217 → 0.1942 に低下したため、デフォルトでは無効です。MCP_RECALL_HALFLIFE_DAYS で有効化できます。また、MCP_RECALL_DECAY_TYPES（デフォルトは working）で経年減衰の対象となるタイプを指定します。減衰率よりもタイプの指定のほうが重要です。
• 重複の自己修復クリーンアップ：レビュー用キューに入れるだけでなく、スチュワードが信頼度の高いほぼ同一の重複グループを自動統合できます。この機能はオプトインで、コンテンツ類似度のしきい値によって保護されているため、固有の内容がアーカイブされることはありません（steward_policy の auto_merge_duplicate_min_confidence）。
• セッション終了時のレコード重複を解消：タスクを終了する際、自動取得したセッション要約を finalize レコードに統合し、slug ごとにほぼ同一のメモリを 2 件目として書き込まなくなりました。これにより、以前スチュワードが誤った矛盾として検出していた重複ペアが減少します。

3 分でローカル起動

おすすめの手順は、まずローカルで実行し、1 つのリポジトリで価値を確認してから、利用範囲を広げることです。

プロジェクトのルートディレクトリから、次のコマンドを実行してください。

前提条件

次のいずれかの方法でバイナリをインストールします。

# Homebrew (macOS/Linux) — recommended, auto-configures Claude Code hooks
brew tap ipiton/tap
brew install agent-memory-mcp

# go install
go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest

次に、埋め込みプロバイダーを 1 つ設定します。

• 最も手早くホスト型の環境をセットアップするには、Jina AI API キー
• OpenAI API キー、または OpenAI 互換の別のエンドポイント
• ローカル環境をセットアップするには、bge-m3 を使用した Ollama

1. ローカルモードを設定する

cp .env.example .env
# Edit .env:
# - keep the solo-local defaults unless you need to change them
# - enable at least one embedding provider
#   JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL

バイナリは現在のディレクトリから .env を自動的に読み込むため、source .env を実行する必要はありません。

おすすめの単独ローカル用プリセットでは、すべてのランタイム状態が 1 つのディレクトリ内に保持されます。

.agent-memory/
  rag-index/
  memory-store/
  logs/

ローカル専用モード

ホスト型 API にテキストを送信せずに埋め込みを行いたい場合は、ローカル専用モードを使用してください。

cp .env.example .env
# Then set:
# MCP_EMBEDDING_MODE=local-only
# JINA_API_KEY=
# OPENAI_API_KEY=

local-only モードでは、次のようになります。

• agent-memory-mcp は Jina AI を呼び出しません
• agent-memory-mcp は OpenAI 互換の埋め込み API を呼び出しません
• 埋め込みは、Ollama または llama.cpp のローカルバックエンド経由でのみ生成されます

ネットワークを使用するものは次のとおりです。

• ローカル Ollama HTTP エンドポイント。通常は http://localhost:11434
• または、ローカル llama.cpp サーバー。通常は http://127.0.0.1:8080/v1

ローカルバックエンドが実行されていない場合、または対応するローカルモデルが利用できない場合、埋め込みリクエストは、バックエンドを起動するか MCP_EMBEDDING_MODE=local-only を無効にするよう案内する、ローカル専用モード固有のエラーで失敗します。

代替のローカルバックエンド：llama.cpp

すでに llama.cpp（Apple Silicon ネイティブ、GGUF モデル）を実行している場合は、Ollama をインストールする代わりに、サーバーが OpenAI 互換の /v1/embeddings エンドポイントを使うよう設定してください。これはオプトインです。有効にするには LLAMACPP_BASE_URL を設定します。設定するとフォールバックチェーンに Ollama より先に追加され（Jina → OpenAI → llama.cpp → Ollama）、local-only モードでも動作します。

# Start llama.cpp with an embedding model
llama-server -m bge-m3.gguf --embedding --pooling cls -c 8192 -ub 8192

# Then configure the MCP server
LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
LLAMACPP_EMBEDDING_MODEL=bge-m3
MCP_EMBEDDING_MODE=local-only

llama.cpp はモデル固有の埋め込み次元を返すため、MCP_EMBEDDING_DIMENSION をその値に合わせてください（bge-m3 の場合は 1024）。一致しない場合、リコール時に拒否されます。

処理速度の遅いセルフホスト型ハードウェア（コア数の少ない環境や ARM VPS 上の Ollama と bge-m3 の組み合わせ）では、1 つのチャンクの埋め込みに 4～7 秒かかることがあり、デフォルトの 5 秒のタイムアウトが繰り返し発生します。制限値を引き上げてください。

MCP_EMBEDDING_TIMEOUT=30s      # default 5s
MCP_EMBEDDING_MAX_RETRIES=3    # default 1

無効な値はデフォルト値に戻るため、サービスは引き続き起動します。

自動インデックス作成／ファイルウォッチャー有効時の並行処理の調整

スロットが 1 つの llama-server は、リクエストを厳密に逐次処理します。MCP_RAG_AUTO_INDEX／MCP_RAG_FILE_WATCHER を有効にすると、バックグラウンドの再インデックスバッチ（各 50 チャンク）が唯一のスロットを数十秒間占有します。そのため、対話的な recall／semantic_search／index_documents がその後ろに並び、context deadline exceeded が発生します。スループットに問題がなくても、サーバーが「劣化」しているように見えます。埋め込みサーバーに並列スロットを設定し、バッチ処理と並行して対話的な呼び出しを実行できるようにしてください。

llama-server -m bge-m3.gguf --embedding --pooling cls \
  -c 32768 -b 8192 -ub 8192 \   # 8192 ctx PER SLOT (see note) — fits the largest chunk
  -np 4 -cb \                   # 4 slots + continuous batching: interactive calls don't wait for the batch
  --metrics                     # exposes Prometheus /metrics; /slots shows live slot occupancy

-np はコンテキストを分割します。 スロットあたりのコンテキストは ctx_size / n_parallel です。bge-m3 はエンコーダーであるため、各チャンク全体が 1 つのスロットに収まる必要があります。また、-b／-ub は最大のチャンクのトークン数以上でなければ、「input too large to process」エラーで失敗します。そのため、-np 4 の場合は、各スロットのコンテキストを 8192 に保つために -c 32768 が必要です。スロットを追加する際に、-c、-b、-ub をシングルスロット時の値より小さくしないでください。

計測結果（Apple Silicon、bge-m3 Q8_0）：50 件の入力バッチは約 50 秒から約 5 秒に短縮され、バッチ処理中の対話的なプローブは 8～20 秒から約 0.03 秒に短縮されます。

編集頻度が高い大きなファイルの再インデックス処理が一気に集中するのも緩和してください（ファイル全体を編集のたびに再チャンク化すると、サイクルの途中で再処理が発生することがあります）。

MCP_RAG_DEBOUNCE=2m         # default 30s — collapses bursts of edits into one reindex
MCP_RAG_WATCH_INTERVAL=5m   # periodic full-scan cadence

2. ローカルサーバーを起動する

Claude Desktop、Cursor、Codex などの MCP クライアントの場合：

agent-memory-mcp

直接 CLI を使う場合は、MCP クライアントがなくても同じバイナリをそのまま使用できます。

agent-memory-mcp store -content "Ingress rollback uses previous Helm revision" -type procedural -tags "helm,rollback"
agent-memory-mcp recall "helm rollback"
agent-memory-mcp stats

3. 動作確認を行う

agent-memory-mcp store -content "Solo local smoke check" -type working -tags "smoke,local"
agent-memory-mcp recall "solo local smoke"
agent-memory-mcp index
agent-memory-mcp search "agent memory"

ソースのチェックアウトから作業している場合は、次のコマンドでも同じ手順を実行できます。

make local-smoke

2つのコマンドでリポジトリをインデックス化

プロジェクトでローカルモードを起動したら、ドキュメントをインデックス化して検索できます。

agent-memory-mcp index
agent-memory-mcp search "recent ingress change"

特に価値の高い情報源には、次のようなものがあります。

• docs/
• README.md
• CHANGELOG.md
• RFC / ADR フォルダー
• 運用手順書やインシデント記録

後からチーム向けサービスにする

ローカルモードの有用性が確認できたら、次の3段階で移行します。

1. 個人でローカル利用
2. 自動インデックス化とファイル監視を有効にしたチームメンバーのノートパソコン
3. HTTP モード、認証トークン、リバースプロキシを使用した共有サービス

共有サービスを最も手早く構築する方法：

cd deploy/docker
cp .env.shared.example .env.shared
# edit MCP_HTTP_AUTH_TOKEN and MCP_PROJECT_ROOT
docker compose --env-file .env.shared up -d --build

これにより、同じ検索スタックを維持したまま、チームで使える形にできます。

参考ドキュメント：

• 共有サービスガイド
• セキュリティポリシー
• バックアップと復元

インストール方法

Homebrew（macOS に推奨）

brew tap ipiton/tap
brew install agent-memory-mcp
brew services start agent-memory-mcp

これにより、バイナリをインストールし、デフォルト設定を作成して、メモリ機能を有効にした状態で 127.0.0.1:18080 でサービスを起動します。RAG ドキュメント検索はデフォルトで無効です。有効にするには、設定を編集してください。

# Edit config
nano $(brew --prefix)/etc/agent-memory-mcp/config.env

MCP_RAG_ENABLED=true、MCP_ROOT=/path/to/your/project、MCP_INDEX_DIRS=docs,README.md を設定します。変更は約30秒以内に自動で反映されます。または、kill -HUP $(pgrep agent-memory-mcp) を実行して再読み込みできます。

サービスを管理するには：

brew services restart agent-memory-mcp
brew services stop agent-memory-mcp
brew services info agent-memory-mcp

以前に Cask でインストールしていて、brew services を使いたい場合：

brew uninstall --cask agent-memory-mcp
brew install ipiton/tap/agent-memory-mcp

バイナリをダウンロード

ビルド済みアーカイブを Releases ページからダウンロードします。

リリースアーカイブのファイル名にはバージョンが含まれているため、先に最新のタグを確認してください。

# Resolve latest version once
VERSION=$(curl -fsSL https://api.github.com/repos/ipiton/agent-memory-mcp/releases/latest \
  | grep '"tag_name"' | head -1 | cut -d'"' -f4 | sed 's/^v//')

# macOS (Apple Silicon)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# macOS (Intel)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# Linux (x86_64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# Linux (arm64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

ソースからビルド

git clone https://github.com/ipiton/agent-memory-mcp.git
cd agent-memory-mcp
go build -o bin/agent-memory-mcp ./cmd/agent-memory-mcp

Docker

docker build -f deploy/docker/Dockerfile -t agent-memory-mcp .
docker run -p 18080:18080 \
  -v memory-data:/data \
  -e MCP_HTTP_MODE=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
  agent-memory-mcp

または、docker compose を使用します。

cd deploy/docker
cp .env.shared.example .env.shared
docker compose --env-file .env.shared up -d --build

MCP HTTP エンドポイントは http://localhost:18080/mcp で利用できます。

デフォルトでは、ベアメタルの HTTP モードは 127.0.0.1 にバインドされます。共有環境やコンテナー環境にデプロイする場合は、MCP_HTTP_HOST=0.0.0.0 とベアラートークンを設定してください。

CLI モード

バイナリはスタンドアロンの CLI としても動作します。

# Memory operations
agent-memory-mcp store -content "Project uses chi router" -type procedural -tags "go,chi"
agent-memory-mcp recall "router middleware"
agent-memory-mcp list -type procedural
agent-memory-mcp delete <memory-id>

# RAG search
agent-memory-mcp search "authentication flow"
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
agent-memory-mcp index

# Project bank and session close
agent-memory-mcp project-bank canonical_overview
agent-memory-mcp close-session -summary "Updated payments rollback runbook after fixing ingress timeout" -context payments-api -service payments-api
agent-memory-mcp review-session -mode incident -stdin < notes/session.txt
agent-memory-mcp accept-session -summary "Added migration caveat for billing schema rename" -mode migration -context billing -service billing-api
agent-memory-mcp accept-session -raw-only -summary "Exploratory notes that are too noisy for consolidation"

# Utilities
agent-memory-mcp stats
agent-memory-mcp config claude-desktop
agent-memory-mcp reembed
agent-memory-mcp export > backup.json
agent-memory-mcp import backup.json

# JSON output for scripting
agent-memory-mcp recall "test" -json
agent-memory-mcp stats -json

各コマンドの詳細を確認するには、agent-memory-mcp <command> -help を実行してください。

CLI のメモリコマンドと MCP のメモリツールでは、同じ検証ルールと正規化ルールが適用されます。

• 無効なメモリタイプは一貫して拒否されます
• カンマ区切りのタグは、同じ方法で前後の空白が削除され、重複が取り除かれます
• verified のタイムスタンプがゼロの場合、CLI と MCP の両方の出力で信頼性の要約に表示されません

コマンドを指定しない場合（またはフラグが - で始まる場合）、以前と同様にバイナリが MCP サーバーを起動します。完全な後方互換性があります。

MCP クライアントの設定

組み込みのジェネレーターを使って、リポジトリのルートからサーバーを起動するプロジェクト固有の設定を生成します。

次の理由から、この方法を推奨します。

• .env の読み込みを維持できるため、各 MCP クライアントに設定を重複して記述する必要がありません
• .agent-memory/ をプロジェクトのルートからの相対パスとして維持できます
• クライアントごとにコピー＆ペーストできるスニペットが1つ用意されます

-root と -command を指定すると、検出されたプロジェクトのルートやバイナリのパスを上書きできます。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に貼り付けます。

agent-memory-mcp config claude-desktop

生成される出力の例：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
      ]
    }
  }
}

Cursor

~/.cursor/mcp.json に貼り付けます。

agent-memory-mcp config cursor

生成される出力の例：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
      ]
    }
  }
}

Codex

~/.codex/config.toml に貼り付けます。

agent-memory-mcp config codex

生成される出力の例：

[mcp_servers.memory]
command = "/bin/sh"
args = ["-lc", "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"]

サーバー名を変更する、またはパスを上書きする

agent-memory-mcp config claude-desktop \
  -name engineering-memory \
  -root /path/to/your/project \
  -command /absolute/path/to/agent-memory-mcp

推奨ワークフローのスニペット

これらのスニペットがない場合、エージェントは基本的な store_memory と recall_memory しか使用しません。セッション終了時の処理、エンジニアリング向けメモリタイプ、プロジェクトバンク、統合機能を利用するには、関連するスニペットをエージェントの指示に追加してください。

追加先：

• Claude Code — プロジェクトのルートにある CLAUDE.md に貼り付けます
• Cursor — プロジェクトのルートにある .cursorrules に貼り付けます
• Codex — システムプロンプトまたは AGENTS.md に貼り付けます
• Claude Desktop — プロジェクト設定のシステムプロンプト欄に貼り付けます

ワークフローに合ったスニペットを選んでください。まずは「セッション開始時の想起」と「コーディング終了時の処理」から始めましょう。最も一般的なケースをカバーできます。

セッション開始時の想起

Before you start, recall the project context for this task.
Then recall recent changes related to the service or component I am touching.
Search for relevant runbooks, RFCs, changelog notes, or incident notes.
Prefer `summarize_project_context` or `project_bank_view view=canonical_overview` for the first pass and then drill into `search_runbooks` or `recall_similar_incidents`.
Summarize the constraints, caveats, and likely risks before making changes.

コーディング終了時

When the coding session ends, call `close_session` with a concise summary, service, and context.
Review the proposed `new`, `update`, `merge`, and `raw_only` actions plus the decision trace.
If the plan looks low risk, use `accept_session_changes`.
If the report is noisy or mostly exploratory, keep `save_raw_only` as the fallback.
Prefer `project_bank_view` at the next session start to confirm what became maintained knowledge.

インシデント終了時

When incident work stabilizes, call `close_session` or `review_session_changes` with `mode=incident`.
Expect stricter review-first behavior for updates, merges, and anything touching canonical operational knowledge.
Capture impact, mitigation, rollback, and unresolved follow-ups in the summary.
Apply only the low-risk actions automatically and leave ambiguous runbook or incident changes in review.
Follow up with `recall_similar_incidents` and `project_bank_view view=incidents` if you need to compare against existing knowledge.

移行終了時

When a migration session ends, call `close_session` with `mode=migration`, affected service, and the migration summary.
Prefer explicit notes about prerequisites, sequencing, rollback, and post-deploy verification.
Treat runbook replacements, caveat changes, and supersede proposals as review-first even when the textual match looks strong.
Use `accept_session_changes` only after checking the report for stale or superseded knowledge.
Finish by checking `project_bank_view view=migrations` to see the maintained migration notes.

生データのみのフォールバック

If the session was exploratory, ambiguous, or too noisy, skip consolidation and save only the raw summary.
Use `close_session` / `review_session_changes` to inspect the plan first, then pick `save_raw_only`.
In CLI mode, `agent-memory-mcp accept-session -raw-only ...` is the explicit override.
This keeps the raw trace without forcing weak knowledge updates into the project bank.

インフラ変更前の確認

Before making infra or platform changes, recall similar fixes, migrations, incidents, and known caveats.
Search for runbooks, postmortems, changelog notes, and recent project context related to this component.
Summarize blast radius, rollback options, and operational risks before editing files.

スチュワードシップの実行

When memory has grown or a session just ended, run `steward_run` with `dry_run=true` to see what needs attention.
Review the report for duplicates, conflicts, stale entries, and canonical promotion candidates.
Check `steward_inbox` for pending review items and resolve them with `steward_inbox_resolve`.
Use `drift_scan` periodically to catch memories that reference files or docs that have changed.
Use `verification_candidates` to find knowledge that has not been verified recently.

時系列の想起

When you need to understand what was true at a specific point in time, use `recall_as_of` with an RFC3339 timestamp.
To trace how knowledge about a topic evolved over time, use `knowledge_timeline`.
When superseding an old decision or runbook, use `mark_outdated` with the superseding entry ID to build a proper chain.

HTTP モード（Docker、リモートサーバー、共有インスタンス）

HTTP モードでサーバーを起動します。

# Standalone
MCP_HTTP_MODE=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=18080 \
MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp

# Or with Docker
cd deploy/docker
docker compose --env-file .env.shared up -d --build

次に、HTTP 対応の MCP クライアントまたはプロキシの接続先を指定します。

http://localhost:18080/mcp

/mcp エンドポイントは MCP Streamable HTTP トランスポートに対応しています。JSON-RPC リクエストは POST で送信され、サーバーからのプッシュチャネルが必要なクライアント（Cursor など）は、GET と Accept: text/event-stream を使って接続します。サーバーは定期的なキープアライブコメントを送信して、そのストリームを維持します。SSE の Accept ヘッダーを付けずに通常の GET を実行すると、引き続き 405 が返されます。

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
  http://localhost:18080/mcp

ブラウザーで検索結果を確認するには、次を開きます。

http://localhost:18080/console

コンソールは、次の操作を行うための軽量な UI です。

• ドキュメント、生メモリ、正規ナレッジに対するクエリの実行
• ドキュメント検索の通常モードとデバッグモードの比較
• ソースの種類、信頼性／鮮度、スコアの内訳の確認

共有モードではページ自体は静的ですが、コンソールからライブクエリを実行するには、引き続き /mcp と同じベアラートークンが必要です。

共有 HTTP モードの場合：

• ベアメタル環境でのデフォルトのバインド先は MCP_HTTP_HOST=127.0.0.1 です。これは安全なローカル向けのデフォルトです。
• 共有環境／コンテナ環境にデプロイする場合は、MCP_HTTP_HOST=0.0.0.0 を設定します。
• MCP_HTTP_AUTH_TOKEN を設定すると、/mcp で Authorization: Bearer <token> が必須になります。
• MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true を明示的に設定しない限り、MCP_HTTP_AUTH_TOKEN を設定せずにループバック以外のアドレスへバインドすると、起動に失敗します。
• ロードバランサーまたはコンテナのヘルスチェックには /health を使用します。
• リバースプロキシまたはロードバランサーで TLS を終端します。
• 認証と TLS を設定せずに、サービスをパブリックインターネットへ直接公開しないでください。
• リバースプロキシ設定の出発点として deploy/nginx/agent-memory-mcp.conf を使用します。
• local -> team laptop -> shared service の全手順については docs/SHARED_SERVICE.md を参照してください。

CLI コマンド

コマンド	説明
serve	MCP サーバーを起動します（stdio/http）。コマンドが指定されていない場合のデフォルトです
store	メモリーを保存します（-content、-title、-type、-tags、-context、-importance、-stdin）
recall	信頼度を考慮したランキングでメモリーを呼び出します（位置指定のクエリ、-type、-tags、-limit、-json）
list	メモリーを一覧表示します（-type、-context、-limit、-json）
delete	IDを指定してメモリーを削除します（位置指定）
search	信頼性メタデータを使用したRAGハイブリッド検索を実行します（位置指定のクエリ、-limit、-source-type、-debug、-json）
index	RAG用にドキュメントを再インデックスします
close-session	セッション終了時の要約を分析し、セッション終了レポートを作成します（-summary、-stdin、-mode、-context、-service、-tags、-metadata、-started-at、-ended-at、-raw-only、-json）
review-session	close-sessionと同じ入力およびレポート機能を備えた、レビュー向けのエイリアスです
accept-session	生の要約を保存し、リスクの低いセッション変更を自動適用します（-summary、-stdin、-mode、-context、-service、-tags、-metadata、-started-at、-ended-at、-raw-only、-json）
stats	メモリーの統計情報を表示します（-json）
config	すぐに使えるMCPクライアント設定のスニペットを生成します
project-bank	構造化されたプロジェクトバンクのビューを表示します（canonical_overview、decisions、runbooks、incidents、caveats、migrations、review_queue）
resolve-review-item	保留中のレビューキュー項目を解決します（<id>、-resolution、-note、-owner、-json）
reembed	アクティブなモデルでメモリーの埋め込みを再生成します（-json。-truncatedを指定すると、本文の冒頭から作成されたベクトルも再エンコードします）
export	すべてのメモリーをJSONにエクスポートします（-oでファイルを指定。デフォルトは標準出力）
import	JSONからメモリーをインポートします（位置指定のファイルまたは標準入力）
index-triples	トリプル（subj、rel、obj）がないメモリーにトリプルを後付けします（-resume、-force、-limit、-context、-dry-run、-progress-every、-json）。recall_multihop MCPツールで使用されます。MCP_TRIPLE_EXTRACTOR_*環境変数を参照してください。
dead-ends-stale	再評価のため、-ageより古いdead_endメモリー（デフォルトは12か月）を一覧表示します（-limit、-json）
setup	~/.claude/settings.jsonにClaude Codeフックを自動設定します（-command、-dry-run、-force）。docs/HOOKS.mdを参照してください
hooks-config	settings.jsonに手動で貼り付けるClaude CodeフックのJSONを出力します（-command、-json）
context-inject	SessionStartフックのペイロード：最近のメモリーと保留中の生の要約（-limit、-pending-limit、-context、-service）
auto-capture	SessionEndフック：標準入力からトランスクリプトを読み込み、抽出 → 計画 → 適用のパイプラインを実行します（-stdin、-summary、-mode、-context、-service、-tags、-dry-run、-json）
checkpoint	PreCompactフック：コンテキストを圧縮する前に、生のセッションチェックポイントを保存します（-stdin、-summary、-boundary、-context、-service、-tags）
sweep-archive	MCP_TASK_ARCHIVE_ROOTSをスキャンし、アーカイブされたすべてのスラッグに対してend-taskを実行します（T47）
end-task	アーカイブされた1つのタスクスラッグに関連する作業用／手順用メモリーを統合します（T47）
mark-dead-end	断念したアプローチを、その失敗理由とともに記録します（T46）
sediment-cycle	メモリーの堆積に伴うレイヤー間の移行を適用します。簡単な昇格は自動適用され、それ以外はレビューキューに追加されます（T48）
recount-refs	既存のメモリー間エッジからreferenced_by_countメタデータを補完します（冪等）

MCP ツールのリファレンス

メモリツール

ツール	説明
store_memory	内容、種類、タグ、重要度を指定してメモリを保存します
recall_memory	セマンティック検索／テキスト検索クエリと任意のフィルターを使ってメモリを呼び出し、信頼度を考慮して順位付けします
update_memory	ID を指定して既存のメモリを更新します
delete_memory	ID を指定してメモリを削除します
list_memories	種類／コンテキストの任意のフィルターを使ってすべてのメモリを一覧表示します
memory_stats	メモリの統計情報（種類別の件数）を取得します
merge_duplicates	重複するメモリを主要エントリーに統合し、残りをアーカイブします
mark_outdated	メモリを古い、または置き換え済みとしてマークし、信頼度を考慮した呼び出しでの順位を下げます
promote_to_canonical	メモリを正規の知識に昇格させ、信頼度の順位を上げます
conflicts_report	重複候補、ステータスの競合、複数の正規エントリーを報告します
list_canonical_knowledge	確認済みメモリから投影された正規の知識エントリーを一覧表示します
recall_canonical_knowledge	生のメモリを結果から除外し、正規の知識のみを呼び出します
recall_multihop	（subj, rel, obj）トリプルコーパスを複数ホップでグラフ探索して呼び出します。各結果に到達したトリプルの連鎖と、集約されたパススコアに基づいて順位付けされたメモリを返します。単一ホップ検索では追跡できない、メモリを横断する推論クエリに使用します。MCP_TRIPLE_EXTRACTOR_* の値が設定されている必要があります。index-triples CLI を使ってバックフィルしてください。

RAG ツール

ツール	説明
semantic_search	インデックス化されたドキュメントを横断してハイブリッド検索します。source_type、信頼度メタデータ、説明用の debug モードを任意で指定できます
index_documents	RAG 検索用にドキュメントを再インデックス化します

ファイルツール

ツール	説明
repo_list	許可リストに登録されたパス配下のファイルとフォルダーを一覧表示します
repo_read	許可リストに登録されたパスからファイルを読み取ります
repo_search	許可リストに登録されたパスを横断してテキスト検索します

エンジニアリングワークフローツール

ツール	説明
store_decision	根拠、ステータス、影響を含むエンジニアリング上の決定を保存します
store_incident	影響、根本原因、解決策、サービス、重大度を含むインシデントを保存します
store_runbook	手順、トリガー、検証、ロールバックに関するメモを含むランブックを保存します
store_postmortem	根本原因とアクションアイテムを含むポストモーテムを保存します
close_session	完了したセッションを分析し、生の要約メタデータ、ナレッジ項目の候補、レビューに安全な統合アクションを作成します
analyze_session	計画と報告の動作はそのままに、close_session と互換性のある別名として機能します
review_session_changes	書き込みを強制せずに、完了したセッションの説明可能なレビュー報告を表示します
accept_session_changes	生の要約を保存し、リスクの低い統合アクションのみを自動適用します
resolve_review_item	保留中のレビューキュー項目を解決し、監査証跡を保持したままアクティブな受信トレイから削除します
search_runbooks	ランブックのメモリとインデックス化されたランブックのドキュメントを検索します
recall_similar_incidents	メモリとインデックス化されたポストモーテムから類似インシデントを呼び出します
end_task	アーカイブ済みタスクのスラッグのメモリを統合します。作業用／手順用の項目を古いものとして扱い、重要度の高い項目をレビューキューに送ります
sweep_archive	MCP_TASK_ARCHIVE_ROOTS をプルモードでスキャンし、アーカイブ済みのすべてのスラッグに対して end_task を実行します
store_dead_end	失敗したアプローチ（理由と使用した代替策を含む）を記録し、関連するクエリで検索した際に落とし穴として警告できるようにします。より大きな決定の文脈がない単独の失敗には、これを使用してください。行き止まりがより大きなアーキテクチャ上の決定の一部であり、両方の記録を1つの根拠の連鎖として関連付ける場合は、store_decision -avoided-dead-end-id <id> を使用してください（T46）
promote_sediment	メモリをより高い堆積層（表層 → エピソード → セマンティック → キャラクター）に昇格させます。docs/SEDIMENTATION.md を参照してください
demote_sediment	メモリを1つ下の堆積層に降格させます
sediment_cycle	堆積層の遷移サイクルを実行します。自明な昇格は自動適用し、自明でないものはレビューキューに送ります
summarize_project_context	最近の決定、ランブック、インシデント、関連ドキュメントを要約します
project_bank_view	正式なナレッジ、決定、ランブック、インシデント、注意事項、移行、レビューキュー、または堆積層の昇格候補について、構造化されたプロジェクトバンクビューを表示します

スチュワードシップツール

ツール	説明
steward_run	重複、矛盾、古い項目、正式なナレッジへの昇格候補をスキャンするナレッジスチュワードシップサイクルを実行します
steward_report	最新のスチュワードシップレポート、または実行IDで指定したレポートを取得します
steward_policy	検出しきい値、自動適用ルール、スケジュールを制御するスチュワードシップポリシーを取得または更新します
steward_status	ポリシーモード、直近の実行概要、保留中のレビュー件数、次回の予定実行を含む現在のスチュワードシップステータスを表示します
drift_scan	メモリ項目と最新のソース（リポジトリのファイル、ドキュメント）を比較し、ドリフト、参照の欠落、古く未検証のナレッジを検出します
verification_candidates	検証が必要なメモリを緊急度順に一覧表示します
verify_entry	メモリ項目を検証済みとしてマークし、検証メタデータを更新します
steward_inbox	メンテナンス実行、ドリフトスキャン、セッション統合で発生した、レビューが必要なアクションをスチュワードシップの受信トレイに一覧表示します
steward_inbox_resolve	アクション（merge、mark_outdated、promote、verify、suppress、defer）を適用して、スチュワードシップの受信トレイ項目を解決します

時間軸に沿った知識ツール

ツール	説明
recall_as_of	時間的な有効性で絞り込み、指定した時点で有効だった知識を取得します
knowledge_timeline	トピックに関する知識の時系列での変遷を表示します。項目がどのように作成され、置き換えられ、時間の経過とともに更新されたかを確認できます

ツールのグループ化モード（トークン効率）

すべての MCP クライアントは、最初のメッセージを送る前の initialize 時に、すべてのツールの完全な JSON スキーマを読み込みます。ツールが約 40 個ある場合、スキーマのペイロードだけで、毎回のセッションにおいてモデルのコンテキストウィンドウを数十 KB 消費することがあります。さらに、2 つのコストが重なります。ツール数が 20～40 個を超えると、LLM が適切なツールを選ぶ精度が目に見えて低下し、セッションを頻繁に再読み込みするたびにコスト全体を再び負担することになります。

MCP_TOOL_GROUPING=true を設定すると、中核となるツールセットを、必須の action 識別子で処理を振り分ける少数のグループ化されたメタツールにまとめられます。

// Grouped form                          // Equivalent legacy form
{ "name": "memory",                      { "name": "store_memory",
  "arguments": {                           "arguments": { "content": "…" } }
    "action": "store", "content": "…" } }

グループ：repo · memory · memory_admin · engineering · search · session に加え、単独の index_documents と project_bank_view。デフォルトのツール数は 41 個から 8 個に減り、スキーマのペイロードが約 42％小さくなります。

• オプトイン方式で、既存動作への影響はありません。 デフォルトは false です。このフラグが変更するのは、tools/list が返す内容だけです。
• どちらの呼び出し形式も常に使えます。 tools/call は、フラグの設定にかかわらず、グループ化形式（memory + action=store）と従来の名前（store_memory）の両方を受け付けるため、既存のスクリプトが壊れることはありません。
• 管理用ツールとスチュワード用ツールは個別のままです。 大量のエージェント実行では一覧に表示される頻度が低く、また steward_inbox_resolve はすでに独自の action 引数を使用しているため、意図的にグループ化していません。

トレードオフ：グループ化された呼び出しでは、呼び出しごとのスキーマ（各アクションの引数の集合）がやや大きくなります。検出コストが支配的な大量のエージェント実行ではグループ化を推奨します。一方、ツールを名前ごとに確認できるほうが分かりやすい対話的なデバッグでは、無効のままにしてください。関連するアーカイブ・スイープの項目については、ポリシーのリファレンス docs/concepts/lifecycle.md を参照してください。

設定

設定はすべて環境変数で行います。全項目については .env.example を参照してください。

設定ファイルは次の順序で読み込まれます（各ファイルは、すでに設定されていない値のみを補います）。

1. --config /path/to/file（明示的なパス。設定ファイルの読み込み順をスキップします。serve だけでなく、すべてのコマンドで使用できます）
2. 現在のディレクトリの .env
3. ~/.config/agent-memory-mcp/config.env（XDG）
4. $(brew --prefix)/etc/agent-memory-mcp/config.env（Homebrew）

ローカルの単独モードでは、.env.example をプロジェクトのルートに .env としてコピーしてください。brew services の場合、設定ファイルは $(brew --prefix)/etc/agent-memory-mcp/config.env に自動作成されます。

ホットリロード

サービスとして実行している場合（HTTP モード）、設定ファイルの変更は 30 秒ごとに監視されます。RAG 関連の設定（インデックスディレクトリ、埋め込みキー、有効／無効）は再起動せずに反映されます。HTTP 設定（ポート、ホスト）を反映するには、完全な再起動が必要です。

すぐに再読み込みを実行することもできます。

kill -HUP $(pgrep agent-memory-mcp)

主な変数

変数	デフォルト	説明
MCP_ROOT	Current dir	プロジェクトのルートパス
MCP_ALLOW_DIRS	"" (only MCP_ROOT)	ファイルツール（repo_list、repo_read、repo_search）が読み取り可能な、リポジトリ相対パスの追加分をカンマ区切りで指定します。パスはMCP_ROOTの配下にある必要があります。絶対パスや..による上位ディレクトリへの移動は、設定の読み込み時に拒否されます。共有／HTTP モードでは特に重要です — 範囲を狭く保ってください
MCP_MAX_FILE_BYTES	2097152	repo_readが返すファイルサイズの上限（バイト単位）。これを超えるファイルは拒否されます
MCP_MAX_SEARCH_RESULTS	200	repo_searchの検索結果数の絶対上限
MCP_MAX_DEPTH	3	repo_listのディレクトリ再帰の深さの上限
MCP_STDIO_MODE	line	標準入出力のフレーミング：line（改行区切り）またはlsp（Content-Length ヘッダー）
MCP_TOOL_GROUPING	false	tools/listでコアツールセットをグループ化されたメタツールにまとめ、検出時のスキーマペイロードを約42%削減します（41→8ツール）。tools/callでは、グループ化された名前（memory＋action）と従来の名前のどちらも引き続き受け付けます。詳しくはツールのグループ化モードを参照してください
MCP_MEMORY_ENABLED	true	メモリツールを有効にします
MCP_MEMORY_PREVIEW_RUNES	0	MCP ツールの応答（recall_memory、list_memories、search_runbooksなど）に含まれるメモリの内容／要約フィールドについて、サーフェスごとの切り詰め上限（ルーン単位）を上書きします。0の場合は組み込みの上限（150／220／300）が適用されます。正の値を指定すると、すべてのサーフェスに同じ上限が適用されます。負の値を指定すると切り詰めが無効になり、全文が返されます。
MCP_RAG_ENABLED	true	RAG／検索ツールを有効にします（Homebrew サービスのプリセットでは、MCP_ROOTを設定するまでfalseに上書きされます）
MCP_HTTP_MODE	stdio	トランスポート：stdioまたはhttp
MCP_HTTP_HOST	127.0.0.1	HTTP のバインドホスト。共有／コンテナ環境でのデプロイでは0.0.0.0を設定します
MCP_HTTP_PORT	18080	HTTP ポート（HTTP モードの場合）
MCP_HTTP_AUTH_TOKEN	-	ループバック以外／共有 HTTP モードで必要なベアラートークン
MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED	false	認証なしでループバック以外の HTTP を使用するための、明示的な安全性の低いオーバーライド
JINA_API_KEY	-	埋め込み用の Jina AI API キー
OPENAI_API_KEY	-	OpenAI API キー（または互換サービス：Together、Mistral）
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI 互換のベース URL
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	埋め込みモデル名
OLLAMA_BASE_URL	http://localhost:11434	Ollama の URL（ローカルのフォールバック）
LLAMACPP_BASE_URL	-	llama.cpp の OpenAI 互換ベース URL（例：http://127.0.0.1:8080/v1）。空の場合は無効になります
LLAMACPP_EMBEDDING_MODEL	bge-m3	llama.cpp の埋め込みモデルラベル（LLAMACPP_BASE_URLが設定されている場合のみ使用）。このラベルは各レコードに保存される派生モデル ID の一部です。そのため、変更するとモデルの変更時と同様にバンクが無効になります。詳しくはdocs/EMBEDDING_MIGRATION.mdを参照してください
MCP_EMBEDDING_MODE	auto	埋め込みモード：autoまたはlocal-only
MCP_EMBEDDING_DIMENSION	1024	ベクトルの次元数（変更するには再インデックスが必要です）
MCP_EMBEDDING_TIMEOUT	5s	リクエストごとの埋め込みタイムアウト。ローカルバックエンドの応答が遅い場合は延長してください
MCP_EMBEDDING_MAX_RETRIES	1	一時的な障害が発生した場合の埋め込み再試行回数
MCP_INDEX_DIRS	docs	RAG のインデックス対象となるディレクトリと個別ファイルをカンマ区切りで指定します。コード上のフォールバックはdocsです。配布される.env.exampleのプリセットでは、一般的なプロジェクト構成向けにdocs,README.md,CHANGELOG.mdが設定されています
MCP_RAG_AUTO_INDEX	true	起動時にドキュメントをインデックス化します。コード上のデフォルトはtrue（HTTP／サービスモードに適しています）。単独のローカル環境向け.env.exampleプリセットではオフになっており、agent-memory-mcp indexを明示的に実行してインデックス化を制御できます
MCP_RAG_FILE_WATCHER	false	MCP_INDEX_DIRSの変更を監視し、段階的に再インデックスします。長時間稼働する共有／サービスインスタンスに便利です
MCP_INDEX_EXCLUDE_DIRS	built-in defaults	RAG のインデックス対象から除外するディレクトリ名またはリポジトリ相対パスを追加で指定します
MCP_INDEX_EXCLUDE_GLOBS	-	リポジトリ相対パスに対して照合する glob パターンを追加で指定します。例：docs/internal/*.md
MCP_REDACT_SECRETS	true	ドキュメントをインデックス化する前に、一般的なシークレットらしき内容をマスキングします
MCP_ARCHIVE_SWEEP_ENABLED	true	ゼロオペレーションの統合：バックグラウンドループによって、アーカイブ済みタスクの作業メモリを古い情報としてマークするか、永続性のあるメモリに昇格します。手動実行は不要です。<MCP_ROOT>/tasks/archiveを自動検出し、存在しない場合は何もしません。詳しくはゼロオペレーションの統合を参照してください
MCP_ARCHIVE_SWEEP_INTERVAL	1h	バックグラウンドでアーカイブをスイープする間隔。0の場合はループが無効になります
MCP_SESSION_TRACKING_ENABLED	true	バックグラウンドのセッション追跡、自動生成される生の要約、リスクの低いセッション終了のオーケストレーションを有効にします
MCP_SESSION_IDLE_TIMEOUT	10m	アクティブなバックグラウンドセッションが自動終了するまでのアイドルタイムアウト
MCP_SESSION_CHECKPOINT_INTERVAL	30m	アクティブなセッション中に、生のチェックポイントスナップショットを定期的に取得する間隔
MCP_SESSION_MIN_EVENTS	2	バックグラウンドの自動終了が実行されるまでに必要な、追跡対象の MCP ツール呼び出しの最小数
MCP_DATA_PATH	data	データ保存用のベースパス
MCP_RAG_INDEX_PATH	<MCP_DATA_PATH>/rag-index	SQLite ベクトルインデックスの場所を上書きします
MCP_MEMORY_DB_PATH	<MCP_DATA_PATH>/memory-store/memories.db	SQLite メモリデータベースのパスを上書きします
MCP_LOG_PATH	<MCP_DATA_PATH>/logs/mcp-diagnostics.log	診断ログファイルのパスを上書きします
MCP_STATS_ENABLED	false	自己観測用に、呼び出しごとの使用状況レコード（jsonl）を追記します
MCP_STATS_PATH	<MCP_DATA_PATH>/logs/mcp-usage.jsonl	統計情報の jsonl 出力パス
MCP_STATS_SAMPLE_RATE	1.0	統計情報が有効な場合に記録する呼び出しの割合（0.0～1.0）
MCP_STEWARD_ENABLED	auto	ナレッジの管理を有効にします（メモリを使用する HTTP モードでは自動的に有効になります）
MCP_STEWARD_MODE	manual	管理モード：off、manual、scheduled、event_driven
MCP_STEWARD_SCHEDULE_INTERVAL	24h	スケジュールされた管理処理の実行間隔
MCP_STEWARD_DUPLICATE_THRESHOLD	0.85	重複検出の類似度しきい値
MCP_STEWARD_STALE_DAYS	30	メモリが古いと見なされるまでの日数
MCP_STEWARD_CANONICAL_MIN_CONFIDENCE	0.80	正規情報への昇格候補に必要な最小信頼度
MCP_CHECKPOINT_DEDUP_THRESHOLD	0.9	同じコンテキストにおいて、チェックポイントが前のものと重複していると見なされる類似度の Jaccard しきい値
MCP_CHECKPOINT_DEDUP_WINDOW	10m	重複検索の時間枠。この時間内に作成されたチェックポイントのみ比較されます
MCP_CHECKPOINT_DEDUP_MIN_CHARS	100	チェックポイントを保存対象とするために必要な内容の最小文字数。これより短い内容は空として破棄されます
MCP_CHECKPOINT_DEDUP_DISABLED	false	緊急時の回避策：チェックポイントフックの重複排除を完全に無効にします
MCP_TASK_ARCHIVE_ROOTS	-	sweep-archive／end-task用のアーカイブルートをコロン区切りで指定します（例：/home/you/tasks/archive）。空の場合は機能が無効になります
MCP_TASK_SLUG_PATTERN	-	アーカイブのサブディレクトリ名をフィルタリングする任意の正規表現。正規表現が無効な場合は設定の読み込みに失敗します
MCP_RERANK_ENABLED	false	ハイブリッド検索後のニューラル再ランキング段階を有効にする全体スイッチです。再ランキングを実行するにはtrueであり、かつMCP_RERANK_PROVIDERが実際のプロバイダー（jina）である必要があります
MCP_RERANK_PROVIDER	disabled	再ランキングプロバイダー：jinaまたはdisabled。disabled（または空）の場合、MCP_RERANK_ENABLED=trueでもパイプラインはハイブリッド検索のみのランキングにフォールバックします
JINA_RERANKER_MODEL	jina-reranker-v2-base-multilingual	Jina 再ランキングモデル ID
MCP_RERANK_TIMEOUT	5s	1回の再ランキング呼び出しに対するハードタイムアウト。タイムアウト時はハイブリッド検索の順序が維持され、デバッグシグナルにrerank_failed:timeoutが追加されます
MCP_RERANK_TOP_N	40	再ランキングに送信する、ハイブリッド検索上位候補の数。呼び出し時に100が上限として適用されます
MCP_RETRIEVAL_STRICT	false	読み取りパスでのサイレントなフォールバックを、呼び出し失敗にします。埋め込みプロバイダーが次のプロバイダーにフォールバックする場合、再ランキングがタイムアウトする場合、グラフがなくマルチホップクエリをたどれない場合が該当します。測定実行（make evalでは有効になります）と、設定が不完全なインストールの診断を目的としています — 本番環境ではオフのままにしてください。答えがないより、品質の低い答えのほうが望ましいためです。このフラグの設定にかかわらず、すべてのsemantic_search応答には、実際に応答を提供したパスを示すretrievalブロックが含まれます
MCP_SEDIMENT_ENABLED	false	レイヤーを考慮した検索スコアリングを有効にします（character は常に表示され、surface はコンテキスト外では除外されます）。スキーマのマイグレーションとバックフィルは常に実行され、検索の重み付けのみがこの設定によって制御されます。docs/SEDIMENTATION.mdを参照してください
MCP_RECALL_CENTERED	true	生のコサイン類似度ではなく、平均中心化した埋め込みを使ってメモリの再呼び出しスコアを計算します。測定で改善が確認されたため採用されました（T76a）：実際のバンクに対する機械ラベル付きクエリ345件では、Hit@5が0.6232から0.7217に、MRRが0.4922から0.5739に向上しました。実際のコーパスでの生のコサイン類似度には異方性があります — 無関係なペアの中央値は0.555で、minScoreは候補の100%を通過させ、何も絞り込めませんでした。平均中心化した場合、同じサンプルで通過したのは34.1%です。埋め込みが100件未満のバンクでは、この設定を無視して生のコサイン類似度を使います。少数のベクトルの平均は、相殺すべきベクトル自体に大きく左右されるためです。falseにすると、以前のリリースと同じ方法でスコアを計算します
MCP_RECALL_HALFLIFE_DAYS	0	T68の再呼び出しスコアに対する指数関数的な経過時間減衰（半減期の日数。これだけ古いカードの重みは半分になります）。0の場合は減衰が無効になります — T121での測定以降のデフォルトです。機械ラベル付きクエリ345件では、減衰なしのHit@5は0.7217で、以前の30日デフォルトでは0.1942でした。間の値も単調に変化し（365日で0.6087、180日で0.4609、90日で0.2870）、減衰による利点があった年代の区分はありませんでした。事実の現在のバージョンを優先する処理は、すでに意味的な置き換えとライフサイクルの状態によって行われています。カレンダーに基づく乗数では、「以前に書かれた」と「もはや正しくない」を区別できません。普遍的に有効なエントリ（正規ナレッジ、character レイヤー）は減衰しません
MCP_RECALL_DECAY_TYPES	working	減衰が有効な場合に、どのメモリタイプを経年劣化の対象にするかを指定します。減衰率を左右するのはタイプの軸です。同じ30日の半減期では、すべてのタイプを減衰させた場合のHit@5は0.1942でしたが、workingだけを減衰させた場合は0.7043でした。以前の動作では、パターンや事実が経年劣化の対象になっていましたが、これらはバンクが蓄積するために存在するナレッジです。空の場合は、すべてのタイプが減衰します
MCP_RAG_KEEP_NOISE	false	T49の緊急時の回避策：ノイズの多い Markdown セクション（目次／参考文献／変更履歴など）を、チャンク化時に削除せずインデックスに残します
MCP_RAG_MAX_CHUNKS_PER_DOC	1	1つのドキュメントから検索結果リストに含められるチャンク数。ファイル内の隣接チャンクはほぼ同じスコアになるため、上限なしの上位5件では、250件の質問に対する異なるドキュメント数が2.07件にとどまり、リストの半分以上が、すでに表示されたファイルの追加チャンクに使われていました。1ドキュメントあたり1チャンクにすると5.00件になり、ドキュメント単位のR@5は0.5104から0.8676に、nDCG@5は0.6184から0.8927に向上しました。一方、最初のヒットに関する指標は維持されました（Hit@5は0.9600から0.9640、MRRは0.9580から0.9590）。250件中207件のクエリが改善し、悪化したものはありませんでした（T127）。この上限は優先設定であり、割り当て数ではありません。存在するドキュメント数が指定された上限より少ない場合は、リストが不足する代わりに、除外されたチャンクが追加されます。0にすると上限なしの順序に戻り、2は中間の設定です（ドキュメント数3.11件、R@5は0.7648）
MCP_TRIPLE_EXTRACTOR_ENABLED	false	T50のナレッジグラフレイヤー。有効にすると、メモリへの書き込みごとに非同期の LLM 呼び出しを行い、recall_multihopを支える3～7個の（主語、関係、目的語）トリプルを抽出します
MCP_TRIPLE_EXTRACTOR_BASE_URL	-	OpenAI 互換の/chat/completionsエンドポイント（DeepSeek、Together、Groq、Qwenなど）。空の場合はOPENAI_BASE_URLにフォールバックします
MCP_TRIPLE_EXTRACTOR_API_KEY	-	抽出器のベアラートークン。MCP_TRIPLE_EXTRACTOR_BASE_URLが空かOPENAI_BASE_URLと等しい場合のみ、OPENAI_API_KEYにフォールバックします。抽出器の接続先に独自のキーを指定せず、サードパーティのエンドポイントを指定した場合は、明示的なメッセージを表示して抽出を無効にします。OpenAI のキーが、発行先ではないアドレスに送信されることはありません
MCP_TRIPLE_EXTRACTOR_MODEL	-	抽出器に渡すモデル ID（例：deepseek-chat、qwen2.5-72b-instruct）
MCP_TRIPLE_EXTRACTOR_TIMEOUT	30s	抽出器への HTTP 呼び出しごとのタイムアウト

データパス

サーバーは MCP_DATA_PATH の下に次のディレクトリを作成します。

• rag-index/ -- ドキュメント検索用の SQLite ベクトルインデックス
• memory-store/ -- エージェントのメモリ用 SQLite データベース

推奨される単独ローカル向けプリセットでは、これらを .agent-memory/ の下に保存します。

インデックス作成の安全対策

RAG のインデックス作成では、対応するドキュメントとエンジニアリング関連のテキストファイルをスキャンしますが、明示的な設定でさらにリスクを軽減できます。

• .git、.agent-memory、node_modules、logs、.terraform など、組み込みで除外されるディレクトリ
• MCP_INDEX_EXCLUDE_DIRS で、docs/private,runbooks/internal のようにリポジトリ相対パスを除外
• MCP_INDEX_EXCLUDE_GLOBS で、docs/internal/*.md のようにグロブ形式で除外
• MCP_REDACT_SECRETS=true で、インデックス作成前に一般的なシークレットに似た行や秘密鍵ブロックを秘匿

ホスト型の埋め込みプロバイダーや共有 HTTP モードを使用する場合は、特に重要です。

セッションの自動追跡

MCP サーバーがデフォルトのセッション追跡ポリシーで実行されている場合、軽量なバックグラウンドセッションバッファーを保持します。

現在の動作：

• 成功した MCP ツール呼び出しは、アクティブなセッションに自動的にまとめられます
• アイドルタイムアウトまたはサーバーのシャットダウンを契機に、バックグラウンドで close_session が実行されます
• クライアントは notifications/session_event と event=task_done|final_summary|checkpoint|reset を使って、アクティブなセッションを明示的にフラッシュまたはチェックポイントできます
• 生のセッション概要は自動的に永続化されます
• 既存の safe_auto_apply ポリシーに基づき、リスクの低い更新は自動適用できます
• リスクが高い変更や曖昧な変更は、管理対象のナレッジを黙って書き換えるのではなく、レビュー受信箱の項目として保存されます
• 長時間のセッション中にクラッシュから復旧するための手掛かりとして、定期的に生のチェックポイントが作成されます

受信箱を確認するには、project_bank_view view=review_queue または agent-memory-mcp project-bank -view review_queue を使用します。 手動レビュー後に項目を閉じるには、resolve_review_item または agent-memory-mcp resolve-review-item <id> を使用します。

通知ペイロードの例：

{
  "jsonrpc": "2.0",
  "method": "notifications/session_event",
  "params": {
    "event": "task_done",
    "summary": "Incident stabilized, workaround verified, follow-up is to replace the temporary fix.",
    "context": "payments",
    "service": "api",
    "mode": "incident",
    "tags": ["done", "verification"]
  }
}

この動作を調整または無効化するには、MCP_SESSION_TRACKING_ENABLED、MCP_SESSION_IDLE_TIMEOUT、MCP_SESSION_CHECKPOINT_INTERVAL、MCP_SESSION_MIN_EVENTS を使用します。

インデックスの整合性と復旧

ドキュメントのインデックス作成では、チャンクの更新と追跡メタデータを単一の論理状態として扱うようになりました。

• 各実行では、チャンクを変更する前にインデックスの状態を dirty に設定します
• 最終コミットが成功すると、indexed_files、embedding_model、last_indexed とともに状態が ready に戻ります
• 実行が中断された場合、または追跡状態の最終コミットに失敗した場合、次回の index_documents / agent-memory-mcp index 実行時に dirty 状態が検出され、再構築が強制されます

これにより、クラッシュ、プロバイダーの中断、ストレージエラー後の増分インデックス作成がより予測しやすくなります。

ソースを考慮した取り込み

インデクサーはエンジニアリング関連のソースを分類し、そのメタデータを検索にも引き継ぐようになりました。

対応するソースタイプ：

• docs：README.md および一般的な Markdown ドキュメント
• adr および rfc：アーキテクチャ決定文書および RFC 形式のドキュメント
• changelog：CHANGELOG.md およびリリースノート形式のドキュメント
• runbook および postmortem：運用ナレッジ
• ci_config：GitHub Actions、GitLab CI、Jenkins のパイプラインファイル
• helm、terraform、k8s：ソースを考慮したインフラファイル

特定のクラスのナレッジに検索対象を絞りたい場合は、source_type を使用します。

agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type adr "cache invalidation decision"

MCP の semantic_search ツールでは、source_type と debug も指定できます。

ハイブリッド検索

検索では、コサイン類似度だけでなく、複数のランキングシグナルを使用するようになりました。

現在のランキングシグナル：

• アクティブな埋め込みモデルによる意味的類似性
• チャンクのタイトル、パス、コンテンツを対象としたキーワード／BM25風のスコアリング
• 検索対象を絞りたい場合のsource_typeフィルタリング
• 最近更新された運用コンテキストに対する新しさのブースト
• ソースを考慮した重み付け。クエリの意図に合致する場合、ランブック、変更履歴、ADRなどのソースクラスが上位に表示されます

検索パイプラインは、次の2段階で動作するようになりました。

• ベクトルインデックスから意味的な上位K件の候補を生成
• 事前計算されたインメモリキーワードインデックスからキーワードの上位K件の候補を生成

再ランキングの対象は、統合された候補セットのみです。これにより、インデックス化されたコーパスが増えても、共有サービスでの検索結果の予測可能性が保たれます。

つまり、ランブックや変更履歴でキーワードが強く一致する結果は、意味的には似ていてもタスクとの関連性が低いドキュメントより上位に表示されることがあります。

信頼度を考慮した検索

検索結果には、保存されたメモリとインデックス化されたドキュメントの両方について、明示的な信頼度メタデータが含まれるようになりました。

各結果には、次の情報を表示できます。

• source_type
• confidence
• last_verified_at
• owner
• freshness_score

実際の動作は次のとおりです。

• テキスト上の一致度が同程度の場合、採用済みの決定事項や検証済みのランブックは、ドラフトや信頼度の低いメモより上位に表示されます
• 完全な標準化レイヤーを追加する前でも、ADR、ランブック、事後分析、変更履歴には、それぞれ異なる信頼度の重みを設定できます
• CLIのsearch／recallと、MCPのsemantic_search／recall_memoryでは、人が読みやすい形式で信頼度の概要を表示するようになりました

エンジニアリングワークフローツールでは、保存されたエントリーにlast_verified_atも付与されるため、最新の運用知識をより信頼しやすく、上位に表示しやすくなります。

説明可能な検索

ドキュメントが返された理由を検索結果に説明させたい場合は、デバッグモードを使用します。

CLI：

agent-memory-mcp search -source-type runbook -debug "ingress rollback"

MCP：

• debug: trueを指定してsemantic_searchを呼び出します
• 通常の簡潔なレスポンスにするには、debugを指定しないか、falseに設定します

デバッグモードでは、次の情報が追加されます。

• source_type=runbookなど、適用されたフィルター
• レスポンスに使用されたランキングシグナル
• 候補数：インデックス済み、フィルターで除外、ノイズとして破棄、返却
• 結果ごとの信頼度の概要：source、confidence、freshness、owner、verified
• 結果ごとのスコア内訳：semantic、keyword_raw、keyword_normalized、recency_boost、source_boost、confidence_boost、final_score
• 結果ごとに適用されたブースト（例：keyword_matchやsource_type:runbook）

検索コンソール

生のCLIやJSON-RPC呼び出しよりも素早く確認できるワークフローを利用したい場合は、HTTPモードで組み込みコンソールを使用します。

/console

主な用途：

• 通常の検索とデバッグ検索を並べて比較する
• ドキュメント検索、生のメモリ検索、標準化されたナレッジの検索を1か所で確認する
• ソースタイプ、信頼レイヤー、信頼度、新しさ、所有者、検証時刻を確認する
• UIに表示されているものと同じ構造化レスポンスの生のJSONを開く

このコンソールは意図的に軽量に設計されており、MCPツールやCLIワークフローを置き換えるものではありません。

エンジニアリングワークフローツール

これらの MCP ツールは、ドメイン固有のワークフローを既存のメモリおよび検索バックエンドに対応付けます。

おすすめの使い始め方：

• HPA の無効化や Ingress のバージョン固定など、アーキテクチャまたは運用上の選択には store_decision
• デバッグ中に参照したい、一時的な運用上の情報には store_incident
• 手順、ロールバックの指示、検証メモには store_runbook
• 長期的に活用できるインシデントの教訓やアクション項目には store_postmortem
• 根拠、トレース、レビューに適したアクションを含む明示的なセッション終了プランを作成する場合は close_session
• セッション終了レポートのリスクが低く、要約の生データを保存して安全な更新を適用する場合は accept_session_changes
• バックグラウンドの受信トレイにレビュー済みの項目がすでにあり、監査証跡を削除せずにクリアする場合は resolve_review_item
• 修正方法が必要で、メモリに保存されたランブックとインデックス化されたランブックドキュメントの両方を参照したい場合は search_runbooks
• 障害やリグレッションのトリアージ中には recall_similar_incidents
• セッション開始時に簡潔な運用ブリーフィングを取得するには summarize_project_context
• 生の想起結果ではなく、ビュー別に整理されたナレッジを参照する場合は project_bank_view。保留中のバックグラウンド判断には review_queue を使用します

これらのワークフローツールは検証メタデータも追加します。これにより、検索時に新しく保存された運用ナレッジを、出所不明の生メモより新しく信頼性の高い情報として扱えます。

メモリの統合

メモリレイヤーでは、過去のメモを削除せずに手動で統合できるワークフローがサポートされるようになりました。

同じプロジェクトのナレッジに揺らぎが生じ始めたときは、次の MCP ツールを使用してください。

• merge_duplicates：繰り返されているメモを1つの主要メモに統合し、残りは統合済み重複としてアーカイブします
• mark_outdated：古くなったランブック、置き換えられた判断、または不要になったインシデントメモを、失わずに降格します
• promote_to_canonical：現在の最適なメモを正規ナレッジとしてマークします
• conflicts_report：duplicate_candidates、status_conflict、multiple_canonical のグループを明らかにします

現在の動作：

• 統合済みまたはアーカイブ済みのメモには引き続きアクセスできますが、信頼度を考慮した想起では優先順位が下がります
• 正規メモは信頼度が引き上げられ、重要度の最低値も高くなります
• 古くなったメモや置き換えられたメモは、自動的にアーカイブされ、優先順位が下がります
• 競合のレポート作成は手動で安全です。明示的に削除を選ばない限り、何も削除されません

ゼロ運用のタスクメモリ統合

終了したタスクごとに作業メモ（Task started、フェーズごとのメモ、 Session close、自動抽出されたレビュー項目）が残ります。放置すると 直線的に増え、すでに完了したタスクのメモも想起で繰り返し表示されます。 このサービスは、cron も手動クリーンアップも設定も不要で、これらを自動的に統合します。

• バックグラウンドループ（デフォルトで有効、MCP_ARCHIVE_SWEEP_INTERVAL、デフォルトは 1h）が アーカイブ済みタスクを走査します。永続的なエントリ（手順を含むもの、または重要度 ≥ 0.70）は 昇格され、それ以外は outdated としてマークされます。起動後すぐに初回走査を実行し、 ループが導入される前に蓄積されたアーカイブもバックフィルします。
• 設定不要。 MCP_TASK_ARCHIVE_ROOTS が未設定の場合は <MCP_ROOT>/tasks/archive の慣例に従って監視します。ディレクトリが存在しない場合は何もせず、 エラーも出力しません。
• 設計上、安全です。 昇格時には出所チェックを通ります。会話由来のメモリは レビューキューに送られ、自動的に正規化されることはありません（メモリポイズニング対策を参照）。
• end_task と sweep_archive の各ツールは、デフォルトで同じ統合動作を行うため、 /end-task を明示的に実行するとすぐに統合されます。

ポリシーの詳細（状態の導出、昇格のしきい値、冪等性、 シンボリックリンク／パストラバーサルのガード）：docs/concepts/lifecycle.md。 MCP_ARCHIVE_SWEEP_ENABLED=false を指定するとループが無効になります。

正規ナレッジレイヤー

このプロジェクトでは、次の2つのレイヤーが公開されるようになりました。

• raw memory：保存された状態のままのメモ、インシデント、決定事項、手順に関する記憶
• canonical knowledge：promote_to_canonical で昇格された記憶から投影される、確認済みのエントリー

変更点：

• list_canonical_knowledge を使うと、未加工のノイズを除いた、現在の確認済みナレッジセットを取得できます
• recall_canonical_knowledge は正規エントリーのみを検索します
• summarize_project_context は、正規エントリーが存在する場合、未加工の記憶セクションより先に正規ナレッジを表示します
• 信頼性の概要に layer=raw、layer=canonical、layer=document が表示されるようになりました

移行について：

• 既存の記憶にスキーマ移行は必要ありません
• 重要度の高い既存の記憶は promote_to_canonical で昇格できます
• decision や service:api などのタグしか持たない従来のワークフローの記憶も、引き続き正規レイヤーで認識されます

ナレッジの管理

管理レイヤーでは、ナレッジの自動メンテナンスと手動メンテナンスを行えます。

steward_run を実行すると、1回の呼び出しでメンテナンスサイクル全体が実行されます。

• 重複候補（エンティティ、サービス、コンテキスト、サブジェクトが一致する記憶）をスキャンします
• 競合するエントリー（正規エントリーの重複、ステータスの不一致）を検出します
• 古くなったエントリー（設定されたしきい値の期間内に検証されていないもの）にフラグを付けます
• 正規への昇格候補（重要度が高く、有効で、認識済みのエンジニアリング種別）を提案します
• アクションごとの理由を含む、構造化されたレポートを生成します
• dry_run=false の場合、安全なアクションを適用し、それ以外を管理用インボックスに送ります

drift_scan は、記憶のエントリーとリポジトリ内の現行ファイルを比較します。

• 参照先のファイルが記憶の最終検証後に変更されている場合、source_changed を検出します
• 参照先のファイルパスが存在しなくなっている場合、source_missing を検出します
• エントリーが古さのしきい値を超えている場合、stale_unverified のフラグを付けます

verification_candidates は、検証が必要な記憶を優先度順に並べます。

• 一度も検証されていない正規エントリー：緊急度が高い
• verification_failed または needs_update のステータスを持つエントリー：緊急度が高い
• しきい値を超えて古くなったエントリー：緊急度が中程度

steward_inbox は、レビューが必要なすべてのアクションを一元管理する場所です。merge、mark_outdated、promote、verify、suppress、defer などのアクションを指定して、steward_inbox_resolve で項目を処理します。

メモリが利用可能な場合、HTTP モードでは管理機能が自動的に有効になります。しきい値とモードは MCP_STEWARD_* 環境変数で設定します。実行時の設定については steward_policy を参照してください。

詳しいガイドは、管理ガイドを参照してください。

時間的ナレッジ

記憶には、ナレッジが有効だった期間や、その変化を追跡する時間的メタデータを持たせることができます。

• valid_from / valid_until — このナレッジが有効だった期間
• superseded_by / replaces — 新旧関係の連鎖を形成する双方向リンク
• observed_at — ナレッジが最初に観測された時刻（created_at と異なる場合があります）

recall_as_of は、指定されたタイムスタンプの時点で有効だったナレッジを取得します。「1月時点でのデータベース戦略は何でしたか？」や「この2つの日付の間に何が変わりましたか？」といった質問に役立ちます。

knowledge_timeline は、クエリに一致するエントリーの変遷を時系列で表示し、valid_from の順に並べます。

後継エントリーを指定して mark_outdated を呼び出すと、システムが古いエントリーに valid_until を、新しいエントリーに valid_from と replaces を自動的に設定し、たどることのできる連鎖を構築します。

セキュリティと運用

デプロイの基本ガイド：

• 個人でローカル利用する場合：MCP_HTTP_MODE=stdio を維持します。データを外部に送信しないことが要件であれば、MCP_EMBEDDING_MODE=local-only を推奨します
• HTTP モードを共有する場合：MCP_HTTP_HOST=0.0.0.0 を設定し、MCP_HTTP_AUTH_TOKEN を設定します。TLS はリバースプロキシで処理し、MCP_ALLOW_DIRS の範囲は必要最小限にします
• インデックス作成：MCP_INDEX_EXCLUDE_DIRS / MCP_INDEX_EXCLUDE_GLOBS を使って、非公開の運用手順書や認証情報のドキュメントを除外します
• バックアップ：.agent-memory/ をコピーするか、agent-memory-mcp export を使ってメモリのみをバックアップします

参考ドキュメント：

• 管理ガイド
• セキュリティポリシー
• 脅威モデル
• バックアップと復元
• 共有サービスガイド

アーキテクチャ

┌──────────────────────────────────────────────────┐
│              MCP Protocol Layer                   │
│            (stdio or HTTP/JSON-RPC)               │
├────────────┬──────────┬───────────┬───────────────┤
│Memory Tools│RAG Tools │File Tools │Steward Tools  │
├────────────┼──────────┼───────────┼───────────────┤
│MemoryStore │RAGEngine │ PathGuard │ Steward       │
│  (SQLite)  │          │           │  Service      │
│            │┌────────┐│           │  Scheduler    │
│ Embedder◄──┤│DocSvc  ││           │  Inbox        │
│            ││VecSvc  ││           │  Drift/Verify │
│            │└────────┘│           │  Policy       │
│            │ (SQLite)  │           │  (SQLite)     │
└────────────┴──────────┴───────────┴───────────────┘

埋め込みプロバイダー

サーバーは auto モードで、次の3つの埋め込みプロバイダーをサポートします。

1. Jina AI（プライマリ） -- jina-embeddings-v3、ネイティブの次元数は1024、多言語対応
2. OpenAI（フォールバック） -- text-embedding-3-small またはOpenAI互換API。ネイティブの次元数は1536です。スタック内の他のモデルと一致させるため、サーバーはOpenAI MRLパラメーターで dimensions=1024 をリクエストします
3. Ollama（ローカルフォールバック） -- bge-m3、ネイティブの次元数は1024で、ローカルで無料で実行できます

3つのプロバイダーはすべて同じベクトル次元数（MCP_EMBEDDING_DIMENSION、デフォルトは 1024）に正規化されますが、互換性があるわけではありません。各モデルには独自の埋め込み空間があります。次元数が一致していても、異なるモデル間でコサイン類似度を安全に使用できるわけではありません。そのため、サーバーはすべてのメモリに embedding_model のタグを付け、再呼び出し時に異なるモデルの混在を拒否します。

auto モードの実際の動作：

• 新しいメモリや新しいRAGチャンクでは、その時点で利用可能な最初のプロバイダーを使用します
• 既存のメモリには、作成時の embedding_model が維持されます
• セマンティック再呼び出しでは、embedding_model が現在のクエリモデルと一致しないメモリをスキップし、それらのレコードにはテキストマッチングを使用します
• RAG検索では、異なるモデルで構築されたインデックスへのクエリを拒否し、再構築を求めます

これにより、プロバイダーのフォールバックによって、自信に満ちているように見えても誤ったセマンティックマッチが返される危険な状況を防ぎます。

プロバイダーやモデルを意図的に変更する場合は、移行として扱ってください。

# rebuild document index for the new embedding model
agent-memory-mcp index

# re-embed stored memories for the new embedding model
agent-memory-mcp reembed

# inspect how many memories still belong to older models
agent-memory-mcp stats -json

MCP_EMBEDDING_DIMENSION で次元数を増やして精度を高めることもできます（たとえば、text-embedding-3-large で 3072）。ただし、次元数またはモデルを変更する場合は、インデックスの再作成と再埋め込みが必要です。

MCP_EMBEDDING_MODE=local-only を設定すると、ホスト型プロバイダーは完全にスキップされ、埋め込みにはOllamaのみが使用されます。

ユーザーにとっての利点

• セマンティック再呼び出しが気付かないうちに破損する心配なく、auto モードを使い続けられます
• 保存済みの知識を失うことなく、別の埋め込みモデルに意図的に移行できます
• agent-memory-mcp stats でモデルの使用状況を監査できます
• ホスト型プロバイダーへのフォールバックを心配せずに、ローカルのみでの運用を優先できます

macOS サービスのインストール

Homebrew（推奨）

brew install ipiton/tap/agent-memory-mcp
brew services start agent-memory-mcp

詳細と設定ファイルの場所については、インストール方法を参照してください。

手動（レガシー）

./scripts/install-macos.sh

これにより、バイナリをビルドし、.env ファイルを作成して、ログイン時に自動起動するlaunchdサービスをインストールします。

手動での制御：

# Status
launchctl list | grep com.agent-memory-mcp

# Start
launchctl load ~/Library/LaunchAgents/com.agent-memory-mcp.plist

# Stop
launchctl unload ~/Library/LaunchAgents/com.agent-memory-mcp.plist

トラブルシューティング / FAQ

「no embedding provider available」または「embedder not configured」

サーバーは auto モードでJina → OpenAI → Ollamaの順に試し、最初に利用可能なプロバイダーを使用します。どのプロバイダーにも接続できない場合、埋め込み（したがってセマンティック再呼び出し）は無効になります。

• JINA_API_KEY または OPENAI_API_KEY のいずれかを設定するか、bge-m3 を取得してOllamaを実行します（ollama pull bge-m3）
• MCP_EMBEDDING_MODE=local-only ではOllamaのみが参照されます。OLLAMA_BASE_URL（デフォルトは http://localhost:11434）が応答することを確認してください

CLIで agent-memory-mcp store … を実行する際、埋め込みプロバイダーがなくてもメモリは保存されますが、ベクトルはスキップされます。agent-memory-mcp reembed を実行するまでは、テキスト／キーワード検索でのみそのレコードを取得できます。

「embedding model mismatch — index built with X, current is Y」

RAG インデックスと保存されたメモリには、それらの生成に使用された埋め込みモデルが記録されています。プロバイダーまたはモデルを切り替えると、検索時に異なるベクトル空間が混在しないように処理を拒否します。

agent-memory-mcp index            # rebuild RAG index for the new model
agent-memory-mcp reembed          # re-embed stored memories
agent-memory-mcp stats -json      # check how many memories still belong to older models

「address already in use」— ポート 18080 は使用中です

別の agent-memory-mcp（または無関係なサービス）がポートを使用しています。

lsof -nP -iTCP:18080 -sTCP:LISTEN
brew services list | grep agent-memory-mcp

2 つのインスタンスを起動している場合は、一方を停止する（brew services stop agent-memory-mcp または kill <pid>）か、MCP_HTTP_PORT を変更してください。

brew services start agent-memory-mcp でデーモンが起動しない

よくある原因は次のとおりです。

• 数式が以前 Cask としてインストールされている場合は、先にアンインストールしてください：brew uninstall --cask agent-memory-mcp && brew install ipiton/tap/agent-memory-mcp
• 設定ファイルの形式が正しくありません：cat $(brew --prefix)/etc/agent-memory-mcp/config.env
• ログ：tail -f $(brew --prefix)/var/log/agent-memory-mcp/mcp-diagnostics.log

Claude Code でフックが実行されない

agent-memory-mcp setup の実行後、Claude Code を再起動してください（フックはプロセスの起動時に読み込まれます）。マージ結果を確認してください。

agent-memory-mcp setup --dry-run     # show what would be written
jq '.hooks' ~/.claude/settings.json  # inspect actual config

brew upgrade でアップグレードした場合は、フックコマンドが新しいバイナリパスを参照するように、agent-memory-mcp setup --force を再実行してください。docs/HOOKS.md を参照してください。

「bind to 0.0.0.0 without auth is not allowed」

HTTP モードでは、MCP_HTTP_AUTH_TOKEN が設定されていない場合、サーバーはループバック以外へのバインドを拒否します。次のいずれかを選択してください。

• ベアラートークンを設定します（MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32)）— 推奨
• または、厳重に管理された環境でのみ、MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true を設定します

メモリデータベースが増え続ける

• agent-memory-mcp project-bank canonical_overview と … review_queue を実行し、昇格または古い情報としてマークする必要がある、生のセッション要約を確認します
• スチュワードシップを有効にします：MCP_STEWARD_MODE=scheduled により、定期的な重複排除／古い情報のスキャンが実行されます
• 重複排除ウィンドウを使ってセッションのチェックポイントを整理します（MCP_CHECKPOINT_DEDUP_THRESHOLD、MCP_CHECKPOINT_DEDUP_WINDOW）
• まずバックアップを作成します：agent-memory-mcp export > backup.json（docs/BACKUP_RESTORE.md を参照）

recall_multihop が空の結果を返す

マルチホップグラフは (subj, rel, obj) のトリプルコーパスをたどります。次のいずれかを行うまでは、コーパスは空です。

• MCP_TRIPLE_EXTRACTOR_ENABLED=true を有効にして新しいメモリを書き込みます（抽出は保存のたびに非同期で実行されます）
• agent-memory-mcp index-triples で既存のメモリをバックフィルします（冪等で、--resume をサポートします）

どちらの方法にも MCP_TRIPLE_EXTRACTOR_* が必要です（主要な変数を参照）。抽出では、OpenAI 互換の /chat/completions エンドポイントが呼び出されます。

HTTP／サービスモードで「設定が再読み込みされない」

変更は約 30 秒以内に反映されます。すぐに再読み込みするには、次のコマンドを実行してください。

kill -HUP $(pgrep agent-memory-mcp)

注：HTTP のホスト／ポートを変更するには、完全な再起動が必要です（brew services restart agent-memory-mcp）。ホットリロードされるのは RAG 関連の設定のみです。

開発

# Build
make build

# Run
make run

# Test
make test

# Full quality gate (lint + tests + smoke)
make quality-gates

リポジトリの構成、コードスタイル、PR の規約については、docs/CONTRIBUTING.md を参照してください。

ライセンス

MIT