JinDaGe - ai_memory_protocol MCP Details

article

README

🚀 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 工具

| 工具 | 描述 | |------|-------------| | memory_recall | 通过文本/标签搜索记忆，并支持格式化选项 | | memory_get | 获取特定记忆的完整详情 | | memory_add | 记录一条带有标签和元数据的新记忆 | | memory_update | 更新记忆的内容或元数据（标题、正文、状态、置信度、标签等） | | memory_deprecate | 将一条记忆标记为已弃用 | | memory_tags | 列出所有标签及其计数 | | memory_stale | 查找过期/逾期的记忆 | | memory_rebuild | 重建 needs.json 索引 |

记忆类型

| 类型 | 前缀 | 使用场景 | |------|--------|----------| | mem | MEM_ | 观察、笔记或发现 | | dec | DEC_ | 设计或架构决策 | | fact | FACT_ | 经过验证的稳定知识 | | pref | PREF_ | 编码风格或约定 | | risk | RISK_ | 不确定性或假设 | | goal | GOAL_ | 目标或指标 | | q | Q_ | 需要解决的未解决问题 |

图链接

| 链接 | 含义 | |------|---------| | relates | 一般关联 | | supports | 证据或理由 | | depends | 硬依赖 | | supersedes | 取代旧记忆 | | contradicts | 冲突或矛盾 | | example_of | 概念的具体实例 |

元数据

| 字段 | 值 | 用途 | |-------|--------|---------| | confidence | low / medium / high | 信任级别 | | scope | global, repo:X, product:X | 适用性 | | tags | prefix:value 格式 | 分类 | | source | URL、提交记录、描述 | 来源 | | review_after | ISO 日期 | 陈旧性触发日期 | | expires_at | ISO 日期 | 自动过期日期 | | created_at | ISO 日期 | 捕获时间戳 |

标签约定

标签使用 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 命令获取详细信息。 何时进行回忆 — 回忆不仅仅是会话开始时的仪式。在以下时刻进行回忆： | 触发条件 | 回忆内容 | |---------|---------------| | 会话开始 | recall --format brief --limit 20 --sort newest | | 新任务或主题 | recall --tag topic:<X> --format brief | | 进入不熟悉的代码 | recall --tag repo:<X> --type fact --format brief | | 进行设计决策之前 | recall --tag topic:<X> --type dec | | 遇到错误或失败 | recall <错误消息关键字> — 在调试之前的第一反应；检查该问题是否已经解决 | | 初始尝试后陷入困境 | recall --tag topic:<X> --type mem,fact — 扩大搜索范围到相关领域和过去的解决方案 | | 实现模式之前 | recall --tag intent:coding-style --type pref |

2. 写入 — 在特定触发点记录

记录记忆不是可选操作。在以下具体时刻进行记录： | 触发条件 | 类型 | 示例 | |---------|------|---------| | 选择方案 A 而非 B | dec | "使用 tl::expected 而非异常处理" | | 修复非显而易见的 bug | mem | "EntityCache 竞态条件修复" | | 发现未记录的 API | fact | "路由按注册顺序匹配" | | 用户表达偏好 | pref | "更喜欢 Zustand 而非 Redux" | | 识别出风险 | risk | "JWT 密钥在测试中硬编码" | | 问题仍未解决 | q | "合成组件是否应暴露操作？" | 任务结束时的写入：总结所学的架构知识（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     # 输出格式化 (简洁/紧凑/上下文/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

ai_memory_protocol