第二天打开终端，Agent 全忘了昨天改到哪：claude-mem 把每次操作压成笔记存进本地，下次自动带上

先说一个几乎每个用 AI 写代码的人都经历过的场面。

昨天你花了三个小时，跟助手一起把一个支付模块的重试逻辑改完。中间讨论过好几轮：为什么重试要放在事务里面、为什么最多三次、为什么新的请求必须复用同一个幂等键。最后方案定了，代码跑通了，你关掉终端去睡觉。

今天早上你打开同一个项目，问它「接着昨天的改」。

它一脸茫然。它不知道昨天有过这场讨论，不知道那三个「为什么」，也不知道那个幂等键是谁定的。你只好重新讲一遍——而这一次讲，比昨天讨论花的力气还多，因为你得先把结论反向还原成过程。

这件事的成本很少被算进账里。我们通常把 AI 编程的效率问题归到「模型不够聪明」，但真正被浪费掉的，很大一块是重复交代背景。

为什么 CLAUDE.md 补不上这个洞

很多人第一反应是：那我写个 CLAUDE.md 不就行了。

行，但只行一半。这两样东西管的根本不是一件事。

CLAUDE.md 装的是规则——「这个项目用 pnpm 不用 npm」「组件一律函数式」「提交信息用中文」。这些是你事先想好、手写下来、长期不变的约定。

而昨天那场讨论产出的东西是记录——「因为超时重发会导致重复扣款，所以重试必须留在事务内」「试过用队列，但和现有的事务边界打架，放弃了」。这些不是规则，是发生过的事。你不可能把每天发生的事都手写进一个文件，写进去了它也就变成一个越来越长、越来越没人读的文档。

这就是 claude-mem 要填的缝：它记录的不是你写的规则，是助手干过的事。而且不需要你写一个字——抓取是自动的。

顺带说一句它的量级：这个仓库 2025 年 8 月底建，到 2026 年 10 月 28 日大约 10.36 万星，v15 这条线在十月最后一周里连着发了好几个版本。能长到这个体量，说明这个痛点不是个别人的。

它到底在做什么：抓、压、存、注

整条链路四步，一步都不复杂，但每一步的选择都挺讲究。

四条里最有意思的是最后一条，官方叫它 progressive disclosure（渐进披露）。它是三层：

第一层 search，只回索引——每条大约 50 到 100 token，你能看到标题、类型、涉及哪些文件，但看不到内容。
第二层 timeline，按时间看前后发生了什么，判断这条记录在不在你要的那条线上。
第三层 get_observations，这时候才把全文取出来，每条 500 到 1,000 token。

官方说这套能省十倍 token。这个「十倍」是它自己算的，没有公开的测量方法，我不会照抄。但这个思路本身是站得住的，而且值得学：如果 50 条记录全部取全文，那是几万 token，一次就能把上下文吃掉小半；而只取索引，只需要几千 token。

这套三层检索是暴露成 MCP 工具给助手用的，也就是说——不是你去搜，是助手自己去搜。它会在需要的时候调用 search，看一眼索引觉得有用，再往下取。你不需要记「上周那个决定存在哪」。

另外它把每条笔记都归了类，一共六种：bugfix（修 bug）、feature（加功能）、refactor（重构）、change（改配置）、discovery（查到了什么）、decision（定了什么）。这个分类看着不起眼，实际挺关键——因为「决策」和「发现」是最容易丢、也最难重建的两类信息。代码里能看出改了什么，但看不出为什么这么改。

装之前先记住这个坑

这一步值得单独拎出来，因为它违反直觉，而且踩了不会报错。

不要用 npm install -g claude-mem。

这条命令能跑通，包也装上了，看起来一切正常。但它只装了 SDK 和库，没有注册任何 hook，也没有起 worker。结果就是：插件看起来装了，实际上什么都没在跑，会话结束不会存下任何东西——而且它不报错，你会以为「这工具好像没什么用」。

正确的两条路：

路一，在会话里装（推荐）。打开 Claude Code，敲这两行：

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

然后重启会话。有个细节：只走 marketplace 这条路的话，hook 的启动器会在你第一次开新会话时才构建，所以那一次可能没有记忆，从第二次开始才有。

路二，在终端装。敲 npx claude-mem install，跟着交互式安装器走。

它在装的时候会把一个小启动器放到 PATH 上（macOS 和 Linux 是 ~/.local/bin），这一步是让 hook 能被调到。所以装完之后如果终端提示「找不到命令」，先看 PATH。

换个宿主的话加参数：OpenCode 用 --ide opencode，Gemini CLI 用 --ide gemini-cli，Codex 走 T3 Code 用 --ide t3code，Antigravity 用 --ide antigravity。没有对应宿主 hook 的（比如某些聊天型客户端）它就去盯聊天日志文件，效果和挂 hook 不一样，别指望完全等同。

安装器的第三关，得自己改一下

用 npx 那条路的话，交互式安装器会问你三件事：选宿主并装运行时、登录、选记忆的提供方。

第三关是重点。它默认预选的是 CMEM Pro——作者自己运营的托管服务，先给你试用，然后引导订阅（30 天试用后 30 美元/月）。

这不是什么见不得人的设计，开源项目靠托管服务收钱是常规做法，而且它确实提供了别处没有的东西：把「压缩笔记」这件事从你的主力订阅上挪走、跨机器云同步、以及用一个私有 MCP 连接让别的客户端（比如支持自定义连接器的 ChatGPT）也能读到同一份记忆。

但如果你要的是全本地、不额外花钱，第三关得自己改：选你自己的模型 key（OpenRouter、Gemini 都行），或者干脆用一个参数跳过——

npx claude-mem install --provider claude

这样压缩就走你自己的订阅，不走它的托管 observer。

这一步的意义不只是省钱。因为「谁来压缩笔记」决定了你的工具调用内容会发给谁。选托管 observer，你的每一次 Read、每一次 Bash 的输入输出都会经过它的服务器；选自己的 key，就只经过你已经在用的那家。这不是危言耸听，是这套架构的必然结果——它必须用一个模型来读你的操作记录，才能把记录压成笔记。

三条必须知道的安全与成本边界

第一条：worker 只能绑 127.0.0.1。

它的 worker 是一个本地 HTTP 服务，默认端口 37777，你可以用浏览器打开看记忆流。问题在于：GET /api/settings 这个端点会把 API key 以明文返回。所以官方明确要求把 host 绑在 127.0.0.1，绝对不能改成 0.0.0.0。改错这一项，同一个局域网里任何一台机器、以及本机任何一个能发 HTTP 的程序，都能把你的 key 读走。

顺带说，绑 127.0.0.1 也不是绝对安全——本机的浏览器扩展、随手装的一个 npm 包，都能访问 localhost。但在共享网络环境里，这是必须做的那一步。

第二条：不想被记的内容，包进 <private> 标签。

这是它给的隐私开关：被这个标签包住的内容不进库。要处理客户数据、内部地址、密钥片段的时候，这条比什么都实用。但它是「标记制」而不是「识别制」——你不标，它不会自己判断这段该不该记。

第三条：每条笔记都是一次模型调用，这是真金白银。

压缩不是免费的字符串处理，是把内容送给模型改写一遍。官方默认用 sonnet 级别的模型，一个会话里几十次工具调用，就是几十次调用。想省，可以在配置里换成更小的模型（比如 haiku 那一档）——笔记会粗一些，但成本能压下来一个量级。

这一点很多人装完才发现：它不是「装了就白用」的工具，它是一个会持续产生小额模型调用的工具。装之前先想清楚你是要「记全」还是「记要点」。

它记录的东西，到底长什么样

理解这个，比看任何介绍都快。一条 observation 大概包含四样：

标题——一句话说清这条是什么，比如「重试策略：三次，退避，复用同一幂等键」。
类型——六类之一，这里是 decision。
事实——几行要点，把这事的结论和理由压下来。
涉及文件——这条记录动过哪些文件，方便下次直接定位。

这四样东西合起来，刚好够回答下次会话里最常出现的三个问题：这个决定是什么、为什么这么定、动过哪些地方。

而它不记录的东西也很清楚：完整的推理过程、你当时说过但没落地的想法、以及被 <private> 挡掉的内容。它是摘要，不是录像。这一点要有预期——别指望它能还原出「当时我们讨论的第三种方案为什么被否掉」，除非那次否决本身构成一条 decision。

和 CLAUDE.md、和宿主自带记忆的分工

很多人会问：Claude Code 自己不是也有记忆吗，为什么还要这个。

是有的，但两者管的东西不同。宿主自带的记忆更像「你写给它看的长期备忘」——放的是稳定的偏好和约定，通常按项目或按目录分，跨机器、跨工具基本不共享。

claude-mem 补的是三块：

一是「发生过什么」这一层。不是规则，是记录，而且是自动攒的。
二是跨工具。同一份记忆可以被 Claude Code、Cursor、Codex、OpenCode 一起读——换工具不用重新教一遍，这在今天这个「一个项目用好几个助手」的现实里价值不小。
三是可检索。自带记忆靠读文件，你得知道去哪个文件找；这个是搜出来的，而且分三层按需取。

所以正确的用法不是「二选一」，而是分工：稳定的约定写进 CLAUDE.md，发生过的事交给 claude-mem。前者你来维护，后者它自己攒。

已知问题和它自己的脾气

不写这些就等于软文，所以逐条摆出来：

Windows 上会闪一下黑框。worker 启动时会短暂弹出一个控制台窗口。官方说这是纯外观问题——为了绕开一个会导致 libuv 崩溃的临时方案，他们选择先保稳定。功能不受影响，但确实碍眼，官方说等 MCP SDK 支持正经的窗口隐藏再修。

macOS 上偶有 worker 进程崩。崩了不会丢已存的数据（在 SQLite 里），但那段会话可能没记全。官方给了重启命令 npm run worker:restart，以及一个自检 npm run test:context。

长会话要自己管保留期。它的 config 里有 storage.maxObservations 和 storage.retentionDays 两个旋钮。如果你天天高强度用，几百上千条记录攒下来，检索会变慢，数据库也会变大。这两个值默认不是给你「永久保存」设计的，得按自己的节奏调。

它会在每个会话事件上跑 hook。这意味着它是一段会在你机器上持续运行的代码。装之前至少做一件事：装完去看一眼它注册了什么（仓库里有 hooks 配置文件），别装完就当黑盒。这不是针对这个项目——任何声称要「记住你所有操作」的工具，都值得你花五分钟看清楚它把数据放哪儿、发给谁。

适合谁，不适合谁

适合的三种人：

一是长期维护同一批项目的人。你的痛点不在「写新功能」，在「隔了三周回来改一个老模块」。这种场景里，记忆的价值最高。

二是同时用多个 AI 编程工具的人。同一份记忆能被几个客户端读，这是它相对宿主自带记忆最大的差别。

三是要做决策留痕的人。它把 decision 单独归了一类，等于顺手给你攒了一份「为什么这么定」的档案。这份档案在三个月后会比代码更值钱。

不适合的三种情况：

一是只是偶尔用一下。用得少，攒不出记录，装它纯属给自己加一个后台进程。

二是绝对不能把代码内容发给第三方的场景。哪怕选了 --provider claude 走自己的订阅，压缩这一步仍然要把操作内容送给模型。这是架构决定的，不是配置能绕开的。真不能出内网，就只能在本地跑自建模型做压缩——那套成本得另外算。

三是指望它提升模型能力的人。它不会让模型变聪明，它只是让模型少问你几遍。这个区别很重要——前者是幻想，后者是省钱。

一条关于 license 的提醒

这个项目的许可在不同版本之间有过变动，不同来源的说法也不一致：多数索引站和仓库 README 写的是 AGPL-3.0（其中 ragtime/ 子目录是 PolyForm Noncommercial），但也有来源称近期的 LICENSE 已经改为 Apache-2.0。

我不替任何一方下结论。如果你要用在商业环境里、尤其是要改完再对外提供服务，去 GitHub 上看当前的 LICENSE 文件，那一份才算数。AGPL 和 Apache 在「改了之后要不要开源」这件事上差别极大，这个不能靠别人转述。

至于付费的 CMEM Pro 那部分，属于独立服务，按它的服务条款走，和引擎的开源许可不是一回事。

结语：它补的是「记忆」，不是「智力」

把这件事压成一句话：AI 编程助手真正浪费你时间的地方，不是它答错了，是它每次都要你从头讲一遍。

claude-mem 干的事很朴素——把「发生过什么」这件事从你的脑子里搬到磁盘上，并且在你需要的时候自动带回来。它没有让模型变聪明，也没有让代码写得更好，它只是把重复交代背景这件事的边际成本压到了接近零。

而它对使用者的要求也很明确：装的时候别用错命令、第三关别默认走过去、worker 别绑 0.0.0.0、不想被记的内容自己打标签、以及接受「压缩笔记要花模型调用」这个前提。

这五条里少做一条，你要么白装，要么白花钱，要么把不该外发的东西发了出去。

所以它不是一个「装上就完了」的工具，是一个需要你花十分钟想清楚边界、然后可以长期不管的工具。而这十分钟，比你今天重新讲一遍昨天那三个「为什么」，要划算得多。