ai-memory:Agent 跨工具长期记忆与交接方案(Markdown Wiki + MCP)

ai-memory 是 GitHub 上 akitaonrails/ai-memory 开源的一套 Agent 长期记忆与跨工具交接方案:Rust 实现、MIT 许可、活跃维护中(2026-09-09 数据约 6.1k Star,仍在持续提交)。它解决的核心场景是——Claude Code 干到一半切到 Codex 时,架构、踩过的坑、未完成任务不必重新口述一遍:记忆以可 Git 管理的 Markdown Wiki 形式沉淀,下一个 Agent 通过 MCP 查询或接手即可继续推进。官方定位:“Long-term memory for AI coding agents and handoff between different agent vendors”。

它解决什么问题

很多 Agent 切换工具时,交接的往往只有分支和终端命令;真正昂贵的是没写进代码的东西——为什么某条路线被否掉、接口的隐含约束、某个 Bug 试过哪些解法、下一步从哪里接。手动写交接文档通常只有两种结局:忙的时候没写,闲的时候找不到。

ai-memory 的思路是:从 Agent 生命周期里收集经过边界控制的观察信息,形成会话摘要、工作记忆和交接内容;换工具后由新 Agent 查询、浏览或接手同一工作流。它强调沉淀可行动的结论,而不是把原始聊天记录整包塞回上下文。

与"给 Agent 加个 RAG"不同,ai-memory 关注的不仅是召回文档,更是任务如何从一个工作会话移交到下一个会话。

工作方式:开发上下文接力带

官方数据流为 capture → consolidate → recall → handoff:

工作时:Hook 捕捉限定范围内的观察信息(提示词、工具调用、会话边界),遵守排除规则;Agent 也可主动查询当前项目已有的规则、决策、未完成工作和历史问题。
会话结束时:观察信息被整合成 Wiki 中可读的 Markdown 页面(可选 LLM 润色,无 LLM 也可用)。
切换或接手时:系统写出摘要与 handoff,下一位 Agent(任意厂商、任意机器)拿到有界简报,并可全文检索、实体/链接/向量检索历史。

一个自包含的 Rust 二进制即运行 MCP/HTTP 服务器并独占一个数据目录:

<data_dir>/
├── wiki/    # markdown 真相源,git 版本管理
├── raw/     # 不可变的脱敏原始会话片段
├── db/      # SQLite 索引:FTS5、实体、嵌入
├── models/  # 本地嵌入模型预留
└── logs/    # 滚动日志

为什么敢把"记忆"放进 Git

关键架构选择:Markdown Wiki 是源数据,SQLite 只是派生索引。长期记忆不必躺在难以检查的向量数据库里——Wiki 可以当普通文本打开、用 grep 查、在 Obsidian 里浏览、用 Git 看变更或回滚;SQLite 负责 FTS5 全文检索、实体与页面链接邻居等更快的召回,且索引可随时从文件重建。

另一个务实特性是 Zero-LLM 路径:不配置大模型也能用 FTS5、实体/图关联检索和规则化摘要;接入 LLM(Anthropic、OpenAI、Gemini 或任意 OpenAI 兼容端点如 Ollama/vLLM)后,才额外获得更连贯的摘要整合、冲突检查与可选向量检索。也就是说可以先把它当本地、可追踪的 Agent 记忆基础设施,不必先背上模型账单。

支持矩阵与多机/团队

首方集成覆盖 20+ Agent/harness(CI 保持诚实):Claude Code、Codex、Command Code、Cursor、Gemini CLI、OpenCode、OpenCode 2、Grok Build CLI、Devin、Kimi Code、Kiro CLI、Pi、Hermes Agent(社区)等,接入方式为 MCP 注册、生命周期 Hook 或两者兼有。

记忆可跨机器:服务器可跑在同一笔记本、homelab 或任意可达主机;团队共享时知识按项目共享、个人交接保持私有,内置多用户认证、按人归因与审计日志(非付费功能)。

快速上手(Docker)

# 1. 安装 CLI wrapper(宿主机上唯一的文件,容器内运行二进制并挂载 $HOME)
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper \
  -o ~/.local/bin/ai-memory && chmod +x ~/.local/bin/ai-memory

# 2. 启动服务(默认仅绑定 127.0.0.1:49374,零 LLM 模式可省去 key 相关环境变量)
docker run -d --name ai-memory --restart unless-stopped \
  -p 127.0.0.1:49374:49374 -v ai-memory-data:/data \
  docker.io/akitaonrails/ai-memory:latest

# 3. 给 Agent CLI 接线:注册 MCP + 安装生命周期 Hook
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

换其他 Agent 只需改参数(--client codex/--agent codex、--client cursor、--agent gemini-cli 等)。日常使用中几乎感觉不到它的存在:Hook 自动捕捉,会话结束生成可读 Wiki 页,下一会话以 handoff 开场。可按需问"我们上次做到哪了/讨论过 X 吗/给我补个进度简报",或运行 ai-memory bootstrap 让老项目一次性吸收历史。

Codex 用户的注意点

ai-memory 对 Codex 提供 MCP 配置与生命周期 Hook 支持,但 README 明确:Codex 没有可自动触发的"真实会话结束"Hook。想要生成最终交接摘要时,需要显式运行:

ai-memory finalize-session

这是有意的工程边界——自动化记忆最怕"看起来保存了,实际最后一步没落盘"。

适用边界

适合先试:经常在 Claude Code、Codex、Cursor 等工具间切换的人;长任务、多人或多 Agent 接力开发;想把开发经验留在 Git/Markdown 中;希望自己控制 Agent 长期上下文。

别期待它解决:不会替你理解陌生代码库;不是完整聊天记录冷备份;不能替代代码、测试和当前分支事实;共享服务仍需认真配置访问令牌与数据边界。

两个现实提醒:一是捕捉内容应通过排除规则或 allowlist 控制,别把密钥、隐私沉淀成"经验";二是历史记忆只是辅助线索,当前代码、测试和配置才是最终事实。

参考资料

项目主页:github.com/akitaonrails/ai-memory
官方 README(架构/安装/支持矩阵):github.com/akitaonrails/ai-memory#readme
设计灵感与先例:先后参考了 Karpathy 的 LLM Wiki、basic-memory、agentmemory、cognee 以及 Hermes Agent 的自我改进循环

原文:有了它,太丝滑啦,5.3k Star ai-memory!!!(小华同学ai,2026-09-03)

它解决什么问题#

工作方式:开发上下文接力带#

为什么敢把"记忆"放进 Git#

支持矩阵与多机/团队#

快速上手(Docker)#

Codex 用户的注意点#

适用边界#

参考资料#