你的AI编程助手,为什么总是“失忆”?

35,000 token的历史记忆，真正有用的可能不到6%。这个开源项目用“渐进式披露”把上下文消耗压到了原来的1/40

用Claude Code写代码的人，大概都经历过这种落差：

昨天花了一整天，和AI把架构敲定、把踩过的坑一个个标出来、把测试失败的根因定位清楚。今天重新打开终端，它像第一次见到你一样，项目背景要重讲，架构约束要重说，昨天刚否决的方案，今天它又兴致勃勃地提了出来。

这不是模型变笨了，而是它的“记忆”天生只有一次会话的寿命。你把上下文窗口关掉的那一刻，所有积累就清零了。

社区开发者 Alex Newman（@thedotmack） 做了一件事：给Claude Code从外部装上一层持久化记忆系统。项目叫 claude-mem，目前GitHub Star已超过10万，是Agent记忆领域星标最高的工具。

项目地址：https://github.com/thedotmack/claude-mem

它不做全量存储，它做“压缩后再给索引”

claude-mem最容易误解的地方，是把它当成“聊天记录存档”。它的核心逻辑恰恰相反：不存原始对话，存AI压缩后的“观察” 。

整个流水线可以拆成四段：

捕获 → 压缩 → 存储 → 注入

捕获靠的是Claude Code的生命周期钩子。claude-mem注册了 SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd 等7个钩子，其中 PostToolUse 负责在每次工具调用结束后，把“读了什么文件、写了什么代码、执行了什么命令”抓下来。Claude Code是闭源二进制，改不了内部，所以只能从外部观察——这也是钩子架构存在的根本原因。

压缩是整套系统最关键的环节。原始的工具调用记录动辄几十万token，直接存下来再塞回去，等于把“失忆症”换成了“上下文污染”。claude-mem用另一个Claude实例（Observer Agent）去读这些原始记录，提取出决策、bugfix、安全警报、测试失败结论、架构约束这类“以后还会影响判断”的知识单元，丢掉闲聊和重复内容。

存储走混合路线：结构化数据和全文检索用 SQLite + FTS5，可选的语义检索用 Chroma 向量库。全部数据落在本地的 ~/.claude-mem/ 目录下，不上云。

注入才是真正拉开差距的地方。

渐进式披露：先给目录，别塞全文

传统RAG的做法是：新会话一开始，把检索到的历史信息一次性全量注入。一篇深度分析算过一笔账：这样一次性注入约 35,000 token 的历史上下文，其中真正和当前任务相关的只有约6%——94%的注意力预算被浪费了。

claude-mem的做法借鉴了信息架构里的 Progressive Disclosure（渐进式披露） ：会话开始时，只给Agent一份紧凑的索引（大约800 token），每条记录只包含ID、时间、标题和极短的摘要。Agent看到索引后，自己决定要不要展开某一条，展开一条的成本大约是120 token。

按这个设计，原本35,000 token的全量注入，被压缩到约920 token——节省超过97%。官方文档把这个模式概括为一句话：“故意披露几条，叫渐进式披露；默认全量披露，只是换了个更大的聊天记录”。

这个设计的价值不只在省token。它把“该看什么”的控制权交还给了Agent本身，而不是由检索系统替它做一次性的判断。对于需要跨天、跨周跟踪同一个项目的场景，这意味着Agent每次进入新会话时，拿到的是一张可导航的地图，而不是一箱未经分拣的旧文件。

两种用法：自动记忆 + 主动搜索

装上claude-mem之后，日常使用几乎是“无感”的。你不需要改变写代码的习惯，正常和Claude Code对话，记忆在后台自动捕获和压缩。下次开新会话时，最近的会话摘要会自动出现在上下文里。

如果你想主动翻旧账，可以用 mem-search 技能做自然语言检索。比如直接问：

“上周修复的登录超时问题，具体改了哪些文件？”

claude-mem会检索对应的观察记录，返回当时修改的文件和关键决策。官方提供了4个MCP搜索工具，遵循同样的三层渐进式披露流程：先拿索引，再按ID取详情，需要时才拉完整记录。

此外还有一个本地Web UI（默认端口37777），可以实时查看记忆流、会话摘要时间线和Token消耗统计。

安装：一行命令，但别装错

最简单的安装方式是在Claude Code终端里通过插件市场：

text

/plugin marketplace add thedotmack/claude-mem/plugin install claude-mem

或者直接用npx安装启动器：

bash

npx claude-mem install

这里有一个必须注意的坑：npm install -g claude-mem 只安装SDK/library，不会注册插件钩子，也不会启动worker服务，装完等于没装。官方明确推荐的路径是 npx claude-mem install 或插件市场安装，安装完成后重启Claude Code才会生效。

环境要求是 Node.js 20+，运行时需要 Bun ≥1.0 来跑worker。

几个需要诚实告诉你的问题

claude-mem迭代极快，6个月内从v3走到v15，提交超过1,400次。这种速度意味着功能在快速完善，但也意味着稳定性需要自己把关。

社区反馈中比较突出的几个问题：

Token成本可能失控。有Issue报告Observer的prompt出现递归嵌套，payload膨胀到近70万字符，导致token爆炸和预算耗尽。另一个Issue提到19GB的数据库导致prompt过大，触发重试循环，耗尽订阅配额。

记忆污染。错误信息一旦被写入记忆，后续会话会反复引用错误结论，形成“错上加错”的循环。claude-mem提供了 <private> 标签来排除敏感内容，但依赖使用者主动标注。

团队场景的治理问题。单机自用问题不大，但如果接进团队开发链路，token归属、日志保留、谁能读Postgres、API key怎么轮换，都会变成真实的运营问题。

一个实用的验收方法：装完开新会话，只给同一个仓库和后续任务，不提任何前情。如果Agent能主动说出上一轮明确的决策、bugfix或测试失败原因，说明闭环生效了；如果它只会泛泛说“我会参考之前的上下文”，说明记忆链路至少有一段没跑通。

它真正改变的是什么

claude-mem最值得关注的地方，不是它“记住了更多”——而是它重新定义了“记住”这件事在Agent系统里的实现方式。

它的创始人有一个判断：Agent的上下文不是越多越好，而是一个“注意力预算”的经济学问题。传统方案把记忆等同于“把历史塞回去”，claude-mem把记忆拆成了三层：原始记录留在库里，压缩后的观察作为可检索的知识，上下文里只放一张让Agent自己导航的索引。

这个模式不只适用于Claude Code。任何需要在长周期任务中保持连续性的Agent系统，都会面对同样的取舍：你是把一切塞进窗口，还是让Agent学会在需要的时候自己去拿？

claude-mem选了后者。至于这条路能走多远，v15的迭代速度会给出答案。

GitHub地址：https://github.com/thedotmack/claude-mem

官方文档：https://docs.claude-mem.ai