如果你和我一样把 Claude Code 当成每天都要用的开发搭子你一定经历过这种无奈上午刚跟它敲定了一套项目规范下午新开一个会话它又变回那个“初次见面”的陌生助手。这不是模型变笨了而是大模型本身没有跨会话的记忆能力——每个会话都是一张白纸聊得再深入关掉就归零。claude-mem 就是为解决这个痛点而生的一个开源的 MCP 服务器专门给 Claude 补上“长期记忆”让它能跨会话记住你的偏好、项目背景、技术决策甚至之前排过错的完整上下文。这篇文章我会从整体设计思路、安装配置、底层原理到实际使用和踩坑记录完整分享我把它接入日常工作的全过程。适合正在用 Claude Code、被“会话失忆”折磨到重复交代上下文的人也适合想给自己的 AI 工作流加一层持久记忆层的开发者。1. 项目要解决的核心痛点与整体设计思路1.1 Claude 会话失忆的本质大模型本身是“无状态”的。它每一次推理只能看到当前上下文窗口里的内容窗口之外什么都不存在。Claude Code 这类 CLI 工具虽然把对话、文件操作、命令执行整合得很好但它的会话仍然是独立的一个 session 结束所有对话内容就留在那个 session 里了。我最早被这个问题搞崩溃是在一个多模块项目里。第一天我跟 Claude 约定“数据库统一用 PostgreSQLORM 用 Drizzle不要引入 Sequelize。”那天它执行得非常好。第二天新开会话我让它写一个新的数据表定义它兴冲冲地给我生成了一段 Sequelize 风格的代码。那一刻我意识到不是模型能力不行是我缺少一个“记忆层”。这就像请了个能力很强的临时工每次都要重新讲一遍公司规章制度效率全耗在重复沟通上。1.2 claude-mem 是怎么给 Claude“装记忆”的claude-mem 的核心思路并不复杂它作为 MCPModel Context Protocol服务器运行给 Claude 提供一套“记忆工具”。模型在对话中可以直接调用这些工具来写入记忆、搜索记忆、更新记忆。MCP 你可以理解成 AI 应用的“USB 接口”标准化了模型与外部工具之间的通信方式Claude Code 原生支持这个协议所以 claude-mem 能以很低的接入成本挂进来。它的记忆并不是存在数据库里而是以 Markdown 文件的形式落盘。这个设计我非常喜欢记忆文件是纯文本人类可读、可编辑、可搜索还能放进 Git 里做版本管理。想看一眼 Claude 到底记住了什么直接打开目录就行不用连数据库跑 SQL。搜索记忆的时候它会把记忆文本转成向量做语义匹配而不是简单 grep 关键词。换句话说你之前写的是“部署时遇到 8080 端口被占用”新会话里搜“启动服务起不来”它也能把这部分记忆捞出来。1.3 为什么不用“复制总结”和“手写 memory 文件”在遇到 claude-mem 之前我试过两种土办法。一种是每次会话结束前让它生成一段摘要我手动复制到项目里的CONTEXT.md下个会话开头再粘贴进去。这办法能解决一部分问题但很脆摘要写长了浪费上下文窗口写短了丢细节而且完全依赖我记住“每次都要做这件事”。另一种是给 Claude 准备一个 memory 文件夹塞一些规范文档需要时让它去读。问题是 Claude 不会主动想到去读你得每句话都提醒“先看看 memory 目录”时间一长就烦了。claude-mem 的优势在于把“记忆”变成了模型的原生能力。它不用我操心什么时候写入、什么时候读取模型自己会在对话过程中调用工具。这个体验差别很关键从“人管理记忆”变成了“模型管理记忆人来监督”。我整理过三种方案的对比供你参考方案记忆持久性主动读取能力维护成本可检索性手动摘要复制会话级无高低手写 memory 文件夹文件级无高低claude-mem文件级有低强语义检索2. 安装部署与核心配置实操2.1 环境准备先确认这三样东西安装之前先确认环境省得后面排查半天。第一Node.js 版本要够新claude-mem 是基于 Node 实现的建议至少 Node 18 以上我用的是 Node 20运行得很稳。第二确认 Claude Code 已经装好并且能正常启动因为 claude-mem 要作为 MCP server 挂到 Claude Code 下面。第三确认你的终端能正常访问 npm registry因为安装是通过 npx 拉取包来完成的。这里多说一句隐私问题。claude-mem 默认可以在本地跑 embedding记忆文件的检索计算尽量不把内容发到第三方服务。如果你配置了远程嵌入模型那记忆内容会经过对应 API这个取舍我后面在配置部分会详细说。对隐私比较敏感的朋友可以直接把记忆目录放在本地磁盘上甚至可以放在一个加密目录里。2.2 安装接入两种方式任选我把 claude-mem 接进 Claude Code 用的方式是手动配置 MCP因为这样我能完全掌握参数。先建一个.mcp.json放在项目根目录内容类似这样{ mcpServers: { claude-mem: { command: npx, args: [-y, jplumey/claude-mem], env: { CLAUDE_MEM_MEMORY_DIR: ./.claude-mem } } } }保存之后重启 Claude Code它会自动发现并加载这个 MCP server。如果你的环境支持 CLI 自动注册也可以直接用命令添加claude mcp add claude-mem -- npx -y jplumey/claude-mem添加完成后可以用claude mcp list查看是否已经注册成功。我记得第一次执行这个命令时输出里直接列出了 claude-mem 的相关工具那一刻就知道接上了。2.3 关键配置项解读claude-mem 的配置主要围绕三块记忆目录、嵌入模型、检索参数。我把它在.mcp.json里用到的一些常用配置项整理成了表格方便你对照设置配置项作用建议CLAUDE_MEM_MEMORY_DIR指定记忆文件存放目录按项目拆分别所有项目共用一个目录CLAUDE_MEM_EMBEDDING_MODEL选择嵌入模型本地优先效果不够再换远程模型CLAUDE_MEM_OPENAI_API_KEY使用 OpenAI 兼容嵌入服务时的密钥仅在你选择远程嵌入时填写CLAUDE_MEM_TOP_K默认检索返回的记忆条数默认 5 左右检索不准时可调大CLAUDE_MEM_SIMILARITY_THRESHOLD语义相似度阈值低于阈值的记忆不返回防止噪声这里重点说一下记忆目录的选择。我最开始图省事把所有项目的记忆都指到同一个目录结果项目 A 的技术约定和项目 B 的环境配置混在一起Claude 检索时经常把不相关的记忆带进来。后来改成每个项目一个独立目录干净多了。如果你有团队协作需求可以在 Git 仓库里建一个.claude-mem目录跟着代码一起版本管理这样团队成员共享同一套记忆资产。2.4 验证安装是否成功配置完成后验证很简单。你可以在 Claude Code 里直接问它“你现在能调用 claude-mem 的工具吗”正常情况下它会回答能并列出可以用的记忆工具。更直接的验证方法是让它执行一次记忆写入比如请记住这个项目使用 pnpm 作为包管理器不使用 npm。等几秒后打开记忆目录看一眼应该能看到一个 Markdown 文件被创建出来内容里包含这条信息。这说明写入链路是通的。然后你再搜一次搜索记忆本项目的包管理器是什么如果它能准确回答“pnpm”说明语义检索链路也正常。我见过不少配置失败的朋友卡在“工具能加载但模型不会调用”这一步这种情况多半是版本不匹配重启 Claude Code 或者升级 claude-mem 通常能解决。3. 核心机制原理解析与关键工具拆解3.1 记忆目录结构与 Markdown 文件格式理解了 claude-mem 是怎么存记忆的你才能真正用好它。它的记忆落盘方式是文件系统不是数据库。我实际项目里的目录结构大概长这样.claude-mem/ ├── memories/ │ ├── 2025-03-12-会话记忆-数据库规范.md │ ├── 2025-03-13-排错记录-端口占用.md │ └── 2025-03-14-用户偏好-代码风格.md ├── archive/ └── metadata.json每个记忆文件是标准的 Markdown带一些元信息头。我印象最深的是记忆文件的第一行通常是标签和时间接着是正文。这种格式的好处在于你完全可以用 VS Code 直接打开记忆文件做人工修正——把过时的信息删掉把错误的记录改对就像维护代码注释一样。Claude 下次搜索时读取的是修正后的版本所以人机协作修正记忆是可行的。3.2 语义检索从“硬匹配”到“语义相似”claude-mem 搜索记忆不是用传统的关键词匹配而是先将文本转成向量。你可以把 embedding 简单地理解为“把一段文字转换成一串有数学含义的数字列表”语义相近的文字数字之间的距离也更近。搜索时它把你输入的 query 也转成向量然后和所有记忆文件的向量做相似度计算返回最接近的 top_k 条。我用过本地嵌入模型也试过远程 API实际体验差异主要在多语言和长文本的场景。本地模型的好处是隐私性强所有计算都在自己机器上完成不经过任何外部服务缺点是首次加载需要一些时间而且对于某些小众领域的专业术语召回效果不如大规模的远程模型。我的做法是普通项目用本地默认配置涉及复杂技术文档的项目切到远程嵌入。切换只需改环境变量记忆文件不用动很省事。3.3 记忆写入的两种方式claude-mem 的记忆写入有显式和自动两种路径。显式写入就是模型主动调用类似create_memory的工具在对话过程中判断“这条信息值得长期记住”。比如我跟它说“记住这个项目的测试命令是pnpm test”它就会把这条信息写进记忆文件。自动路径稍微复杂一点部分版本支持在会话结束时做短时记忆到长时记忆的总结或者通过 hook 机制触发记忆提取。简单说就是模型会回顾当前会话里出现过的重要决策、关键信息把它们抽取成结构化记忆存下来。这种方式不用我一条条手动指定但它的触发时机和抽取质量跟版本有关。我的经验是重要的约定和决策最好显式告诉 Claude 去记自动抽取更偏辅助不能完全依赖。3.4 常用 MCP 工具速查表claude-mem 以 MCP 工具的形式给 Claude 提供能力实际使用中我主要用到这几个工具名作用使用时机create_memory创建一条新记忆明确了长期有效的约定、偏好、决策时search_memories语义搜索相关记忆新会话开头、需要回忆背景时save_relevant_metadata保存当前对话的元数据需要记录上下文附加信息时tag_memory给记忆打标签给记忆归类便于后续检索update_memory更新已有记忆信息已经变化时get_memory_context获取当前记忆上下文摘要想快速了解已经知道什么时这些工具模型会自动调用但你最好也知道它们的存在因为遇到问题时要能判断是哪个环节出了岔子。如果 Claude 一直搜不到记忆先确认它有没有真正调用search_memories而不是在那里瞎猜。4. 实际使用场景与效果演示4.1 场景一跨会话记住技术栈偏好举一个我每天都在用的场景。我有一个长期维护的项目技术栈约定是“数据库用 PostgreSQLORM 用 Drizzle后端路由写作风格偏好函数式”。以前每个新会话我都要把这段话重新发给 Claude后来我直接让它记住请记忆以下项目约定数据库使用 PostgreSQLORM 使用 Drizzle不要使用 Sequelize 或 Prisma。它回复“已保存”这条约定就进了.claude-mem/memories/。之后再开新会话我只要说“按项目约定帮我写个新表”Claude 会自己搜索记忆然后给出符合 Drizzle 风格的代码。我不需要重复背景它也不需要反复问。这个体验比“手动粘贴上下文”顺畅太多。4.2 场景二把“排错记录”变成个人知识库程序员每天都在排错但大部分排错过程都随着会话关闭消失了。claude-mem 让我开始积累“个人排错知识库”。有一次部署测试环境时遇到 8080 端口被占用我花了不少时间排查是哪几个进程占的。解决之后我让 Claude 记住这个过程包括根本原因、用到的排查命令和最终解决方案。两周后另一个项目又出现类似的问题新会话里我随口问了一句“服务起不来找不到原因怎么搞”Claude 竟然把那次排错记录搜了出来直接给出检查命令。那一刻我真的觉得这工具值了。如果你经常在同一类问题上反复踩坑把排错记录变成记忆就是给自己的 AI 助手装上“经验包”。4.3 场景三多项目记忆隔离与团队共享记忆隔离是我非常看重的能力。我给每个项目配置了独立的CLAUDE_MEM_MEMORY_DIR这样项目 A 里记住的约定不会污染项目 B。比如项目 A 是 Node 后端项目 B 是 Python 数据处理两边的依赖管理方式完全不同记忆混在一起会出大问题。团队共享方面我建议把.claude-mem目录加入代码仓库。团队成员拉到代码的同时也拉到了记忆库配合 prompt 里的一句“开始前先搜索相关记忆”整个团队的上下文就能对齐。这样做唯一要注意的是别把敏感信息写进记忆因为代码仓库的可见范围就是记忆的可见范围。5. 常见问题与排错技巧实录5.1 Claude 不调用记忆工具怎么办这个问题我遇到得最多。配置好后 Claude 完全不理 claude-mem自说自话地回答问题。排查思路是这样的先执行claude mcp list确认服务器已经加载然后在对话里直接问“你可以使用哪些工具”看回复里是否包含记忆相关工具。如果没有很可能是配置文件没生效或者 Claude Code 需要重启。如果工具列表里有但模型就是不主动调你可以换个更直接的问法“请先搜索 claude-mem 记忆再回答我。”几次之后模型会逐步学会在合适时机调用。这条经验说来也简单模型对工具的主动调用倾向受 prompt 和上下文影响你可以在系统提示里加入“执行任务前先搜索记忆”。5.2 embedding 模型慢或失败本地嵌入模型在首次加载时会有几秒钟的冷启动延迟这不是故障耐心等一下就好。我碰到过报错的情况大多是因为 Node 版本太低或者依赖没有装全。升级 Node 版本后基本解决。如果你选了远程嵌入模型还可能出现请求超时的现象这时候先检查网络环境再确认 API Key 是否有效。我的习惯是能本地就本地省得依赖外部服务即使稍微慢一点也值。5.3 检索不准调参思路检索不准通常是三个原因记忆文件太碎片化、相似度阈值设置不合理、top_k 太小。记忆文件碎片化表现为一条信息拆成好几条搜出来各带一部分拼不完整。解决办法是定期整理记忆目录把同一主题的几条合并成一个文件。阈值和 top_k 则需要根据实际效果微调如果搜出来的结果明显不相关调高阈值如果漏召回重要记忆调大 top_k。这个调参思路跟搜索引擎调相关性是一样的没有标准答案靠观察实际结果迭代。5.4 隐私与安全记忆文件是明文这一点非常关键。claude-mem 的记忆文件是明文 Markdown存了什么谁都能读。我见过有人把数据库连接串、API 密钥、内部系统地址写进记忆然后项目仓库一提交秘密全暴露了。我的建议是三条第一敏感信息绝不写进记忆让 Claude 记“配置文件位置”而不是“密码内容”第二如果记忆目录进了 Git记得在.gitignore里评估好是否需要完全排除第三本地使用也注意目录权限公共开发机尤其要小心。记忆是一种资产也可能成为一种风险管理它要像管理代码一样认真。5.5 兼容性版本升级与 MCP 变化claude-mem 还处在快速迭代阶段Claude Code 对 MCP 协议的支持也在不断升级。我升级过一次 Claude Code 之后旧版 claude-mem 突然识别不了了日志提示工具注册失败。解决办法很简单把 claude-mem 升到最新版。因为 npx 每次执行都会拉取最新的包所以我会定期在配置里加上-y参数确保它总是用最新版本。如果某个版本引入的行为变化让你不习惯也可以锁版本号但长期来看还是跟着升级更省心。写在最后把记忆当成资产去维护用了 claude-mem 一段时间之后我最直观的感受不是它“更像一个人”而是它让我在工具上少说了一半的废话。以前每个新会话都要交代一遍背景现在只需要开场问一句“先查一下记忆里的相关上下文”它自己就能把事情接起来。这种体验上的改变比任何花哨的 prompt 技巧都实在。我会建议你从一个小范围开始试用选一个你经常重复交代上下文的项目装上 claude-mem让 Claude 记住两三条确定性的约定然后在新会话里验证它能不能主动调出来。不要一上来就追求“完整记忆库”记忆这东西需要慢慢沉淀也需要定期清理。我个人体会最深的一点是记忆文件不是越多越好而是越准越好。保持一个能让自己看懂的记忆目录其实比让 Claude 什么都能记住重要得多。等你习惯了这种带记忆的工作流再回头去看那种每次从零开始的对话模式大概率你就回不去了。