Claude Code 记忆持久化：用 claude-mem 告别无状态会话

用 Claude Code 写代码的朋友应该都体会过这种憋屈明明昨天刚和它敲定好项目里的命名规范今天开个新会话它照样给你生成下划线风格的变量名上周刚讨论过不再用那个废弃接口这周它又在代码里调上了。我一开始以为是提示词没写清楚后来才发现问题出在 Claude Code 的会话本质上是无状态的——关掉一个 session上下文就归零。直到我在 GitHub 上翻到 claude-mem 这个项目才算是把这块短板补上了。claude-mem 是一个专门给 Claude Code 加持久化记忆的开源工具底层基于 Mem0 记忆框架实现。它做的事情翻译成人话就是会话结束后把你和 Claude 的对话过一遍抽取出偏好、决定、约定这类需要长期记住的信息存到本地库里下一次开新会话时再把跟当前项目相关的记忆提前塞进 Claude 的上下文里。适合谁用重度依赖 Claude Code 写代码、做技术调研的开发者尤其是手头同时维护好几个项目、经常在多个会话间切换的人。安装不难接入也不复杂但里面有一些设计和配置上的讲究值得好好说清楚。1. 项目概述claude-mem 到底解决什么问题1.1 没有记忆的 Claude Code 有多别扭先说我自己的场景。我手头同时维护三个项目一个是 Go 写的内部工具一个是 Python 的数据管道还有一个是给客户做的前端。Claude Code 陪我写了半年代码能力和速度都没得说但有一个问题从第一天起就一直在膈应人它记不住事。有次我在 Go 项目里明确跟它说了两遍这个仓库不用指针接收者统一值接收者结果第三天新会话里它又给我生成了一堆 *T 的方法。你说它错了吗也没错很多人就这么写。问题是这个约定我们明明说好了。这就是大模型会话的无状态特性每次会话的上下文只存在于当前 session一旦 Stop 或者开新对话之前聊过的内容就像被橡皮擦擦掉一样。你当然可以把要求写进 CLAUDE.md但 CLAUDE.md 是静态的写死了它不会跟着项目的演进自动更新你也不会天天去维护它。于是同一个问题反复交代、同一个坑反复踩成了 Claude Code 高频用户的日常。1.2 claude-mem 是什么一个记忆层claude-mem 是 GitHub 上一个开源项目作者是 Harper Reed定位非常明确给 Claude Code 加一层持久化记忆。它底层基于 Mem0 这个记忆框架把对话和记忆分离开——对话是一次性的记忆是长期沉淀下来的。简单说它干了三件事一是监听你每一次 Claude Code 会话的开始和结束二是在会话结束后把这次聊天的 transcript 读一遍用模型把值得长期记住的信息偏好、决定、约定、环境细节抽取出来去重后存进本地记忆库三是在下一次会话开始前根据当前项目把相关的记忆捞出来注入到 Claude 的上下文里。因为记忆是单独存的所以它不占 Claude 的上下文窗口也不会像 CLAUDE.md 那样需要手动维护。1.3 这个工具适合谁不适合谁判断标准很简单如果你经常在 Claude Code 里重复交代同样的事就适合如果每次都是全新任务那记忆反而可能变成噪音。适合的人群包括重度使用 Claude Code 的开发者每天开好几个会话多项目并行经常在会话间切换不想每次重新对齐背景想沉淀团队约定、个人编码风格的人注重隐私不想把代码上下文留在第三方服务的人不适合的场景我也遇到过偶尔用一下 Claude Code、项目是一次性脚本、会话之间没有连续性那记忆系统就是纯开支没必要上。2. 架构拆解记忆是怎么流动的2.1 三个核心组件Daemon、MCP、CLIclaude-mem 不是单文件脚本而是由三个组件配合工作我第一次看的时候也花了点时间才理清它们的分工。组件形态职责Daemon常驻本地服务默认监听 8001 端口接收 hook 上报、管理记忆库、提供 HTTP 接口MCP ServerModel Context Protocol 服务把记忆能力封装成 Claude 能调用的工具CLI命令行工具安装、状态查看、搜索、导入导出等管理操作Daemon 是核心。它负责所有脏活对话结束后的 transcript 处理、记忆抽取、向量化、存储、检索。设计成常驻服务而不是每次现起进程是为了避免重复加载模型和连接数据库的开销——你想想如果每次会话结束都要冷启动一遍光等就等死人了。MCP 是 Claude Code 用来调用外部能力的标准协议。claude-mem 的 MCP Server 会暴露几个记忆工具比如 add_memory、search_memories、delete_memory会话里 Claude 想主动记点什么或者查点什么的时候就直接调这些工具。CLI 则是人机接口你日常管理记忆、看状态、导入导出都用它。2.2 一次完整的记忆读写流程我把整个流程拆成七个步骤搞懂这七步后面出什么问题都能自己排查SessionStart hook 触发claude-mem hooks on_session_startDaemon 根据当前项目目录查询相关记忆取 top K 条最相关的把记忆以固定格式注入系统提示词例如你有持久记忆以下是你之前和该用户确认过的事情……会话过程中Claude 遇到新决定时通过 MCP 工具主动调用 add_memory 保存会话结束时Stop hook 触发claude-mem hooks on_stop把 transcript 路径传给 daemonDaemon 读取 transcript用 LLM 抽取值得记住的事实与已有记忆做去重合并向量化后写入本地库等待下次检索这里值得注意第 4 步和第 6 步是双通道会话中主动记会话后兜底抽。主动记通常更准因为你明确说了记住这个事后抽取则是兜底防止你以为说了但其实上下文里没触发保存。我实际用下来两条通道都开着效果最好只开任何一条都会有遗漏。2.3 底层到底存了什么Mem0 的数据模型Mem0 的记忆模型核心是记忆条目和用户/代理维度的关联。每条记忆本质是一段短文本比如数据库统一用 PostgreSQL 15用户偏好 tab 缩进而不是空格项目部署走 GitHub Actions 的 production workflow。它不只是简单追加还会做去重和更新。举个例子你第一次存的记忆是缓存用 Redis过了两周你又说缓存改用本地内存Redis 只用在限流场景Mem0 不会把两条都留着而是把旧的那条更新成新的语义。这个去重和更新机制是记忆库能长期保持整洁的关键。存储上默认采用本地优先方案向量索引放在本机用户目录不强制要求外部数据库。你要是用过 Qdrant、Chroma 这些向量库可以理解为它内置了一个轻量实现够个人使用不需要额外运维。2.4 为什么选择本地优先的存储方案代码片段、业务细节都是敏感资产很多人不愿意往第三方服务传。本地存储意味着记忆库里装了什么只有你自己知道这个隐私边界很重要。而且没有外部数据库依赖部署成本几乎为零。代价也有换机器、重装系统后记忆库不会自动跟着走需要自己做导出备份。好在它有 export/import 命令我每两周会导出一份放到自己的备份盘里这个习惯已经救过我一次——有次我误清了记忆库靠备份直接恢复。3. 安装与配置实操3.1 环境准备与安装claude-mem 是 Python 写的所以第一步是确保机器上有 Python 3.10 以上版本。然后一条命令pip install claude-mem装完先别急着用跑一下claude-mem status确认基础状态能出来。如果命令找不到大概率是 pip 的 bin 目录没在 PATH 里去查一下你的 pip 装到哪了把对应目录加进 PATH 就行不用重装。3.2 自动接入 Claude Codeinstall 命令下一步执行claude-mem install这条命令会改写 Claude Code 的配置文件自动添加 SessionStart 和 Stop 两个 hook。安装完可以打开配置文件确认位置通常在~/.claude/settings.json或项目下的.claude/settings.json。核心内容长这样{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: claude-mem hooks on_session_start } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: claude-mem hooks on_stop } ] } ] } }这里有个容易搞混的点install 只是接入了 hooks不代表 daemon 会自动跑。你需要另开一个终端把 daemon 常驻起来claude-mem daemon看到类似 listening on http://localhost:8001 的日志就说明起来了。也有人用 nohup 后台跑或者交给 systemd 托管看个人习惯。我自己的做法是写进开机自启脚本省得每次手动起。3.3 可选但推荐本地 Ollama 嵌入模型记忆要支持检索就得先把文本向量化。claude-mem 默认走云端嵌入接口好处是开箱即用坏处是要配密钥、数据要出一趟本机。如果你不想这样推荐配置本地嵌入模型。最省事的方案是 Ollama先装 Ollama拉一个轻量模型ollama pull all-minilm然后在启动 claude-mem 之前设置环境变量让它使用本地嵌入export OLLAMA_BASE_URLhttp://localhost:11434 export OLLAMA_MODELall-minilm claude-mem daemon不同版本可能对变量名的叫法略有差异具体以你安装版本的 README 为准我给的这套是当前比较通用的做法。all-minilm 这个模型很小CPU 上跑都飞快对记忆检索这种短文本场景足够用了。我自己就是配的本地模型获得感很强既不用申请额外的密钥也不用担心对话数据出本机。3.4 密钥与环境变量配置如果你选择云端嵌入或者希望记忆抽取走云端模型就需要配密钥。常见的是 OPENAI_API_KEY如果抽取用的是 Claude 的接口则要配 ANTHROPIC_API_KEY。个人建议把密钥写进.env文件然后用类似 dotenv 的方式加载别直接写死在 shell 配置里尤其不要写进会被提交到 Git 仓库的文件。还有一个容易被忽略的配置如果你开了 MCP服务默认走 8001 端口跟 daemon 共用。端口被占的话可以用环境变量指定别的端口改完记得重启 daemon 和 Claude Code 才生效。3.5 验证安装是否成功一次完整测试配置完之后我习惯按下面三步验收全部通过才算真正装好claude-mem status输出正常daemon 状态是 healthyclaude-mem ask what do we know能返回内容哪怕是暂无记忆也算通在 Claude Code 里跟它说一句请记住本项目的测试框架是 pytest不要用 unittest然后等会话结束再开一个新会话问我们的测试框架用什么——如果它能答对说明整条链路通了这条链路任何一个环节断了问题多半出在 hook、daemon、MCP 三者的连通性上排查思路下一节细讲。4. 日常使用让 Claude 真正记住这些东西4.1 CLI 命令速查记忆这东西光能存不行还得能查、能管、能删。我用得最多的命令整理成一张表命令作用claude-mem status查看 daemon / MCP 状态claude-mem daemon启动常驻服务claude-mem mcp启动 MCP serverclaude-mem ask 问题基于记忆回答一个问题claude-mem search 关键词检索相关记忆原文claude-mem view查看最近记忆列表claude-mem harvest transcript离线抽取一段会话记录中的记忆claude-mem export/import导出 / 导入记忆库claude-mem clear清空记忆claude-mem uninstall卸载并移除 hooksask和search的区别要分清ask是让模型基于记忆组织一段回答适合我之前说过什么来着这种问题search是直接返回原始记忆条目适合你想精确核对某句话到底存没存。排查记忆问题时我一般先用 search 定位到原文再用 ask 看整体结论。4.2 在会话里直接让 Claude 记事情日常使用中最顺手的用法就是直接在对话里说。Claude 会通过 MCP 工具把这句话沉淀成记忆。我常用的指令形如记住本项目的部署环境统一是 staging 和 production 两套preview 环境已废弃。记住我喜欢用 Redis 做缓存不引入额外的缓存中间件。记住这个仓库的提交信息格式是 conventional commits。反过来你也能在会话里问它我之前说过关于日志库的偏好是什么这个项目之前决定用哪个 ORM这里有个使用心得主动记忆时说清楚主语和边界很重要。比如记住本项目数据库统一用 PostgreSQL 15比记住用 PostgreSQL要好因为后者会被其他项目的会话捞到造成串味。4.3 记忆的查看、搜索和删除记忆库攒多了以后一定会有过时和错误的信息。我通常每周做一次瘦身先claude-mem view看最近存了啥再claude-mem search 关键词定位到具体条目确认没用的就清掉。删除这块不同版本命令略有差异新版有的在 MCP 工具里暴露了 delete 能力可以在对话里让 Claude 自己删如果 CLI 没有提供单条删除也可以直接去本地存储目录清理操作前记得先 export 备份。我的原则是任何批量操作之前先导出一份成本很低但能防止手滑。4.4 多项目与团队协作场景记忆按项目隔离这点对多项目用户很重要。我的做法是每个项目在项目自己的.claude/settings.json里配置 hooks 和 MCP 注册这样记忆不会跨项目串味。否则你在 A 项目里存的用 pytest跑到 B 项目里可能会被检索出来干扰判断。团队场景下可以把记忆库导出文件提交到仓库里注意别把密钥带进去或者定期用 export 分享给队友让大家的 Claude Code 起点一致。更精细的做法是让不同项目挂不同的记忆文件目录实现按团队隔离。这种用法官方文档没有写得太细属于我自己摸索出来的玩法但实测下来挺管用。5. 核心参数与调优建议5.1 服务端口与网络配置daemon 默认监听 127.0.0.1:8001只允许本机访问这个设计是对的别随便改成 0.0.0.0除非你清楚自己在干什么。MCP 通信同样走本机不存在跨网络暴露面。如果端口被其他进程占了排查时先看占用lsof -i :8001然后按需改环境变量换端口或者直接 kill 掉占用进程再重启 daemon。我遇到过一次是某个本地监控服务抢了 8001当时问了好一会儿才反应过来是端口冲突所以建议大家在 status 里一眼能看到端口配置省得瞎猜。5.2 嵌入模型选型与成本对比嵌入模型决定了检索的召回质量。我画了个对比表方便大家选型维度本地 Ollama all-minilm云端 OpenAI 嵌入成本0按 token 计费隐私数据不出本机要过云接口召回质量短文本够用更强长文本优势明显部署复杂度要装 Ollama只要配密钥实际体验记忆大都是短文本一两句话all-minilm 的召回效果已经可以接受我在日常使用中没感觉到明显差距。只有在记忆条目特别长、语义特别绕的时候云端模型才有肉眼可见的优势。如果你只是为了省事默认云端嵌入也能用如果你在意隐私或想省掉密钥管理本地 Ollama 是更好的选择。5.3 上下文注入量与 token 成本控制SessionStart 时注入多少记忆是一个权衡。注少了Claude 想不起来注多了既占窗口又可能引入跟当前任务无关的噪音。我的经验值取 top 5 条最相关的记忆就够了。每条记忆通常一两百 token注入成本大概 1k token 上下对 Claude 动辄几万 token 的编程会话来说可以忽略。粗算一下假设一天开 10 个会话每会话多花 1.5k token 在记忆注入上一天也就 15k token对比实际写代码消耗的 token 占比很小。所以放心用记忆注入不是成本大头。真正的成本大头是 Stop hook 的事后抽取因为长会话 transcript 可能上万 token模型要完整读一遍再做抽取。如果每天有大量长会话这个成本会累积。我的控制方式是把超长会话的自动抽取改成手动 harvest需要沉淀的会话才抽不需要的就让它过去。5.4 记忆的隔离与清理策略越是不清理记忆质量越差。我给自己定了几条规则技术选型类决定必须存个人表达偏好可以存一次性任务细节不存暂时两个字开头的约定不存因为大概率会变。清理节奏我是按周来的每周花五分钟执行claude-mem view加search把过时条目删掉。做项目大版本升级前先 export 一份记忆库避免误删后没法恢复。这套流程坚持下来我的记忆库一直保持在几十条有效条目的规模检索又快又准。6. 常见问题与排查技巧实录6.1 install 后 hook 没生效症状是会话开开关关但记忆库一直空的。第一步检查 settings.json 里 hook 是不是真的写进去了第二步确认命令能不能在 Claude Code 的进程环境里执行。hook 配置里的 command 是从 Claude Code 进程里执行的如果 claude-mem 不在 Claude Code 的 PATH 里就会静默失败。这种时候把命令改成绝对路径最稳比如/Users/你的用户名/.local/bin/claude-mem hooks on_session_start。改完一定要完全重启 Claude Code不是开新会话是退出进程再进来。6.2 daemon 连不上最典型的报错是连接 localhost:8001 被拒绝。先claude-mem status再确认 daemon 真在跑。第二个常见问题是环境变量改了没重启 daemon旧配置还留在进程里导致连接的目标地址不对。端口被占用时按顺序执行lsof -i :8001 kill -9 pid claude-mem daemon另外提醒一句如果你用了 .env 加载配置改完文件后 daemon 必须重启别想当然以为能热加载。6.3 MCP 工具在会话里不出现装完发现 Claude 不会用记忆工具多半是 MCP 没有注册成功。Claude Code 里可以用claude mcp list查看已注册的 MCP server。手动注册的通用姿势类似这样claude mcp add claude-mem -- python -m claude_mem.mcp注意把模块路径换成你本机实际的安装位置也可以先用which claude-mem确认再阅读官方 README 里给出的注册命令为准。注册完必须完全重启 Claude CodeMCP 列表才会刷新。这一步我栽过跟头当时以为是工具坏了其实是没重启。6.4 记忆检索不准、乱记如果 ask 出来的结果牛头不对马嘴先检查嵌入模型不同模型向量空间不一致从云端切换到本地 Ollama 之后历史记忆可能需要重新向量化。最简单的做法是清掉重建——先 export再 clear再 import让系统重新走一遍向量化。乱记的问题更常见。Stop hook 会把整个 transcript 交给模型抽取有时候会把临时探索性的结论当成最终决定存进去。解决办法有三个一是在会话里多用主动记忆重要决定明确说成请记住二是定期 review 加删除三是引入人工审核机制每周末看一遍新增记忆只保留真的需要长期遵守的。我自己现在基本靠这套三板斧乱记问题缓解了不少。6.5 隐私、密钥与成本控制记忆库是文本里面可能包含业务逻辑、变量名、甚至零散的密钥片段。我的原则是生产环境的密钥、密码这类东西永远不要让它进入记忆库。一旦发现记忆里出现疑似密钥的字符串立即删除该条目并去轮换真实密钥。成本控制前面说过主要开销是事后抽取。我一般把超长会话的自动抽取改成手动 harvest需要沉淀的会话才抽不需要的就让它过去。这也算一种精打细算的用法——记忆系统的目标是记住有用的东西不是把你所有的废话都存档。最后分享一点我自己的使用体会。从装上 claude-mem 到现在最明显的变化不是 Claude 变得多聪明而是我重复交代事情的次数大幅下降。以前每开一个会话都要重新跟它对齐一遍项目背景现在开新会话它自己就知道这个项目用 pytest、部署走 staging/production、变量命名要驼峰。这种它在慢慢了解我的感觉是 CLAUDE.md 给不了的。如果让我给新接触的人一个建议那就是先把记忆当成显式记录来用重要约定用嘴说出来让它记住而不是指望事后抽取全自动搞定。等你对它的脾气摸透了再慢慢放开自动抽取的开关。记忆这个东西贵精不贵多攒一堆正确的废话还不如干干净净留十句真用得上的约定。