给 Claude Code 装上第二大脑：claude-mem 长期记忆工具原理与实践

用过 Claude Code 的人大概都有过这种体验：前天晚上和它一起把某个模块的重构方案聊得明明白白，连拆几步、改哪几个文件都定了，第二天新开一个会话，它一脸无辜地看着你，好像你们从未见过。你重新讲一遍背景，它又问了一遍项目结构，再复述一遍前面的决定，一来一回，半个上午就没了。

我后来在技术社区看到一个叫 claude-mem 的开源工具，专门给 Claude Code 补上这块短板。它的思路说穿了很简单：把每轮会话里产出的关键信息结构化落盘，形成一份可检索、可维护的长期记忆，然后在后续会话中按需重新注入。用一句话概括——给没有长期记忆的 Claude Code 装一个"第二大脑"。

这篇文章我会把 claude-mem 的原理、接入步骤、实际使用感受和一些坑都摊开讲。我自己在两三个项目上跑了大概两个月，中间踩过不少雷，也调试出了一些成熟用法，适合正在被"会话失忆"困扰、想给 AI 编程工作流增加持久上下文的人参考。

1. 每次开新会话都像重新面试？这份记忆工具解决的正是这个刚需

1.1 我为什么开始找记忆方案

先说场景。我手里有个微服务项目，前后端加起来十来个仓库，每个仓库有自己的技术栈和目录约定。早期我直接在 Claude Code 里干，对话一长，上下文窗口塞满了，它就开始丢三落四。后来我学聪明了，把任务拆细，每次会话只聚焦一个小目标。这样虽然准确率上来了，但我发现自己变成了一个"人肉上下文加载器"——每次新会话都要把项目的背景、技术选型、待办事项、踩过的坑重新说一遍。

最典型的一次：我在 A 仓库和 Claude Code 一起解决了数据库连接池耗尽的问题，结论是某某配置参数不能超 50，超了会频繁重建连接。第二天在 B 仓库遇到类似问题，我顺手问它，它给出的答案完全没关联到前一天的分析，等于同一个问题花了两次钱和时间。

当时网上能找到的方案大致几种。有的靠维护一份 CLAUDE.md，把项目约定手动写进去；有的是写复杂的 prompt 模板，把历史对话摘要塞进 system prompt；有的干脆用脚本把日志里的对话抽出来再灌回去。前两种维护成本高，第三种副作用大。直到我看到 claude-mem，才觉得思路对了：记忆应该是由 AI 增量自动提取，而不是靠人肉维护一篇 Hacker News 式的长文。

1.2 CLAUDE.md 与 claude-mem 的分工

Claude Code 本身支持项目级配置文件 CLAUDE.md，很多人用它存项目说明、编码规范、常用命令。这个文件作用很大，但它本质上是一份静态文档，需要人主动维护。一旦项目快起来，文档就慢慢过期，到最后反而变成误导。

claude-mem 做的事和 CLAUDE.md 不冲突，它是动态补位。Claude Code 负责"干活"，claude-mem 负责"记账"。每次会话结束，它把对话里出现的结论、代码决策、环境信息、偏好提取出来，沉淀为记忆；下次会话开始，它再把相关记忆作为额外上下文喂给模型。

我在实际使用中是把两者当成一个组合用的：

我的体会是：CLAUDE.md 更像项目的"宪法"，claude-mem 是每天产生的"会议纪要"。宪法不需要天天改，但纪要缺一天都不行。

2. claude-mem 记忆到底存哪、怎么被想起来：架构拆解

2.1 三层记忆结构：项目档案、会话摘要、全局偏好

claude-mem 不是简单地把对话日志堆在一个文件里硬塞回去。它对记忆做了分层，按我的使用观察，大致有三层结构：

• 项目档案（Project Profile）：与当前仓库绑定，记录这个项目的技术栈、目录结构、关键约定、历史决策。比如"本项目使用 pnpm workspace""数据库迁移文件放在 db/migrations 下""API 返回格式统一用 { code, data, message }"。
• 会话摘要（Session Summary）：每一轮 Claude Code 会话结束后生成的浓缩版，包括这次处理了什么问题、产出了哪些文件改动、还有什么待办。
• 全局偏好（User Preference）：不绑定项目，跨仓库通用的个人信息，比如"用户偏好 TypeScript 严格模式""提交信息统一用 Conventional Commits 风格""不要自动修改 package-lock.json"。

这套三层结构是我觉得 claude-mem 比粗暴"拼接对话记录"高明的地方。对话记录本身噪声极大，模型闲聊、来回试探、错误纠正常常占了 80%，这些东西直接回灌不仅浪费 token，还会让模型被错误信息带偏。claude-mem 做了一次提炼，把对话里的"事实性内容"抽出来，扔掉过程性内容，这样注入的上下文才是有用的。

2.2 MCP 集成：模型如何自动"翻旧账"

claude-mem 是以 MCP（Model Context Protocol）服务器方式运行的。MCP 你可以理解成给模型插 U 盘的标准接口，Claude Code 通过它动态发现工具和数据源，而不是把所有东西都塞进 system prompt。

它暴露出来的能力大致是几个工具方法：查询项目记忆、追加一条新记忆、全文检索、按标签筛选等。模型在会话中会根据当前问题自行判断要不要调用这些方法。比如你问"我们之前讨论过的连接池参数结论是什么"，它就会触发一次记忆检索，把相关的段落拉回来。

我当初比较担心的是模型"不知道去查记忆"。实际跑下来，只要配置没问题，Claude Code 在开场阶段通常会主动检查一次项目档案，而且问题提到"之前""上次""我们决定过"这类词时，它基本都能触发查询。偶尔漏掉，我就在对话里点名一句"先查一下 claude-mem"，它就会去调用。

2.3 记忆的压缩与遗忘策略

记忆不能只增不减，否则会变成第二个上下文爆炸。claude-mem 的处理方式我总结为"分层压缩 + 阈值遗忘"。

短期记忆在会话结束后生成摘要，摘要累积到一定量，比如同一个项目的话题超过若干条，就会触发一次合并整理，把零散结论压缩成主题块。超过一定时间没人访问的记忆，会被降级为"归档检索"而不是"主动注入"，这样既不丢历史，又不会每个会话都被大量无关记忆拖累。

我实际在用的过程中，明显感觉到记忆的"新鲜度"是有权重的。最近一周的结论很容易被引用，一个月前的决策需要我主动提醒才会被翻出来。这种设计贴近人的记忆方式，用起来比全部平等对待要舒服得多。

3. 从安装到接入 Claude Code：完整操作与容易忽略的细节

3.1 安装与目录布局

claude-mem 的安装方式很常规，依赖 Node.js 环境。我当时是在几台开发机上装的，基本流程就是全局安装 CLI 工具，然后初始化一个记忆目录。以我的环境为例：

npm install -g claude-mem claude-mem init

初始化后它会创建一个默认的记忆根目录，常见做法是放在用户主目录下，也可以按项目单独指定。我习惯在项目根目录建一个.claude-mem/，好处是记忆随仓库走，换机器 clone 下来还能带着历史上下文，坏处是容易把项目目录搞乱，所以我在.gitignore里把这类目录排除了。

如果你同时在多个仓库工作，我的建议是全局目录 + 项目目录两层配合：全局存个人偏好，项目目录存该仓库特有的结论，访问规则简单，还原也省事。

3.2 MCP 配置与 Claude Code 的关联

接入的关键是把 claude-mem 注册为 Claude Code 的 MCP 服务器。Claude Code 的配置文件里有一块 mcpServers 字段，我那时候是这样加的：

{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": ["serve"], "env": { "CLAUDE_MEM_DIR": "/path/to/your/mem" } } } }

这里有几个坑我要单独拿出来说。首先是命令路径，如果你用了 nvm 或 volta 管理 Node 版本，全局安装路径可能不在系统默认 PATH 里。配置里填claude-mem找不到命令，但终端里明明能跑。我最后是直接在配置里填了绝对路径：

"command": "/home/you/.nvm/versions/node/v20.11.0/bin/claude-mem"

其次是CLAUDE_MEM_DIR环境变量，不配置的话它会用默认目录。如果你同时维护多个项目又分别指定了项目级记忆目录，这里的环境变量要小心别覆盖错了。

配置完成后，重新启动 Claude Code，它启动时会自动拉起 MCP 服务器。你可以通过会话内的工具列表确认 claude-mem 的工具是否出现，出现了就说明接入成功。我第一次配置完看不到工具，排查了一会儿才发现是 MCP 服务启动报错但被 Claude Code 静默忽略了，这问题我后面在第六节里细说。

3.3 首次会话标记与记忆触发条件

接入成功后，并不是第一句话就会触发记忆机制。按我的观察，claude-mem 的触发大致有几类情形：

• 新会话开始时，模型初始化上下文时读取项目档案；
• 对话里出现"之前""上次""我们决定过""我记得"等回溯性措辞；
• 用户主动调用记忆查询工具，比如直接说"查一下关于部署流程的记忆"；
• 会话进行中，当模型觉得当前信息不足时，可能检索相关记忆补全上下文。

刚开始用的时候，我对它自适应触发持怀疑态度，有几次明明相关的记忆它没查。后来我调整了习惯：涉及旧结论的提问，我会在 prompt 里带一句"先查记忆再回答"。这不算什么负担，反而让结果稳定很多。

4. 换成 claude-mem 之后，我的工作流发生了哪些实质变化

4.1 跨会话接续：从"复述背景"到"直接开干"

最明显的变化是跨天工作的体验。以前第二天开会话，光是恢复上下文就要花十几分钟：贴项目路径、解释模块职责、附上昨天的输出。现在打开 Claude Code，它自己先加载项目档案，很多背景不再需要我讲。

有一个真实例子。我给某个服务加了一个新的告警项，涉及配置校验逻辑。第一天和 Claude Code 讨论到一半，确认了大致的改法，但没来得及实施。第二天我直接开新会话说"继续昨天那个告警校验的改动"。它检索记忆后，自己说出了要改哪两个文件、校验规则放在哪个函数里，我只需要确认一遍，它就开始动手写了。这种体验一旦习惯，就回不到以前那种"人工同步上下文"的模式了。

4.2 跨项目隔离：一个工具同时管多套上下文

我同时在维护两三个项目，它们的约定差异很大。一个项目用 pnpm + monorepo，另一个是单仓的 Go 服务。如果没有 claude-mem 这类工具，我就要靠人工切换 CLAUDE.md，或者祈愿模型别把 A 项目的约定套到 B 项目上。

claude-mem 按项目隔离记忆之后，这种串味问题基本消失了。它知道当前工作目录对应哪个记忆域，只加载该项目相关的档案和摘要。我自己做过一个测试：在 A 项目里和它讨论完一种代码风格，再到 B 项目里问同样的问题，它给出的建议就明显偏向 B 项目的既有风格。这说明记忆的作用不是简单复读，而是能改变模型的行为偏好。

4.3 配合脚本与自动化：把记忆变成团队资产

除了交互式挂载，claude-mem 的数据还能被脚本读取。我写了一个简单的收尾脚本，在每天下班前跑一次，会把当天记忆里新增的结论整理成一份日报，追加到项目文档的底层。这样即使团队里其他人不用 Claude Code，也能共享到我这边沉淀出来的项目知识。

另一个用法是 CI 里面做摘要归档。某个仓库的测试失败时，我会让 CI 把失败日志和当时的会话摘要一起打出来，排查的人不用去翻大段历史记录，直接看摘要就能定位。这个玩法一开始只是我图省事，后来发现对团队排障效率提升挺明显。

5. 记忆越堆越多，修剪策略和隐私边界必须提前想清楚

5.1 什么时候应当主动清理记忆

claude-mem 有自动压缩和遗忘机制，但我建议还是要定期人肉清理，原因是自动机制只保证"规模可控"，不保证"内容正确"。项目重构之后，过期结论还留在记忆里是最危险的情况。

比如我有个项目改了数据访问层，从直接连数据库改成了走统一 API。旧记忆里关于"如何连库"的结论如果不删，Claude Code 后来居然在一段新代码里用旧模式生成了实现，差点把一个只读查询写成了直连数据库。从那以后我定了规矩：

• 每一次架构调整、依赖替换、目录重构后，主动清理相关主题的记忆块；
• 季度性做一次全量 review，把明显过时的话题标记为归档或直接删除；
• 全局偏好这类长期记忆也要检查，随着自己技术习惯变化，旧偏好会变成束缚。

5.2 敏感信息和访问权限：记忆也会变成泄露面

记忆文件是纯文本落盘的，里面会包含一些你当时没太在意的话。代码路径、内部服务命名、某些实现细节，如果记忆目录被同步到公共仓库或者别人拿到，这些信息的暴露面比源码还要大，因为它们是被提炼过的、极易被理解的描述。

我的做法有几条：

• 项目级.claude-mem/目录一律加入.gitignore，确保不会随 PR 流入仓库；
• 远程开发机上尽量不开全局记忆，或者把记忆目录放到加密文件系统里；
• 不在对话中提到明文密钥、token、内网地址等敏感信息，即使项目是私有的也不写，因为记忆的留存时间比会话长得多，风险是累积的；
• 定期导出记忆做人工检查，把不该留的内容清掉再重新导入。

5.3 备份、迁移与多机同步

由于记忆就是一堆文件，备份非常简单，直接拿文件系统工具打压缩包就行。我给自己做了一个 cron 任务，每周把记忆目录打包推到私有对象存储，保留四周滚动副本。迁移的时候，新机器上装好 claude-mem，把目录解压回原位，历史记忆就带过来了。

如果你有多台机器，我的经验是不要把记忆目录直接放到同步盘里实时同步，因为 claude-mem 写入是持续的，文件锁和多进程冲突问题会非常烦。更好的方式是每台机器各自维护记忆，定期用 claude-mem 自带的迁移或导入命令做增量合并。要特别注意，两台机器同时写入同一份记忆文件，会导致某一端的内容丢失，这个坑我踩过一次，后面不再用即时同步方案了。

6. 实测中遇到的四个坑与排查思路

6.1 MCP 服务静默失败，记忆工具列表里找不到

症状是 Claude Code 正常启动，但对话中和记忆相关的工具全部不存在。我排查过程是这样的：先在终端手动运行claude-mem serve，看它能不能正常起来。结果显示进程起不来，报的错和 Node 版本有关。

问题根源在于我用 nvm 装了多个 Node 版本，MCP 子进程继承的环境和我终端不一样，PATH 里指向的 Node 版本不一致，全局安装的 claude-mem 找不到对应运行时。解决方法是固定配置里的命令路径和 Node 路径，不依赖 PATH 推断。改完之后，重启 Claude Code 刷新 MCP 列表，工具就出现了。

6.2 会话摘要丢关键决策，记忆内容不够完整

有一段时间，我发现了很怪的现象：明明进展很大的会话，第二天的记忆摘要却只记了边角料。后来我翻了自己的对话方式，问题出在我没有明确做"阶段性结论收口"。

claude-mem 的摘要提取依赖对话本身的质量。如果对话里全是过程性讨论、试验性改动，没有明确的收尾结论，它很难提炼出持久信息。改进方法很简单：每个任务完成或告一段落时，明确告诉 Claude Code"把这次的两个关键结论记下来"，它会主动生成结构化摘要。这个习惯一养成，记忆质量立刻上一个台阶。想让它记住却说"你看着办"，是最容易丢信息的方式。

6.3 上下文注入过长，挤占了主任务的思考空间

另一个反面效果是记忆太多太全，每个会话开头就灌入一大坨项目档案和历史摘要，接近窗口上限后，模型在真正写代码时反而"变笨"，上下文里有效代码片段占比下降。

我最后做的调整是通过配置控制记忆的注入量，只让最近一周的高权重记忆随会话注入，更早的内容一律走主动检索；同时精简项目档案，让它控制在实用范围内。我开始图省事把所有内容都塞进项目档案，后来发现文档越写越长，实际被有效引用的就那几项。精简之后，记忆的作用不减，干扰反而明显下降。

6.4 与其他插件/工具冲突，记忆目录文件被覆盖

我在项目里还装了另一个文件观察工具，它和我用的文件同步插件互相抢过目录。结果是某个记忆子目录被另一套流程当成临时目录清掉了，claude-mem 读不到历史，等同失忆。

排查了半天才发现，是那个观察工具把我的记忆目录加进了忽略清单之外的"自动清理"范围。解决方法是把所有和 claude-mem 相关的目录路径统一加入工具的排除规则，并且在文档里注记清楚：凡是不认识的隐藏文件夹，不清理、不同步、不移动。我后来养成习惯，每次为新项目搭环境时，先检查所有后台工具对隐藏目录的处理策略，统一排除掉记忆目录，这类问题再没出现过。

claude-mem 这个东西说穿了不复杂，它就是把 AI 对话产生的知识沉淀下来，在需要的时候再还给你。但恰恰是这一存一取，省掉了我大量重复解释的流程。现在我基本离不开它了，至少用 Claude Code 干活时，它已经是我的标配。如果你也被"每次会话从零开始"折磨得够呛，建议先拿一个小项目跑一周试试，重点体会一下第二天在新会话里提起"昨天那个方案"时，它能不能接得住话。能接住，你就回不去了。