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 cmem='claude-mem search "$(echo '')" | fzf'这样输入cmem之后会出现一个模糊搜索列表，选中哪条直接把内容回显到终端，再Ctrl+C复制到对话里，非常顺手。
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 Code，claude-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只有正常结束时才会触发，如果你用Ctrl+C强制中断、终端崩溃、或者进程被杀，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这套方案已经能让日常开发的体验上一个明显的台阶。
