Ai Memory Protocol

🚀 AIメモリプロトコル

AIコーディングエージェント向けのバージョン管理されたグラフベースの永続的メモリ — Sphinx-Needsによって提供されます。

AIエージェントはセッション間でコンテキストを失います。このプロトコルは、AIエージェントに対して、完全なGit履歴、型付きエントリ、グラフリンク、および機械可読な出力を備えた、知識を記憶、想起、進化させる構造化された方法を提供します。

✨ 主な機能

• 型付きメモリ — 観察結果、決定事項、事実、好み、リスク、目標、未解決の質問
• グラフリンク — 関連する、支持する、依存する、置き換える、矛盾する、例示する
• タグベースの検索 — topic:api, repo:backend, tier:core
• コンテキスト最適化出力 — 要約 / コンパクト / コンテキスト / JSON形式で本文の表示切り替え可能
• 古いデータの検出 — 自動期限切れ、レビューリマインダー、古さのチェック
• 自動スケーリング — RSTファイルは50エントリで分割され、クエリには透過的
• Gitネイティブ — すべてのメモリはRSTディレクティブであり、完全に差分可能かつバージョン管理される
• MCPサーバー — メモリをClaude Desktop、VS Code Copilot、およびその他のMCPクライアント向けのツールとして公開
• ビルド時の品質ゲート — needs_warnings品質ゲートにより、ビルド時にタグ付け、リンク、および本文の品質が強制される
• CLI中心 — 完全なライフサイクル管理のための12のサブコマンド

📦 インストール

git clone https://github.com/bburda/ai_memory_protocol.git
pipx install -e ai_memory_protocol/

# MCPサーバーサポート付き
pipx install -e 'ai_memory_protocol/[mcp]'

これにより、memory CLIコマンド（必要に応じてmemory-mcp-stdio）がグローバルにPATHにインストールされます。

🚀 クイックスタート

# 1. メモリワークスペースを作成
memory init .memories --name "My Project" --install

# 2. 最初のメモリを追加
memory add fact "API runs on port 8080" \
  --tags "topic:api,repo:backend" \
  --confidence high \
  --body "Gateway listens on 0.0.0.0:8080 by default" \
  --rebuild

# 3. 検索
memory recall api port
memory recall --tag topic:api --format brief

# 4. 詳細を取得
memory get FACT_api_runs_on_port_8080

📚 ドキュメント

仕組み

RSTファイル (memory/*.rst)          ← 人間とAIが編集可能、Gitで追跡
    │
    ▼ memory rebuild (sphinx-build)
needs.json (_build/html/needs.json)   ← 機械可読なインデックス
    │
    ▼ memory recall / get / list
整形された出力                  ← LLMコンテキストウィンドウに最適化

メモリは、RSTファイル内のSphinx-Needsディレクティブとして保存されます。memory rebuildコマンドはSphinxを実行してneeds.jsonを生成します — これはすべての検索操作の単一のクエリ層です。これは、メモリが人間が読めるドキュメントであると同時に、機械がクエリ可能なデータでもあることを意味します。

CLIリファレンス

memory init <dir>                       # 新しいワークスペースを作成
memory add <type> "<title>" [options]   # メモリを記録
memory recall [query] [--tag ...] [--format brief|compact|context|json]
memory get <ID>                         # 1つのメモリの詳細を取得
memory related <ID> [--hops N]          # メモリからのグラフウォーク
memory list [--type TYPE] [--status S]  # すべてのメモリを閲覧
memory update <ID> [--confidence ...] [--add-tags ...] [--body ...] [--title ...]
memory deprecate <ID> [--by NEW_ID]     # 非推奨としてマーク
memory tags [--prefix PREFIX]           # 使用中のタグを検索
memory stale                            # 期限切れ/見直し期限を過ぎたメモリを検索
memory review                           # 見直しが必要なメモリを表示
memory rebuild                          # needs.jsonを再構築

recallの主要なフラグ:

• --format brief — 超コンパクト、最小限のトークン
• --body — 本文を含める（デフォルトではオフ）
• --sort newest|oldest|confidence|updated
• --limit N — 結果を制限
• --expand 0 — グラフ展開を無効にする
• --stale — 期限切れ/見直し期限を過ぎたもののみ

MCPサーバー

Model Context Protocolを介して、LLMクライアントにメモリツールを公開します。

セットアップ

MCP拡張機能を含めてインストールします:

pipx install -e 'ai_memory_protocol/[mcp]'

Claude Code

claude mcp add --transport stdio --env MEMORY_DIR=/path/to/.memories memory -- memory-mcp-stdio

または、プロジェクトルートの.mcp.jsonに追加します（プロジェクトスコープ）:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "memory-mcp-stdio",
      "env": {
        "MEMORY_DIR": "/path/to/.memories"
      }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.jsonに追加します:

{
  "servers": {
    "memory": {
      "command": "memory-mcp-stdio",
      "env": {
        "MEMORY_DIR": "${workspaceFolder}/.memories"
      }
    }
  }
}

利用可能なMCPツール

メモリの種類

グラフリンク

メタデータ

タグ付けの規約

タグは一貫した検索のためにprefix:value形式を使用します:

• topic: — 主題領域 (topic:gateway, topic:auth)
• repo: — リポジトリ (repo:backend, repo:web-ui)
• domain: — 知識領域 (domain:robotics, domain:web)
• tier: — 重要度レベル (tier:core, tier:detail)
• intent: — 目的 (intent:decision, intent:coding-style)

AIエージェントの統合

推奨ワークフロー

1. READ — ピークしてから掘り下げる（二段階の想起）

常に二段階のアプローチを使用します。広い範囲のクエリで直接本文を読むことは避けてください。

フェーズA — ピーク (タイトルをスキャン、本文なし):

memory recall --tag topic:gateway --format brief --expand 0

[ID] タイトル (信頼度)の一行形式で返されます。最小限のトークンです。最初にこれを行います。

フェーズB — 掘り下げる (特定のメモリの本文を読む):

memory get DEC_handler_context_pattern

ピークした後にのみ、最も関連性の高い2 - 3つのIDを選択し、個別にgetします。

想起のタイミング — 想起はセッション開始時の儀式だけではありません。以下の各タイミングで想起します:

2. WRITE — 特定のトリガーポイントで記録する

メモリの記録は任意ではありません。以下の具体的なタイミングで書き込みます:

タスク終了時の書き込み: 学んだアーキテクチャを要約 (fact)、規約を記録 (pref)、将来のエージェントに必要なことをメモ (mem)、未完了の目標をキャプチャ (goal) します。

書き込みの品質ルール:

• --tagsは必須です — タグがないと、メモリは検索できません
• --bodyはファイルパスと具体的な詳細を含めた自己完結型でなければなりません
• --rebuildフラグを使用して、新しいメモリをすぐに検索可能にします

3. 編集ではなく、置き換える

知識が変更されたときは、--supersedes OLD_IDを指定して新しいエントリを追加し、古いエントリを非推奨としてマークします。

4. 定期的に古さをチェックする

長いセッションの開始時にmemory staleを実行して、グラフを正確に保ちます。

コンテキストウィンドウの最適化

• recallはデフォルトで本文を省略します — これは意図的なものであり、制限ではありません
• --format briefでピーク → get <ID>で掘り下げる — これが核心パターンです
• 広いトピックを探索するときは--limit 10と--expand 0を使用します
• 自由テキストではなく--tagフィルターを使用して結果を絞り込みます
• フィルターする前にmemory tagsを使用して利用可能なタグ接頭辞を検索します

プロジェクト構造

ai_memory_protocol/
├── pyproject.toml           # パッケージ定義、CLI + MCPエントリポイント
├── README.md
├── LICENSE                  # Apache 2.0
├── CONTRIBUTING.md
├── .pre-commit-config.yaml
├── .github/workflows/ci.yml
└── src/
    └── ai_memory_protocol/
        ├── __init__.py
        ├── cli.py           # CLI (argparse, 12サブコマンド)
        ├── mcp_server.py    # MCPサーバー (8つのツール、stdioトランスポート)
        ├── config.py        # 型定義、定数
        ├── engine.py        # ワークスペース検出、検索、グラフウォーク
        ├── formatter.py     # 出力整形 (brief/compact/context/json)
        ├── rst.py           # RST生成、編集、ファイル分割
        └── scaffold.py      # ワークスペースのスカフォールディング (initコマンド)

メモリデータは別のワークスペース（例: .memories/）に保存され、memory initで作成されます。

ビルド時の品質ゲート

Sphinxビルドは、メモリグラフの品質ゲートとして機能します。conf.pyのneeds_warningsは、memory rebuild中に適用される制約を定義します:

needs_warnings = {
    "missing_topic_tag": "type in ['mem','dec','fact',...] and not any(t.startswith('topic:') for t in tags)",
    "empty_body": "description == '' or description == 'TODO: Add description.'",
    "deprecated_without_supersede": "status == 'deprecated' and len(supersedes_back) == 0",
}

sphinx-build -W（警告をエラーとして扱う）を使用すると、いずれかのメモリがこれらの制約に違反するとビルドが失敗します。これは次のことを意味します:

• すべてのメモリには少なくとも1つのtopic:タグが必要です
• 空のプレースホルダーはインデックスに残りません
• 非推奨のメモリは置き換えるものによって置き換えられなければなりません

エージェントは自己修正を学習します: rebuildが失敗した場合、エージェントは警告を読み、問題のあるメモリを修正して再試行します。

人間の役割

人間は観察者および編集者であり、ゲートキーパーではありません:

• ダッシュボード — memory/dashboards.rstには、メモリグラフのライブ状態をHTMLとしてレンダリングするneedtable、needlist、およびneedflowディレクティブが含まれています
• RST編集 — メモリは通常のRSTであり、任意のテキストエディタまたはIDEで編集可能で、Gitで完全な差分/責任追跡が可能です
• 上書き — 人間はCLIまたは直接のRST編集を介して、任意のメモリのステータス、信頼度、またはタグを更新できます
• レビュー — memory reviewはreview_after日付が過ぎたメモリを表示し、人間による検証を促します

このプロトコルは、エージェントが自律的に知識を維持しながら、人間が完全な可視性と上書き能力を保持するように設計されています。

🤝 コントリビューション

コントリビューションのガイドラインについては、CONTRIBUTING.mdを参照してください。

📄 ライセンス

Apache 2.0