用 Claude Code 写代码的人，终于不用每次开新会话都从头解释项目背景了。
我们就借着 Claude-Mem 这个爆火项目，系统聊聊：为什么 AI 编程助手必须要'长期记忆'？Claude-Mem 具体怎么实现？它在工程上有什么值得借鉴的地方？以及，它的边界和未来会走向哪儿？
一、概述
先说清楚，这篇文章主要写给三类人看：
- 日常在用 Claude Code / VS Code AI 插件写代码的开发者。
- 正在做 Agent、工具调用、RAG 等方向的工程师和研究者。
- 对 AI 编程效率有兴趣、想弄清楚'AI 记忆系统'到底咋做的技术爱好者。
我们围绕一个核心问题展开： 如何用一个开源插件，把'金鱼记忆'的 Claude Code，改造成年纪再大也记得你项目细节的'老同事'？
二、痛点：为什么 AI 编程助手必须要'长期记忆'？
2.1 日常真实场景有多难受？
举一个很多人都经历过的场景：
- 周一，你和 Claude 反复讨论微服务架构、数据库分片、接口约定。
- 周二，为了修紧急 Bug，临时切到另一个分支处理。
- 周三回来接着做架构，Claude 一脸懵：这是什么项目？之前聊过啥？
你被迫重新解释项目背景、模块划分、约定规范。这些本来应该是'共享上下文'的东西，每次新会话都要重来一遍。
GitHub 上也有人在 issue 里直接把这种体验称为'重大工作流程中断'，并明确提出要'跨会话持久记忆'能力。
2.2 问题本质：每次会话都是一张白纸
AI 编程助手现在广泛存在几个共性问题：
- 会话级记忆：只记得当前窗口的一次对话，关掉就没了。
- 上下文窗口有限：长项目只能塞一部分历史进去，越用越乱。
- 工具调用受限：为了省 Token，你不敢'什么都扔进去'。
本质上，现在多数 IDE 插件的记忆方式是'短期 + 纯上下文'，而不是'长期 + 按需召回'。
这会带来几个直接后果：
- 项目一旦跨天，重复解释成本非常高。
- 长期演进的设计决策，难以被系统化保留与回溯。
- 多人协作场景中，新加入的人无法顺畅接上历史上下文，只能靠人肉补档。
2.3 开发者已经开始'自救'
GitHub 上已经出现不少自建方案：memory-mcp、mcp-memory-keeper、rlm-claude 等。
这些项目说明两件事：
- 痛点是真痛，不是个别人的'矫情'。
- 现有官方能力不够用，社区已经开始自己想办法'给 AI 装记忆'。
Claude-Mem 恰好踩在这个需求点上：专门针对 Claude Code 做跨会话持久记忆，而且是免费开源，装完就能用。
三、Claude-Mem 是什么？
用一句话概括 Claude-Mem：
这是一个给 Claude Code 用的本地持久化记忆插件，通过事件驱动 + 混合存储 + 三层渐进式检索，把你和 AI 一起做过的事，压成结构化'长期记忆'，在后续会话中按需注入，同时大幅减少 Token 消耗。
几个关键信息：
- 它是开源项目，由 @thedotmack 开发，专为 Claude Code 设计。
- 截至近期，GitHub Star 超过 2.2 万，持续霸榜 Trending。
- 官方宣传的数据是：常规场景节省约 90% Token，'无尽模式'最高可达 95%，工具调用上限提升约 20 倍。
对于习惯用 GitHub 看热度的人来说，一个'记忆插件'能涨到这个量级，已经说明它不只是'玩具小工具'，而是踩到了真实需求。
四、整体架构：它怎么把'碎片操作'变成'长期记忆'？
Claude-Mem 的整体思路，可以拆成三步：
- 监听会话生命周期，自动捕获有价值的观察记录。
- 利用本地数据库和向量库做混合存储，为后续检索打好基础。
- 在新会话里，通过三层渐进式披露，按需注入相关记忆，避免 Token 爆炸。
4.1 事件驱动：在不打扰你的情况下，捕获所有关键动作
Claude-Mem 内部挂了 5 个生命周期钩子：
| 钩子 | 触发时机 | 作用 |
|---|---|---|
| SessionStart | 会话启动 | 初始化检索和上下文准备 |
| UserPromptSubmit | 用户提交问题时 | 记录用户意图和上下文 |
| PostToolUse | 工具调用完成之后 | 捕获文件读写、代码改动等 |
| Stop | 任务暂停 | 保存中间状态 |
| SessionEnd | 会话结束 | 触发总结、压缩与入库 |
这些钩子有几个特点：
- 对用户来说几乎是'隐形'的，不需要改变现有使用习惯。
- 重点记录的是'工具使用带来的变化'，比如改了哪些文件、执行了什么命令，而不是一股脑儿把所有聊天记录都存下来。
- 把这些东西统称为'观察记录'（Observations），类似一个时间序列的项目事件日志。
这一步解决的是：怎么把人机协作过程变成结构化、可追溯的历史，而不是散落一地的对话记录。
4.2 本地混合存储：结构化 + 全文 + 语义
Claude-Mem 的存储设计也比较'务实'：
- 使用 SQLite + FTS5：
- 存结构化数据（会话 ID、文件路径、时间戳、操作类型等）。
- 做全文检索（像搜索日志一样搜关键词）。
- 使用 Chroma 向量库：
- 把摘要、重要片段向量化，用来做语义检索。
- 适合处理'模糊问题'，比如'上周讨论的那个支付风控策略'。
所有数据统一存放在用户本地目录 ~/.claude-mem/ 下，不走云端服务，这点对隐私敏感行业（金融、医疗）比较重要。
从工程角度看，这套组合有几个优势：
- 部署成本低：不需要额外起一套服务，SQLite + 本地向量库就够用。
- 查询灵活：结构化筛选（按时间、项目）+ 全文 + 语义，可以随场景组合。
- 用户可见可控：目录是本地的，想备份、加密、甚至手动清理都可以。
4.3 记忆压缩：别把'原始流水账'端给模型看
只存是第一步，更关键的是：会话结束时，要把大量零散的观察记录压成模型看得懂、又不费 Token 的摘要。
Claude-Mem 在 SessionEnd 阶段会调用 Claude Agent SDK，把会话中累计的 Observations 汇总成结构化摘要，典型包含四块：
- 调研内容：查了哪些方案、看过哪些资料。
- 学习成果：最后采纳了什么认知结论。
- 已完成工作：改了哪些代码、做了哪些重构、修了哪些 Bug。
- 后续步骤：下一步建议做什么，是否有 TODO 留下。
这一步的关键是：不再把完整的原始历史直接塞进上下文，而是只注入高度浓缩后的'记忆索引 + 摘要'。
它为后面的'渐进式披露'打好了基础。
五、三层渐进式披露：Token 成本怎么砍到 95%？
Claude-Mem 的核心创新，总结为'三层渐进式披露'（progressive disclosure）。
简单理解：不是一开始就把所有历史端给模型，而是分三层，按需解锁。
5.1 三层结构长什么样？
| 层级 | 主要内容 | Token 开销（大致） | 使用场景 |
|---|---|---|---|
| 第一层：Search | 摘要级索引与概要 | 约 50–100 / 结果 | 快速定位相关历史 |
| 第二层：Timeline | 会话 / 事件时间轴 | 中等开销 | 理解前后因果 |
| 第三层：Get_Observations | 完整观察记录详情 | 约 500–1000 / 结果 | 深挖实现细节、重现过程 |
大致流程可以想象成这样：
- 用户在新会话发起问题，比如'接着上周的支付风控策略，帮我补充风控规则'。
- 插件先在本地做 Search，找出最相关的一些历史摘要（这一步开销很小）。
- 如果当前任务需要更多上下文，再拉对应时间段的 timeline，看看前后做了什么。
- 若还不够，最后才会调用 Get_Observations，把当时的具体操作记录（文件改动、命令输出等）拉进上下文。
5.2 为什么这种设计能大幅省 Token？
如果没有这三层，常规做法有几种：
- 暴力法：直接把过去几天的对话和改动全扔给模型看，Token 爆炸。
- 手动挑：开发者自己翻历史，复制粘贴上下文 —— 太累，而且容易漏。
三层渐进式披露，本质上是把'召回'和'注入'这两步拆开，优先只注入压缩后的高价值摘要。
- 常规使用场景下，大约可以节省 90% 左右的 Token。
- 在'无尽模式'（项目持续很久、记忆特别多）下，最高可以节省 95%。
- 因为 Token 压力下降，工具调用上限也可以放宽到原来的 20 倍量级。
对开发者来说，体感上就变成：同样的预算，AI 可以陪你做更长时间的活，而且不会越用越'傻'。
六、实战效果：在不同场景里能带来什么变化？
几个实测和反馈场景，我们可以按使用者身份来拆开看。
6.1 企业团队：复杂项目里的'团队记忆库'
在大型代码库、多团队协作的企业场景，Claude-Mem 能做的事包括：
- 持续记录模块设计的演变过程，知道为什么当时选了方案 A 而不是方案 B。
- 跟踪缺陷修复：这个 Bug 曾经怎么排查、怎样验证过。
- 给新同事一个'可查询'的历史上下文，而不是光靠问人。
有团队反馈过这样的数字：
- 新人上手时间缩短约 40%。
- 代码评审效率提升约 25%。
对于动辄数月、多人接力的企业项目来说，这种提升是实实在在的： 记忆系统不是多一个'功能点'，而是让 AI 真正融入现有协作流程。
6.2 个人开发者：长线 side project 的'自动笔记助手'
对一个长期在搞 side project 的个人开发者，Claude-Mem 带来的变化会更直接一些：
- 你可以用自然语言直接问之前的决策，比如：'上周我重新设计过登录流程，当时用了什么鉴权策略？'
- 插件可以帮你回溯出当时讨论过的选项、最终采用的方案，以及改动的代码范围。
- 打开本地 Web 界面（默认是
http://localhost:37777），能实时看到记忆流和会话摘要，类似'项目日记自动生成版'。
这对很多'间歇性推进'的个人项目尤其友好 —— 哪怕你中间停了两周，回来之后不会全靠自己翻 Git commit 和脑补。
6.3 隐私敏感行业：合规边界怎么守？
在金融、医疗这类对隐私特别敏感的行业，大家最担心的是：
- '这些数据会不会上传到云端？'
- '有没有可能误把敏感信息存进记忆里？'
Claude-Mem 的做法主要有两点：
- 数据全部本地存储，而且目录可见、可控。
- 支持标签机制，可以给某些内容打上'不要记录'类标签，阻止敏感信息被纳入记忆。
这意味着你可以根据项目和合规要求，自定义'能记什么、不能记什么'，而不是一刀切地'要么全记，要么全不记'。
七、安装与使用体验
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
执行完插件安装后，重启 Claude Code，大部分功能就能直接用上。
对普通开发者来说，有几点体验上的好处：
- 无需改动现有工作流，不用写额外脚本。
- 无需部署额外服务，不用自己搭一套后端。
- 多数配置有合理默认值，用起来更像'开关一个功能'，而不是做系统集成。
当然，如果你想进一步定制（比如不同项目用不同记忆策略），就需要了解一些配置项和阈值设定，这对高级用户来说也是可控的工程成本。
八、和其他方案对比：它到底好在哪儿？
几个常见的'替代方案'，我们可以稍微整理成一张表：
| 方案类型 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 传统 RAG 系统 | 功能强大，可接多种数据源 | 部署复杂，依赖额外基础设施 | 企业内部知识库 / 大型系统 |
| 简单文件注入 | 实现容易，维护成本低 | 缺乏智能检索，容易信息过载 | 小项目、一次性任务 |
| 手动复制粘贴 | 不需要额外工具 | 非常耗时，无法扩展 | 偶发需求，临时补充上下文 |
| Claude-Mem（现状） | 本地混合存储 + 渐进式披露 | 依赖 Claude Code 生态，需调阈值 | Claude 用户，日常持续开发项目 |
从工程折中来看，Claude-Mem 走的是一条'中等复杂度'的路线：
- 比简单注入和手动复制强得多：有检索、有结构化、有自动摘要。
- 又比全自研 RAG 系统轻量很多：不用搭服务、不用管集群和运维。
这也是为什么很多人把它称为：在 IDE 内部实用层面，目前最接地气的一种长期记忆方案。
九、局限与风险：它不是'万能记忆药丸'
Claude-Mem 的几个局限，展开讲一下，方便评估是否适合自己的场景。
9.1 摘要质量取决于底层模型
记忆压缩是靠 Claude Agent SDK 来做的。 这意味着，在极端复杂场景下（比如几十个相关模块、跨多团队改动），摘要可能会出现信息遗漏或侧重点不太符合预期的问题。
所以在一些关键决策类项目中，仍然有必要保留人类写的设计文档和决策记录，不能完全依赖自动摘要当'唯一真相来源'。
9.2 对版本和生态有一定依赖
因为它是为 Claude Code 量身定制的插件，所以：
- 需要较新的 Claude Code 版本支持对应插件机制。
- IDE 和插件生态更新时，可能会遇到兼容性问题，需要跟进升级。
这对走企业大规模部署的团队来说，需要在内部有一套插件版本管理和回滚机制，不然遇到版本冲突会比较头疼。
9.3 需要一点'调参意识'
虽然默认配置可以直接用，但要在复杂项目里用得顺手，多少需要调一下参数，比如：
- 检索阈值：相关度多少以上的记忆才注入？
- 注入上限：一次允许带入多少条历史？
- 不同项目是否需要单独命名空间或标签？
这些都关系到：既要让 AI 记得你，又不要记得太多，把上下文弄成'信息垃圾场'。
