解决AI失忆问题，ai-memory开源项目完整拆解

文章目录前言1. 先说说这事有多烦1.1 记忆碎成渣的日常2. 这项目到底干了啥2.1 一句话版本2.2 两个反常识的设计2.2.1 Markdown 是原件SQLite 是复印件2.2.2 默认不花钱零 LLM2.3 还有三个惊喜2.3.1 交接协议2.3.2 混合检索2.3.3 管理式 workstream3. 架构长啥样3.1 写入路径3.2 记忆状态机3.3 检索3.4 安全边界4. 上手三分钟4.1 命令行日常4.2 局域网共享5. 数字说话5.1 检索成绩单5.2 项目体检5.3 增长曲线6. 适合谁、不适合谁7. 最后说两句P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看 传送门https://blog.csdn.net/qq_34419312前言写代码这件事现在最大的敌人已经不是 bug 了是失忆。工具越换越多记忆越切越碎。Claude Code 记得你上周拍的架构决策Codex 在旁边一脸茫然Gemini CLI 觉得你在讲天书Cursor 和 OpenCode 互相交换了个眼神这哥们是不是换人了你每换一个 CLI就得把项目背景、踩坑记录、待办事项重新讲一遍。讲完对方还未必记得住。这体验比跟一条鱼解释什么叫昨天还绝望——毕竟鱼只是记性差它至少不会反过来问你你刚说的那个数据库迁移是什么数据库来着1. 先说说这事有多烦以前写代码工具就是编辑器加终端记忆全靠自己脑容量够用。现在不一样了你手底下二十多个 AI 工具每个都有自己的小脾气也都有自己的小记忆。问题在于这些记忆之间不互通。你在 Claude Code 里花了仨小时才搞明白的部署流程切到 Codex 那边它一脸真诚地问你这个项目用的什么框架来着那一刻你想把三个小时的回放视频直接甩它脸上。1.1 记忆碎成渣的日常记忆碎片化的后果很直接每次切换工具都是一次重新入职。自我介绍、项目背景、技术债清单全套流程走一遍一个都不能少。换台电脑更惨上下文直接归零。比搬家的断舍离还彻底——至少搬家你还知道东西装在哪个箱子里换电脑是你连箱子都没了。2. 这项目到底干了啥今天这个项目就是来治这个病的。名字叫 ai-memoryGitHub 上 7.9K starsRust 写的MIT 协议随便用。它不是再给你加一个聊天记录搜索框——那种东西你装过不下十个了每一个都躺在收藏夹里吃灰偶尔打开一次还得跟它重新认识。它是把 Agent 会话里的提示词、工具调用、暂停点整理成一个 Git 化的 Markdown Wiki再用 SQLite 建索引做检索和交接。Claude Code / Codex / Gemini / OpenCode / Kimi ... │ │ lifecycle hooks: SessionStart / UserPrompt / ToolUse / Stop / SessionEnd ▼ /hook ingress → sanitizer → writer actor → observations/session/handoff │ ├─ wiki/pages: Markdown source of truth └─ SQLite: FTS5, entities, links, audit, optional embeddings2.1 一句话版本给编码 Agent 做跨工具、跨机器、甚至跨团队的长期记忆层。说得更通俗点给每个 AI 工具配一个公共大脑。谁干活谁用干完活都往里写下一个工具接着读。谁也不用重新自我介绍。2.2 两个反常识的设计这项目有两个设计跟市面上大多数记忆方案是反着来的。2.2.1 Markdown 是原件SQLite 是复印件第一个反常识Markdown 文件是事实源数据库只是可重建的派生索引。市面上大多数方案是把一切丢进向量库数据库就是一切数据库一崩记忆跟着陪葬。ai-memory 反着来原件是一堆你能用记事本打开的 Markdown 文件数据库丢了重建。索引过期了重建。向量库塌了还是重建。这就像你家房产证是手写的复印件被复印机吃了——慌什么原件还在再印一份不就完了。2.2.2 默认不花钱零 LLM第二个反常识默认路径一个 LLM 都不调用。你没听错。捕获会话、全文搜索、交接记录全部本地跑不需要 API key不需要花钱。配置了 LLM 之后才解锁更强的会话整理、语义检索、rerank 这些高级功能。默认本地 embedding 用的是 all-MiniLM-L6-v2一个勤俭持家的老牌小模型。这年头一个开源项目默认不烧你的钱已经算是一种温柔了。2.3 还有三个惊喜除了上面两个反常识还有三个点值得单独拿出来说。2.3.1 交接协议handoff 是 typed、带 owner、claim-once 的记录。翻译成人话A 工具干到一半写一张未完成事项交接单B 工具只能领取一次领了就得干活不能领完又扔回去。这比公司里某些离职交接还正规。至少它不会出现交接文档写了但没人看的经典事故——因为它根本不允许你装没看见。2.3.2 混合检索检索不是一条道走到黑。FTS5 全文搜索、实体匹配、图邻居三个结果先做 RRF 融合配置了向量再加一路最后还可以加一道可选的 LLM rerank。说白了就是鸡蛋不放一个篮子里关键词、文件路径、实体、向量谁靠谱听谁的。对代码记忆来说这招特别实用。很多查询是上次那个 migration 名字是啥“这个模块为什么不能删”——这种问题关键词和文件路径经常比 embedding 靠谱得多。2.3.3 管理式 workstream还有一个叫 managed workstream 的东西ai-memory run 一条命令选择或恢复工作流启动指定 Agent把之前的可见上下文注入进去进程退出后自动导入记录和 Git checkpoint。野心很大复杂度也肉眼可见。文档里把 lease、claim、递归注入过滤这些边界写得极其细致——细到让我怀疑作者是不是当年被这种 bug 坑到怀疑人生才写得这么较真。3. 架构长啥样整体可以拆成四个平面看捕获、知识、注入、治理。capture/storage plane agent hooks → bounded event payload → typed sanitizer → single SQLite writer → observations / sessions / handoffs / audit → Markdown wiki commits knowledge plane wiki markdown pages → FTS5 index → entity index → wikilink graph → optional local/cloud embeddings → hybrid retrieval injection plane MCP / CLI / managed run → scope resolver: workspace project actor → briefing / query / handoff accept → bounded startup packet → next Agent session governance plane users / bearer / OIDC / API keys → attribution → audit log → purge / backup / restore / reindex → pending auto-improve proposals3.1 写入路径写入路径的设计哲学一句话热路径短重活后移。Agent 每次工具调用都可能触发 hook如果 hook 写入链路慢你的编码体验会被当场拖垮。所以 hook 事件先走短超时发出去服务器入口做清洗和类型归一化写入交给一个单写者 actor 串行化。会话结束才触发总结和 handoffLLM 整理又是可选项。翻译前台收银只管收钱清点库存这种重活等关门以后再说。客人还在排队呢你蹲在柜台后面盘货像话吗。代码结构也守这条线各干各的crates/ ├── ai-memory-core domain types, ids, errors ├── ai-memory-hooks hook payload schemas and sanitizer ├── ai-memory-store SQLite writer actor, reader pool, decay math ├── ai-memory-wiki Markdown file writes, watcher, git history ├── ai-memory-mcp MCP transport and tool router ├── ai-memory-llm provider auth and embedder traits ├── ai-memory-consolidate consolidation, lint, sweep, auto-improve ├── ai-memory-workstream managed run and native transcript adapters ├── ai-memory-web read-only web UI └── ai-memory-cli binary entry and thin commands3.2 记忆状态机这项目有个很轴的细节原始输入不是记忆条目而是 Agent 的生命周期事件。session-start、user-prompt、pre-tool-use、post-tool-use、pre-compact、post-compaction、notification、stop、session-end……一共归一到一个封闭集合未知事件默认收敛成 other。第三方扩展可以保留自己的事件但不能绕过清洗、背压和 writer actor。这个设计思路很朴素它不猜你想记什么它只记录发生了什么。就像日记本不负责替你筛选今天值不值得记它只负责把日子写下来。observation stream ├─ prompts ├─ tool calls ├─ compaction notes └─ stop/session-end │ ▼ rule-based session summary │ ├─ optional LLM consolidation → concepts / decisions / gotchas / procedures └─ automatic handoff → pending → accepted / expired / cancelled3.3 检索memory_query 默认先跑 FTS5、实体匹配、链接邻居的 RRF配了 embedder 就加向量 cosine配了 reranker就在最终候选上再排一遍。rerank 失败、超时、结果非法、并发饱和就自动退回本地排序。这种高级功能挂了就自动降级的设计比某些高级功能挂了就直接报错的软件体面太多了。人家至少给你留了条回家的路。3.4 安全边界安全这块文档把事分得很开一点不含糊默认 loopback-only只绑 127.0.0.1非 loopback 无认证直接拒绝启动局域网部署要 bearer token、allowed hostsTLS 交给 Caddy、nginx、Cloudflare Tunnel 这类成熟反代本地静态数据不搞花活靠 OS 文件权限。local-only default ├─ server binds 127.0.0.1:49374 ├─ no telemetry ├─ wiki SQLite live under operator-controlled data dir └─ local embeddings can run without API key external-data opt-ins ├─ cloud embedding provider: page text leaves host ├─ assistant final-turn capture: double opt-in └─ LLM reranker: query bounded snippets leave host一句话总结默认只爱自己社交恐惧友好型软件。当然边界也很诚实没有每页 RBAC。多用户共享服务器能做身份、归属和审计但它不是强隔离的多租户知识库。打个比方这是合租不是酒店。合租能分清谁住哪个房间但衣柜里的衣服是共用的。你要酒店级别的隔离出门左转那得加钱。4. 上手三分钟说那么多上手才是硬道理。官方给了 Docker 路线先装一个 host wrapper带校验和验证防中间人再跑容器最后接入你的工具。mkdir -p ~/.local/bin wrapper_tmp$(mktemp -d) trap rm -rf $wrapper_tmp EXIT wrapper_basehttps://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper curl -fsSL $wrapper_base -o $wrapper_tmp/ai-memory-wrapper curl -fsSL $wrapper_base.sha256 -o $wrapper_tmp/ai-memory-wrapper.sha256 expected$(awk NR 1 { print $1 } $wrapper_tmp/ai-memory-wrapper.sha256) actual$(shasum -a 256 $wrapper_tmp/ai-memory-wrapper | awk { print $1 }) [ -n $expected ] [ $actual $expected ] || { echo wrapper checksum mismatch 2; exit 1; } install -m 0755 $wrapper_tmp/ai-memory-wrapper ~/.local/bin/ai-memory rm -rf $wrapper_tmp trap - EXIT启动本机服务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接入 Claude Code两条命令搞定ai-memory install-mcp --client claude-code --apply ai-memory install-hooks --agent claude-code --apply4.1 命令行日常装好之后日常操作就这么几条清清爽爽# 查看状态 ai-memory status # 搜索 Wiki 记忆 ai-memory search database migration rollback # 读取某个页面或者按查询取最相关页面 ai-memory read-page --path decisions/0001.md ai-memory read-page why did we change auth middleware # 手动结束没有 SessionEnd hook 的 agent 会话 ai-memory finalize-session --agent codex想走 managed workstream 也行ai-memory run claude ai-memory run codex --yolo ai-memory continue4.2 局域网共享想给团队用先搞个 token再改成非 loopback 绑定。TOKEN$(ai-memory generate-auth-token) docker run -d --name ai-memory \ --restart unless-stopped \ -p 0.0.0.0:49374:49374 \ -v ai-memory-data:/data \ -e AI_MEMORY_AUTH_TOKEN$TOKEN \ -e AI_MEMORY_ALLOWED_HOSTSserver-ip,localhost,127.0.0.1 \ akitaonrails/ai-memory:latest ai-memory install-mcp --client claude-code --apply \ --server-url http://server-ip:49374/mcp --auth-token $TOKEN ai-memory install-hooks --agent claude-code --apply \ --server-url http://server-ip:49374 --auth-token $TOKEN注意这只是参数形态。真实部署还得加 TLS 反代和 host 白名单。别裸奔上公网——公网不是你家后院是野生动物园。5. 数字说话5.1 检索成绩单项目自带 eval harness 跑出来的数字条件写得挺清楚commit、数据集 sha256、硬件、模式都有记录。放出来给大家看看模式指标结果说明zero-llmpre-2.0 FTSoverall hit50.617旧 FTS 基线zero-llmstopword-filtered FTSoverall hit50.668去停用词后的本地检索local embeddings2.0 defaultoverall hit50.823FTS5 entity graph 本地向量融合从 0.617 到 0.823加了实体和图再加本地向量一路从勉强能用爬到了相当能打。5.2 项目体检版本面得分开看不能糊成一团版本面观测值来源最新 GitHub Releasev2.4.0GitHub 元数据main 分支 Cargo workspace2.3.2Cargo.tomlRust 工具链rustc 1.95.0rust-toolchain.toml 与本地 rustc --version默认分支 HEAD5157c6b本地浅克隆Docker 镜像akitaonrails/ai-memory:latestREADME 快速上手还有一份源码体检712 个 Git 跟踪文件295 个 Rust 文件约 25 万行 Rust。25 万行 Rust 是什么概念写的时候有多快乐编译的时候就有多痛苦。这已经不是 README 驱动的小壳了是实打实的工程量。5.3 增长曲线仓库 2026-05-21 创建到 2026-09-22 快照124 天7,893 颗星。粗算平均每天 63.7 颗。这增长速度比我发际线后退的速度还稳定。羡慕。顺便看下当天 Trending 榜单快照没保留每日新增就不编数字了RankRepositoryLanguageStarsForks1BuilderIO/agent-nativeTypeScript6,1825582trycua/cuaHTML25,8501,7783Open-Dev-Society/OpenStockTypeScript18,0922,2254akitaonrails/ai-memoryRust7,8935305coder/coderGo16,5361,5726anthropics/financial-servicesPython35,9695,2787cloudflare/quicheRust12,4411,1398mvt-project/mvtPython13,7291,3359zhouxiaoka/autoclipPython8,5321,58910ruanyf/weekly-104,2864,46011Crosstalk-Solutions/project-nomadTypeScript38,0233,77612yynxxxxx/Codex-XRust3,800468旁边那一堆熟面孔就不展开聊了今天的主角是排第四这位。6. 适合谁、不适合谁场景适合程度原因个人同时使用 Claude Code、Codex、Gemini CLI高共享一个项目级 Wiki 和 handoff减少重复交代上下文团队内部共享 Agent 项目记忆高支持多用户归属、API key、审计日志和局域网部署对外部 LLM API 敏感的代码库中高默认零 LLM可用本地检索但仍要管好本机数据目录和日志想把会话沉淀成可读知识库高Markdown Wiki 是事实源适合人工审阅和 Git diff只想要简单向量搜索中它能做检索但完整系统包含 hook、handoff、server、MCP、运维动作可能偏重强多租户 SaaS 记忆平台低文档明确没有每页 RBAC本质是自托管单租户/团队工具生产级远程共享服务中有认证、审计和部署文档但还需要 TLS、备份、权限、监控等运维配套一句话总结单人多工具、团队共享、想要可审计知识库的都是高适配想拿它搞强多租户 SaaS 的洗洗睡。7. 最后说两句这项目最有意思的地方是它拒绝把记忆简化成 embeddings。事实源回到文件系统Markdown 页面、Git 历史、SQLite 派生索引、MCP 工具、hook 捕获、handoff 协议。这堆东西不轻但方向是对的。等 Agent CLI 变成日常工具真正难的不是模型能不能回答而是上一轮的工作怎么可靠地交给下一轮。个人用loopback Docker 起步就够了团队试点先想清楚三件事数据目录放哪、谁能访问、什么内容允许发给外部 provider。把这三件事讲清楚文件优先的架构会比黑盒记忆服务更容易被工程团队接受。毕竟能 grep 的记忆才是好记忆。P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/qq_34419312