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