AI memory protocol

AI内存协议

  

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/

# With MCP server support
pipx install -e 'ai_memory_protocol/[mcp]'

这将安装 memory CLI命令（以及可选 memory-mcp-stdio)在PATH全球范围内。

快速开始

# 1. Create a memory workspace
memory init .memories --name "My Project" --install

# 2. Add your first memory
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. Search
memory recall api port
memory recall --tag topic:api --format brief

# 4. Get full details
memory get FACT_api_runs_on_port_8080

运作原理

RST files (memory/*.rst)          ← Human + AI editable, Git-tracked
    │
    ▼ memory rebuild (sphinx-build)
needs.json (_build/html/needs.json)   ← Machine-readable index
    │
    ▼ memory recall / get / list
Formatted output                  ← Optimized for LLM context windows

记忆存储为 斯芬克斯需要 RST文件中的指令。A. memory rebuild 命令运行Sphinx以生成 needs.json --用于所有搜索操作的单个查询层。这意味着存储器同时是人类可读的文档和机器可查询的数据。

CLI参考

memory init                        # Create a new workspace
memory add  "" [options]   # Record a memory
memory recall [query] [--tag ...] [--format brief|compact|context|json]
memory get                          # Full details of one memory
memory related  [--hops N]          # Graph walk from a memory
memory list [--type TYPE] [--status S]  # Browse all memories
memory update  [--confidence ...] [--add-tags ...] [--body ...] [--title ...]
memory deprecate  [--by NEW_ID]     # Mark as deprecated
memory tags [--prefix PREFIX]           # Discover tags in use
memory stale                            # Find expired/overdue memories
memory review                           # Show memories needing review
memory rebuild                          # Rebuild needs.json

关键标志 recall:

• --format brief --超紧凑、最少的代币
• --body --包含正文（默认情况下禁用）
• --sort newest|oldest|confidence|updated
• --limit N --上限结果
• --expand 0 --禁用图形扩展
• --stale --仅过期/审核过期

MCP服务器

通过向LLM客户端公开内存工具 模型上下文协议.

设置

安装MCP附加组件：

pipx install -e 'ai_memory_protocol/[mcp]'

克劳德代码

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代码（GitHub副本）

增添 .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] Title (confidence) 一个衬垫。最少的代币。先做这个。

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 --这是核心模式
• 使用 --limit 10 和 --expand 0 在探索广泛的主题时
• 使用 --tag 筛选以缩小结果范围，而不是自由文本
• 使用 memory tags 在筛选之前发现可用的标记前缀

项目结构

ai_memory_protocol/
├── pyproject.toml           # Package definition, CLI + MCP entry points
├── 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 subcommands)
        ├── mcp_server.py    # MCP server (8 tools, stdio transport)
        ├── config.py        # Type definitions, constants
        ├── engine.py        # Workspace detection, search, graph walk
        ├── formatter.py     # Output formatting (brief/compact/context/json)
        ├── rst.py           # RST generation, editing, file splitting
        └── scaffold.py      # Workspace scaffolding (init command)

内存数据存在于 独立工作空间 （例如。， .memories/)，创建于 memory init.

作为守护者建造

Sphinx构建充当内存图的质量门。 needs_warnings 在 conf.py 定义在以下过程中触发的约束 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中使用完整的diff/funce
• 以（权力）否决 --人类可以通过CLI或直接RST编辑更新任何内存上的状态、置信度或标签
• 审查 — memory review 表面记忆 review_after 日期已过，提示人工验证

该协议的设计使代理能够自主维护知识，而人类则保持完全的可见性和覆盖能力。

贡献

看 贡献.md 了解如何做出贡献的指导方针。

许可证

Apache 2.0