1. 为什么需要记忆Claude Code的“失忆症”与MCP解法1.1 Claude Code再聪明也逃不过“聊完就忘”Claude Code作为命令行里的AI编程助手单次会话内的表现确实很强——能读仓库、能改代码、能跑测试几乎像一个坐在你旁边的资深工程师。但我重度用了几个月之后最崩溃的不是它能力不够而是它每次新开对话都是“金鱼记忆”。举个例子上午我和它讨论了某个模块的重构方案把接口设计、边界条件、甚至是变量命名风格都对齐了。下午开个新会话让它修另一个bug它完全不记得上午的结论。轻则重复聊一遍背景重则直接给出和上午方案冲突的代码。更麻烦的是项目里一些约定俗成的东西——比如“这个仓库不用X库”“测试文件放tests/目录”“提交前必须跑lint”——每次新会话都需要重新强调。这背后的原因很简单Claude Code的上下文窗口是跟着当前会话走的会话一结束上下文就清空了。它没有“硬盘”所有信息只能临时存在模型窗口里。对于长期维护的项目、跨天的任务、需要积累上下文的工作流来说这种“无状态”特性是最大的效率杀手。1.2 MCP协议给AI插上“外部硬盘”那怎么解决思路很直接把记忆从模型窗口里搬出来放到外部存储里。这正是MCPModel Context Protocol模型上下文协议在做的事。可以把MCP理解成一个标准化的“USB接口”——Claude Code是主机外部数据源是U盘、移动硬盘、打印机。以前每个工具都要单独适配现在只要双方都支持MCP协议插上就能用。claude-mem这个开源项目就是基于MCP协议为Claude Code定制的一个“记忆硬盘”。它做的事可以概括为三件记录自动把每次会话的对话内容保存下来存成可读的JSON文件提炼当会话达到一定轮数后自动调用模型生成摘要把冗长对话压缩成简洁的“记忆”调取在新会话开始时自动检索与当前任务相关的历史记忆注入到Claude的上下文中。也就是说你不需要手动告诉Claude“我们上次聊过什么”它自己会去看。这才是长期记忆该有的样子——不是靠你提醒而是靠系统自动完成。1.3 claude-mem能解决哪些具体场景我整理了日常使用中claude-mem真正有感的几个场景供你对照参考跨会话接续任务昨天改到一半的功能今天打开新会话直接说“继续把昨天的重构做完”它知道昨天改到哪了不会从零开始项目约定沉淀你多次强调过的偏好“用pnpm不要用npm”“变量命名用驼峰”会被写进长期记忆之后每次新会话自动生效多项目上下文隔离不同项目的记忆分目录存储不会互相污染上下文窗口节省历史内容被提炼成摘要后不需要把整段旧对话塞进上下文节省大量token也减少了“上下文超长导致回答质量下降”的问题。适合谁用如果你只是偶尔用Claude Code问几个一次性问题那claude-mem的价值不大。但如果你每天长时间用Claude Code写代码、做代码审查、维护多个仓库或者你在同一个项目上会连续工作很多天那这个工具就是刚需。2. 安装与配置给Claude Code接上“记忆硬盘”2.1 环境准备与安装方式选择claude-mem的安装本身不复杂但有几个前置条件需要注意。首先你机器上得有Node.js环境版本建议18以上因为claude-mem是npm包通过npx直接运行。其次Claude Code得已安装并正常登录使用。最后是存放记忆文件的目录建议单独建一个比如~/.claude-mem/history后面配置会用到。安装方式上我推荐用npx直接作为MCP服务端运行而不是全局安装。原因有两点用npx可以始终拉到最新版本升级不用手动管不污染全局Node模块删除也干净——直接改配置即可。2.2 在Claude Code中注册MCP服务Claude Code本身支持MCP服务管理可以直接用内置命令来添加claude mcp add claude-mem -- npx claude-mem这条命令的意思是注册一个名为claude-mem的MCP服务通过npx claude-mem启动。执行完之后可以用claude mcp list检查注册情况claude mcp list # 应该能看到类似这样的输出 # claude-mem: npx claude-mem [connected]connected字样很关键说明Claude Code启动MCP服务成功。如果显示failed或者disconnected大概率是Node版本问题或者npx首次拉包太慢超时了后面在常见问题章节我会详细讲排查方法。2.3 配置参数与推荐值如果你只是测试一下上面那行命令就够了。但要用得顺手我还是建议在配置文件里加上几个关键参数。Claude Code的MCP服务配置可以放在两个位置用户全局配置~/.claude.json所有项目生效项目级配置项目根目录的.mcp.json只对当前项目生效。我个人的习惯是基础配置放在全局项目特定的记忆路径、会话窗口放在项目级.mcp.json里。下面是一份完整配置参考{ mcpServers: { claude-mem: { command: npx, args: [claude-mem], env: { CLAUDE_MEM_FILE_SAVE_PATH: /home/yourname/.claude-mem/history, CLAUDE_MEM_SESSION_WINDOW: 20, CLAUDE_MEM_MAX_SUMMARIES: 10, CLAUDE_MEM_MATCH_THRESHOLD: 0.7 } } } }几个关键参数的作用我展开说一下CLAUDE_MEM_FILE_SAVE_PATH记忆文件存储根目录。这个目录最好在.gitignore里否则记忆文件会被误提交进仓库CLAUDE_MEM_SESSION_WINDOW会话达到多少轮时自动生成摘要。默认值我记得是20轮左右。太小结摘要频繁太大又容易“忘事”后文有专门调优段落CLAUDE_MEM_MAX_SUMMARIES本地保存的摘要数量上限超出后老摘要会让位给更高层级的汇总摘要CLAUDE_MEM_MATCH_THRESHOLD记忆检索匹配阈值0.7是相对均衡的起点。如果目录不存在claude-mem会在首次运行时自动创建不用手动mkdir。2.4 存储层设计JSON与SQLite各司其职我刚开始用的时候一直好奇为什么既要文件存储又要数据库后来看它的设计逻辑才明白这是“原始档案”和“检索索引”分离的思路。JSON文件层保存每次会话的完整原始记录包括每轮用户消息、助手回复、工具调用等。这一层的作用是“留底”可读性强方便备份和回溯也可以用来做数据分析SQLite层存储提炼后的记忆条目、摘要、标签等结构化数据。这一层的作用是“检索”Claude Code每次对话开始时会通过MCP工具从SQLite里做相似度检索找出和当前任务相关的记忆再注入上下文。这样设计的好处是原始记录可以无限留存但进入AI上下文的永远只是提炼后的摘要部分命中记忆token消耗可控。如果只存原始对话上下文迟早会被塞爆如果只存摘要又会丢失很多细节。两层结构兼顾了“完整性”和“可用性”。3. 核心机制拆解记忆是如何被写入、检索和遗忘的3.1 自动会话存档每一次对话都被“写进日记”claude-mem的运作始于自动存档。启动后会监听Claude Code的会话事件每当有消息交换就把对话内容追加写入对应的记忆文件。文件命名通常带时间戳与会话标识这个机制有两个很实际的作用第一断点续传。哪怕Claude Code本身崩溃了、终端关了只要记忆文件在下次恢复会话时还能把历史翻出来。第二人工审计。如果你想知道某天聊了什么直接打开对应日期的JSON文件就能看到原始记录比翻聊天记录还方便。我踩过一个坑早期我把记忆目录放在项目仓库里又没加.gitignore结果几个会话之后提交代码时发现diff里出现了一堆巨型JSON文件把仓库搞得乱七八糟。所以再次强调记忆目录一定要隔离在仓库之外或者在.gitignore里写死。3.2 摘要管线从“流水账”到“经验”光有原始记录还不够如果每次都是从大堆JSON里翻上下文那跟没有记忆也没区别。claude-mem的核心是自动摘要管线。当一次会话的消息轮数达到CLAUDE_MEM_SESSION_WINDOW设定的阈值时它会调用模型对当前会话内容做一次总结把对话压缩成包含关键决策、用户偏好、待办事项的摘要条目然后存入SQLite。更细节的是如果会话特别长比如超过几十万token它还会做分层摘要——先按话题分段总结再把多个小总结汇总成一个大总结。这就像人脑一样短期记忆先压缩成中期记忆再沉淀为长期记忆。这个机制直接决定了记忆的质量。我发现摘要质量跟任务类型强相关如果是写代码、重构、debug这类目标明确的任务摘要很精准但如果是开放式讨论、头脑风暴摘要可能会丢掉一些重要分支。解决办法我放在后面“实战调优”部分——通过自定义指令约束Claude“该记住什么”。3.3 记忆检索新会话如何“想”起旧事新会话开始时claude-mem会做两件事把与当前项目相关的高置信度记忆自动注入系统提示词暴露一组MCP工具给Claude Code让它在对话过程中按需主动调取。工具层面常用的是build构建记忆、recall召回历史、reset重置当前上下文、augment上下文增强这几个。其中recall走的是SQLite里的相似度检索核心逻辑是文本embedding向量匹配加上一定权重、关键词匹配然后按相关度排序返回。检索质量受CLAUDE_MEM_MATCH_THRESHOLD影响阈值设得低比如0.5召回的内容多但噪音多Claude可能被无关记忆干扰阈值设得高比如0.85召回精准但容易漏掉边缘相关信息。0.7是一个比较稳妥的起点如果你发现Claude老是在无关记忆上发散就往0.75以上调如果发现它该记起来的没记起来就往下调到0.65左右。3.4 记忆的“遗忘”与体积控制很多人会问记忆无限增长怎么办答案藏在CLAUDE_MEM_MAX_SUMMARIES和分层摘要机制里。当摘要数量超过上限时旧摘要不会直接删除而是被合并成更高层级的“汇总摘要”。这个汇总摘要再超过限制又会继续向上合并。也就是说它用层级结构实现了“自然遗忘”——最久远的会话最终只会留下一句“这个项目曾经做过XXX最终方案是XXX”级别的元记忆。单条记忆的token占用被压得很低长期来看SQLite文件的体积增长是可控的不会把Claude的上下文撑爆。不过这不意味着你可以永远不管它。我的经验是每两三个月手动看一眼记忆文件体积如果SQLite超过几十MB就把原始JSON归档一次再把SQLite里的极老记录清掉一批保持检索效率。4. 实战让claude-mem越用越懂你的调优技巧4.1 关键参数的调参建议配置参数不是越多越好关键是契合你的使用方式。我按照不同使用场景给出一组参考值使用场景SESSION_WINDOWMAX_SUMMARIESMATCH_THRESHOLD轻度使用偶尔提问1550.75日常编码半天以上连续使用20100.7深度开发多任务交叉10150.65知识管理长期积累沉淀25200.6取值背后的考量是会话轮数少的小窗口会频繁触发摘要如果生成摘要还会打断当前对话体验那说明窗口太小如果session-window太大一次会话积累的内容太多摘要生成时会丢细节记忆质量反而下降。日常编码场景推荐10-20之间。匹配阈值这块我踩过一个具体例子有一次它在新会话里把另一个项目的记忆当成当前项目的给出的方案里混进了不相关的依赖建议。排查下来发现是我把阈值调到了0.55召回噪音变大。调回0.7问题就消失了从那以后我不再盲目追求“召回全”而是更看重“召回准”。4.2 用CLAUDE.md约束记忆提炼方向这是我认为最值得做的一个优化效果立竿见影。claude-mem生成摘要时会调用模型但模型默认不知道该重点记什么。如果你像记流水账一样把所有内容都平等对待最终沉淀下来的记忆就会缺乏重点。解决办法是通过项目里的CLAUDE.md文件给Claude定规矩# 记忆提炼规范 当Claude Code为本次会话生成记忆摘要时请遵循以下优先级 1. 项目架构当前主模块、关键文件路径、依赖关系 2. 决策记录为什么选这个方案、放弃过什么选项 3. 用户偏好代码风格、工具链选择、禁忌事项 4. 未完成事项明确的下一步行动与待验证假设 以下内容不需要进长期记忆 - 一次性调试细节如临时打印的日志 - 与当前项目无关的闲聊 - 过于具体的报错堆栈除非是反复出现的模式加了这个规范之后我能明显感觉到第二天的会话“懂事”了很多——它记住的不再是零散对话而是项目真正的上下文骨架。这个文件本身也被Claude Code原生支持所以是双赢。4.3 多项目隔离与团队协作claude-mem支持按目录隔离记忆。如果你同时在多个项目里使用Claude Code最好给每个项目配置独立的CLAUDE_MEM_FILE_SAVE_PATH否则所有项目的记忆混在一个库里面检索时容易出现跨项目串味。团队场景下我目前的做法是把项目的记忆摘要定期导出整理成一份DECISIONS.md或HANDOVER.md放在仓库里。这样即使同事没有装claude-mem也能通过文档获得上下文。有同事装了的话他们也可以把这份文档喂给Claude Code相当于给团队共享一个轻量级的“项目记忆库”。另外注意记忆文件不要提交到Git仓库。它包含大量对话细节和中间过程提交进去既暴露信息又污染仓库。正确做法是让每个成员在本地各自生成记忆核心共识通过文档沉淀。4.4 与子代理结合记忆查询自动化Claude Code里可以自定义子代理把记忆检索交给专门的“记忆查询员”主对话不直接频繁调用MCP工具。简单说就是写一个子代理的system prompt让它专注于从claude-mem里调取信息你是一个记忆查询助手。用户提出问题时先调用recall检索相关历史记忆 再结合当前会话的上下文给出简洁回答。回答必须注明信息来源是“历史记忆” 还是“当前上下文”方便用户判断可信度。这样做的收益是主对话上下文更干净不会每轮都夹带大量召回内容同时记忆查询有固定的输出格式后续处理也更简单。Claude Code对子代理的支持在从命令行工具调用的模式里比较成熟了值得一试。4.5 把记忆“固化”成项目文档最后分享一个我坚持在做的习惯。claude-mem很好用但我不把所有信息都压在它的记忆库里。每隔一段时间我会对它进行一次“知识萃取”让Claude把近期记忆里反复出现的项目约定、决策原因、重要约束汇总整理成一份结构化的项目文档。这就像给记忆做了一次“备份到纸面”的动作。这么做有两个原因一是如果哪天claude-mem配置崩了、记忆库丢失了项目文档还在不至于全盘归零二是文档作为人类可读的共识远比AI记忆库更适合团队协作。所以我一直把claude-mem当作“工作记忆缓存”而不是唯一的真相来源。5. 常见问题与排查技巧实录5.1 安装后Claude Code不加载或连不上这是出现频率最高的一类问题。正常安装后claude mcp list里看不到服务或显示disconnected。我按经验把可能原因排一下npx首次拉包超时MCP服务启动时npx需要去npm仓库下载包网络慢可能导致Claude Code认为服务启动失败。解决先手动在终端跑一次npx claude-mem让包缓存到本地再重启Claude CodeNode版本过低MCP的现代SDK要求Node 18以上如果本地默认Node是16或更低服务会启动失败。用node -v确认版本必要时用nvm切换端口或进程冲突如果你之前装过其他MCP服务占用了同样的进程名可能造成冲突。重启终端、确认没有重复注册服务名即可配置格式错误手写.mcp.json时JSON格式不对Claude Code会静默忽略这个服务。用jq .检查一下文件能不能正常解析。5.2 记忆摘要太频繁打断当前会话如果SESSION_WINDOW设得太小一次对话进行到一半就会触发摘要生成你能明显感觉到Claude Code的响应变慢了甚至插入一段与当前任务无关的总结输出。这是比较常见的调参问题。解决思路是调大SESSION_WINDOW到20左右并确认MAX_SUMMARIES不是1——如果摘要上限只有1它会反复覆盖同一条记忆更容易触发重复生成。我自己的习惯是窗口20、摘要上限10基本不会再注意到摘要的存在它会在后台安静地完成。5.3 新会话总是“想不起来”该记的事如果你明确感觉历史里明明讨论过某件事但新会话Claude完全没反应按顺序排查看匹配阈值MATCH_THRESHOLD是不是设太高了导致相关记忆没被召回——往0.65方向调看当时的会话摘要是否真的生成了——打开SQLite或摘要文件搜关键词确认确认当前会话所在项目目录跟历史会话是不是同一个FILE_SAVE_PATH。很多人开了新项目文件夹后发现失忆就是因为路径变了记忆没有跟着走检查CLAUDE.md里是否写了“不要主动调用历史记忆”之类的指令这会压制工具的主动行为。5.4 SQLite文件体积膨胀明显记忆库用了几个月之后SQLite文件是会增长的。如果你发现它膨胀得厉害通常是原始事件表里积累了过多工具调用记录和临时调试内容。我目前的处理方案是定期把原始JSON目录压缩归档比如按月打包成tar.gz对SQLite做一次清理删除超过半年的冗余事件记录只保留摘要表和记忆表清理前先备份cp整个目录即可安全第一。5.5 MCP工具调用权限不生效Claude Code有时候不会自动调用MCP工具尤其在权限模式比较严格的时候。这时候你需要手动批准或调整权限配置。如果你发现Claude从不调用recall、build这些工具先确认MCP服务名是否正确然后在Claude Code的权限设置里确认工具权限没有拦截。还有一个容易被忽略的小问题如果你在多个终端窗口同时开Claude Code并共用同一个记忆目录SQLite的并发写入偶尔会出问题。建议同一时间只在主工作终端开Claude Code其他窗口用只读模式查看历史内容。5.6 常见问题速查表症状可能原因解决方向claude mcp list显示disconnectednpx首次拉包超时/Node版本低手动运行npx claude-mem预热缓存升级Node到18会话中途莫名变慢或插入总结SESSION_WINDOW设置过小调整到15-20轮历史内容怎么都回想不起来MATCH_THRESHOLD过高或路径不匹配降到0.65核对记忆目录是否一致记忆库文件增长飞快原始事件记录过多定期归档JSON清理冗余事件表MCP工具从不被调用权限拦截或服务名冲突检查工具权限确认服务注册名唯一两个项目记忆互相串味共用了同一个FILE_SAVE_PATH每个项目独立记忆目录最后补充一点实操中的个人体会用claude-mem将近半年我最大的感受是真正的效率提升不是来自“查旧账”而是来自“持续的上下文惯性”。当它稳定记住了你的代码风格、项目边界、技术选型偏好之后Claude Code从“一个很强但每次都重新认识你的实习生”变成了“一个越用越默契的长期搭档”。前期一两周的调参磨合是值得的。我砍掉了“全量回忆”的执念不再追求它记住所有细节而是让它把力气花在记住项目的结构、关键决策和未完成的todo上。配合CLAUDE.md的沉淀和定期的文档固化这套组合拳让我维护项目的成本和“重新说明背景”的次数都降了一个量级。最后再分享一个小技巧如果你发现某段时间某个项目的记忆越来越“碎”与其调各种参数不如直接在CLAUDE.md里加一行——“当前阶段最重要的三件事是XXX”然后让Claude每次总结时都优先围绕这三件事。记忆的方向感比记忆的容量重要得多。