你有没有遇到过这种情况昨天刚和 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。MCPModel 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 一次机会从安装到形成自己的记忆习惯值得花上一个周末去尝试。