你有没有遇到过这种情况：昨天刚和 Claude Code 花了两个小时，把一套订单状态机的约束、字段定义、异常流转顺序都敲定了，今天新开一个会话，它劈头就问“订单状态流转用哪几个字段？”。我当时的反应先是无奈，然后是理解——对话窗口本来就是临时的，新会话里 AI 没有任何上一轮的痕迹。
这个问题的正式说法叫上下文丢失，解决思路也很明确：给 Claude 加一层持久记忆。claude-mem 就是为此出来的，它是一个为 Claude Code 提供跨会话记忆的 MCP 服务器，把每次交谈中值得留下的决策、偏好、术语定义沉淀成本地知识库，并在后续会话开始的时候，自动把相关记忆内容回传给 Claude。这篇文章我从原理、接入、日常使用到维护边界，完整梳理了自己的实测经验，给同样被 AI 失忆困扰的人一份能直接抄作业的方案。
1. 为什么 Claude Code 需要一个记忆层，而不是更长对话
1.1 无状态会话的底层机制
先把记忆问题拆开看。Claude Code 每次启动会话，都会加载一个上下文窗口，里面主要有三样东西：系统提示、CLAUDE.md、当前对话的消息历史。这个窗口不是无限的，而且一旦会话结束，除了你主动保存到文件里的东西，其余都会被释放。
你可以把 Claude 想象成一个记性很好但工作记忆有限的外包同事：每次他来上班，你递给他一份新的项目简报，他只能看到简报上的内容；昨天口头敲定的细节不在简报里，他就是不知道。所以新会话里他不厌其烦地重复问你已经确认过的方案，不是他笨，也不是他态度不好，是架构决定了他“看不到”。
1.2 CLAUDE.md 能做什么，不能做什么
有人会说：那我把约定写进 CLAUDE.md 不就行了？确实，CLAUDE.md 是官方推荐的常驻上下文入口，它适合承载“长期不变”的规则，比如代码风格、目录结构、运行命令。但它有两个明显的边界：
- 静态性：CLAUDE.md 需要手动维护，而项目里的决策每天都在变，很多人一开始写得很认真，后面就再也不更新了。
- 容量压力：CLAUDE.md 放得太多，会挤占上下文窗口的可用空间，反而影响主任务的推理质量。
真正棘手的是那些“动态产生、事后才需要召回”的内容，比如某次对话里敲定的接口命名规则、用户对某个框架的明显偏好、某个模块为什么要拆成两层的背景。这些内容适合事后自动沉淀、下次按需唤醒，而不是一股脑塞进静态文档。
1.3 一个合格记忆层应该做的四个动作
我理解中的记忆层，至少要完成四件事：
- 提取：在对话进行中，自动识别哪些内容值得长期保留。
- 存储：用结构化但人类可读的格式保存，不能是黑盒数据库。
- 检索：新会话开始的时候，按相关性找到与当前任务有关的旧记忆。
- 注入：把检索到的记忆拼到上下文里，成为 Claude 的“工作记忆”。
claude-mem 做的事情，就是把上面四步串成一个自动化闭环。后面章节我会具体拆解。
2. claude-mem 的本质：把对话沉淀成本地知识库
2.1 MCP 协议是怎么把记忆工具交给 Claude 的
claude-mem 本身是一个 MCP server。MCP（Model Context Protocol）是 Claude Code 调用外部工具的标准协议，你只要把一个 MCP server 注册进去，Claude 就多了一批以记忆为中心的工具。
这个过程对使用者来说很透明：装好之后，你在对话里可以直接说“记住：这个项目禁止直接改 dist 目录”，Claude 就会调用记忆工具把这条写进记忆库。对新会话来说，它又能通过另一个工具把相关记忆读出来。本质上，claude-mem 就是给 AI 配了一个本地笔记本——不靠人工复制粘贴，而是通过协议自动读写。
2.2 双层记忆：全局偏好与项目上下文的隔离
claude-mem 的记忆分为两个层级，这个设计我觉得非常实用：
| 记忆层级 | 典型内容 | 存放位置 |
|---|---|---|
| 全局记忆 | 用户跨项目的通用偏好：习惯用 pnpm、提交信息用约定式、错误回复要带修复命令 | ~/.claude-mem/ |
| 项目记忆 | 当前项目内的决策和约定：订单表主键用雪花 ID、本仓库禁止提交 dist、上线前要跑迁移 | 项目目录下的.claude-mem/ |
这两个层级的隔离很重要。全局记忆换一个项目仍然生效，每次开新项目不用重新交代个人偏好；项目记忆则只属于当前仓库，不会串到别的项目里。实际体验中，这个分层能明显减少噪音：我同时维护五六个仓库，每个仓库的约定都不同，如果不隔离，全局记忆会导致方案互相“打架”，很快就没法用了。
2.3 一条记忆是如何被保存的
记忆不是存在某个私有数据库里的，而是以 Markdown 文件为主体，文件头部用 YAML 记录元信息，类似下面这样：
--- title: 订单状态机使用状态枚举而非布尔字段 tags: [订单, 数据模型] project: order-service created: 2025-01-14 --- 订单状态使用独立的 status 枚举，不要使用布尔字段组合表达状态。 原因：状态数量已经超过 4 个，布尔组合会显著提高理解成本。这意味着记忆库完全是透明的。你可以直接用编辑器打开、修改、删除任何一条记忆，也可以把它纳入版本控制。这点我很看重：记忆层本身不该成为新的黑盒，它更像一个半结构化的个人 Wiki，只不过读写交给 Claude 来完成。
2.4 提取与注入的自动化闭环
claude-mem 通常以 sidecar 方式读取对话记录，也就是抓取 Claude Code 产生的会话转录，从中识别“可能值得长期保留的结论”，经过规则过滤后写成记忆条目。到了新会话开始的时候，它会读取全局和项目两个层级的记忆库，筛选出与当前任务最相关的一部分，注入到上下文的最前面。
这套机制的关键在于过滤和相关性，而不在于存得全。存得越多，检索越难；存得越准，注入越有效。这一点我一开始没有概念，结果是记忆库迅速膨胀，后面专门花了一周去清理，这个教训我在第五章会展开讲。
3. 从零接入：安装、配置与验证
3.1 前置条件
接入 claude-mem 之前，你的机器上需要满足两件事：
- 已经能正常使用 Claude Code，也就是本地 CLI 可以跑通。
- Node.js 版本在 16 以上，因为 claude-mem 是一个 npm 包。
这两个条件基本是标配，没有额外依赖。不需要 Docker，不需要自己维护数据库，冷启动成本很低。
3.2 安装命令与 MCP 注册
安装本身非常简单，我用的命令是：
npm install -g @bernardo-mp/claude-mem claude-mem installclaude-mem install会把 MCP server 的配置写进 Claude Code 的配置文件里，省去了手写 JSON 的麻烦。如果你更喜欢自定义，也可以手动注册，命令大致是：
claude mcp add -s user claude-mem -- npx @bernardo-mp/claude-mem需要注意：无论用哪种方式，装完 MCP server 之后都要重启 Claude Code。MCP 工具是在会话启动时加载的，不重启就不会生效。这个步骤卡了我十分钟，后来发现只是没重启。
3.3 最关键的一步：在 CLAUDE.md 里定义使用策略
工具装上只是第一步，真正让它发挥价值，需要给 Claude 一份“使用说明书”。我强烈建议在项目的 CLAUDE.md 里加上这样一段：
## 记忆管理 - 本项目使用 claude-mem 管理跨会话记忆。 - 当用户说“记住”时，调用记忆工具保存结论，并简单确认。 - 开始重要任务前，先查看项目记忆，避免重复提问。 - 发现关键决策、命名约定、技术选型时，主动建议保存为记忆。 - 记忆内容要求简洁、具体、无歧义，一条记忆只表达一个结论。这是整个接入过程中最容易忽略、也最影响效果的一步。没有这个指令，Claude 很可能只是把工具挂在列表里，从不主动调用——很多用户装了之后觉得“没变化”，根源就在这里，不是工具不工作，而是 AI 不知道怎么用。
3.4 验证安装的三个痕迹
装完之后，我建议按下面三个步骤确认是否真的生效：
- 在会话里直接问：“你现在有哪些记忆相关工具？”如果正常，Claude 会列出记忆工具，命名视版本而定，通常包含浏览记忆、保存记忆等。
- 说一句“记住：测试一下记忆功能”，然后去记忆目录看看是否有新的 Markdown 文件生成。有文件，说明写入链路是通的。
- 新开一个会话，问“你还记得我刚才让你记住什么吗？”能复述出来，说明读取链路也正常。
3.5 升级与卸载
升级 npm 包很简单：
npm update -g @bernardo-mp/claude-mem claude-mem install卸载则要记得把 MCP server 配置移除，避免残留报错：
claude mcp remove -s user claude-mem # 具体参数视版本而定记忆文件本身不会因为卸载而删除，建议卸载前先做一次备份。
4. 日常使用模式：让记忆越用越准
4.1 主动记忆优先
使用 claude-mem 两三个月后，我的结论非常明确：主动说“记住”比自动提取可靠得多。原因是自动提取很难判断“什么值得留”，而人在对话现场最清楚哪句话是关键决策。
我的用法是在每次讨论出结论时，附带一句明确指令，比如：
- “记住：本仓库的测试文件统一放在
__tests__目录。” - “记住：接口返回的错误码格式为标准错误结构
{code, message}。” - “记住：我们决定不用 Redux，改用 Zustand，原因是模板代码更少。”
这种一条命令对应一条结论的模式，长期来看最干净。它把“要不要记”的判断权留给人，而不是交给模型去猜。
4.2 自动提取的取舍
自动提取的能力是 claude-mem 的一个重要卖点，它能把你的对话转录变成记忆草稿。但它有一个现实问题：噪音。实测中自动提取出的内容，可能包含“这个报错解决了”这种一次性信息，也可能把不重要的细节跟核心决策混在一起。
我的建议是：第一次用的时候，先开两天自动提取，观察它沉淀了什么。如果噪音率超过一半，就关掉自动提取，只保留主动记忆和人工整理。关闭的方法一般能在配置文件中找到对应开关，具体名称因版本不同而异，问一下 Claude 就能找到。
4.3 每周维护：把记忆库当成 Wiki 来编辑
记忆库是需要维护的，就像 Wiki 需要有人整理一样。我每周会花大概十分钟做一次“记忆评审”，直接用编辑器打开记忆目录，做三件事：
- 删除已经失效的条目，比如某个旧方案已经被推翻。
- 合并重复条目，把同类结论归并到同一条里。
- 补上背景说明，让未来打开的人（包括未来的我）能看懂当时为什么这么做。
维护频率不用太高，每周一次足够。关键是不要放任不管，否则三个月后记忆库就会退化成一堆过时结论的合集，反而误导 Claude。
4.4 三个真实使用场景
我在实际项目里最常用的三个场景，可以给你参考：
第一个是项目初始化。新接一个仓库时，我会让 Claude 把项目的技术栈、启动命令、提交规范、目录约定逐条存进项目记忆。之后任何新会话都不用再贴一遍背景，直接说“继续改登录模块”就能接上。
第二个是中断后接续。很多任务不是一口气做完的，中间可能隔几天。我会在收尾时说“记住：任务进行到图片上传接口，下一步做断点续传”，下次回来直接续上，不用重新读一遍代码。
第三个是多仓库统一偏好。我在全局记忆里存了“代码风格用 prettier + eslint，提交信息用约定式提交”，所有仓库的新会话都会自动带上这条偏好，省去了每个项目都要重复交代的麻烦。
5. 实测项目中的经验、教训与边界
5.1 记忆膨胀：最常踩的坑
我最大的教训是让记忆库在两周内膨胀到了几百条。罪魁祸首除了自动提取，还有我自己滥用“记住”。比如我随手记住了“这个函数改成 async 了”，这类一次性信息根本没有长期价值，几周后只剩下噪音。
对策很简单：创建记忆前多问一句“下个月我还会需要这条吗”。答案不确定的，就让它留在对话里，不写进记忆。另外，一旦发现记忆库超过一百条，就该安排一次清理，删除明显的过时内容。记忆贵精不贵多，一百条高质量决策远比三百条杂讯有价值。
5.2 如何确认记忆真的生效
确认记忆是否起效，最直接的方法是在新会话里问：“你还记得我们之前关于订单状态的约定吗？”
能准确复述，说明检索和注入链路正常。如果复述的内容过时了，就去记忆库里找到对应条目改掉或删掉。我特别提醒一点：记忆库更新之后，当前会话里的 Claude 可能还停留在旧信息上，因为记忆注入发生在会话启动时。所以改了记忆文件之后，重启一个新会话再验证，才是最干净的测试方式。
5.3 claude-mem 与其他方案的边界对比
很多人会把 claude-mem 和 CLAUDE.md、手动复制粘贴上下文混为一谈。我的看法是，它们解决的是不同维度的问题：
| 方案 | 适合场景 | 局限性 |
|---|---|---|
| CLAUDE.md | 长期不变的规则、风格、目录结构 | 静态，需要手动维护，容量受限 |
| claude-mem | 动态产生的决策、偏好、上下文召回 | 需要维护质量，不适合存储海量代码细节 |
| 手动复制上一轮总结 | 临时快速接力 | 容易遗漏、粘贴错误，无法自动检索 |
claude-mem 和 CLAUDE.md 是互补关系，不是替代关系。CLAUDE.md 放“常量”，claude-mem 放“变量”，一静一动配合起来才舒服。
5.4 什么时候不该依赖 claude-mem
我也要说明它不能做什么。它不是代码搜索引擎，当项目有成百上千个文件时，你需要记住的是“代码为什么这么设计”，而不是靠记忆定位每一行代码。它也不适合存密钥、口令、个人敏感数据，记忆会被读回上下文中，最终可能体现在模型生成的代码或建议里。团队共享敏感项目信息时，一定要先判断信息等级，再决定要不要入库。
6. 记忆库管理、团队共享与备份安全
6.1 本地优先与敏感数据最小化
claude-mem 默认是本地存储，记忆文件就在你的磁盘上，不会自动上传到外部服务。但你要清楚：Claude Code 在运行时会读取这些文件，它们会以上下文方式被模型处理。所以请像对待源码一样对待记忆库，尤其是涉及密钥、账号、内部敏感信息的时候，最好的策略就是根本不写进去，密钥走专门的密钥管理工具，不要存在记忆里。
6.2 团队共享记忆库的两个纪律
如果团队共享项目记忆，把.claude-mem目录纳入版本控制是可以的，但要有两个纪律：
一是写入规范。约定记忆条目的格式，包括标题、标签、结论、背景四个字段，禁止写情绪化内容和无关信息。无规矩不成方圆，记忆库一旦多人写入，没有格式约束会迅速变成一座垃圾山。
二是变更审查。在 Pull Request 里 review 记忆库的改动，就像 review 代码一样。谁新增了什么决策、删除了什么结论，都要有迹可循。我会在团队规范里明确要求：涉及到架构决策的记忆修改，必须附带讨论上下文链接。
6.3 备份与恢复
备份记忆库的成本极低，收益很高。代码丢了可以 git clone，记忆库丢了可就真的只剩“失忆”了。我的做法是双备份：
- 全局记忆目录用系统备份工具定期快照。
- 项目记忆目录放进 git 私有仓库，随代码一起提交。
恢复也很直接：从备份里把对应目录复制回来，重启 Claude Code 即可。实测过一次，整个过程不到两分钟。
最后再分享一个小技巧。我习惯在每个周五做一次“记忆评审”：把这一周新产生的记忆通读一遍，把散落的零碎结论合并成一份清晰的“决策记录”，并删掉已经过期的旧条目。这个习惯坚持了几周之后，Claude Code 在我这儿几乎成了“一个真正记得住上下文的老同事”——我再也不用在新会话里重复解释那些已经解释过三遍的事情了。如果你也在被 AI 反复失忆困扰，不妨给 claude-mem 一次机会，从安装到形成自己的记忆习惯，值得花上一个周末去尝试。
