如果你长期用 Claude Code 写项目，八成遇到过同一个场景，昨天刚让它记住的一条约束，今天新开一个会话，它直接给你演了一出“我们好像在哪见过，但完全不记得”。我自己的做法是反复在对话里贴背景说明，贴到最后恨不得写一本书。直到我注意到 claude-mem 这个项目，才意识到问题不是 Claude 不够聪明，而是它缺少一层真正属于自己的记忆层。
claude-mem 是一个给 Claude Code 做持久化记忆的开源工具，核心思路是把对话里值得留存的决策、偏好、技术约束自动或手动保存起来，下次会话通过语义检索找回。它基于 MCP（Model Context Protocol）工作，不把数据送上网，全部落在本地。这篇文章我会把它的原理、安装配置、实测表现和踩过的坑一次性讲清楚，适合正在重度使用 Claude Code、也对 AI Agent 工作流感兴趣的开发者参考。
1. Claude Code 的“失忆症”：问题到底有多痛
1.1 会话隔离是设计特性，不是缺陷
先说一个容易误解的点：Claude Code 每个会话之间相互独立，这其实不是 bug，而是架构上的主动选择。
大模型本身没有跨会话记忆，推理时只能看到当前上下文窗口里的内容。Claude Code 作为一个终端编程助手，每次启动新会话都相当于找了一个“刚入职、只看了当天邮件”的新同事。它不知道你昨天定过什么技术方案，不知道你习惯用 pnpm 而不是 npm，更不知道某个模块为什么绕了一大圈不用现成库。为了保持单次会话的上下文可控、token 开销稳定，Claude Code 选择了“一会话一清空”。
这种设计的收益是每次对话的上下文都不会无限膨胀，但代价也显而易见：项目周期一长，大量有效信息被丢在了一个又一个已经关闭的会话里。
1.2 我遇到的三个典型失忆场景
我在实际开发里，反复踩过这三类坑。
第一类是架构决策的流失。比如上周我和 Claude 讨论过，为什么订单模块最终选了单机事务而不是分布式事务，结论是因为当前量级和团队维护能力根本不匹配。本周我新开会话，让它继续写订单结算逻辑，结果它又一本正经地把分布式事务方案重新拿出来，理由是“更健壮”，完全不知道我们已经否决过了。
第二类是隐性约束的遗忘。我习惯要求生成的代码里不放 console.log，错误处理统一用自定义 BizError，接口返回统一包一层 data。这些偏好在某个会话里说了一次，Claude 照做了，但换一个会话，它又回到了通用开发规范，我得把同样的偏好逐字再输入一遍。
第三类是跨会话一致性问题。项目里的常量命名、目录结构约定、数据库表的命名规则这些信息，分散在多个历史会话中。新会话要么只能看到最近一次的描述，要么干脆看不到。我花在“让 Claude 重新理解项目规矩”上的时间，占比相当高。
1.3 CLAUDE.md 能解一部分，但离“记忆”还很远
很多人第一反应是：项目根目录不是有 CLAUDE.md 吗，把约束写进去不就完了？
CLAUDE.md 确实能承载一部分静态约定，适合放项目简介、目录结构、代码规范这类稳定信息。但它有两个绕不过去的问题。
一是维护成本高。每次决策变化都得手动改文档，而改文档这件事，开发者在赶进度时通常没空做。二是检索能力弱。CLAUDE.md 是一份线性文档，当项目复杂到十几个章节、几千行时，Claude 每次会话都要把全部内容塞进上下文，token 开销大不说，真正相关的信息还会被淹没在没有优先级的长文本里。
我更愿意把 CLAUDE.md 比作一本“入职手册”，适合描述项目是什么。但记忆不一样，记忆是你跟这个项目共同经历过的决策过程，是动态的、有上下文的、分优先级的。claude-mem 补的正是这一层。
2. claude-mem 的核心设计：存、管、取三层拆解
2.1 MCP 通道：让 Claude 多了一双“能翻笔记本的手”
claude-mem 不是改写了 Claude Code 内部逻辑，而是以 MCP Server 的身份接入。
MCP 可以简单理解成给 AI 助手上外挂能力的标准协议。通过 MCP，Claude Code 能调用外部工具，就像人类多了一双可以随时翻笔记本、查资料的手。claude-mem 把自己做成一个本地 MCP Server，向 Claude 暴露几类工具，比如保存记忆、搜索记忆、删除记忆、列出记忆。
当你问 Claude“我上次为什么选用这个方案”，它会先调用搜索记忆的工具，在本地记忆库里做一次检索，再把命中的片段带回对话里。整个过程对用户来说几乎是透明的，你看到的只是 Claude 突然“想起来”了之前的决定。
这个设计的好处是低侵入。claude-mem 不需要改动 Claude Code 本身，只要按 MCP 标准接入就能工作。哪怕以后 Claude Code 升级，只要 MCP 协议兼容，记忆层基本不用动。
2.2 两类记忆：自动沉淀的和手动钉牢的
claude-mem 里有两类记忆，分别对应两种使用习惯。
自动记忆是让 Claude 在对话过程中自己判断“这条信息值得存”，然后调用工具写入记忆库。比如你明确说“本项目统一使用 pnpm”，这句话大概率会被自动保存为一条偏好记忆。它适合捕捉那些你嘴上说了、但没意识到要留档的信息。
手动记忆是靠用户主动触发的。在 Claude Code 会话里加#memories标签，或者调用/memories命令，把当前上下文里的关键决策显式存成一条记忆。比如技术选型讨论结束后，我会手动总结一句“订单模块保持单机事务，不引入分布式事务框架”，然后钉进记忆库。
我个人的经验是，自动记忆负责兜底，手动记忆负责关键节点。自动记忆能捞到很多你根本想不起来要存的东西，但它的判断标准是通用性的，不一定懂你项目的优先级。真正重要的架构决定、不可逆的选择，一定要手动存。
2.3 语义检索：为什么“模糊找”比“精确找”更关键
claude-mem 和普通数据库最大区别，在于取记忆的方式是语义检索而不是关键词匹配。
它会把每条记忆文本做向量化处理，存进本地向量索引。搜索时，拿你的问题也做一次向量化，然后找出语义上最接近的记忆片段。这意味着你不需要记得原话。哪怕你问“上次我们为什么不用那个消息队列”，它也能匹配到之前保存的“Kafka 引入成本过高，维持现有 Redis Stream 方案”这类表述。
这个设计很聪明。因为人的记忆本来就是模糊的，你能记住的是“我们讨论过某个事，大概结论是不用”，而不是精确到标点的原话。语义检索正好贴合这种使用方式。
底层存储上，claude-mem 默认使用 SQLite 保存结构化数据，搭配本地向量索引做近似检索。所有数据都落在项目目录下的.claude-mem里，默认配置下不依赖外部数据库服务。如果项目团队需要共享记忆，可以改成 PostgreSQL 或其他远端存储，但单机使用场景下本地方案就够了。
2.4 数据落在本地：隐私和成本的权衡
这一点我很看重。claude-mem 默认的向量化和存储都在本地完成，不会把你的代码和决策送进某个云端。
有些同类工具会把记忆库同步到云端，方便多设备访问，但代价是代码相关的记忆片段被第三方服务器经手。对商业项目来说，这通常不能接受。claude-mem 的本地优先策略，意味着 memory 库和项目代码一样，只存在于你自己的磁盘里。
成本方面，本地向量化模型不消耗 OpenAI 或 Anthropic 的 API 额度，检索也快。我试过在普通笔记本上跑，搜索一条记忆的延迟对对话流畅度基本没有可感知的影响。唯一要留意的是记忆量大了以后，自动记忆的精准度会下降，这个我后面单独说。
3. 从零到跑通：安装、初始化与首次体验
3.1 环境前提：Node、Claude Code 与 MCP 配置入口
先说环境要求。claude-mem 是 npm 包，所以本机得有 Node.js，建议 18 以上。Claude Code 本身也是跑在 Node 环境里的，一般安装了 Claude Code 的机器都不会缺。
接着要搞清楚 MCP 配置入口。Claude Code 的 MCP 配置分三个层级：用户级、项目级、本地级。用户级配置对所有项目生效，写在~/.claude.json里；项目级配置写在当前项目的.mcp.json；本地级是~/.claude/.claude.local。
我建议首选用户级注册，因为 claude-mem 这种通用工具没有理由限死在单个项目里。一个记忆服务管所有项目，反而省事。
3.2 安装并注册 MCP Server
安装分两步。第一步用 npm 全局安装 claude-mem：
npm install -g claude-mem第二步是把 claude-mem 注册成 Claude Code 的 MCP Server。新版 Claude Code 提供了claude mcp add命令，可以直接注册：
claude mcp add claude-mem -- npx -y claude-mem这里加npx -y是让 Claude Code 在启动 MCP Server 时自动拉取并执行 claude-mem，避免手动维护全局安装路径。如果你已经全局安装，也可以直接用claude-mem作为命令。
注册完之后，跑一下claude mcp list确认 claude-mem 出现在列表里，并且 status 是 connected。这一步我见过太多人卡住，后面会专门讲。
3.3 初始化记忆仓库
MCP Server 注册好后，还需要在项目目录里初始化记忆库：
claude-mem init这条命令会在当前目录下创建.claude-mem文件夹，包含配置文件和存储目录。初始化完，可以顺带看一眼配置：
claude-mem config show你会看到几个关键项：存储路径、自动记忆开关、嵌入模型配置、每次检索返回的最大记忆条数和 token 上限。这些参数我先不建议改，默认值跑通再说。
3.4 在会话里第一次调用记忆
初始化完成，进入 Claude Code 交互界面，最直接的验证方式就是触发一次记忆保存和读取。
我在会话里输入：
#memories 记住：本项目的所有数据库表名统一使用小写下划线，不用驼峰过一会儿，Claude 会通过 MCP 调用保存工具，然后回复一条类似“已保存”的确认。这一步本质上是把会话里的一句话写入记忆库，并向量化。然后我新开一个会话，问：
#memories 数据库表命名有什么要求？正常情况下，Claude 会检索到刚才那条记忆，并给出准确回答。到这里，整个链路已经通了：自动提取、向量存储、语义检索、对话注入。
3.5 常用 CLI 命令清单
平时管理和排查记忆，我会用到这几条命令：
# 列出当前项目所有记忆 claude-mem list # 查看某条记忆的完整内容和元信息 claude-mem view <memory-id> # 按关键词/语义搜索 claude-mem search "表命名规范" # 删除某条记忆 claude-mem forget <memory-id> # 查看整体统计信息 claude-mem statsview是我排查问题时最常用的。它能显示这条记忆是哪次会话自动提取的、原始文本是什么、嵌入模型版本是什么。有时候 Claude 答非所问，不看记忆原文根本定位不了问题。
4. 真实开发里的实测效果：哪些场景真香，哪些场景拉胯
4.1 场景 A：跨会话恢复技术选型上下文
我试用 claude-mem 最典型的场景，是连续开发一个订单系统。
第一天，我在会话里和 Claude 讨论并确定“订单状态流转用状态机模式，不用状态字段散落多处判断”。我手动把它存成一条记忆。第二天新开会话，让它继续实现订单取消接口，我没提任何背景，只是问了一句“按照我们之前定好的订单状态流转方式来写”。
Claude 检索到了那条记忆，然后真的按状态机模式实现了状态变更逻辑，还在回复里补充了状态机当前的四个状态和流转条件。这种体验就很接近“同一个老同事第二天接着干活”的感觉，而不是“刚来的实习生”。
4.2 场景 B：自动记忆的精度与噪声
自动记忆是 claude-mem 的亮点，但也最容易翻车。
我用默认配置跑了两周，发现它对明确指令的识别效果很好，比如“移除用户表中的冗余字段”这种带明确动词和对象的句子。但对话里出现感想式、判断式内容时，它偶尔会记下一些没什么还原价值的碎片。比如我随口说“这段代码看起来有点冗余”，它也可能存进去。这种记忆本身不危险，但它会污染后续检索结果。
后来我给自动记忆加了一些过滤习惯。一是关键决策继续手动存，自动记忆只当兜底；二是每隔几天用claude-mem list扫一遍，看到没价值的直接forget掉。记忆不是越多越好，是越准越好。
4.3 场景 C：多项目间的隔离
claude-mem 默认按项目隔离记忆。A 项目的.claude-mem里只存 A 项目的记忆，B 项目检索不到 A 的内容。
这个设计在最初使用时会觉得不方便，但长期看非常正确。不同项目的技术栈、编码风格、业务背景差异很大，如果记忆库是全局共享的，A 项目的一句“这个用 Redis 就行”很可能会被 B 项目误当成技术选型依据，那就成了跨项目污染。
不过要注意一点，如果你确实想让多个项目共享部分记忆，比如同一套公司级编码规范，就需要手动维护全局记忆路径或者用远端存储方案。默认的项目隔离更安全，也更简单。
4.4 性能开销：有没有让 Claude 变笨变慢
这是我很关心的一个点。加了 claude-mem 之后，Claude Code 的响应会不会变慢，token 会不会暴涨？
实测下来，单次搜索的开销非常低。本地嵌入模型跑一条查询基本在毫秒级，返回的记忆会以额外上下文形式注入，但这个量级是可控的。claude-mem 有配置项控制每次检索返回的 token 上限，默认值不会把整个记忆库都塞进上下文。
真正影响体验的不是插入记忆这个动作，而是记忆质量。如果检索出来的记忆跟当前问题无关，Claude 会尝试把这些无关信息也纳入推理，反而降低输出质量。这就是为什么前面强调要定期清理、要手动钉牢关键决策。
5. 踩坑记录与当前版本的使用边界
5.1 坑一：MCP 注册后始终显示 disconnected
我最初用claude mcp add注册时，一直显示 disconnected。排查到最后，发现是 Node 路径问题。
Claude Code 以 GUI 应用方式启动时，PATH 环境变量里可能不包含 nvm 管理的 Node 路径，导致它找不到npx。解决办法有两个：一是用绝对路径注册，比如claude mcp add claude-mem -- /path/to/npx claude-mem；二是手动指定全局安装路径上的可执行文件。
另外一个快速验证技巧：直接打开终端跑npx -y claude-mem，看进程能不能正常启动。如果命令行能跑通，大概率只是 PATH 没被 Claude Code 继承。
5.2 坑二：自动记忆开太猛，检索结果被污染
我有段时间把自动记忆相关参数调得很高，结果新会话里搜索任何问题，都先翻出来十几条无关记忆。Claude 的回复风格明显变得发散，开始把不相关的历史决策拉进当前讨论。
解决思路有两条。第一是调低每次搜索返回的记忆数量，优先保证最相关的两三条进入上下文。第二是定期做减法，把自动记忆里明显没用的内容清理掉。如果你用的是claude-mem配合团队共享库，清理时还要考虑影响面，所以更要控好入口质量。
5.3 坑三：升级 Claude Code 后 MCP 配置丢失
有一次我升级了 Claude Code 版本，重新登录了 CLI，结果claude mcp list里空空如也。不是 claude-mem 的问题，而是升级过程重置了用户级配置。
这类问题很难完全避免，我能给的实用建议是：把注册命令写进项目的 README 或者存成一个 setup 脚本。真丢了，跑一遍命令就回来了，不用重新想当初是怎么配的。
还有一个保险做法，把 claude-mem 写进项目级.mcp.json。项目级配置会跟着仓库走，就算本机用户级配置重置，新成员拉取代码或你重新装环境，也能快速恢复。
5.4 边界：什么时候别依赖 claude-mem
claude-mem 很实用，但不是万能的。我遇到过几种不适合依赖它的场景。
第一种是记忆内容涉及大量代码块。比如你想保存某段完整的 SQL 脚本或一段算法实现，这类内容用文件存放更合理，记忆库更适合放“结论型”信息。如果你非要塞一坨大代码块进记忆，检索时大概率会截断，因为单条记忆的长度是有限制的。
第二种是需要严格时效性的信息。claude-mem 本身没有内置过期机制，一条几个月前的记忆，如果项目架构已经重构，它还在那躺着。你只能在架构大变动时手动清理相关记忆，没有更聪明的自动办法。
第三种是实时性强的任务状态，比如“当前正在重构哪个模块”。这类状态变化太快，不适合写入记忆库，更适合用任务管理工具维护。
5.5 顺着源码改一版的可能性
如果用过一段时间后，你觉得默认配置不够用，可以考虑直接看源码改。它的代码结构不算复杂，核心就那几块：MCP Server 入口、记忆管理器、向量索引模块、CLI 命令层。
我做过一次最小改动，给自动记忆加了一条规则：包含“取消”“删除”“不再”这类否定词的高频指令，不再自动保存。因为经验告诉我，这类“反向决策”虽然是重要变更，但自动提取时很容易脱离上下文，存下来反而误导后续会话。
直接引用 claude-mem 的依赖包做二次开发也是个思路。它在 MCP 生态里是比较标准的实现，对想学习怎么写 MCP Server 的开发者来说，本身就是一份不错的学习素材。
最后说点实打实的经验
用 claude-mem 这段时间，我最深的感受是：工具提供的不是“AI 记得所有事”这个结果，而是一个让你和 AI 之间“共同维护项目记忆”的工作流。只要养成两个习惯——关键决策手动存，无关记忆定期清——它给 Claude Code 带来的连续性提升是肉眼可见的。如果你正准备给自己的 AI 编程工作流加一层持久记忆，我建议不要全局一键全自动，先从手动记忆跑起，等摸清了它的脾气，再逐步放开自动提取。这样你获得的不是一个“什么都记得但什么都记不全”的助手，而是一个真正懂你项目脉络的搭档。
