Claude Code用多了最难受的一点倒不是它写不出代码而是它——不记事。你昨天刚告诉它“这个项目用Python 3.12依赖统一用uv管理”今天新开一个会话它又一脸茫然地问你“这个项目用什么语言”那种感觉就像你每次见到同一个同事他都得重新跟你自我介绍一遍。claude-mem就是专门治这个毛病的开源工具它通过Session Summaries和Auto Memory双通道机制给Claude Code装上一套跨会话的“长期记忆”让项目上下文、代码偏好、任务进度都能被自动沉淀、随时调取。这篇文章我会从为什么需要它、它的记忆机制怎么运作、怎么安装配置、实际使用场景到踩坑排查完整过一遍适合所有被“新会话失忆”折磨的Claude Code重度用户也适合想给自己的AI工作流加一层记忆持久化的开发者。1. 为什么Claude Code需要一剂“记忆针”1.1 无状态会话的日常痛点Claude Code默认是无状态的每次新会话都是“一张白纸”。这个设计本身不算错毕竟上下文窗口再大也有限不可能无限塞历史。但落到真实开发节奏里问题就非常具体了。我在一个中型Node.js项目上连续工作了两周中途退出终端再进来Claude问我“这个项目的入口文件在哪”“数据库连接串在哪个配置文件里”“你之前是不是决定用pnpm而不是npm”。这些问题我第一天就回答过一遍第二周还在重复回答那感觉真的很崩。更麻烦的是它也会忘记我明确强调过的偏好比如“测试文件统一放tests目录”“报错信息用英文”“不要用TypeScript的enum”。每次都得重新交代一遍交代完它也不一定能完全按规矩来。这不是Claude本身不够聪明而是它的工作记忆只存在于单次会话的上下文窗口里关掉终端就“失忆”。人不是这样的逻辑我们解决问题靠的往往是“过去的经验当前的问题”而不是每次从零开始学习一遍怎么做开发。1.2 claude-mem的整体思路三层结构claude-mem的设计思路很清晰三层结构采集层、存储层、回调层。采集层靠Claude Code的Hook机制实现。Claude Code支持在会话开始SessionStart、会话结束Stop等事件触发时执行外部命令claude-mem注册了这些Hook在会话结束后自动把对话内容送入记忆系统。存储层交给记忆框架来处理默认支持两条路线一条是Honcho负责生成会话摘要Session Summaries另一条是Mem0负责抽取长期事实Auto Memory。后端存储可以是Mem0的SaaS服务也可以是本地Zep或SQLite数据在自己手里。回调层解决“怎么用起来”的问题这是很多同类方案做不好的地方。claude-mem通过MCP Server暴露记忆检索能力Claude在新会话里可以主动调用工具查询相关记忆。另外也提供了一整套CLI命令开发者可以直接搜索历史记忆。这三层合起来完成了一件事把“对话过程”变成“可检索的长期经验”而不是一次性消耗品。1.3 和“伪记忆”方案的区别没有claude-mem之前也有人用其他办法给Claude Code“加记忆”。最常见的是维护一个CLAUDE.md文件把自己的偏好、项目说明、代码规范写在里面。但这是静态文档内容全靠手动维护。项目跑了一段时间文档早就过时了。另一类做法是接一个知识库插件把公司文档、API说明放进去让Claude在回答时检索。但这类知识库关心的是“已经存在的知识”不是“用户最近做了什么、说了什么、怎么想的”。claude-mem和这两类方案最大的区别在于它会主动从对话中抽取值得记住的信息自动归类、摘要、沉淀不需要开发者维护任何记忆文件。而且它对“用户行为偏好”这种软信息的捕捉是CLAUDE.md这类静态方案做不到的。能力维度CLAUDE.md静态维护知识库插件claude-mem更新方式手动手动索引自动捕捉行为偏好不擅长不涉及核心能力跨会话上下文衔接无有限有数据检索方式全文加载关键词检索语义搜索是否需要维护成本高中低2. 两种记忆机制到底怎么配合2.1 Session Summaries给每次会话写“会议纪要”Session Summaries这条链路由Honcho驱动作用相当于给每次会话自动写一份结构化会议纪要。它记录的不是对话逐字稿而是几个核心维度这次会话的目标是什么、做了什么关键决策、改动了哪些文件、有哪些遗留问题、下个会话从哪里继续。这份纪要会写入存储库在新会话里作为“短期记忆”被调取。它的特点是时间近、粒度细比长期记忆更具体但时效性也更强。例如昨晚改到light_entity那一步今天新开会话Claude通过摘要直接就知道进度不需要我把昨天那个py文件翻出来给它看。2.2 Auto Memory沉淀“长期不变量”Auto Memory这条链路基于Mem0框架负责的是比短期摘要更长线的记忆。它的关注点是那些反复出现、跨会话稳定的信息项目技术栈、语言版本、你的代码风格偏好、模块划分习惯、命名规范、依赖管理方式。这类信息有个特征它们不太会随时间变化属于“长期不变量”。Mem0会用算法判断一条信息值不值得长久保存只有重要性足够高时才会写入长期记忆。我在实际使用中体会很深的一点是它的抽取并不只是关键词级别的匹配而是基于语义和上下文的判断。比如我说“函数命名用动词开头”它不会只记住这句话的表面意思而是会在后续会话里体现在新写的函数名上。2.3 双通道配合短期详细长期稳定两个机制不是各干各的而是互补配合。新会话启动时Claude会同时拿到两类信息和当前任务相关的最新摘要短期记忆以及和项目相关的稳定事实长期记忆。短期记忆解决“上次做到哪了”长期记忆解决“这个项目一贯的风格和约定是什么”。两者一合相当于一个带记忆的“老同事”上岗了。打个比方来描述这种差异Session Summaries像你上一周开过的工作日志记录的是具体进度和安排Auto Memory像你这个人做事习惯的积累例如“从来不用空格缩进”“从来不写没类型的PHP参数”。工作日志每天在变做事习惯则相对稳定。2.4 记忆怎么被“想起来”存进去只是第一步关键是新会话怎么把这些记忆“想起来”。这里我必须说实话光装了claude-mem还不够得让Claude知道什么时候应该去查记忆。claude-mem通过MCP暴露了记忆检索接口Claude可以调用一个类似get_memories的工具去查询。但Claude不会闲得没事就查它需要有指令告诉它“新任务开始时先看看有没有相关记忆”。这个指令一般放在CLAUDE.md里我会在后面实操部分给出具体写法。除MCP之外CLI的claude-mem search命令也可以直接搜历史记忆搜出来可以直接粘贴给Claude用。这个属于“手动挡”在Claude没有自动查询能力的时候很实用。3. 安装与配置全流程半小时让Claude“记住你”3.1 环境准备和安装方式安装前确认三个前提Node.js版本在18以上Claude Code已经装好并正常登录环境里能访问npm或GitHub。claude-mem本身是Node生态的工具依赖Node运行时所以Node版本太老是真的跑不起来。安装有两种方式一种是用官方脚本curl -sSL https://raw.githubusercontent.com/dotenv-ai/claude-mem/main/install.sh | bash另一种是用npm全局安装npm install -g claude-mem我个人建议用npm方式因为后续升级方便一条npm update -g claude-mem就搞定。脚本安装的好处是它会同步处理好PATH环境变量不用你自己配。安装完成后跑一下claude-mem --version能输出版本号就说明装好了。3.2 初始化选择记忆后端安装完成后第一步是初始化claude-mem init这个命令会引导你选择记忆后端。默认选项是使用Mem0的SaaS服务配置最简单注册一个免费API Key就能跑起来适合个人项目和快速体验。如果你对数据敏感或者公司规定代码内容不能出内网那就选本地模式用Zep Community Edition或者SQLite数据完全存在自己机器上。这里要特别强调一句后端选型想清楚再动手后面切换比你想象中麻烦。因为不同后端的存储格式和检索语义不完全一致迁移时记忆并不会全部跟着搬过去。我的经验是个人项目直接用默认SaaS公司项目一律走本地Zep两边分开用互不干扰。初始化完成后claude-mem会生成一个API Key。这个Key要放进环境变量里例如# 在 ~/.bashrc 或 ~/.zshrc 里 export CLAUDE_MEM_API_KEY你的key配好之后注意source一下然后运行claude-mem status确认能连上后端。3.3 修改Claude Code配置文件这是整个安装过程里最关键的一步。claude-mem要通过Hook挂进Claude Code的生命周期事件才能在会话结束时自动存记忆、会话开始前自动加载记忆。配置文件在~/.claude/settings.json在hooks字段下增加两个事件监听{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: claude-mem onSessionStart } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: claude-mem onStop } ] } ] } }解释一下这两个Hook的作用SessionStart会在每次新会话打开时执行claude-mem onSessionStart作用是加载和当前工作区相关的历史摘要与长期记忆Stop会在会话结束时触发claude-mem onStop作用是分析本次对话内容更新Session Summaries和Auto Memory。提示改完settings.json之后在Claude Code里输入/hooks命令可以查看所有Hook的匹配情况。这一步能确认Hook是否真的被识别很多“装了但没生效”的问题都出在这。如果配置好之后新会话里Claude完全没有记忆的样子先跑一下claude-mem doctor做自检。这个命令会逐项检查环境变量、Hook配置、后端连通性、MCP Server注册状态基本能定位80%的安装问题。3.4 让Claude主动用记忆CLAUDE.md配置装好Hook只是打通了存储链路。要让Claude在新会话中真正去查询记忆还得在CLAUDE.md里告诉它怎么用。在~/.claude/CLAUDE.md里加一段配置说明# claude-mem usage You have access to claude-mem, a persistent memory system that stores relevant facts from previous conversations with this user. When starting a new task, use your available MCP tools to retrieve relevant memories first. If a memory retrieval tool is not available at the start, you can instruct the user to run: claude-mem search query Always reference insights from past sessions when offering recommendations, be concise but relevant.这段配置的核心作用不是给Claude塞记忆而是告诉它“存在一个可以查询记忆的机制”。没有这段指令记忆就只是躺在存储库里睡觉Claude不会自己去主动取用。这是我实际用下来最深的感受很多人装了claude-mem说没用八成是漏了这一步。3.5 CLI常用命令速查配置完成后claude-mem的命令行工具就完全可用了。上表是我日常用得最多的几条命令用途使用场景claude-mem status查看后端连接和配置状态安装后验证claude-mem stats查看记忆条数、会话数、摘要数了解记忆沉淀进度claude-mem search 关键词语义级全文搜索历史记忆手动检索或辅助对话claude-mem recent查看最近几场会话摘要快速回忆昨天的工作claude-mem remember 自定义记忆手动写入一条记忆重要决策主动建档claude-mem reset清空全部记忆换项目或者调试claude-mem doctor全链路自检排查问题安装后或报错时我习惯在终端里配个别名把搜索接到fzf上做交互式筛选alias cmemclaude-mem search $(echo ) | fzf这样输入cmem之后会出现一个模糊搜索列表选中哪条直接把内容回显到终端再CtrlC复制到对话里非常顺手。4. 实操场景什么样的工作流最受益4.1 隔夜/隔周续作的“接力模式”跨天续作是claude-mem收益最大的场景。我在一个实际项目里的体感是这样的第一天晚上让Claude写了一个数据迁移脚本改动了三个文件中途发现一个API版本兼容问题决定用兼容层方案解决最后没跑完就关了终端。第二天新开会话我先问了一句“昨天那个数据迁移项目到哪一步了”然后Claude直接给出了完整状态迁移脚本写了两个主要函数、兼容层方案已定但还没实现、还剩一个索引重建的步骤没有完成。这些信息不是我给的而是它通过Session Summary自动加载的。这种“AI自动接续工作”的体验用过之后真的回不去。4.2 风格偏好的“自动内化”Auto Memory对长期开发偏好的沉淀解决的是另一个大问题——风格一致性。我明确说过“TypeScript里不要用enum”Auto Memory会把它记成一条长期事实。后续会话写代码时Claude会自觉用const object as const来替代不需要我每次重新强调。这里有个看起来有点玄学的点它不仅仅记住那句原话而是会把偏好“内化”到行为里。比如说过“错误处理统一返回Result类型”新会话里的函数签名就会自然体现出这个风格。这种内化能力靠CLAUDE.md写静态规则是做不到的毕竟静态规则只能覆盖你能想到的表述而行为偏好往往藏在具体对话里。4.3 记忆资产的跨工具复用claude-mem虽然是为Claude Code设计的但它的存储层是通用的记忆服务不是只绑定一套工具。Mem0本身就支持LangChain、LlamaIndex等框架这意味着你沉淀下来的记忆资产可以切换到其他Agent或应用里复用。我在实践中做过一个“每日回顾”的脚本通过claude-mem recent导出最近的会话摘要再用脚本做统计分类生成当天的开发记录。也有一些场景是把记忆检索接入Home Assistant的自动化——之前说过“客厅灯走哪个实体、联动逻辑是什么”下次新会话里只需要说“按上次的联动方案再做一遍”Claude直接调出当时的对话上下文执行。这个能力把它当成一个“记忆即服务”来理解会更清晰CLI是入口MCP是接口后端是数据资产。具体的载体是Claude Code还是LangChain其实不算核心限制。4.4 团队协作中的“知识交接”如果团队共用一台开发机或多人在同一个项目里用Claude Codeclaude-mem还能承担一部分“知识交接”的作用。新成员加入时历史记忆里有前任留下的决策记录和技术选型理由可以让新会话快速建立项目认知。需要注意的是一条原则记忆以个人配置目录为准多人共用一个机器时需要区分记忆隔离。好在claude-mem默认把记忆数据放在用户目录下多用户系统天然隔离。5. 常见问题与排错实录5.1 为什么记忆完全没有写入现象会话结束之后claude-mem stats显示记忆条数为0或者Claude新会话依然一脸茫然。第一优先检查Hook是否生效。很多安装脚本会尝试自动修改settings.json但如果你的settings.json原本有注释、格式不规范脚本可能改出问题。直接在Claude Code里执行/hooks看SessionStart和Stop两个事件是否绑定了claude-mem命令。第二检查Stop Hook的触发链路。Claude Code的Stop Hook只有正常结束时才会触发如果你用CtrlC强制中断、终端崩溃、或者进程被杀Hook不会执行记忆自然不会写入。规避办法是重要对话结束时正常输入exit或说一句“claude保存进度”让会话自然结束。第三检查网络和后端。如果用的是Mem0 SaaS后端连通性出问题会导致写入失败。claude-mem doctor会明确指出是哪一环断了照着修就行。5.2 记忆检索出来的东西答非所问现象Claude确实能查到记忆但检索结果相关性差回答里混入了无关上下文。主要原因在于MCP检索的结果是按语义相似度排序的如果查询词太宽泛比如就输一个“Python”那相关和不相关的记忆都会进来。解决方法是在CLAUDE.md的指令中明确要求Claude先用一个句子描述“当前任务需要什么信息”再执行记忆查询让检索条件更准确。另外一个经验是定期清理废弃记忆比扩充新记忆更重要。项目切换之后旧项目的记忆会在检索里制造噪声。claude-mem search定位到不需要的条目后用CLI按ID删除或者直接claude-mem reset一键清空重新开始。5.3 隐私风险和数据管控安装时默认连的Mem0 SaaS会把你的对话内容发送到外部服务去分析。个人项目无所谓但公司代码相关的内容尤其是涉及核心业务逻辑、数据库结构、内部API的对话直接往外部服务送是有风险的。我的实际策略很简单个人电脑上跑默认SaaS公司电脑上用本地Zep。并行用互不混。另外在.gitignore里把.claude-mem相关的配置目录和密钥文件忽略掉避免API Key被不小心提交到仓库里。如果你的项目安全要求更高还可以在Prompt里给Claude加一条“不要主动查询记忆除非用户明确授权”的指令把记忆调取改成手动控制模式。5.4 上下文窗口和token占用记忆检索是拉取性强的内容但存储本身不会自动消耗上下文。MCP工具在调用时只返回top-k条结果Claude也只把命中的记忆带进上下文因此正常使用不会爆context窗口。不过“检索过多导致上下文被低价值记忆占据”的情况确实会出现。如果你的任务上下文很长、token吃紧可以在CLAUDE.md里加上一条限制“只用一条最相关的记忆来辅助判断无关的历史摘要一律忽略。”这个限制很管用实测下来既保住了记忆的效力也控制了token消耗。5.5 我踩过的几个冷门坑一个比较隐蔽的问题是当Claude Code的会话中产生子代理工作比如代码审查、测试生成时子代理的对话默认不被记录。如果你希望子代理的决策也被记忆需要在settings.json里增加对SubagentStop事件的监听。命令格式和Stop一样把事件名换成SubagentStop即可。具体情况每个人做法不同不过这一步很容易被人忽略我提醒一下。还有一个跟版本有关的问题Claude Code的Hook在旧版本里对SessionStart阶段调用外部命令有一定限制装完之后如果发现Hook一直在报错优先检查Claude Code是否升级到了最新版本。老版本装不上新Hook是很常见的问题很多时候升级一下就全通了。6. 结语让AI从“临时工”变成“老同事”我把claude-mem翻了底朝天包括安装、机制、工作流、排错都跑通了一遍完整的链路从“采集对话”到“摘要/抽取”再到“新会话检索调用”闭环已经比较成熟了。最让我觉得值得推荐的地方不是它能记住多少信息而是它把“记忆”设计成了自动采集、自动分类、按需调用的流程改掉了手动维护知识文档的毛病。我的建议很简单先从默认的SaaS方案开始跑配好Hook和CLAUDE.md用一周观察记忆沉淀的效果。觉得不行就去claude-mem doctor找问题觉得行就往本地后端迁移把数据控制权拿回自己手里。在Claude Code全面进化出原生记忆之前claude-mem这套方案已经能让日常开发的体验上一个明显的台阶。