给Claude Code装上长期记忆：claude-mem原理与配置实战

刚开始用 Claude Code 做项目的时候我最大的困扰不是它能力不够而是它记不住事。上午刚和它讨论完模块划分、依赖关系下午开个新窗口它又开始从零开始问你项目背景。会话一结束上下文就清空所有讨论过的决策、踩过的坑、确认过的约定全部归零。直到我找到 claude-mem 这个开源工具才第一次感受到AI 助手真的有记忆是什么体验。claude-mem 本质上是一个给 Claude Code 加长期记忆的命令行工具同时也是一个 MCPModel Context Protocol服务器。它会自动读取 Claude Code 的历史会话把里面的关键决策、项目约定、用户偏好提取出来存进本地数据库并在你下次开会话时把相关记忆自动塞回上下文里。说白了它就是给 Claude 装了个第二大脑。这篇就聊聊它到底怎么工作怎么配、怎么用以及我实际用下来踩过的坑。1. claude-mem 是干什么的先把记忆这件事拆清楚1.1 Claude Code 的会话失忆问题比你想的更严重Claude Code 这类 AI 编程助手工作方式是一个会话一个窗口。每个会话都有独立的上下文窗口窗口里的内容一旦超出上限或者会话结束就彻底翻篇了。你上一个会话里精心设计的一套接口规范、命名约定在下一个会话的 AI 眼里完全不存在。这种模式在日常写代码时还能忍毕竟每次需求比较独立。但一旦涉及跨多天的项目或者要并行开多个任务窗口问题就非常明显你得反复粘贴背景资料、重新描述业务约束、重复解释为什么不采用某个方案。我算过一笔账一个中等规模的仓库新开一个会话光对齐上下文这一步就要多消耗几千到上万 token还得搭上几分钟的对话时间。claude-mem 的思路不是去改 Claude Code 的上下文机制那改不了而是从外部做一层记忆管理。它把历史会话的内容离线处理提取出结构化的记忆再在合适的时机注入到新会话里。这样你开新窗口的时候它已经知道这个项目之前的约定不用你重复。1.2 两条主线事实记忆和语义记忆我把 claude-mem 的设计拆成两条线来看。一条是事实记忆。它从会话里抽取出明确的、可以结构化表达的信息比如项目使用 Go 1.22 和 gin 框架支付模块采用事件驱动架构用户偏好使用 table 格式输出对比结果。这类信息适合存在关系型数据库里精确匹配快速查询。另一条是语义记忆。很多东西没法用一句话概括比如一段讨论为什么选择 PostgreSQL 而不是 MySQL的长对话很难压缩成一条结构化记录。claude-mem 会把这类内容切成 chunk向量化之后存进向量数据库检索时用语义相似度去匹配。你新会话里提到数据库选型它能联想到之前那场讨论。两条线合起来就是完整的记忆系统精确的事实用 SQLite 管模糊的语义用 ChromaDB 管。这个设计在后面排查问题时很关键因为很多检索不到记忆的情况其实是查错了存储层。1.3 什么人适合用、什么时候值得上如果你只是偶尔用 Claude Code 写个一次性脚本那 claude-mem 的价值不大多装一个工具反而增加心智负担。但如果你是下面几类人我建议认真试试重度使用者每天和 Claude Code 大量对话重复解释背景让你烦了。项目长期维护者一个仓库要改几个月每次开新会话都要重新交接。多任务并行的人同时开好几个会话处理不同模块希望每个窗口都知道全局约定。团队协作场景你把一段有价值的设计讨论分享给新成员或者希望 AI 助理保持团队统一的代码风格。一句话总结当你发现自己给 AI 重复讲解同一件事超过三次的时候就该上记忆工具了。2. 核心原理解密一条会话记录是怎么变成长期记忆的2.1 记忆的原材料Claude Code 的会话转录文件claude-mem 能读取记忆的前提是Claude Code 本身会把会话内容以 JSONL 格式落盘。每一条消息是一条记录包含角色、时间戳、内容、token 用量等信息。这些转录文件存放在本地目录下具体路径因系统而异但通常位于用户目录下的.claude相关文件夹中。我第一次打开这个 JSONL 文件的时候发现信息量比想象中大得多。不只是对话文本还包括工具调用记录、文件读取路径、代码修改前后内容、用户反馈。claude-mem 要做的第一件事就是解析这些文件把用户消息和助手消息按会话重新分组清理掉那些纯噪音内容比如系统提示词、重复渲染的代码块、被截断的中间状态。这里有一个很重要的设计哲学claude-mem 不需要你主动教它记忆什么它通过解析你的历史会话自动提取。你正常用 Claude Code它就在后台积累素材。当然你也可以手动执行快照命令把当前正在进行的会话强制保存一份。2.2 事实提取管线让 LLM 当信息提炼工拿到原始会话后claude-mem 会调用一次大型语言模型默认是 Anthropic 的 Claude 模型来执行信息抽取任务。它会设计一个专门的 prompt要求模型从会话中提炼出值得长期记住的事实。什么样的事实算值得记住我观察下来的标准大致有三类项目的硬约束技术栈、目录结构、端口号、API 前缀、环境变量要求。用户表达的偏好不要用分号错误处理用自定义异常日志输出用 JSON 格式。已经达成共识的决策包括决策背后的理由。抽取结果被整理成结构化的形式包含主题、内容摘要、关联项目、发生时间、来源会话 ID 等字段。这些字段在后续检索时非常重要比如你可以按时间过滤最近两周的约定也可以只检索某个项目的专属记忆。这一步会消耗 token而且是一次性成本。每处理一个会话可能花几千 token换算成钱其实很少但正因为有成本claude-mem 才默认只在会话结束或者你手动触发时才执行抽取而不是每对话一轮就抽一次。2.3 向量化存储ChromaDB 承担的语义检索事实记忆解决的是明确知道叫什么的查询但很多记忆是模糊的。比如之前聊过熔断器在服务不可用时的降级策略后来你想查服务挂掉之后有什么兜底方案这两句话字面上没一个词是重合的精确匹配完全失效。这就轮到向量存储出场。claude-mem 把会话段落尤其是用户提问和助手长篇解释的部分切成固定长度的文本块用 embedding 模型转成向量存进 ChromaDB。当你发起一次检索时查询语句同样会被向量化然后通过余弦相似度找出语义上最接近的那一批文本块。这里有个细节值得说向量检索的阈值非常影响体验。阈值设高了很多本来相关的记忆被过滤掉你会觉得它怎么什么都想不起来阈值设低了又会混入大量无关内容浪费上下文窗口。我实际用过之后发现claude-mem 默认配置偏保守对我的使用习惯来说阈值还可以再调低一点后面我会给出具体建议。2.4 SQLite 与 ChromaDB 的分工双库配合不是玄学为什么不干脆全用向量库因为事实查询和语义查询是两种完全不同的检索模式。比如你问项目用的是什么数据库如果走向量检索返回的是一堆看起来相关的对话片段你还得自己翻效率很低。但如果它是一条结构化记录SQLite 里一行就能查出来直接展示。反之像之前有没有讨论过日志去重方案这种开放性问题SQLite 的表结构也很难表达。所以 claude-mem 用双库是有道理的SQLite 管已知的明确事实ChromaDB 管模糊的语义片段。一个精确一个灵活两者互补。你的数据就存在本地的 SQLite 文件和 ChromaDB 目录中这意味着所有记忆都是私有的不会上传到任何第三方服务器。唯一和外部 API 打交道的是抽取事实和生成 embedding 时调用模型服务。3. 安装配置与 Claude Code 集成实操3.1 安装先装工具再连模型claude-mem 是个 Python 项目安装方式推荐用 pipx 或者 uv tool避免污染系统 Python 环境。pipx install claude-mem # 或者 uv tool install claude-mem安装完先跑一下版本确认claude-mem --version如果你机器上没有 pipx可以先用python -m pip install pipx装一下。我个人更推荐 uv它速度快工具隔离也干净。装完之后claude-mem 需要和你的 Claude API 建立连接。它默认读取环境变量ANTHROPIC_API_KEY你需要在 shell 配置里把它做一次持久化。比如在~/.zshrc里加export ANTHROPIC_API_KEY你的-api-key然后顺手建好配置目录mkdir -p ~/.claude-mem这一步做了之后工具才能调用模型执行事实抽取和向量化。很多新手在这一步就卡住了经常是 API Key 没配对后面的命令全部报 401。3.2 全局配置理解 config.toml 里的关键字段claude-mem 的配置集中在~/.claude-mem/config.toml。第一次运行时会自动生成默认配置但不同版本生成的字段略有差异。以我接触到的版本为参考关键配置长这样provider anthropic model claude-sonnet-4-20250514 [memory] database_path ~/.claude-mem/claude-mem.db vector_store_path ~/.claude-mem/chroma [retrieval] top_k 10 similarity_threshold 0.5 use_session_context true我重点说一下几个字段的含义。model决定了用哪个模型来抽取事实和生成 embedding越强的模型抽取质量越高但成本也更高。database_path是 SQLite 文件的存放位置vector_store_path是 ChromaDB 的数据目录。top_k是每次检索返回多少条候选记忆similarity_threshold是语义检索的相似度阈值低于这个值的记忆会被丢弃。实际调整建议如果你的对话日产量很大top_k可以降到 5避免返回太多碎片化记忆挤占上下文如果你发现什么记忆都召回不了那大概率是阈值设太高了降到 0.4 左右体验会明显改善。3.3 通过 Hooks 实现会话自动记忆这是 claude-mem 最常用的集成方式。Claude Code 支持配置 hooks会在特定事件发生时执行外部命令。claude-mem 利用这一点在会话启动时召回记忆在会话结束时收集记忆实现全自动闭环。在 Claude Code 的全局配置~/.claude/settings.json里加入类似这样的配置{ hooks: { SessionStart: [ { hooks: [ { type: command, command: claude-mem recall --session-start } ] } ], SessionEnd: [ { hooks: [ { type: command, command: claude-mem collect --session-end } ] } ] } }注意Claude Code 的 hooks 配置格式在不同版本间有过调整具体以官方文档为准。但思路是一致的SessionStart时把相关记忆注入上下文SessionEnd时把本次会话的内容抽取成记忆。我建议先在项目级配置里实验也就是仓库根目录下的.claude/settings.json这样改动只影响当前项目不会污染全局。3.4 手动操作snapshot、recall、collect 三条命令实战hooks 是自动化的但手动命令更适合你理解它内部发生了什么。我最常用的三条命令是第一条claude-mem snapshot。它会对当前正在进行的会话做一份记忆快照相当于立刻把脑中的想法落盘。适合那种聊到一半、怕上下文快被冲掉、但里面还有重要结论的场合。claude-mem snapshot第二条claude-mem recall。它把当前项目相关的记忆拉出来展示。你可以加关键词缩小范围比如只查和数据库选型有关的记忆claude-mem recall --query 数据库选型第三条claude-mem collect。它遍历所有历史会话做一次全量记忆收集。第一次使用或者换电脑之后建议跑一次全量收集把积压的会话全部处理掉。claude-mem collect --all我实际跑全量收集的时候几千条会话处理了几分钟因为每条都要过一遍模型抽取急不来。如果只想处理最近的增量不加--all就行。4. 检索效果调参与常见问题排查实录4.1 检索不到记忆从三个维度逐个排查先说排查思路。检索不到记忆未必是工具坏了很多时候是机制没对。第一步看数据层。先跑claude-mem stats或者直接查看 SQLite 文件确认记忆到底存没存进去。很多情况下是会话结束后 hooks 根本没触发collect 压根没执行数据库空空如也。解决办法是先手动跑一次claude-mem collect --all把历史数据补上。第二步看检索层。如果数据存了但召回结果还是稀烂那就是阈值和 top_k 的问题。默认 0.5 的相似度阈值对某些项目来说偏高尤其是技术名词堆砌的对话往往需要更低的阈值才能匹配到。我把阈值调到 0.4 之后可变性明显好很多。第三步看上下文注入。claude-mem 的 recall 结果会被注入到 Claude Code 的会话开头但这些内容也是要占用上下文的如果一次注入太多或注入的内容与当前任务不相关反而会干扰模型判断。所以 recall 命令支持按项目、按时间过滤建议每次注入不超过 15 条记忆精选远比堆量有效。4.2 记忆数据存在哪、怎么备份和迁移所有记忆数据就存放在配置目录下主要是 SQLite 数据库文件和 ChromaDB 目录。想知道确切的路径用一条命令就能查到claude-mem config show备份其实很简单把这个目录整体压缩拷贝走就行。如果换电脑除了拷贝数据目录别忘了把config.toml和 API 环境变量也迁移过去。有一点要注意ChromaDB 的目录结构对版本敏感跨版本迁移时如果向量库打不开干脆删掉重建再用collect --all全量重建向量数据比折腾兼容性快得多。4.3 隐私与成本核算别忽略这两笔账claude-mem 默认把数据存在本机这点让我比较安心。但有两个坑必须提醒。一个是隐私边界。虽然数据库是本地的但 claude-mem 在抽取事实时会把会话内容发送给模型 API 处理也就是那一小段对话文本会经过外部服务。如果你在会话里贴过敏感的代码或密钥这部分数据实际上已经走了外部通道。所以我从不把真实的生产密钥贴在 Claude Code 对话里这个习惯比任何工具配置都重要。另一个是 token 成本。收集和抽取不是免费的全量收集尤其费 token。我算过一笔账每天产生 20 个会话每个抽取消耗约 2000 token一天大概额外消耗 4 万 token折合成本并不高但如果你的会话动辄几万字成本会线性上升。解决办法是降低抽取频率比如只在会话真正结束时收集或者定期手动批量跑而不是每个会话都触发。4.4 常见问题速查表我把实际遇到的高频问题整理成一张表方便大家直接对照。问题原因解决方案命令执行后报 401 或 API key 错误环境变量未配置或失效检查 ANTHROPIC_API_KEY重新 export 后重试collect 执行很久不结束历史会话量太大逐条抽取耗时先跑不带 --all 的增量收集或者分批次处理开新会话完全没有注入记忆hooks 配置未生效或路径错误检查 settings.json 的 hooks 结构用 claude-mem recall 手动测试检索结果和当前任务毫无关系similarity_threshold 太低、top_k 太大提高阈值到 0.5 以上top_k 降为 5-8同一个项目有多个目录分支记忆串味缺少项目隔离标识在配置或命令中显式声明 project 维度按项目过滤升级 claude-mem 后 ChromaDB 打不开存储结构版本不兼容备份后删除向量库目录用 collect --all 重建这张表覆盖了我踩过的大部分坑但不代表没有新坑。遇到不确定的问题先跑claude-mem doctor类的诊断命令看看环境变量、配置、数据库完整性是否正常比盲目改配置要高效。写在最后我的实际体会用 claude-mem 已经一个多月给我最大的感受是心态上的变化以前开新会话前总要先整理一遍背景现在直接开干AI 自己能想起来。但如果让我给新手一个建议就是别一上来就上全套 hooks 自动化先把手动命令跑通理解数据是怎么流动的再加自动化。因为自动化一旦出问题你难排查到底是 hooks 没生效、抽取失败了还是阈值没调对。我个人的路径是先手动 snapshot、collect、recall 各跑一遍确认存储和检索都能正常工作然后才去改 hooks 配置。这样每一步的可控性都很好。最后分享一个小技巧如果你经常在多个项目之间切换建议在每个项目的根目录建一个独立的 claude-mem 配置而不是全局共用一套。项目级隔离能显著减少记忆串味让每次召回的结果都和当前任务强相关。我第一次用全局配置时经常在 A 项目里召回 B 项目的旧约定改成项目级配置之后这个现象基本消失。记忆这件事关键是精准不是量多。