用 ai-memory 给编码 Agent 装一份跨工具长期记忆：Markdown wiki 真相源、四步生命周期与跨 Agent 交接实操

两条路线选一条。一键脚本最省事：装好包装脚本后跑 setup，它会建数据目录、起一个用户级服务，并把 MCP 与钩子挂到它检测到的 Agent 上；脚本会先给你看计划再动手，只想看计划就加 --plan。想把服务单独隔离、或者放在家里另一台机器上给大家共用，走 Docker 更合适。默认端口是 49374，只绑在回环地址上。

# 路线 A：一键脚本（Linux / macOS，无需 root）
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup          # 建数据目录、起用户级服务、挂载检测到的 Agent

# 只看计划，不改任何东西
ai-memory setup --plan

# 路线 B：Docker（隔离运行 / 放到另一台机器上）
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

数据目录里有三个子目录，理解它们的分工能省掉后面很多困惑：wiki 是真相源，纯 Markdown 文件，可以 grep、可以用 Obsidian 打开、可以手工改，也可以 rsync 或进 Git；db 是派生索引，SQLite 全文检索加实体与图邻居检索，随时能从 wiki 重建；raw 是脱敏后的原始会话片段，属于不可变留痕。这个设计的实际好处是：索引坏了不影响内容，内容你随时能读能改，不像向量库那样是个黑盒。浏览器打开 http://127.0.0.1:49374/web 可以直接翻 wiki。

挂载分两件事：install-mcp 让 Agent 能主动检索记忆；install-hooks 让会话的开始与结束触发捕获与整理。两条都要装，只装 MCP 就只能读不能记。命令是幂等的——重跑只替换 ai-memory 自己的条目，你已有的其它钩子不受影响，而且每次改动前会写一份 .bak 备份。装完务必重启你的 Agent，否则配置不生效，这是这一步最高频的「装了没反应」。

ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

# 其它 Agent 重复一次即可
ai-memory install-hooks --agent codex   --apply
ai-memory install-mcp   --client cursor --apply

# 也可以让 ai-memory 直接拉起 Agent
ai-memory run claude
ai-memory run codex

零配置就能用：捕获、检索、注入简报、交接都不需要任何 API Key。想让会话摘要写得更像人、或者想要语义检索，再配一个模型服务商（官方支持 Anthropic、OpenAI、Gemini、GitHub Copilot，以及 Ollama、LM Studio 这类 OpenAI 兼容端点）。还有一个可选的 dream 能力，会在空闲时把冷笔记整理成更干净的页面，默认关闭，且不会删掉原始内容。

在一个已经有几个月历史的项目上装 ai-memory，wiki 是空的，头几次会话你只往里填、不从里取，体感是净亏——很多人就是在这个阶段判定它没用然后卸载的。官方给的答案是 bootstrap：它收集你的提交历史、README、docs 与模块头，交给模型生成一批种子页，让第二天的会话就有东西可检索。官方给出的体感成本约 0.05 美元量级（输入上限 5 万 token），但一定先跑 --dry-run 看看会发出去什么。

cd ~/Projects/my-project
ai-memory bootstrap --dry-run    # 先看会发什么，不花钱
ai-memory bootstrap              # 用 git log / README / docs 生成种子页

播种之后还有一个使用习惯值得养成：让记忆里留下「结论」而不是「流水」。一句「本项目的鉴权走 X，Y 方案在 9 月验证过会挂，别再用」的价值，远大于二十条工具调用记录。你会慢慢发现，能被检索到的决策理由越多，Agent 重复踩坑的次数越少。

跑一个真实任务，做完之后正常退出会话——注意是正常结束，钩子在会话结束时才整理。然后同一个目录里另开一个会话，直接问「你还记得这个项目上次做了什么吗」。召回的详略是随时间自适应的：距上次会话不到一小时只回一行，超过三十天则给一份相对完整的回顾。这个自适应很关键，它保证日常高频切换时不会每次都被灌一大段简报。

# 会话 A（Claude Code）
> 记住：这个项目的鉴权走 X，别再用 Y 方案了，9 月验证过会挂
…（做了一轮修改）…
> /exit

# 同一目录，几小时或几天后（换成 Codex）
$ codex
> 接着上次继续，先说说你现在了解的情况

三条验收标准：新会话开头出现一段简短简报；能全文检索到上次提到的决策与失败方案；wiki 目录里多出可读的 Markdown 页。三条都满足才算接对了。只有前两条而没有第三条，说明你没有写权限或数据目录挂错了；只有第三条没有前两条，通常是钩子没装上或者客户端没重启。

真正的杀手锏是交接：会话结束时，工具会把这次没做完的事整理成一条带类型的记录，里面有未决问题与下一步建议，并且带 owner、被认领一次后即失效。这个机制解决的是多 worker 抢同一份待办的问题，是多数记忆工具没有的并发原语。换机器同理：把服务端跑在一台常开的机器上，其它机器的客户端配好令牌，就能共用同一份 wiki。

# 本机升级（包装脚本 + 镜像 + 钩子脚本，幂等）
ai-memory upgrade

# 服务端在别的机器上时，本地只更新客户端
ai-memory install-mcp --client claude-code --apply

日常使用中，跨项目还有一层收益：项目级的约定可以被抽成跨项目档案，把团队的包管理器、测试目录结构、架构偏好带进每一个新仓库。新人或新 Agent 打开任何项目，都能先拿到这套通用约定，再叠加项目自身的记忆。

常用的就四条命令：lint 找矛盾与过期页，并提示哪些结论该提升进 CLAUDE.md 之类的规则文件；backup 打包数据目录（wiki 加 SQLite），restore 回滚；rename-project 改名，只动一列数据与一次目录改名；purge-project 清掉整个项目，原子操作，不会波及邻居项目。升级用 ai-memory upgrade，它会同时刷新包装脚本、镜像与钩子脚本。

ai-memory lint                                   # 找矛盾、过期页
ai-memory backup                                 # 打包数据目录
ai-memory restore                                # 回滚
ai-memory rename-project --from old --to new
ai-memory purge-project --project xxx --confirm  # 原子删除单个项目

最后提醒两件事。一是平台：Linux、macOS、NixOS 与 WSL2 是受支持的，原生 Windows 仍标注为实验性，Windows 用户请走 WSL2。二是预期管理：项目公布的召回指标是作者自测结果，且明确说明与 Mem0、Zep 公布的端到端问答准确率不是同一种口径，不要拿来横向比较。稳妥的做法是先在一个小项目上跑两周，把 backup 排进日常，再决定是否推广到团队。