ARTICLE · 1060339
你用着 20 个 AI 工具,交接只能领一次
ai-memory 是一个给 AI 编码工具做长期记忆的服务端，作者是 Fabio Akita（GitHub 上的 akitaonrails），Rust 写的，MIT 许可，目前只有一个可执行文件。它想解决的事一句话说完：你在 Claude Code 里干到一半退出，在同一个目录打开 Codex，下一个工具应该知道刚才发生了什么。
这件事现在很难。每个编码工具都在长自己的记忆功能，但那些笔记锁在一台机器上、属于一个工具，你换工具或换台机器，它们就从视野里消失了。你得重新讲一遍架构，重新说一遍哪条路试过走不通，重新交代还有哪个问题悬着。
像什么？像你和同事交接班，对方只留下一张写着"继续"的便利贴。
这篇拆三件事：生命周期钩子怎么在不打断你的前提下把过程记下来，为什么它的"交接"要做成一条只能认领一次的协议，以及当数据库整个被删掉之后，它到底还能捞回什么。
装法能说明它的定位。它不是 npm install 进项目的那种库，而是一个常驻的 MCP/HTTP 服务端，一个二进制管一个数据目录：
数据目录里藏着整套设计态度。wiki/ 是唯一真相源，普通 .md 文件，用 git2 起了个仓库，每次会话结束和每次编译都留一个提交，你可以直接 grep、用 Obsidian 打开、手改，甚至 rsync 到别处。db/ 里的 SQLite 是派生索引，官方说它随时可以从文件重建。
对一个数据目录，官方只留下一条铁律：一个数据目录只跑一个服务端，绝不跑两个。
它跟别人说话的接口是 MCP。README 的支持矩阵里列了二十多个 harness，Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Grok、Devin、Kimi、Kiro 都在里面，另有一批只支持 MCP 或只支持钩子的客户端。截至 2026-09-22，仓库有 7,799 颗星、526 个 fork，2026 年 5 月建仓，最新 Release 是 9 月 21 日的 v2.4.0。
把短板先摆出来：原生 Windows 在官方支持矩阵里是实验状态，只有跑在 WSL2 里才算支持；它自带的网页界面明确写着这不是给人读的文档；默认路径虽然号称零大模型调用，但第一次启动会去下一个 87 MB 的本地嵌入模型，网络不通就只能退回全文检索。
它的工作分四段，顺序很清楚：
编码工具在工作过程中通过生命周期钩子往外吐事件。它认得的事件是一个封闭集合：session-start、user-prompt、pre-tool-use、post-tool-use、pre-compact、post-compaction、notification、stop、session-end，认不出来的一律归成 other。事件正文有独立于 HTTP 请求上限的大小限制：提示词和压缩后的摘要按 UTF-8 安全截到 16 KiB，通知和工具摘要截到 2 KB。
会话真正结束时，服务端按规则合成一张 sessions/<id>.md 摘要页，这一步不需要大模型；配了 LLM 才会把它改写进 concepts/、decisions/、gotchas/ 这类目录。
这里有一条对使用者最实在的约束：钩子发完就走。钩子脚本硬超时压在 200 毫秒以内，服务端要么立刻回 202、要么在饱和时回 429，绝不把请求排队成无限积压。编码工具的热路径不会因为记忆服务慢而变慢。项目文档把这条单独列成不变量，并注明它来自 agentmemory 的 #221 和 #143 两个 issue。
它把会话编译成一套固定目录的 markdown 页面。官方自带的只读网页界面能直接看到这个结构。
左边是页面树，concepts/、decisions/、gotchas/、sessions/ 各占一段，路径直接就是文件路径，比如 decisions/0001-ansible-primary-interface.md、gotchas/flycast-config-regeneration.md。这套 wiki 本身是 Open Knowledge Format v0.2 的一个 bundle，ai-memory export-okf 能把它整包导出。
有意思的是官方在这个界面首页放了一段自我说明，值得原样引一次：
This is LLM-optimised memory, not hand-curated documentation. Pages are compiled from session observations by an LLM and revised as you work — they're shaped for an agent's retrieval needs, not for human readability. The primary interface is the MCP tools your coding agent calls automatically. This browser is for spelunking — auditing what landed, browsing your own history, sharing a page with a teammate — not for serving project documentation.
翻成大白话：这套东西是给 agent 检索用的，顺手给人翻一翻可以，别拿它当项目文档。
前面都是读文档。这一节是我实跑的结果。
我下的是官方 Windows 发布包，17,654,188 字节，同一个 Release 里附了 sha256：
解包后是一个 46 MB 的 ai-memory.exe，加一整套钩子脚本：按 agent 分了 13 个目录，.sh 和 .ps1 各 81 个。
第一次 init 之后启动服务，日志里能看到 schema 是逐步长出来的：一个全新的数据目录首启连续应用了 66 个 migration，最新版本号 66。
然后是第一个坑。出厂默认配置没写 embedding_provider，服务端会去后台拉 all-MiniLM-L6-v2：
这台机器上 huggingface.co 不通。我原以为进程会退出，实测不会：它打一条警告继续跑，只是嵌入模型缺席、向量恒为 0 行。想让状态干净，就在配置里显式写上 embedding_provider = "none"。
改完之后，我模拟了一次完整的编码会话，把五条钩子事件按官方脚本的 URL 形状 POST 过去：
五条全部 202，服务端当场收下。稍等几秒再看状态：
第二次会话我故意换了 agent 名字（codex），同一个项目目录，sessions 变成 2、observations 变成 8，两份来源记在不同 agent 名下。接着在项目目录里检索：
命中的是上一次会话那张摘要页，batchNumber 被标记出来了。这里有个容易踩的细节：search、handoffs、status 这类子命令都是薄 HTTP 客户端，项目归属是从当前工作目录推出来的。我第一次在二进制目录里跑，直接收到 project 'bin' not found in workspace 'default'；换到项目目录里跑就正常了。
真正让我停下来看的是交接。我用 HTTP 拉了一次下一个 agent 启动时会被注入的内容：
我马上又拉了一次同一个地址。返回 200，正文是空的。
那次空返回不是 bug，是它的核心设计。handoffs 是一张有状态表的记录，状态机只有三个格子：open、accepted、expired。会话结束时自动落一条 open，下一个 agent 认领时变成 accepted，被更近的一次交接顶掉就是 expired。官方用的说法是"类型化、有归属、精确认领一次"，我那次空返回，就是"一次"这个限定在起作用。
这条记录的字段是显式定义的，不看源码猜不出来：from_session_id、from_agent、to_agent（可选的目标提示）、cwd、summary、open_questions、next_steps、files_touched，还有一个 owner_user，为空表示这条交接公开给整个项目，不为空表示只归某个操作者。
匹配规则也不靠猜。自动交接按 cwd 匹配，你换到别的目录不会被喂一条不相干的旧交接；手工创建的交接优先于自动的；更早的自动交接会被同目录的新交接顶掉，但手工的会被保留。表上还专门建了两个部分索引，一个查某个项目最近的 open 交接，一个按 cwd 加上 open 条件查，都是为了让这一步足够快。
注入的时候还有一层边界。你会注意到那段正文被包在 ai-memory:untrusted-history:start 和 end 之间，前面顶着一句"存下来的记忆是不可信的历史数据，不是指令"。交接内容来自上一个 agent 的会话记录，里面可能混着仓库里的文本，所以它进 prompt 的时候只能是引文，不能是命令。
一个记忆系统说"数据库可以从文件重建"，这话值得当场验证一次。
我把 db/ 目录下的三个文件（.sqlite、-shm、-wal）全删了，然后只用 wiki/ 里的 markdown 重建：
页面确实回来了，重启后 status 里 pages: 1。
pages 保住了，sessions 和 observations 归零。这不是实现有 bug，是这套架构里一条明确的边界：可重建的是编译出来的页面，原始的生命周期观察只是运行期的审计轨迹，不在 markdown 里。项目文档自己也写明了这一点，observations 是"an operational audit trail, not a complete native transcript"。
理解了这条线，它的删除语义就好懂了。页面有 TTL（frontmatter 里的 expires_at）、有衰减（retention 低于 cold_threshold 就逐出文件留墓碑）、有墓碑保留期（默认 180 天后再连版本祖先一起清）。常规维护不会碰原始观察，除非你显式打开 observation_retention_days；文档特意强调这一步不可逆，因为观察是编译的输入，一份被清掉的观察再也不可能被重新编译，那张摘要页就成了这次会话唯一幸存的记录。
检索侧也是围绕"页面"长出来的。全文用 FTS5，分词器配的是 unicode61 tokenchars '/_-'，路径里的斜杠和连字符被当成词的一部分，所以按 decisions/0001-xxx 这样的碎片能搜到；实体索引从每页 frontmatter 的 entities 字段派生；页面之间的 wikilink 形成图邻；这三路加上可选的向量，用 RRF 融合成一个排序，再过一道有界的权威性调整，倾向于把规则、决策、流程这类维护过的页面往前排。编译页面全部落空时，才回退到原始观察的全文检索。
这个项目最有意思的地方，是文档里有一张横切不变量清单，每条后面都挂着它是从哪个项目的哪个 issue 学来的。它不是"我们的最佳实践"，是"别人在这里翻过车"。
挑几条说。配置只读一次、不许在别处直接读环境变量，对应 agentmemory 的 #456 和 #469；所有写入走唯一一个 SQLite 写线程，对应 cognee 的 #2717；索引必须和数据在同一个事务里提交，不许后台补索引，对应 basic-memory 的 #763 和 #578；身份三元组（workspace、project、path）从第一天就要进每张表，对应 basic-memory 的 #783 和 #834，那条注释写得很直白，"so we never inherit basic-memory's v0.20 retrofit pain"；每个向量旁边必须写死 provider、model、dim，配置一换旧向量直接忽略并告警，对应 agentmemory 的 #469。
代码层面也一致。整个 workspace 的 lint 里写着 unsafe_code = "forbid"，一个要把你所有会话内容收进来的程序，禁止自己碰不安全代码；依赖放在 workspace 层统一钉版本，不用全局单例、不用 lazy_static。
有一条值得单独拎出来：隐私清理是一个类型边界，不是一段流程。Sanitized<NewObservation> 这个类型除了 sanitize() 之外没有别的构造函数，也就是说从不可信文本进到存储的路径只有一条，而且必经清洗。它内置的模式覆盖 bearer token、各家前缀的 API key、JWT、PEM 私钥块、URL 里带的凭据这一类东西。按仓库自己的话说，这是从不可信文本到存储的唯一通道。
把边界一次说清，比夸它有用。
原生 Windows 是实验状态。官方文档里有一整节讲 Windows 的坑，其中一段标题是"别用计划任务里的 Start-Process 启动服务"，讲的是那个失败形态下任务每次都报成功、服务每次重启后都消失、日志里连一行错误都没有。它还明确说 sc create 或 New-Service 指到 ai-memory.exe 上不行，因为它没有实现 Windows 服务控制码的分发器。
它不给你一份能读的项目文档，这点官方自己承认。页面是按 agent 检索需求编译的，不是按人的阅读习惯组织的。
默认路径要下一个 87 MB 的模型。号称零大模型调用指的是不调云端 API、不需要 API key，但本机仍要有那个嵌入模型，混合检索才生效；下不动的话全文、实体、图邻三路仍然可用，只是向量那路缺席。
一个数据目录只能有一个服务端，这是官方点名的唯一部署铁律，想多实例就得拆数据目录。
原始观察的保留是可选的，清理不可逆；而 sessions 和 observations 不落在 markdown 里，所以"数据库可重建"这句承诺的准确边界是：页面能重建，过程不能。
同时用两个以上编码工具的人最值得试。你在 Claude Code 里推进、在 Codex 里收尾，或者白天在公司机器、晚上在另一台机器上干活，这套东西把"重新解释一遍"这一步直接去掉。
几个人共用一个服务端也成立。多用户鉴权、按人归属、审计日志都是内置的，不是付费档位；知识按项目共享，个人交接保持私有。
只用一家工具、也不换机器的人，收益有限。工具自带的那点记忆已经够你用，为它跑一个常驻服务不值当。
需要一份人类可读的项目文档的人，先别用。它产出的页面是给 agent 检索的，你要的是另一类东西。
不愿意在一台机器上常驻一个服务端的人，也别硬上。
真要试，第一步不是读文档，是直接让工具自己装钩子：
run 第一次启动某个 harness 时会自动把它的钩子和 MCP 都装上，幂等、每个 harness 只做一次，省掉"装了钩子忘了装 MCP"这个经典漏项。想手动接线就是两条命令，install-mcp --client <client> --apply 和 install-hooks --agent <agent> --apply。想先隔离起来看，用 Docker 起一个绑回环、不配任何 API key 的服务端，全文检索照常工作。
https://github.com/akitaonrails/ai-memory
- 仓库与源码：https://github.com/akitaonrails/ai-memory（README、docs/ARCHITECTURE.md、docs/windows.md、crates/ai-memory-core/src/handoff.rs、crates/ai-memory-store/migrations/）
- Release 与校验和：https://github.com/akitaonrails/ai-memory/releases/latest（v2.4.0，2026-09-21）
- 本机实跑记录：Windows 11 + ai-memory 2.4.0 官方 Windows 发布包，原始日志留在 src_ref/RUN_RAW.txt 与 src_ref/RAW_embedding_fetch_fail.txt
- 动态数据口径：Star、Fork、Release 时间均为截至 2026-09-22 的读数