ai-memory：给 AI 编码代理装上跨厂商的长期记忆

它解决的是代理切换时的上下文断裂

AI 编码代理的痛点很具体：你在 Claude Code 里干到一半，换到 OpenAI Codex 继续，结果新代理对项目架构一无所知。ai-memory 的定位就是解决这个断裂。它把对话历史、失败尝试、未决问题沉淀成可复用的记忆，然后在下一个代理启动时注入。目标用户是那些会在多个代理 CLI 之间切换的开发者，尤其是同时使用 Claude Code、Codex、Gemini CLI 这类工具的人。它不是一个通用的记忆数据库，而是专门为代理生命周期设计的。

MCP 加生命周期钩子，两条腿走路

ai-memory 的机制分两层。第一层是 MCP 配置，代理通过 Model Context Protocol 访问记忆服务，可以查询和写入记忆条目。第二层是生命周期钩子，代理在会话开始、结束、工具调用失败等事件时触发 ai-memory 的命令，自动捕获上下文。比如 Claude Code 支持通过 install-mcp --session-aware 启用按会话隔离，而 Kimi Code 则通过 10 个钩子事件（包括子代理启停和 PostToolUseFailure）来捕获工具失败。数据流大致是：钩子捕获事件，ai-memory 把关键信息写入本地存储，下次会话开始时通过钩子或 MCP 注入交接摘要。这个设计的好处是，即使代理本身没有原生记忆功能，也能通过外部钩子获得类似能力。

安装与配置：命令具体，但代理差异大

安装方式因平台而异。Linux 上有 Docker 镜像和 Arch/AUR 包，macOS 有原生二进制，Windows 则要依赖 WSL2。核心命令是 install-mcp 和 install-hooks。比如为 Grok Build CLI 安装，你需要运行 ai-memory install-mcp --client grok，它会写入 $GROK_HOME/config.toml（默认 ~/.grok/config.toml），然后运行 ai-memory install-hooks --agent grok，写入 ~/.grok/hooks/ai-memory.json。对于 Codex，因为没有自动的会话结束钩子，你需要手动运行 ai-memory finalize-session 来生成最终摘要。每个代理的配置路径和钩子事件都不同，README 里有一张很长的支持矩阵，你必须逐项核对。

支持矩阵的坑：不是所有代理都平等

表面上看支持 15 种以上的代理，但细看会发现支持程度参差不齐。Claude Code 和 Command Code 有完整的生命周期钩子，包括会话结束捕获。但 Codex 没有真正的会话结束钩子，你得手动 finalize-session。Grok Build CLI 会忽略 SessionStart 的 stdout，所以无法通过钩子注入交接，只能靠 MCP 的 memory_handoff_accept 来恢复。Zero 和 Grok 类似，也会丢弃 sessionStart 输出。Antigravity CLI 只有 PreInvocation 且 invocationNum = 0 时才映射到 SessionStart，后面的模型调用无法消费交接。Swival CLI 则只有 MCP 支持，连生命周期钩子都没有，因为它的回调契约不暴露稳定的会话标识。这些差异意味着，你以为的“支持”可能只是能连接，而不是能完整交接。

managed workstreams：另一种工作方式

除了传统的钩子方式，ai-memory 还提供了 ai-memory run 命令，用于管理跨代理的工作流。它支持 Claude Code、Codex、OpenCode、Pi、Crush、Kimi Code、Command Code、Kiro CLI、OMP、Grok Build CLI 和 Antigravity CLI。这个模式会透明地恢复会话，比如 ai-memory run antigravity 会通过 --conversation 参数恢复工作流。但注意，对于 Antigravity，对话文本不会被解码，所以它的账本只能来自钩子捕获。Crush 是仅托管模式，ai-memory run crush 会恢复其项目本地会话数据库，并通过临时全局上下文文件提供可移植上下文，但没有生命周期钩子安装器。这种设计适合那些不想依赖钩子事件、希望更主动控制会话流程的用户。

局限与失败模式

最大的局限是原生 Windows 支持仍处于实验阶段。虽然发布了 ai-memory-windows-x86_64.zip，但文档明确说“实验性”，并且钩子命令的格式在不同代理间不一致，Claude Code 使用 Windows exec 形式，其他代理使用原生单命令字符串。这可能导致脚本兼容性问题。另一个失败模式是，某些代理没有自动会话结束钩子，如果你忘记手动运行 finalize-session，就不会生成最终摘要，交接就会丢失。还有 capture_assistant 功能，它默认关闭，需要双重启用（安装时加 --capture-assistant，服务端开启 capture_assistant），如果你不知道这个开关，助手最后一轮的重要信息可能不会被记录。最后，项目更新非常频繁，最近三天内发布了 v1.33.1、v1.34.0、v1.35.0 三个版本，这意味着 API 和配置格式可能快速变化，升级成本不可忽视。

替代方案与本质差异

一个直接的替代方案是使用代理自带的记忆功能，比如 Claude Code 的 CLAUDE.md 文件或 Codex 的 AGENTS.md。这些文件是静态的，需要手动维护，但优点是没有额外的运行时依赖。ai-memory 的动态捕获和自动注入是它们没有的。另一个替代方案是使用类似 mem0 这样的通用记忆层，它提供向量检索和语义记忆，但通常不针对代理生命周期钩子做适配。ai-memory 的差异在于它深度绑定各代理的钩子事件，比如 Kimi Code 的 PostToolUseFailure，这是通用记忆库不会去处理的。如果你只需要简单的项目说明，静态文件可能就够了；如果你需要跨代理的自动上下文延续，ai-memory 这类工具才值得考虑。

维护成本与许可证

项目采用 MIT 许可证，可以自由使用和修改，没有明显的商业限制。维护成本主要来自两方面：一是版本更新频繁，你需要定期跟进 release notes，因为配置格式可能变化；二是代理本身的钩子契约可能变化，比如 Kiro CLI 有 v2 和 v3 两种不兼容的钩子注册方式，ai-memory 为它们分别提供了 --agent kiro-cli 和 --agent kiro-cli-v3 目标，这种适配需要持续维护。如果你使用的是小众代理，可能得不到及时更新。另外，项目没有提供官方主页，文档都放在仓库的 docs/ 目录下，比如 docs/macos.md 和 docs/windows.md，你需要自行查阅。

编辑结论

ai-memory 适合那些频繁在多个 AI 编码代理之间切换、且厌倦了每次重新解释项目背景的开发者。它不适合只用单一代理、或者对原生 Windows 有硬性要求的用户，因为原生 Windows 目前只是实验性支持。在采用之前，你应该先确认自己所用的代理是否在支持矩阵中，并且仔细阅读对应文档，特别是那些没有自动会话结束钩子的代理（如 Codex、Kiro CLI），你需要手动运行 ai-memory finalize-session 才能生成交接摘要。另外，capture_assistant 功能默认关闭且需要双重启用，如果你依赖助手最终轮次的记录，务必在安装时加上 --capture-assistant 并在服务端开启对应配置。最后，鉴于项目最近几乎每天都有新版本，升级频率很高，建议固定版本号并关注 release notes 中的行为变化。

官方来源

1. Official README
2. Project repository
3. Release notes