很多人第一次看到 Claude-Mem，都会有一个很直接的问题：

Claude Code 想要“有记忆”，直接把关键信息写进 CLAUDE.md 不就行了？为什么还要单独搞一个项目？

先说结论：

不行，但也不是完全不行。

CLAUDE.md 能解决的是“静态说明书”问题。claude-mem 解决的是“动态长期记忆”问题。两者有交集，但不是一回事。

如果你只是想告诉 Claude Code：项目规范是什么、代码风格是什么、目录结构怎么理解，那 CLAUDE.md 已经很好用了。

但如果你想让 Claude Code 记住：

  • 你上周为什么这么改；
  • 某个技术决策背后的权衡；
  • 哪个 bug 已经踩过坑；
  • 你在某个会话里调试了两小时才定位到的问题；
  • 某个功能做到一半时的中间结论；
  • 多个会话之间的上下文延续；

那单靠 CLAUDE.md 就开始吃力了。但这正是 Claude-Mem 的价值所在。

Claude-Mem 是什么

根据项目仓库 README，Claude-Mem 是一个给 Claude Code 提供跨会话持久化记忆（persistent memory）的插件。它会自动捕获 Claude 在编码会话中的行为和工具使用，把这些内容压缩成可检索的记忆，并在未来会话中把相关上下文重新注入回来。

项目首页对它的描述大意是：

它会自动捕获 Claude 在编码会话中做过的事，用 AI 压缩成记忆，并在后续会话中注入相关上下文。

这句话其实已经把核心说完了：

  1. 自动采集：不是你手工整理。
  2. 压缩整理：不是把原始聊天记录整段塞进去。
  3. 可检索：不是堆成日志后没人能用。
  4. 回注上下文：不是“存了就算了”，而是以后真能拿出来用。

所以它本质上更像：“Claude Code 的项目长期记忆层”。

Claude-Mem 的核心能力

从 README、仓库内置 CLAUDE.md 以及文档说明来看，这个项目主要有几类能力。

1）自动记录 Claude 会话中的关键行为

它不是只记你手写的一段备注，而是会围绕 Claude Code 的会话生命周期做捕获。

项目内置 CLAUDE.md 明确提到它有 5 个生命周期 Hook：

  • SessionStart
  • UserPromptSubmit
  • PostToolUse
  • Summary
  • SessionEnd

这意味着它并不是“会话结束后写个总结”那么简单，而是在会话过程里就能拿到很多有效信息，比如：

  • 用户问了什么；
  • Claude 调用了哪些工具；
  • 做了哪些修改；
  • 会话结束时总结出了什么；
  • 哪些观察值得沉淀成记忆；

这点很关键。

因为真正有价值的“记忆”，很多并不在最后一句结论里，而是在过程中：

  • 试过哪些方案；
  • 哪个方案失败了；
  • 失败原因是什么；
  • 哪个文件看起来相关其实没用；
  • 哪个路径表面可行但会引入副作用；

这些东西，手工维护 CLAUDE.md 很难长期保持完整。

2）把原始过程压缩成可复用的记忆

项目说明里提到，它会使用 Claude Agent SDK 来压缩观察结果，生成结构化、语义化的“记忆”。

换句话说，它不是把整段会话粗暴归档，而是做了一层“提炼”：

  • 什么值得记；
  • 什么只是噪音；
  • 什么和未来最相关；

这一步很像你自己做工作笔记时的动作：

原始记录是流水账，记忆则是“以后还会用到的结论和线索”。

3）支持语义搜索，而不是纯文本 grep

仓库架构里明确提到：

  • 本地数据库用 SQLite；
  • 语义检索用 Chroma 向量能力；
  • 有专门的 Search Skill 用于搜索过去的工作内容；
  • 相关搜索工具会在用户询问“历史上下文”时被自动调用；

这说明它不是只会“字符串匹配”。

比如你问：

  • “上次为什么把缓存层拆开？”
  • “之前那个 SQL 死锁问题是怎么定位的？”
  • “我们在 auth 重构时有没有讨论过 token 刷新策略？”

这种问题，很多时候你并不会记得精确关键词。

如果只是 CLAUDE.md，你得自己翻、自己 grep、自己猜词。

如果是向量检索式记忆，Claude 更有机会靠语义相似度把相关历史捞回来。

4）把相关记忆重新注入未来会话

这是最关键的一步。

很多“记忆方案”只解决“存”，不解决“用”。

Claude-Mem 的目标不是把历史资料堆起来，而是让 Claude Code 在下一次开新会话时，还能尽量延续之前的认知。

也就是说，它想解决的是：

“会话一断，Claude 就像失忆了。”

这才是开发中真正烦人的点。

Claude-Mem 的工作原理

结合项目文档和仓库内置 CLAUDE.md，它的整体链路大致可以理解为：

第一步：监听会话生命周期

Claude Code 会话里的关键节点，会触发插件 Hook。

第二步：把关键事件送去异步处理

仓库说明里提到有一个 Worker Service，由 Bun 管理，跑在本地端口 37777，负责异步 AI 处理。

也就是说，采集和记忆生成不是全堵在主交互里做，而是交给后台服务处理。

第三步：落库

项目说明里写到本地数据库路径是：

~/.claude-mem/claude-mem.db

数据库层使用 SQLite3。

第四步：向量化同步

项目中还有 ChromaSync，用于做语义向量检索能力。

第五步：在未来会话中按相关性检索并注入

当你问到和过去工作有关的问题时，搜索能力会把相关记忆捞出来，再反馈给 Claude。

这套东西和手写文档相比，最大的区别就是：

它是“自动流转”的系统，不是“静态放在那里”的文件。

如何安装 Claude-Mem

根据仓库 README 的说明，安装入口走的是 Claude Code 的插件市场。

在新的 Claude Code 会话里执行：

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

这是项目 README 里公开展示的安装命令。

安装前你需要知道的依赖

从仓库说明和 issue 信息看，至少要注意下面几点：

1）它依赖 Bun

多个 issue 都提到：

  • claude-mem 运行 Worker 需要 Bun；
  • 某些版本或某些环境下，Bun 不一定会被完全自动处理好；
  • 如果安装后 Worker 起不来，第一排查项之一就是 Bun；

所以别把它理解成“纯零依赖插件”。

2）它会在本地启动后台服务

它不是只有一个 Markdown 文件。

它会启动本地 Worker，还会用到数据库和向量检索组件。这个也解释了为什么它的能力明显比 CLAUDE.md 强，但复杂度也高得多。

3）Windows 用户要特别关注兼容性

仓库 docs 和 issue 里能看到一些 Windows 相关修复，比如：

  • 用户名路径含空格时的启动问题；
  • Worker 启动失败；
  • Bun / 子进程拉起问题；

这不代表 Windows 不能用，而是说明：

它能用，但 Windows 环境更值得多看一眼安装日志和故障排查文档。

如何使用 Claude-Mem

1）最核心的一点：它不是“装完还要天天手工维护”

Claude-Mem 的卖点恰恰是：

很多事情它会自动做。

也就是：

  • 你正常在 Claude Code 里开发；
  • 它在后台采集和整理；
  • 会话结束后沉淀记忆；
  • 下次遇到相关问题时再拿出来；

所以它的“使用方式”不是传统软件那种“打开界面、点按钮、导入数据”。

它更像一个你装上后就开始工作的基础设施。

2）你可以把它当成“可检索的项目历史”

README 提到它有 Search Tools，项目内置 CLAUDE.md 也提到有 Search Skill，用于搜索过去的工作内容。

从相关 issue 里还能看到一些工具名，比如：

  • search
  • get_recent_context
  • decisions

这类名字很能说明问题：

  • search：搜历史内容；
  • get_recent_context：拿最近上下文；
  • decisions：查过去的技术决策；

所以实际使用时，你更像是在和 Claude 正常对话，只是 Claude 背后多了一层历史检索能力。

比如你可以问这类问题：

  • 我们之前为什么把某个模块拆开？
  • 上次修这个 bug 时试过哪些方案？
  • 最近在这个项目里改过哪些关键点？
  • 有没有做过和这个需求类似的事情？
  • 上次讨论过的技术决策是什么？

这种问题，单靠当前对话上下文，Claude 很容易失忆；有了 Claude-Mem，命中历史信息的概率会明显高很多。

3）有本地 Viewer UI

仓库内置 CLAUDE.md 提到有一个 Viewer UI，地址是：

http://localhost:37777

说明项目并不只是“后台黑盒”。

它还有一个本地界面，用来看相关数据和处理状态。

如果要 Claude Code 有记忆，直接写到 CLAUDE.md 不行吗？

这是最值得展开的部分。

答案是：可以解决一部分，但解决不了 Claude-Mem 想解决的那部分。

CLAUDE.md 擅长解决什么

CLAUDE.md 特别适合放这些内容：

  • 项目背景；
  • 编码规范；
  • 架构约定；
  • 常用命令；
  • 提交规范；
  • 测试方式；
  • 模块说明；
  • 不要碰的危险区域；
  • 团队共识；

说白了，它适合做：“给 Claude 看的项目说明书 / 操作手册 / 规则文档”。

它的优点是：

  • 简单；
  • 透明；
  • 可控；
  • 没有后台服务；
  • 没有数据库；
  • 没有额外运行时；

如果你的需求只是“给 Claude 一个稳定规则集”，那 CLAUDE.md 已经够好。

CLAUDE.md 不擅长解决什么

问题在于，项目记忆不是只有“规则”，还有大量“过程知识”。

而过程知识通常有几个特点：

1）它会不断变化

今天踩了一个坑，明天又有一个新坑。

你不可能天天手工把这些全补进 CLAUDE.md，而且补多了文件会越来越肿。

2）它很多是局部信息，不适合进总文档

比如：

  • 某个 bug 的定位过程；
  • 某次重构为什么中途改路线；
  • 某个依赖升级时踩了兼容性问题；
  • 哪个目录你以为有用其实是废弃代码；

这些内容很有价值，但不适合都堆进一份总说明书。

3）它很依赖检索，而不是全文灌输

如果把所有历史都塞进 CLAUDE.md，会有两个问题：

  • 太长：上下文成本高；
  • 太杂：真正相关的信息反而被淹没；

好的记忆系统，不是把所有东西永远放在眼前。

而是：

需要的时候再拿出来。

这就是 claude-mem 的检索式思路。

一句话区分两者

你可以这样理解：

  • CLAUDE.md = 项目静态说明书
  • claude-mem = 项目动态长期记忆系统

前者像员工手册，后者像一个会持续积累经验、还能回忆历史的同事脑子，这俩不是互斥关系。

最合理的做法往往是：两者一起用。

Claude-Mem 的优点到底是什么

1）把“会话记忆”从一次性变成长期资产

很多人用 Claude Code 最大的痛点就是：

这一轮聊得很聪明，下一轮全忘了。

Claude-Mem 的核心价值，就是尽量把一次会话里的产出，沉淀成下次还能复用的资产。

这件事对长期项目尤其重要。

2）减少重复解释和重复调查

没有持久化记忆时，你会反复做这些事：

  • 重新解释项目背景；
  • 重新解释历史决策；
  • 重新解释这个模块为什么长这样；
  • 重新让 Claude 扫代码、猜上下文；

这非常浪费 token，也浪费人脑。Claude-Mem 的意义就在于：

把已经解释过一次的东西，尽量别再解释第二次。

3）保留“过程知识”而不只是“最终答案”

很多 bug 和架构决策，真正值钱的不是最后那句结论，而是：

  • 为什么不是 A；
  • 为什么最后选 B；
  • C 看起来更快但其实会炸；
  • 哪个坑已经试过别再踩；

这种信息对未来的协作和自动化特别重要。

4）语义检索比手翻日志靠谱得多

你不需要精确记得当时说过哪一句。

你只需要大概知道“那件事和什么有关”，系统就有机会帮你把相关历史找回来。

这对大型项目、多轮调试、长期重构特别有价值。

5）自动化程度高

它的优势不是“功能多”，而是“你不需要每次主动记”。

真正能坚持下来的记忆系统，往往都不是靠人的自觉，而是靠自动化。

它解决了哪些具体痛点

痛点 1：Claude 开新会话后上下文断裂

这是最直接的。项目越大、周期越长，这个问题越烦。

痛点 2：同一个项目反复解释背景

每次都从头介绍一遍，真的很蠢。Claude-Mem 的目标就是减少这种重复劳动。

痛点 3：历史决策没有地方沉淀

很多团队会有这种情况：

  • 代码在；
  • 但“为什么这么写”没人记得；
  • 两周后连自己都忘了；

Claude-Mem 想保留的，就是这些决策上下文。

痛点 4：bug 排查经验会随会话丢失

排过一次很难的 bug，如果没有沉淀机制，下次换个会话还得重来一遍。

痛点 5：日志很多，但没有可用记忆

普通日志系统只能证明“发生过”。

它不一定能高效回答：

  • 为什么发生；
  • 哪个方向试过；
  • 后续怎么处理；
  • 与当前问题有什么关系；

Claude-Mem 想把“日志”往“记忆”升级。

Claude-Mem 的局限和现实问题

1）它比 CLAUDE.md 复杂得多

CLAUDE.md 只是一份文件。

Claude-Mem 则涉及：

  • 插件；
  • Hook；
  • Worker；
  • Bun；
  • SQLite；
  • 向量检索；
  • 本地服务；

能力强，复杂度也高。

2）安装和环境兼容性更敏感

从仓库 issue 看，Bun、Windows、Worker 启动、路径空格、依赖安装，都可能成为实际障碍。

这类项目很吃环境稳定性。

3）不是所有信息都应该被记住

项目也考虑了隐私控制。仓库内置 CLAUDE.md 提到可使用：

<private>content</private>

来阻止特定内容被存储。这说明作者也知道：记忆系统不是存得越多越好。如果没有边界，后面反而容易引入噪音和隐私问题。

4）记忆质量取决于提炼质量

自动总结听起来很美，但也有现实问题：

  • 提炼错了怎么办；
  • 压缩过度怎么办；
  • 召回不准怎么办；
  • 旧记忆过时怎么办；

所以它不是“装上就完美”，而是“值得试，但要接受它是一个系统工程”。

Claude-Mem 相比 CLAUDE.md 到底多出来了什么

最核心的差异，可以压缩成下面这张表。

对比项 CLAUDE.md claude-mem
信息类型 静态规则、说明、约定 动态记忆、历史过程、决策上下文
维护方式 主要靠手工维护 主要靠自动采集与整理
检索方式 全文阅读 / grep / 手找 语义搜索 + 相关性召回
时效性 依赖人是否更新 会随会话持续积累
适合内容 规范、文档、项目背景 调试过程、决策、历史上下文
成本 低 高
能力上限 稳，但偏静态 强，但更复杂

所以如果你问：

“想让 Claude Code 有记忆，直接写到 CLAUDE.md 不行吗？”

我的答案是：

  • 轻量场景：行。
  • 长期项目：不够。
  • 想要自动沉淀历史与检索：还是得上记忆系统。

最合理的实践建议

如果你真的要在项目里用 Claude Code，我更建议这样分工：

用 CLAUDE.md 管“规则”

把下面这些放进去：

  • 项目简介；
  • 技术栈；
  • 目录结构；
  • 命名规范；
  • 提交规范；
  • 测试命令；
  • 风险提示；
  • 不要修改的区域；

用 Claude-Mem 管“经验”

让它去沉淀：

  • 调试历史；
  • 技术决策；
  • 试错路径；
  • 会话总结；
  • 最近上下文；
  • 过去类似需求；

这才是比较像样的搭配。别把 CLAUDE.md 写成一锅粥，也别指望记忆系统替你写清楚基础规范。两者分工明确，效果最好。

这项目值不值得试

我的判断是：

值得试，尤其是长期项目、多人协作项目、复杂重构项目。

但前提是你要接受三件事：

  1. 它不是一份简单文档，而是一套系统；
  2. 它会带来额外依赖和运维复杂度；
  3. 它的收益，通常在“项目越大、周期越长”时越明显；

如果你只是偶尔让 Claude 帮你改几个文件，CLAUDE.md 可能已经够了。

但如果你是真的把 Claude Code 当长期开发用，那 Claude-Mem 这种项目就很有意义。

因为它瞄准的，正是现在很多 AI 编程工具最尴尬的短板：聪明，但不长记性。

而 Claude-Mem 想补的，就是这块。

CLAUDE.md 是静态说明书，claude-mem 是动态记忆系统。前者告诉 Claude“项目是什么”，后者尽量让 Claude 记住“项目发生过什么”。