AI Agent Memory MCP Server

AI Memory MCP Server

MCP サーバーとして提供される、エージェントに依存しない永続メモリです。ローカルファーストで、メモリはプロジェクトとともに .aamm/ に保存され、Claude Code / Qoder / Cursor 間で共有されます。

中文 | 日本語

MCP サーバーとして公開される、エージェントに依存しない永続メモリレイヤーです。Claude Code、Qoder、Cursor など、あらゆる MCP クライアントで再利用できます。メモリは各プロジェクトの .aamm/ ディレクトリに保存され、プロジェクトとともに移動します。同じプロジェクトで作業する異なるエージェントは、1 つのメモリストアを共有し、書き込み元は source_agent の記録で識別されます。

アーキテクチャ

• SQLite — 構造化データの信頼できる情報源（CRUD + FTS5 キーワード検索）
• Chroma（組み込み） — ベクトル検索。.aamm/chroma/ に永続化されます
• 埋め込み — あらゆる OpenAI 互換サービス（Volcengine / SiliconFlow / OpenAI / その他）を利用できます。デフォルトは Volcengine の doubao-embedding-vision です
• Markdown ミラー — 各メモリは .aamm/memories/<category>/<id>.md にも書き込まれ、人が読んだり編集したりできます

3 つのレイヤーは id で結合されています。

メモリのカテゴリ

category	用途
user	ユーザー設定（技術的な背景 / 開発習慣 / 回答スタイル）
project	プロジェクトに関する知識（アーキテクチャ / 技術スタック / 構成 / 設計上の決定）
process	作業プロセス（解決した問題 / バグ / デバッグ / 教訓）
agent	エージェント間の連携（実施内容 / 引き継ぎメモ）

インストール

PyPI から：

pip install ai-agent-memory-mcp

ソースから：

cd ai_agent_memory_mcp
pip install .          # or: pip install -e .   (editable, for development)

Python 3.11 以降が必要です。

埋め込みの設定（あらゆる OpenAI 互換サービスに対応）

埋め込みレイヤーは汎用の OpenAI 互換クライアントです。Volcengine / SiliconFlow / OpenAI をはじめ、あらゆる互換サービスを利用できます。初回実行時に .aamm/config.yml にデフォルト設定が生成されます。必要に応じて編集してください。

フィールド（.aamm/config.yml の embedding セクション）

フィールド	意味
provider	ラベル（情報表示のみ）
model	埋め込みモデル名
base_url	OpenAI 互換エンドポイント
api_key_env	キーを保持する環境変数
dim	ベクトルの次元数（モデルと一致する必要があります）

キーをプロジェクトのルートにある .env に設定し、config.yml の embedding セクションを編集してください。

例

Volcengine doubao-embedding-vision（デフォルト。Agent/Coding Plan のキーでは Plan エンドポイント /api/plan/v3 を使用する必要があります。標準の /api/v3 では 401 が返されます）

embedding:
  provider: volcengine
  model: doubao-embedding-vision
  base_url: https://ark.cn-beijing.volces.com/api/plan/v3
  api_key_env: VOLCENGINE_API_KEY
  dim: 2048

.env：VOLCENGINE_API_KEY=...

SiliconFlow bge-large-zh（中国語テキスト向けに最適化）

embedding:
  provider: siliconflow
  model: BAAI/bge-large-zh-v1.5
  base_url: https://api.siliconflow.cn/v1
  api_key_env: SILICONFLOW_API_KEY
  dim: 1024

.env：SILICONFLOW_API_KEY=...

OpenAI

embedding:
  provider: openai
  model: text-embedding-3-small
  base_url: https://api.openai.com/v1
  api_key_env: OPENAI_API_KEY
  dim: 1536

.env：OPENAI_API_KEY=...

その他の OpenAI 互換サービス：base_url / model / api_key_env / dim を設定するだけです。

埋め込みモデルを切り替えた後は、古いベクトルと次元が一致しない場合があります。.aamm/chroma/ を削除して再度 remember を実行するか、python tests/rebuild_vectors.py を実行してください。

検索

recall では、ヒット率を最大化するために 3 種類の検索結果を融合します。

• ベクトル（重み 0.6）：Chroma のコサイン類似度。埋め込みは title + tags + content から計算されるため、タイトルとタグの情報もベクトルに反映されます
• キーワード（重み 0.25）：SQLite FTS5 のトライグラム検索
• タイトル / タグ一致（重み 0.15）：クエリがタイトルに含まれる場合は +0.15、タグに含まれる場合は +0.075

候補は top_k*3 件まで拡張してから、top_k 件に絞り込まれます。クエリに FTS5 の特殊文字（., *, ", -, ...）が含まれている場合、エラーを避けるため、キーワード検索では LIKE による部分文字列検索にフォールバックします。

作業ジャーナル

検索可能な記憶に加えて、aamm は人が読める作業ジャーナルを保持します。ユーザーのリクエストを完了した後、エージェントは journal_entry() を呼び出して、依頼された内容／実行した内容／未解決の質問を記録します。ジャーナルはタイムラインを読む人のためのもので、recall では検索されません。「過去のやり取りで何があったか」を復元する必要がある場合に限り、フォールバックとして search_journal() を使用してください。

ジャーナルは .aamm/logs/ に保存されます。

• journal.db — 単一の SQLite ストア（検索対象のソースで、全日付にわたります）
• YYYY-MM-DD.md — 1 日につき 1 つの Markdown ファイルで、タイムラインに追記されます

.aamm/logs/
├── journal.db        # search source (all dates)
├── 2026-07-14.md     # per-day timeline
└── 2026-07-15.md

MCP ツール

記憶（8）：

• remember(title, content, category, tags?, scope?) — 保存（三方向同期、自動埋め込み）
• recall(query, category?, top_k=5) — 複合検索（ベクトル＋キーワード＋タイトル一致）
• get_memory(id) — 1 件を取得
• search_memories(category?, tag?, agent?) — 条件を指定して絞り込み
• update_memory(id, ...) — 更新（再埋め込み＋md の更新）
• forget(id) — 削除（三方向同期）
• list_memories(category?) — 一覧表示
• who_am_i() — 現在のエージェント＋プロジェクトのコンテキスト

ジャーナル（3）：

• journal_entry(question, answer_summary, key_points?, open_question?, session_id?) — タイムラインの項目を記録
• search_journal(query, date_from?, date_to?, agent?, limit=10) — ジャーナルを検索するフォールバック
• setup_profile(user_name) — ユーザー名を設定（ジャーナルに表示されます）

管理 CLI

python -m ai_agent_memory_mcp.cli init                  # initialize .aamm in the current project
python -m ai_agent_memory_mcp.cli status                # store overview (categories / vectors / md / journal)
python -m ai_agent_memory_mcp.cli export [--dir DIR]    # export all memories to Markdown
python -m ai_agent_memory_mcp.cli sync                  # rebuild SQLite + Chroma from Markdown
python -m ai_agent_memory_mcp.cli check                 # consistency check (db / md / chroma)
python -m ai_agent_memory_mcp.cli journal [--limit N]   # show recent journal entries

Claude Code への接続（ユーザースコープ：コードは共有、データはプロジェクトごと）

PyPI から（PYTHONPATH は不要）：

claude mcp add aamm -s user -- python -m ai_agent_memory_mcp --agent claude-code --project-from-cwd

ソースをクローンした場合は、-e PYTHONPATH=<clone dir>\ai_agent_memory_mcp を追加します：

claude mcp add aamm -s user -e PYTHONPATH=<clone dir>\ai_agent_memory_mcp -- python -m ai_agent_memory_mcp --agent claude-code --project-from-cwd

Qoder／Cursor も同様です。--agent を変更するだけです。

データ構成

.aamm/
├── memory.db                    # SQLite: structured memories + FTS5
├── chroma/                      # Chroma vector store
├── memories/<category>/<id>.md  # Markdown mirror (editable)
├── logs/
│   ├── journal.db               # work journal (search source)
│   └── YYYY-MM-DD.md            # per-day journal timeline
├── config.yml                   # embedding config
└── profile.json                 # user name

ライセンス

MIT