Ai Memory Protocol

🚀 AI 內存協議

AI 內存協議 為 AI 編碼代理提供了基於圖結構的版本化持久內存，由 Sphinx-Needs 提供支持。該協議解決了 AI 代理在不同會話間丟失上下文的問題，為它們提供了一種結構化的方式來記憶、回憶和發展知識，具備完整的 Git 歷史記錄、類型化條目、圖鏈接以及機器可讀輸出。

🚀 快速開始

# 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

✨ 主要特性

• 類型化記憶：包括觀察、決策、事實、偏好、風險、目標、未解決問題等。
• 圖鏈接：支持關聯、支持、依賴、取代、矛盾、示例等關係。
• 基於標籤的發現：如 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）。

💻 使用示例

基礎用法

# 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

高級用法

# 更多的高級使用示例和場景說明
# 例如使用特定的參數進行搜索等操作
memory recall --tag topic:gateway --format brief --expand 0

📚 詳細文檔

工作原理

RST files (memory/*.rst)          ← 人類和 AI 均可編輯，由 Git 跟蹤
    │
    ▼ memory rebuild (sphinx-build)
needs.json (_build/html/needs.json)   ← 機器可讀索引
    │
    ▼ memory recall / get / list
Formatted output                  ← 針對 LLM 上下文窗口進行優化

記憶以 Sphinx-Needs 指令的形式存儲在 RST 文件中。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>                         # 獲取一條記憶的完整詳情
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 代碼

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. 讀取 — 先預覽再深入（兩階段回憶）

始終使用兩階段方法。在進行廣泛查詢時，不要直接訪問正文文本。 階段 A — 預覽（掃描標題，不顯示正文文本）：

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

返回 [ID] 標題 (置信度) 格式的單行信息，使用最少的令牌。首先執行此操作。 階段 B — 深入（讀取特定記憶的完整正文）：

memory get DEC_handler_context_pattern

在預覽之後，選擇 2 - 3 個最相關的 ID 並分別使用 get 命令獲取詳細信息。 何時進行回憶 — 回憶不僅僅是會話開始時的儀式。在以下時刻進行回憶：

2. 寫入 — 在特定觸發點記錄

記錄記憶不是可選操作。在以下具體時刻進行記錄：

• --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     # 輸出格式化 (簡潔/緊湊/上下文/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（將警告視為錯誤），如果任何記憶違反這些約束條件，構建將失敗。這意味著：

• 每個記憶必須至少有一個 topic: 標籤。
• 索引中不會存在空佔位符。
• 已棄用的記憶必須被替換。 代理學會自我糾正：如果 rebuild 失敗，它們會讀取警告信息，修復有問題的記憶，然後重試。

人類角色

人類是觀察者和編輯者，而非守門人：

• 儀表盤 — memory/dashboards.rst 包含 needtable、needlist 和 needflow 指令，將記憶圖的即時狀態渲染為 HTML。
• RST 編輯 — 記憶是普通的 RST 文件，可以在任何文本編輯器或 IDE 中編輯，並且在 Git 中具有完整的差異和 blame 信息。
• 覆蓋 — 人類可以通過 CLI 或直接編輯 RST 文件來更新任何記憶的狀態、置信度或標籤。
• 審查 — memory review 會顯示 review_after 日期已過的記憶，提示人類進行驗證。 該協議的設計使得代理能夠自主維護知識，而人類仍然可以保持完全的可見性和覆蓋能力。

貢獻指南

有關如何貢獻的指南，請參閱 CONTRIBUTING.md。

📄 許可證

Apache 2.0