智猩猩AI整理
编辑：金水
你大概遇到过这种情况：用 Claude Code 改到一半，因为某种原因想切到 Codex 或者 Cursor 接着干。
新开的会话对之前的架构、踩过的坑、还没收尾的事一无所知，你只能把背景重新讲一遍，把"上次做到哪了"再复述一遍。
这不是个别现象。现在主流的 AI 编程助手，会话一关，上下文就清空了。同一个项目里，助手和助手之间是"失忆"的。
ai-memory 想解决的正是这件事，给这些助手一个共享的、能长期保留的记忆，让它们跨会话、跨工具地接着干。
这个项目最近热度不低，八月持续出现在 GitHub 趋势榜上，目前累计获得 5.4k 个 star。
ai-memory 把一次会话里观察到的信息，你说过的话、工具调用、会话的起止边界，清洗掉敏感内容后，汇编成一份纯 Markdown 写的"项目 wiki"。
会话结束时，相关的观察会被整理成一段连贯的摘要；下一个会话开始前，助手会收到一份有边界的"交接说明（handoff）"。
这份 wiki 就是普通的 Markdown 文件，放在一个 git 仓库里，能用 grep 直接搜、能拖进 Obsidian 当笔记看、能用 rsync 备份。
没有向量数据库要维护，不用为了记一件事专门去"写一条笔记"，也不用每次手动加载上下文。
1、换工具接着干
在 Claude Code 里进行到一半，关掉会话，几小时后再用 Codex 进入同一个目录。下一个助手在第一次提问前就能看到一段"上次做到哪了"的交接说明，其中列着尚未解决的问题、下一步动作，以及一段会话摘要。
2、隔了几天再回来
下午四点收工，第二天早上换另一个助手接着干，流程一致。如果所用工具没有真正的"会话结束"钩子（比如 Codex、Grok），就手动跑一次 ai-memory finalize-session 收尾。
3、查历史决策
当问"我们当时为什么选 Postgres"，它会用全文检索加实体匹配把相关的决策页找出来。想看排名依据，传一个参数就能看到每条结果排在这个位置的原因。
4、记一条一直保留的笔记
有些内容值得超出自动会话日志单独留存，例如一条决策、一条约定，或是一个踩过的坑。告诉助手"把这条记成项目规则"，它就写一页带 git 版本号的 wiki 页，之后会一直出现在检索结果里，直到你主动修改。
5、给有历史的项目补记忆
项目已经写了好几个月，ai-memory 才接进来？跑一次 ai-memory bootstrap，它会读 git log、README、docs 和模块头，把既有历史总结成种子页面，后续便在此基础之上继续积累。
无 LLM 依赖的运行模式。即便不接入任何 LLM，钩子仍照常采集会话；检索能力退化为全文检索（FTS5）加显式声明的实体与图邻域，摘要由规则生成。等接入 provider 后，才启用页面合并、矛盾检测与自动改进等能力。
记忆作为证据而非指令。ai-memory 自己写得很直白：检索返回的页面内容不具备权威效力。落地前请以当前代码库为准，它能告诉你"上次怎么想的"，但不能替代你阅读现有代码、运行测试。它建议把历史记忆和活的结构化代码工具（LSP、符号检索）配合使用，各司其职。
按项目的天然隔离。每个项目按 git 仓库根映射到独立目录，用稳定的 UUID 分组。同一个仓库的不同 worktree 共享同一个项目身份。重命名仅涉及一条字段更新，删除则直接 rm -rf，且不会影响其他项目。
隐私可控。仓库内可声明忽略规则，使匹配路径的采集事件在写入本地队列前即被丢弃；也可反向配置为仅在有标记的文件内采集。敏感内容由 native hook 在进入本地队列之前拦截。
单二进制与内置服务。单一二进制同时提供 MCP 与 HTTP 服务，数据目录下包含 wiki（Markdown 源）与 SQLite 索引；另含只读的 /web 界面，用于浏览项目树、全文检索与 Markdown 渲染。
现在已经覆盖了主流那一批：Claude Code、Codex、OpenCode、Cursor、Gemini CLI、Devin、Kiro、Grok Build CLI、Kimi Code、Zed（仅 MCP）、VS Code Copilot（仅 MCP）等。
ai-memory 本体是一个常驻服务，装好后再把你的助手接上来。
下面几种方式任选其一，零 LLM 模式下都不需要任何 API key。
1、Docker（最省事，推荐先体验）
先把 CLI 包装脚本装到本机，它负责把你的 HOME 挂进容器，并在本机转发 status、bootstrap 等命令：
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper \ -o ~/.local/bin/ai-memorychmod +x ~/.local/bin/ai-memory
启动服务（默认只绑本地回环，单用户笔记本上外人是连不进来的）：
docker run -d --name ai-memory \ --restart unless-stopped \ -p 127.0.0.1:49374:49374 \ -v ai-memory-data:/data \ akitaonrails/ai-memory:latest
想启用 LLM 合并页面、做矛盾检测，启动时加
`-e AI_MEMORY_LLM_PROVIDER=anthropic -e ANTHROPIC_API_KEY=...`即可；只想先跑通，这俩环境变量可以省。
2、macOS（原生二进制，官方推荐）
去 Releases 页下载 ai-memory-macos-aarch64.tar.gz（Apple 芯片）或 ai-memory-macos-x86_64.tar.gz，解压后把 ai-memory 放进 PATH，再初始化：
ai-memory --data-dir ~/.local/share/ai-memory \ --config ~/.config/ai-memory/config.toml init
3、Linux / WSL2（原生二进制或 AUR）
Arch 用户直接装包：
其他发行版下载 ai-memory-linux-x86_64 放到 /usr/local/bin 并初始化：
curl -L https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-linux-x86_64 \ | sudo tar -xzf - -C /usr/local/bin ai-memory --data-dir ~/.local/share/ai-memory \ --config ~/.config/ai-memory/config.toml init
4、Windows
走 WSL2 用上面的 Linux 路径；或下载 ai-memory-windows-x86_64.zip 里的 ai-memory.exe（原生 Windows 目前仍属实验性）。
接上助手基本是两行命令的事：
ai-memory install-mcp --client claude-code --apply ai-memory install-hooks --agent claude-code --apply
换成 Codex、Cursor、Gemini CLI 等，把 client / agent 名字换掉即可。之后正常开会话，每次提示和工具调用就会自动落进 ai-memory。
回过头看，ai-memory 解决的其实是个很实在的问题：你在一个项目上花掉的上下文，不该因为关掉一个会话窗口就蒸发掉。
它没把这件事包装成什么新概念，核心就一句：把每次会话整理成 Markdown，放进一个 git 仓库，下一个助手来取。
如果你正被"换工具就得重新讲一遍"困扰，或者只是想在某个项目里留一份能 grep、能时间回溯、能审计的历史记录，它值得花半小时跑通。不接 LLM 也能用，哪天不想要了，删掉容器和数据目录就行，试错成本不高。
唯一要接受的，是它得常驻一个服务、装几个钩子。它不是那种"装上就忘"的工具，更像在项目里多养了一个需要打理的小部件。值不值，取决于你在这个项目上打算待多久。
