ai-memory 3.1.1：Claude Code 与 Codex 共用一份 git 里的 markdown 记忆

ai-memory 是开发者 Fabio Akita（GitHub 账号 akitaonrails）在 2026 年 5 月创建的开源项目，Rust 写成，MIT 协议，目标只有一个：让 Claude Code 里干到一半的活，换 Codex 打开同一个目录还能接着干。2026-10-17T18:09:02Z，项目发布 3.1.1；这个版本的 CHANGELOG 只有一组「Fixed」，28 条全在修问题，其中最重的一条是 Windows 主线程栈溢出——异步 CLI 命令树长大后，Windows 原生测试套件里每个启动 ai-memory 的集成测试都在处理命令前崩掉。

要点

• 3.1.1 不带新功能。除了 Windows 栈溢出，它还修了进程在 spool 文件同步后、原子 rename 前被杀导致 hook 事件永久滞留的问题，并按 CodeQL #176 收紧了 OIDC 凭据传输。
• 「20 多个 harness 共用一份记忆」和「默认零 LLM 调用」在 2026-09-02 的 2.0 博客里就已写明，属于项目级主张，不是 3.1.1 的卖点；功能主要落在前一天的 3.1.0：IBM Bob、CodeBuddy Code、managed harness 切换时续接本机历史、Windows 登录服务。
• 记忆的源文件是 git 版本化的 markdown wiki，页面行、链接与 FTS 可以由 ai-memory reindex 从文件重建；但 sessions、observations、handoffs、embeddings 只存在 SQLite 里，reindex 不重建。2026-10-18 用 GitHub API 查：10,084 星、727 fork、3,922 次提交。

背景

项目 2026-05-21 建仓，GitHub 的具名贡献者约 150 人（API 列表每页 1 人，末页为第 150 页）。发布节奏很密，按 GitHub release 的 UTC 时间：3.0.0 在 10-14T00:44Z、3.0.1 在 10-15T22:57Z、3.1.0 在 10-16T05:43Z、3.1.1 在 10-17T18:09Z。3.1.0 才是功能版：接入 IBM Bob 与腾讯 CodeBuddy Code；ai-memory run 在 managed harness 之间切换时给接收方一份本机临时可见历史；install.ps1 两行装加 Windows 登录服务；setup --web；以及一个 Tauri 桌面安装器预览。

站内的记忆类条目已经不止一条，最接近 ai-memory 的是 deja-vu：默认也不调模型，同样让 Claude Code 与 Codex 看到对方做过的事；区别是 deja-vu 把磁盘上已有的会话记录建成索引，单个 Go 二进制、纯词法检索，而 ai-memory 用 hooks 实时捕获，把会话编译成可编辑的 markdown wiki 页，再用 claim-once handoff 把未完成的活交出去。Basic Memory 同样以 Markdown 文件为记忆本体；Graphiti 是 Zep 开源的时间知识图谱，ai-memory 与它共享「事实有新旧」这一点，代价是没有完整的时序推理。跨 Agent 共享也和 LangChain Deep Agents 那篇上下文工程不是一回事，后者解决的是单个 harness 的窗口管理。

3.1.1 的改动

3.1.1 的修复清单里，最容易被忽略的是 hook 滞留。CHANGELOG 写得很具体：harness 在 spool 文件同步完成、原子 rename 还没执行时杀掉进程，事件就永远留在那里。修法是后续 drain 在五分钟宽限期后接管完整有效的 *.json.tmp，并清理畸形残留；Claude Code 的设置安装把 SessionEnd 超时从默认 1.5 秒改成 15 秒，插件 hook 因为 Claude 不允许自升超时，只能靠恢复路径（#1377）。

OIDC 那条来自 CodeQL #176：refresh-grant 的共享 sink 现在要求带类型的 TLS 或 loopback 端点，device authorization 与 token polling 在每次请求前重新校验端点，调用方改过的 discovery 对象不能再绕过登录时的 HTTPS 检查。同一天还修了 device login 与 refresh 把带凭据的请求发往非 TLS 端点的问题（#1354）。还有一个会实际坑人的配置 bug：anthropic 和 openai 两个 provider 之前会丢弃显式的 llm_base_url（或 AI_MEMORY_LLM_BASE_URL），请求和 API key 直接发往 api.anthropic.com 或 api.openai.com，日志里什么都不留（#1347）。想用网关或反向代理的人，流量其实一直没走网关。

文档层面的修正同样值得记一笔。3.1.1 改掉了 comparison 和 competitive-parity 里「Windows 没有 service 步骤、安装是 experimental」的旧说法，CHANGELOG 明确写 3.1 的 install.ps1 加 setup Windows 服务步骤「is shipped production, not experimental」（#1271）。Bitdefender 的问题只解决了一半：3.1.0 改用注册表 API 写 Run 键、不再运行 reg.exe，因为无签名二进制对 Run 键执行 reg.exe add 是常见持久化信号，Bitdefender 的行为引擎曾隔离 ai-memory.exe；3.1.1 清掉了命令行里的 \\?\ 前缀，但原话是「does not by itself resolve Bitdefender’s behavioral detection」。

记忆怎么存

ai-memory 的数据目录由五部分组成：wiki/ 是 markdown 源文件，git 版本化；raw/ 存不可变的、已脱敏的 managed 会话片段；db/ 是 SQLite，既存 FTS5、实体、链接这些可从 wiki 重建的索引，也存 sessions、observations、handoffs、embeddings 这些只在这里落地的状态；models/ 留给本地向量模型；logs/ 是滚动日志。一个 Rust 二进制同时跑 MCP/HTTP server，写入经过单个 SQLite writer 串行化，会话结束后观察被编译成 markdown 页。

检索走 FTS5、实体匹配、图邻居三路 RRF，可选向量 RRF，再加一条默认开启的 observation evidence stream：某次会话的页在捕获的回合命中时会被抬上来。跨 Agent 的 handoff 是带类型的协议，每个 handoff 有 owner，只能被领取一次；团队版把每个人指向同一个 server，知识按项目共享，个人 handoff 保持私有，多用户认证和审计日志内置，不是付费档。

零 LLM 的边界要写清楚。默认路径（捕获、检索、handoff）不需要 API key；记忆老化里访问加权保留始终开启，因为它只会让记忆留得更久；会改写或丢弃内容的压缩、去重、按档衰减曲线默认关闭，要自己打开。README 说近似重复会合并成一条、疑似矛盾会被标出来，也都是零 API 调用；「Nothing is hard-deleted」——原始版本留在 git 里，restore-page 可以取回。

安装有五条以上路径：Linux/macOS 的 install.sh（校验 SHA-256）加 ai-memory setup，Windows 的 install.ps1，Arch 的 AUR，Fedora 的 RPM，Docker 镜像，macOS 菜单栏 app，以及 Claude Code 与 Codex 的市场插件。默认只绑 loopback，init 会生成 bearer token；捕获在带类型的隐私边界脱敏，每个仓库可以用 [capture] 规则排除路径，或反转成白名单。

口径对不上

同一件「支持多少 Agent」，仓库里有三个数字。官网写「Works with 32 coding agents」；README 写「More than twenty harnesses」；docs/support-matrix.md 一共 48 行，去掉 5 行平台、2 行功能与 2 行提供方之后是 39 个 agent 条目：24 个 Supported、6 个 MCP-only、6 个「MCP-only (documented)」、2 个 Hooks-only、1 个 Managed-only。矩阵开头自己注明，带 (documented) 的 6 行只有手写配方、没人端到端跑过，而它们不在 README 的紧凑表里。

Windows 状态是同一天的两套说法。README 和 support-matrix 都还写「Native Windows | Experimental」，3.1.1 的 CHANGELOG 却说 Windows 安装与服务步骤已经是 production。两边都在同一个仓库里，我没有替作者选一个；读者现在只能按平台实际表现自己判断。

这种口径问题不算致命，矩阵把 MCP-only、Hooks-only、Managed-only 分开列，已经比多数项目诚实。问题在于三个数字没有一处统一，引用时得说清用的是哪一个。

基准与外部评价

官方公布的检索数字是 LongMemEval-S v1 上的 0.951 hit@5，470 道题，2026-10-16 复跑，代码 commit a288a10，数据集 sha256 以 08d8dad4 开头。同一份报告里 FTS 的 hit@1 是 0.857、hit@10 是 0.972，p50 12 毫秒、p95 101 毫秒，前五条命中的平均上下文 528 token。这是仓库自带 harness 的产物，官网自己标了「caveats included」，并写明 hit@5「measures retrieval, not answer accuracy」。我没有找到任何第三方复现或横评。

独立报道只有一家。LinuxPro 的 nilton 在 2026-10-10 写了一篇 2.4 到 2.6.3 的演进梳理，文末自述「As descrições acima vêm das notas oficiais, não de benchmarks próprios」——描述来自官方发布说明，不是自己的基准。他提了两条有价值的保留：完整备份要连数据库状态一起存，不能只拷 wiki；关掉 Agent 的确认框不算安全机制。第一条说对了，而且能在仓库文档里找到依据。README 称数据库是「derived index that can always be rebuilt from the files」，docs/backup.md 也把 db/ 列进「不用备份」一栏，理由是可以用 ai-memory reindex 重建。但 docs/lifecycle-ops.md 把 reindex 的边界写得很清楚：它能重建的是 workspaces/projects、最新的 page 行、page links 和 FTS；sessions、observations、handoffs、users/tokens、审计行、访问计数和 embeddings 属于 DB-only state，reindex 不重建，需要的话得自己备份。docs/backup.md 的另一段也承认这些数据「live only in the DB」，只能从配套 tarball 恢复。所以删掉 db/ 再 reindex 不会恢复全部数据，完整备份必须连 db/ 一起存——这正是 LinuxPro 的提醒，不是过时的版本特例。作者把这句放在「Ponto de partida」一节，紧接的一句是「Esses fundamentos já existiam antes da 2.4」——这些基础在 2.4 之前就存在。

社区反应基本缺席。HN Algolia 上只有一条 2.0 的投稿（2026-09-02，item 49543786），1 分、0 评论。这里没有能当作社区讨论来写的东西，也不编。

编辑判断

对同时用 Claude Code 和 Codex、又不想把项目上下文交给某一家托管的团队，ai-memory 是少数能直接自托管的选项：一个二进制、一个数据目录、一个可达的 server，记忆是能用 grep 和 Obsidian 打开的 markdown，备份和迁移都不依赖厂商。默认零 LLM 也意味着「记东西」这件事不单独烧 token。

它和 deja-vu 的差别在数据来源与写入方式：deja-vu 索引磁盘上已有的会话文件，不装 hook 也能立刻搜到几个月前的历史；ai-memory 要装 hook、跑一个常驻 server，换来的是会话结束后自动编译成页面、可手改、可共享给团队。它和 Basic Memory 的差别在自动捕获与跨 Agent handoff：后者是人和 Agent 共写的笔记库，前者在会话生命周期里自动记录，再把未完成的活以 claim-once 的方式交给下一个 Agent。它和 Graphiti 的差别在投入：不搭图数据库，代价是没有完整的时序推理，README 自己叫 bi-temporal-lite。

诚实的代价有四条。支持矩阵里标为 Supported 的 agent 行是 24 行，不是官网写的 32；Windows 仍是 experimental 与 production 两说；会改写内容的零 LLM 老化默认关闭，要用得自己开；捕获会记录 prompt 和部分工具观察，脱敏之后官方仍提醒「filtering can miss sensitive text」。另外，README 的 Acknowledgements 写明代码是与 Claude Code（Opus 4.7）协作写成，这一点值得知道，也值得当成透明度而不是扣分项。

怎么试

一台 Linux 或 macOS 机器上两条命令：

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

setup 会列出它找到的 Agent，确认后写入 MCP 与 hooks；重启 Agent，问一句「这个项目你记得什么」，看它能不能从 ai-memory 取回上下文。想先看计划不加改动，用 ai-memory setup --plan；想先在浏览器里勾选，用 --web。