使用说明

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 <dir>                       # Create a new workspace
memory add <type> "<title>" [options]   # Record a memory
memory recall [query] [--tag ...] [--format brief|compact|context|json]
memory get <ID>                         # Full details of one memory
memory related <ID> [--hops N]          # Graph walk from a memory
memory list [--type TYPE] [--status S]  # Browse all memories
memory update <ID> [--confidence ...] [--add-tags ...] [--body ...] [--title ...]
memory deprecate <ID> [--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工具

工具	说明
`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] Title (confidence) 一个衬垫。最少的代币。先做这个。

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 <error message keywords>` --调试前的第一反应；检查此问题是否已解决
初次尝试后被卡住	`recall --tag topic:<X> --type mem,fact` --将搜索范围扩大到相关领域和过去的解决方案
在实现模式之前	`recall --tag intent:coding-style --type pref`

2.WRITE——在特定触发点记录

录制记忆不是可选的。在这些具体时刻写下：

触发器	类型	示例
选择方法A而不是B	`dec`	“在异常情况下使用tl:：expected”
修复了一个不明显的错误	`mem`	“EntityCache竞争条件修复”
发现未记录的API	`fact`	“注册顺序中的路线匹配”
用户表示偏好	`pref`	“更喜欢Zustand而不是Redux”
已识别风险	`risk`	“JWT secret在测试中硬编码”
问题仍未得到解答	`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           # 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