如果你经常用 Claude Code 写代码、搞重构大概率碰到过这种事上午刚和它对齐了项目的目录结构、技术栈和代码风格下午新开一个会话它又回到“失忆”状态连你用 React 还是 Vue 都要问两遍。这个问题的根源在于 Claude 的对话是无状态的每次会话都是一张白纸。claude-mem 就是为解决这个痛点而生的开源 MCP 服务器它的作用通俗讲就是给 Claude 装上一套长期记忆让它能自动记住哪些信息值得留在下一次会话里按需把旧记忆“翻”出来用。这篇文章我会从使用者的角度拆解 claude-mem 的记忆机制、安装接入、配置项、数据管理以及我实测过程中踩过的几个坑。内容主要面向已经在用或打算长期用 Claude Code 的开发者也适合想给自己的 Agent 加记忆层的玩家。我会尽量把“为什么这么做”讲清楚而不是只给一套命令让你复制。1. Claude 的“失忆”是设计使然claude-mem 到底在补什么缺1.1 无状态不是 bug是一笔成本账Claude 的 API 在设计上就是无状态的。每次请求服务端不会主动保存上一轮对话的状态你需要把所有历史消息作为上下文传给它。对服务方来说无状态意味着可以横向扩容不需要维护海量的会话状态对应用层来说无状态也意味着数据更可控对话结束即是删除安全和合规上的负担小。这些都是实打实的优点。但对开发者来说无状态的代价在长期项目里会越来越明显。第一上下文窗口再大也是有限的Token 成本却在持续累积。你手动在 system prompt 里塞历史记录到了第 20 轮对话基本就不可用了。第二即使你愿意花 Token 钱那些散落在对话日志里的关键决策、用户偏好、技术约束也不会自动收敛成一条干净的记录。新会话开始时Claude 知道的和你第一次打开它时一样多。所以在 Claude Code 这类编程工具里社区通用的做法是“外置记忆”把项目说明、常见约束写进 CLAUDE.md 或项目文档手动引导模型每次读取。这个方案我用了挺久它有效但有一个致命前提你得记得去维护而且 Claude 只能在你明确指示下被动地记它不知道“什么东西值得记”、什么时候该把旧记忆翻出来。claude-mem 切入的角度就是从这里开始的。它不是一个帮你写文档的辅助工具而是一个跑在 MCP 协议上的记忆服务由 Claude 自己在对话中判断该记什么再把信息结构化存下来下次对话由 Claude 按需检索、注入到上下文。相当于把“外置记忆”这个需要人肉维护的状态变成了一套自动运转的机制。1.2 记忆方案对比为什么我最后选了 claude-mem在决定用 claude-mem 之前我也比较过几种方案这里直接给一张表方案记忆来源检索方式维护成本与 Claude Code 的集成度手写 CLAUDE.md人全量载入高容易过时原生但不聪明自建 RAG 管道外部脚本向量检索需自己写接口高需要自己封装claude-memClaude 自主提取语义全文检索通过 MCP 注入低原生 MCP 服务器表格里最值得展开的是最后一行。claude-mem 最吸引我的点有两个第一它不是被动的知识库而是“调度器”。决定记什么、什么时候记、什么时候取这些判断都由 Claude 来完成。你不需要维护一个专门的处理脚本也不需要在每次对话开始时手动指定“请先读取记忆”。记忆的写入和读取都发生在对话流程之中。第二它跑在 MCP 协议上。Claude Code、Claude Desktop 以及很多支持 MCP 的客户端都原生兼容装好 MCP 服务器就能用不需要改业务代码。你既可以把它当成个人助手的长效记忆也可以扩展为团队共享上下文。当然它也不是万能的。记忆质量高度依赖 Claude 本身的判断力如果模型在某个领域表现不佳记忆的准确性也会打折扣。但作为开发者工具它已经足够好用。2. 记忆的运转逻辑Claude 怎么知道该记什么、该翻什么2.1 两套记忆显式记忆文件 语义数据库第一次用 claude-mem 的人容易把它理解成一个“聊天记录存档器”但它的设计比这精细得多。据我目前的使用经验它把记忆分成了两层。第一层是显式记忆文件通常以 Markdown 形式存放在本地记忆目录里Claude 在需要的时候可以直接读取。这个文件的定位类似于一份“从历史对话中提炼出的项目速写”特点是结构化、可读、稳定适合承载那些需要反复出现的硬信息——比如用户的名字、项目的主要约束、你惯用的包管理器、测试命令、分支策略等。第二层是语义数据库。claude-mem 默认用 PGLite 把记忆向量化后存起来并建立全文索引。它的价值在于搜索当你在新会话里问“之前关于数据库分表我们是怎么定的”Claude 不是去翻原始聊天记录而是通过 SearchMemory 工具做语义检索把相关度最高的片段捞回来。对应到人的记忆模型这就像“模糊回忆”——你不必给出准确关键词描述个大概就能把旧账翻出来。我自己是这样理解这两层关系的记忆文件是长期贴在桌面上的便签它一直在视线里但你不会给便签写长篇小说语义数据库是身后的一整柜档案平时锁着问到了才去查。两条路径互补既保证核心信息一定能被看到又避免把所有历史都塞进上下文窗口。2.2 Memory 工具让 Claude 学会“记重点”自动记忆的核心不在数据库而在 Claude 的判断规则。claude-mem 启动后会通过 MCP 向 Claude 暴露一组工具同时往 system prompt 里注入一段记忆指令里面规定了什么时候该调用工具、该存什么。这条指令的大意是当你发现用户透露了可复用的个人信息、项目决策、代码约定时调用 Memory 工具把这信息存下来。也就是说记忆动作的发起方从“用户”变成了“模型”。我举个例子有次我在对话里说了一句“这个项目里我们统一用 pnpm不用 npm”下一轮 Claude 就调用了 Memory 工具把“项目使用 pnpm 作为包管理器”这句话写进了记忆。全程我都没有说“请记住”。根据我的观察它判断“值得记”的信息大致有几类用户身份与偏好姓名、角色、常用技术栈、沟通风格项目级约束目录结构约定、依赖管理策略、测试工具选择关键决策为什么选了某个方案、哪块代码被重构过、结论是什么术语与命名内部缩写、特殊文件路径、专有名词这里必须说一句真正好用的记忆不是“什么都存”而是“知道该扔什么”。Claude 现在的判断力还远称不上完美但已经能覆盖大部分高频场景而且它有用结构化输出规范来限定记忆条目格式的意识防止记成流水账。2.3 SearchMemory 与上下文注入检索结果怎么进入对话每开一个新会话claude-mem 并不会把所有记忆一股脑塞给 Claude。如果那样做无状态问题的解法只是换了种方式把 Token 烧掉。它的实际工作方式更像“按需取用”。对话开始后Claude 结合当前任务判断是否需要历史记忆。如果需要就调用 SearchMemory 工具把用户的问题或当前上下文作为检索条件在语义数据库里找相关片段。检索结果会以上下文片段的形式返回Claude 再把它自然融入当前回复。这个设计有两个直接好处第一Token 开销可控不会被旧记忆占满上下文第二避免信息污染你问“这周的发布计划”它不会把三个月前的琐事也给翻出来。不过按需取用也有代价检索质量决定记忆利用率。如果检索召回了一堆弱相关片段或者漏掉了关键片段Claude 依然表现得像失忆。claude-mem 在这块的处理是在底层同时做全文检索和向量检索再对结果做排序尽量把相关度高的内容送进上下文。实际用下来“我记得好像有这回事”这类模糊查询的命中率还不错。除了 SearchMemory工具集里还有负责拉取上下文前情的工具名称在不同版本里可能略有差别。我习惯把两者的分工理解为SearchMemory 回答“我记得好像有这回事具体是什么”前者回答“这个项目的前情提要是什么我接手时的状态如何”。2.4 对话归档SaveChat 让每次会话都留底除了点状记忆claude-mem 还会把完整的对话保存下来对应的是 SaveChat 工具。这个功能在项目复盘和问题回溯时特别有用。比如某个 bug 从发现、分析到修复中间经历了哪些讨论靠记忆碎片拼不出完整链路但有完整会话文档就可以查。对话保存策略可以通过环境变量控制比如 CLAUDE_MEM_SAVE_CHATS 控制总开关CLAUDE_MEM_CHAT_STRATEGY 控制保存节奏。归档的格式一般是可读的 Markdown 或 JSON 文件存放在本地数据目录里之后可以交给其他脚本做二次分析。对我来说这个功能最舒服的用法不是“留档”而是作为“工作日志自动生成器”。每隔一段时间我直接翻会话归档就能还原出某个功能是怎么一步步定下来的省去了自己写周报时翻聊天记录的时间。3. 五步上手安装接入、初始化和自检3.1 环境准备Node 版本与 MCP 客户端在装 claude-mem 之前先确认环境满足最基本的三点Node.js 18 或更高版本npm/npx 可用你日常使用的客户端支持 MCP比如 Claude Code、Claude Desktop或者其他兼容 MCP 的编辑器插件能正常访问 npm registry因为首次启动需要拉取依赖包Node 版本这块多说一句如果你的 Node 太老启动 MCP 服务器时可能会报一些莫名其妙的模块错误但错误信息里通常不会直接提示版本问题。我的习惯是先node -v看一眼达不到要求就用 nvm 切换。3.2 命令行安装与 MCP 服务器注册我推荐用 npx 方式运行不需要全局安装也能快速体验。先跑一下版本号确认包能正常拉取npx -y hackmd/claude-mem --version确认没问题后在 Claude Code 里把它注册为 MCP 服务器claude mcp add claude-mem -e CLAUDE_MEM_SAVE_CHATStrue -- npx -y hackmd/claude-mem命令里的-e CLAUDE_MEM_SAVE_CHATStrue是给 MCP 服务器传入环境变量表示允许保存会话。不同版本的 claude CLI 参数可能略有差异以你本地的claude mcp add --help输出为准。如果你用的是 Claude Desktop 或其他 MCP 客户端就需要手动编辑客户端的 MCP 配置文件写法是这样的{ mcpServers: { claude-mem: { command: npx, args: [-y, hackmd/claude-mem] } } }配置完一定要完全退出客户端再重新打开。MCP 的服务器列表是在启动阶段加载的有些客户端提供了热重载按钮但据我经验完全重启最可靠。3.3 初始化目录与配置注册成功后执行初始化命令claude-mem init这个命令会创建 claude-mem 的数据目录和默认配置文件。跑完之后可以执行claude-mem config打印当前生效的配置包括记忆文件路径、数据库路径、是否保存对话等。刚 init 完看到的基本都是默认值后面想调参再通过环境变量覆盖不需要改代码。3.4 健康自检doctor 一定要跑一次装好之后我强烈建议先跑一次claude-mem doctor它会检查 Node 版本、MCP 连接状态、数据库可写性、记忆文件路径是否存在这几项发现问题会给出对应的修复提示。这个命令特别适合在你改动过环境变量、切换过 Node 版本后用来排查。还要提醒一个细节如果你不希望每次启动都通过 npx 联网拉包可以改成全局安装npm install -g hackmd/claude-mem然后把 MCP 注册命令里的 command 从npx -y hackmd/claude-mem换成claude-mem。这样更稳定响应也更快算是团队里多人统一环境时的一个小技巧。4. 配置项与数据管理让记忆库按你的节奏生长4.1 关键配置项速查claude-mem 的配置基本靠环境变量我列几个最常用的环境变量作用我常用的取值CLAUDE_MEM_HOMEclaude-mem 数据根目录~/.claude-memCLAUDE_MEM_MEMORY_PATH显式记忆文件路径$CLAUDE_MEM_HOME/memory.mdCLAUDE_MEM_DB_PATHPGLite 数据库路径$CLAUDE_MEM_HOME/pgliteCLAUDE_MEM_SAVE_CHATS是否保存完整对话trueCLAUDE_MEM_CHAT_STRATEGY保存对话的时机策略autoCLAUDE_MEM_SYSTEM_PROMPT自定义记忆系统提示词视版本支持内置即可组合起来大概是这样export CLAUDE_MEM_HOME$HOME/.claude-mem export CLAUDE_MEM_MEMORY_PATH$HOME/.claude-mem/memory.md export CLAUDE_MEM_DB_PATH$HOME/.claude-mem/pglite export CLAUDE_MEM_SAVE_CHATStrue如果你在登录 shell 里写了这些变量记得让客户端继承同样的环境。Claude Code 的 MCP 注册命令里也可以逐个-e传进去保持一致性。4.2 存储后端PGLite 与 Postgres 怎么选默认情况下claude-mem 使用 PGLite 作为存储后端。PGLite 是嵌入式 Postgres 的 WASM 实现不需要单独安装数据库服务数据落在本地文件夹里。对个人开发者来说这是最省心的方案零运维、零配置数据就在自己的磁盘上。如果你跑团队项目想让多个人的 Claude 共享一套记忆或者想把记忆数据放到中心化数据库里统一备份那可以切换到完整 Postgres。做法是设置 DATABASE_URLexport DATABASE_URLpostgresql://user:passwordlocalhost:5432/claude_mem需要提前在数据库里启用 pgvector 扩展因为 claude-mem 的向量检索依赖它做相似度查询。两种后端我各用了一段时间。个人项目的结论是PGLite 够用不用折腾团队协作或者想把记忆和现有审计体系串起来时Postgres 更合适。切换后端之前记得先把原有记忆文件备份好。4.3 CLI 实操手动补记、搜索和清理虽然自动记忆是主打功能但 CLI 手动操作在日常维护中也很重要。我常用的几条命令如下# 手动补记一条信息 claude-mem remember 用户偏好使用 pnpm 管理依赖 # 搜索记忆库 claude-mem search 项目约定 # 列出保存过的会话 claude-mem chats # 查看某次会话详情 claude-mem chat 会话ID # 查看当前配置 claude-mem config # 重置数据库慎用 claude-mem reset手动补记适合在 Claude 没意识到某信息重要时使用。搜索则是我定期检查记忆质量的工具——如果搜索出来的结果和我的记忆有偏差说明它在自动提取时存歪了需要及时修正。4.4 记忆维护锁定重要条目清掉过期信息记忆库和代码库一样需要维护。我目前的操作习惯是直接编辑显式记忆文件把那些必须长期生效的强约束条目放在最前面并且保持表述简短让 Claude 每次读到这里都能第一时间看到语义数据库里的内容则交给检索和数据沉淀自然筛选。如果发现某条记忆过时了直接在对话里跟 Claude 说“更新一下我们已经不用 Jest 了改成 Vitest”它会走 Memory 工具更新记忆。如果错误信息已经污染了很多条目最干净的办法是先claude-mem search看一眼污染范围再决定是手动清理还是 reset 后重新积累。5. 实测避坑我用 claude-mem 踩过的四个坑5.1 记忆文件越写越长反而等于没记我刚开始用的时候把记忆文件当成“详情页”恨不得把每个决策的原因、讨论过程都写进去。结果文件越来越长Claude 每次都要花大量 Token 读取重点反而不突出了语义检索的质量也跟着下降因为相似度计算被一堆弱相关条目干扰。后来我强迫自己遵循两个原则第一记忆文件控制在 200 行以内只写结论和摘要第二每条记忆尽量一句话讲清楚比如“项目使用 pnpm禁 npm”而不是“我们讨论了 npm 和 pnpm 的优劣最后由于团队习惯选择了 pnpm”。细节留到语义数据库里按需检索别想着一次性全部塞给模型。5.2 MCP 注册后工具不生效大概率是重启不到位这是我遇到次数最多的问题。明明claude mcp add执行成功了也看到配置文件里多了 claude-mem 的条目但进了 Claude Code 之后工具列表里就是没有 claude-mem。排查下来几乎都是同一个原因配置修改后没有完全退出客户端。MCP 服务器列表在启动阶段加载。一些客户端虽然提供了热重载或刷新按钮但实测并不可靠。我的建议是改完配置直接退出进程重新打开。另外如果 npx 方式首次拉包较慢或者网络状况不佳注册阶段也可能直接失败。遇到这种情况换成全局安装再注册把npx -y hackmd/claude-mem改成claude-mem几乎所有偶发问题都能绕过去。5.3 自动记忆会把推测存成事实这是自动记忆的固有风险Claude 在对话中如果听到了“我可能想用 Node 写个服务端”这类带推测色彩的话有可能把它当成客观事实记下来。下次对话它可能煞有介事地引用“用户需要用 Node 写服务端”实际上你只是随口一提。我的应对方法是分三层日常对话中关键决策尽量用明确句式说出口比如“最终决定用 Deno”少用“可能”“或许”定期跑claude-mem search抽查记忆条目发现问题当场纠正如果某条记忆的判断价值很高直接在记忆文件里手动改成强约束句式5.4 多项目共用一套记忆串味之后很难受claude-mem 的记忆可以是全局的也可以按项目隔离。我在刚开始时就吃过亏A 项目用 ReactB 项目用 Vue结果两个项目的对话被放进同一套记忆里Claude 在 B 项目里偶尔会建议我用 React 的生态库非常难受。后来我针对不同工作目录分别配置了独立的 CLAUDE_MEM_HOME 和 CLAUDE_MEM_MEMORY_PATH让每个项目各有一份自己的记忆库。这个操作不复杂但非常关键。如果你平时会接多个不同类型的项目我强烈建议从一开始就按项目分目录而不是等串味了再重构。6. 从“能用”到“好用”记忆层的进阶做法6.1 用记忆模板统一信息粒度为了让自动记忆的条目更结构化我试过把记忆模板固定成几段字段Context这条记忆适用的场景Decision当时定下的结论Reason选的这个方案的原因Action后续要执行的行动效果很明显。模板化之后记忆条目不再是散装句子而是上下文清晰的“决策卡片”。后期我做语义检索时召回率没有明显变化但 Claude 引用记忆解释问题时更有条理了因为 Reason 字段直接给了它推理材料。如果你用的版本没有暴露自定义提示词的配置也不用担心。直接在记忆文件里把零散条目整理成统一格式同样能达到大部分效果。重点是记忆的存储格式决定了模型读取时的利用率。6.2 定期整理记忆我的维护节奏我目前给 claude-mem 配了每个工作日结束前的“记忆体检”习惯。具体动作是用claude-mem config看一下记忆文件路径打开记忆文件扫一眼确认核心约束没丢如果发现过时条目直接在文件里改掉或让 Claude 更新每周我再跑一次claude-mem search挑几个本周高频出现的主题做抽查看看语义数据库里有没有存歪的内容。这套节奏花不了几分钟但能让记忆库长期保持健康。6.3 把 claude-mem 当作 Agent 的记忆层来设计最后再往远说一步。claude-mem 虽然是为 Claude 设计的但它的本质是一个 MCP 记忆服务完全可以作为更通用 Agent 架构里的一个组件。我在写内部工具时就把它的能力暴露给了自己的编排框架Agent 接到任务前先通过 MCP 拉取历史上下文任务结束后把结果写回记忆库。这样一来跨会话的状态管理就不散落在各处了而是统一沉淀在一套记忆服务里。如果你也打算在项目里引入长期记忆我的建议是从小的场景开始先把 claude-mem 挂在 Claude Code 里跑一周观察哪些信息它记住了、哪些记歪了再决定要不要继续往 Agent 框架的深处走。记忆这个东西只有用起来才知道怎么优化。