agentmemory:给 AI 编程助手装一个可搜索的长期记忆

这两天看 AI Agent 记忆相关项目时，我发现了一个挺有意思的开源项目：agentmemory。

它的目标很直接：让 Claude Code、Codex、Hermes、Cursor 这类 AI 编程助手，能跨会话记住项目里发生过什么。

听起来像“长期记忆”这个老概念。但我看完之后，真正吸引我的不是这个词，而是它选择的实现方式。

它没有把记忆做成一个更大的 MEMORY.md，也不是让模型自己维护一份越来越长的笔记。它更像是在 Agent 后面挂了一个小型记忆基础设施：自动捕获工具调用和会话，压缩成结构化观察，再用 BM25、向量和知识图谱去检索，最后只把最相关的一小段上下文塞回下一次会话。

这件事如果做对了，AI 编程助手的使用方式会有一点变化：我们不用每次都从零解释“这个项目怎么跑”“上次为什么选这个库”“那个坑之前怎么修过”。

AI 助手真正缺的不是“记住”，而是“该想起时想起”

现在很多 Agent 已经有记忆机制。

Claude Code 有 MEMORY.md，Cursor 有 rules / notepads，很多工具也会让你写项目说明。它们很有用，但本质上更像便签：适合放少量长期规则、偏好和项目约定。

问题在于，真实项目里的记忆不是几条规则。

它可能是：

• • 某次鉴权方案为什么从 jsonwebtoken 换成了 jose；
• • 某个测试为什么不能删；
• • 某个接口字段其实是历史包袱；
• • 上次部署失败是因为环境变量，而不是代码；
• • 你偏好先写验证脚本，再让 Agent 改实现。

这些东西都不是“永远要放进系统提示词”的内容。它们只在某个具体问题出现时有价值。

所以 Agent memory 的核心问题，不是“能不能多存一点”，而是：能不能在正确的问题上，把正确的旧上下文找回来。

这也是 agentmemory 的主线。

它不是记忆文件，而是后台记忆引擎

按项目文档，agentmemory 当前发布版本是 0.9.18，包名是 @agentmemory/agentmemory，Apache-2.0 许可证。

最小启动方式很简单：

npx @agentmemory/agentmemory

启动后，本地会有几个核心入口：

• • REST API：默认在 http://localhost:3111/agentmemory/*
• • 实时 viewer：默认在 http://localhost:3113
• • MCP shim：通过 npx -y @agentmemory/mcp 暴露给各类 MCP 客户端
• • iii console：用于看底层函数、状态、trace 和队列

如果接到 Hermes，可以在 ~/.hermes/config.yaml 里加 MCP server，并把 memory provider 指到 agentmemory。更深一点的方式，是把 integrations/hermes 复制成 Hermes plugin，让它参与 pre-LLM context injection、turn capture、MEMORY.md mirroring 和 system prompt block injection。

这说明它不是只服务某个 Agent 的插件，而是试图做成一个共享记忆层。Claude Code、Codex、Hermes、Cursor、Gemini CLI 等都可以通过 hooks、MCP 或 REST 接同一个后台。

这个方向我觉得是对的。

以后一个开发者很可能同时用多个 Agent：一个在终端里改代码，一个在 IDE 里补测试，一个在浏览器里查文档。如果每个 Agent 都维护自己的孤立记忆，最后会变成多个小脑袋各记各的。agentmemory 想做的是，把这些记忆收拢到同一个检索系统里。

记忆管线：先捕获，再压缩，再检索

项目文档里给出的 memory pipeline 大概是这样：

PostToolUse hook fires
  -> SHA-256 dedup
  -> Privacy filter
  -> Store raw observation
  -> LLM compress
  -> Vector embedding
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction

SessionStart hook fires
  -> Load project profile
  -> Hybrid search
  -> Token budget
  -> Inject into conversation

这条管线有几个关键点。

第一，它尽量自动捕获，而不是要求用户手动 add memory。

真实使用里，手动记忆很难坚持。你刚修完一个 bug，大概率不会停下来认真写“这次经验应该保存”。所以 agentmemory 通过 lifecycle hooks 捕获 UserPrompt、PreToolUse、PostToolUse、Stop、SessionEnd 等事件，把工具调用、文件访问、错误上下文和会话摘要都作为原始观察进入系统。

第二，它不是把原始日志原样塞回上下文。

原始工具输出太长，也太脏。agentmemory 会先做去重、隐私过滤，再把 observation 压缩成结构化事实、概念、叙事和重要性。后续检索用的是这些结构化记忆，而不是每次翻一大堆历史日志。

第三，它把记忆分成几个层级。

文档里用了四层：working、episodic、semantic、procedural。粗略理解就是：工具调用的短期观察、会话级摘要、抽取出来的事实和模式、以及可复用的流程/决策习惯。

这比“把所有东西写进一个文件”更接近真实工作方式。不是所有记忆都应该同等重要，也不是所有记忆都应该永远保存。项目还实现了 decay、auto-forget、supersession、audit trail 等机制，说明它在考虑记忆生命周期，而不只是存储。

检索：BM25 + 向量 + 图，而不是只靠 embedding

agentmemory 的搜索不是单一路径。

源码里的 HybridSearch 会先跑 BM25，再在有 embedding provider 的情况下跑向量检索，同时根据 query 里的实体做图检索。最后用 RRF（Reciprocal Rank Fusion）融合排名，并限制同一个 session 不要霸占太多结果。

这点挺务实。

很多人一提长期记忆，第一反应就是“上向量数据库”。但项目记忆里有大量代码文件名、函数名、错误码、命令、路径，这些东西用关键词检索反而很强。BM25 能抓精确词，向量能抓语义相近，知识图谱能把实体和关系拉出来。三种信号叠在一起，比单纯 embedding 更稳。

它默认推荐本地 embedding：all-MiniLM-L6-v2，不需要 API key。也支持 Gemini、OpenAI、Voyage、Cohere、OpenRouter 等 provider。对中文/日文/韩文，README 里还提到可以安装可选分词器，让 BM25 不只是按整段 CJK 文本粗切。

这里有一个实际判断：如果你的 Agent 主要处理代码项目，混合检索比纯语义检索更合适。因为代码世界里，一个文件名、一个错误码、一个 middleware 名字，往往就是最关键的线索。

上下文注入：真正进入模型的，只是一小段预算内记忆

我还看了它的 mem::context 实现。

这个函数做的事很关键：它不是把所有搜索结果都扔进去，而是按 token budget 组装上下文块。

它会优先拿几类东西：

• • pinned memory slots；
• • 当前 project profile，比如 top concepts、key files、conventions、common errors；
• • lessons learned；
• • 最近相关 session summaries；
• • 没有 summary 的 session 里重要性较高的 observations。

然后按 recency 排序，在预算内逐块加入，最后输出一个类似：

<agentmemory-context project="...">
  ...
</agentmemory-context>

这和静态 memory file 的差异很大。

静态文件的问题是：要么太短，很多历史丢了；要么太长，每次都占上下文。agentmemory 的思路是：历史可以很大，但进入模型的永远只是一小块。这一小块由检索、项目画像、经验教训和预算共同决定。

最近 0.9.18 还修了一个闭环：lessons 以前生成后存进 KV，但 Agent 通常不会主动调用 memory_lesson_recall。现在 lessons 会自动进入 mem::context 的候选块，按 project relevance 和 confidence 排名，最多取前 10 条。这个改动很小，但方向是对的：记忆不是“存了就算”，必须能在下一次行动前自动浮出来。

Benchmark 要看，但要看懂口径

agentmemory README 里最显眼的数字是 LongMemEval-S retrieval：BM25+Vector 的 R@5 95.2%、R@10 98.6%。

这个数字不错，但要注意口径。

项目自己的 benchmark 文档写得比较清楚：这是 retrieval recall，不是端到端 QA accuracy。也就是说，它评估的是“gold session 有没有出现在 top-K 检索结果里”，不是“模型最终有没有答对问题”。

这点很重要。很多 memory 项目容易把 retrieval benchmark 讲成“记忆能力满分”，但真正应用里还要看后面的 reader model、上下文拼接、冲突处理和回答质量。

不过这个 benchmark 仍然有价值。它至少说明：在 LongMemEval-S 这种多会话检索场景里，agentmemory 的混合检索能把相关会话比较稳定地找出来。

另一个更贴近工程的问题是规模。

项目的 scale benchmark 里，50,000 条 observations 时，内置 memory 如果全量进上下文，理论 token 会到 2,216,173；agentmemory top-10 检索结果约 1,981 tokens，基本不随语料规模增长。混合搜索延迟文档里记录为约 108ms。

这些数字不用迷信，但方向很明确：当项目历史从几十条变成几千条时，“把记忆都放进上下文”会失效，检索层会变成刚需。

它适合谁？不适合谁？

我会把 agentmemory 的适用场景分得比较窄一点。

如果你只是偶尔让 AI 帮你写一段脚本，或者一个项目只用一两个短会话就结束，那它可能有点重。维护一个记忆服务、MCP 配置、viewer、iii-engine，对轻量用户来说不一定划算。

但如果你已经有这些情况，它就值得试：

• • 一个项目持续用 AI 改几周甚至几个月；
• • 经常跨会话恢复上下文；
• • 同时使用 Claude Code、Codex、Cursor、Hermes 等多个 Agent；
• • 你希望 AI 记住真实踩坑，而不是只记住抽象偏好；
• • 你在意审计、删除、隐私过滤和可视化观察。

它尤其适合“AI coding agent 重度用户”。因为这类用户的问题不是不会写 prompt，而是项目上下文会持续累积，单个会话装不下，单个 memory file 管不过来。

当然，风险也要看清楚。

第一，项目仍然是 0.9.x，还没到 v1.0。REST / MCP surface 未来可能继续变化。

第二，它依赖 iii-engine 这套底层运行时。这个选择让它获得 functions、triggers、KV、streams、traces 等能力，但也意味着你不只是装一个 npm 包，还要理解背后的 engine。

第三，隐私过滤不是免死金牌。README 和 changelog 里提到会在存储前过滤 secrets、API keys、PEM private key、JWT 等，但我仍然不建议一开始就把公司敏感仓库和生产凭证环境接进去。先拿个人项目试，确认行为和数据落点，再考虑更严肃的使用。

我会怎么试

如果只是想体验，最小路径是：

npm install -g @agentmemory/agentmemory
agentmemory
agentmemory demo

然后打开：

http://localhost:3113

先看 viewer 里 memory 是怎么被捕获和检索的。

如果你用 Hermes，大致是把 MCP server 加到 ~/.hermes/config.yaml：

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

如果只看到 7 个 MCP tools，通常不是坏了，而是 MCP shim 没连上正在运行的 agentmemory server。README 里写得很清楚：@agentmemory/mcp 在能访问 AGENTMEMORY_URL 时才代理完整 51 tools；连不上时会退回本地 7 tools。

这个项目真正值得看的地方

我觉得 agentmemory 最值得看的，不是某个具体功能，而是它代表了一个趋势：AI Agent 的长期能力，不可能只靠模型上下文窗口变大来解决。

上下文窗口再大，也不应该把所有历史都塞进去。真实工作里的记忆需要分层、检索、衰减、审计、删除、共享和可观察。

换句话说，Agent memory 会从“提示词里的几段文字”，慢慢变成一个独立基础设施。

agentmemory 现在还不是最终答案，但它已经把几个关键问题放在同一张桌子上了：自动捕获、混合检索、上下文预算、跨 Agent 共享、viewer、MCP/REST、隐私过滤和生命周期管理。

这比单纯做一个“更聪明的记忆文件”有意思得多。

如果你已经把 AI 编程助手当成日常 worker，而不是偶尔问答工具，我建议拿一个个人项目试一下。不是为了立刻替换所有 memory 机制，而是看看：当 AI 不需要每次从零认识你的项目时，协作体验会不会真的变轻。

项目地址：

• • GitHub：https://github.com/rohitg00/agentmemory
• • npm：https://www.npmjs.com/package/@agentmemory/agentmemory