Claude Code 失忆症的救星：claude-mem 长期记忆实践

Claude Code 用久了，你大概率会跟我一样遇到同一个坎：这玩意每次开新对话都像得了失忆症。上午刚跟它敲定的技术选型、目录约定、接口返回值结构，下午新开一个 session 它全部不认，你得把同样的背景从头再讲一遍。遇到复杂项目，光是解释上下文就能耗掉几百 token。这个问题缠了我好一阵子，直到我用了 claude-mem 这款开源工具，情况才彻底改观。

如果你正在用 Claude Code 写项目，或者你是一个重度依赖 AI 编程助手的开发者，claude-mem 绝对是值得你花半小时接进来的工具。它做的一件事非常朴素：让 Claude 具备跨会话的长期记忆。简单说，它会在你每次对话结束后自动提炼并保存关键信息，下次开新对话时再把相关的记忆找回来塞进上下文。本篇文章我就从它的整体设计、核心机制、完整接入步骤和踩坑经验四个层面，把我这段时间的实际使用心得全部写出来。

1. 项目定位与设计思路

1.1 没有记忆的 AI 编程助手，到底有多痛

先聊聊痛点。Claude Code 本身是个非常好用的终端编程助手，但它原生的上下文管理是"一次性"的——每个会话都是独立世界。我实际维护一个中型后端项目时被这个问题折磨得够呛：项目里有一套约定俗成的错误码规范、数据库表命名风格、接口返回的包裹结构，这些信息每次新开对话我都要手动交代一遍。

你可能会说，那我不新开对话不就行了？问题是 Claude Code 的上下文窗口是有限的，长时间对话到后期，模型会严重“忘记”早期内容。而且重启终端、切换分支、换台机器都会开启全新对话。每次切换都是一场事故现场：它又给我提出了和昨天完全相反的目录结构建议，或者把早已废弃的旧接口拿出来当参考。经历过两三次之后，我意识到必须给这个助手配一个“外挂笔记本”。

1.2 claude-mem 给出的答案：本地记忆层

claude-mem 的核心思路很直接：在 Claude Code 和模型之间插入一层本地记忆存储。它把所有值得保留的信息——聊聊了哪些决策、用户偏好什么技术栈、项目中每个文件大概是干什么的——统统写进本地 SQLite 数据库和 JSONL 文件中。

关键的一点是，它不是在对话中被动记录，而是通过 Claude Code 的 hook 机制在你每次对话结束后主动“复盘”。对话停止后，claude-mem 会把完整对话内容发给 Claude 进行一次总结提炼，生成结构化记忆，存到本地。下次对话开始时，它又会通过语义搜索把相关的记忆注入到上下文里。

这种设计思路我特别认可，它有点像给团队里的实习生配了个随身的笔记本：不是让实习生把每句话都记下来，而是让他听完会自行总结重点，下次遇到同类问题时翻本子找到对应的经验。这比单纯的“对话日志存储”聪明得多——存下来的不是流水账，而是可以反哺新对话的高质量上下文。

1.3 为什么“本地优先”这步棋很关键

claude-mem 在架构上坚持本地存储，数据全部落在你自己的机器上，而不是送到某个云端服务。这个选择我认为有两层考量。

第一层是隐私。编程对话里经常夹着业务逻辑、内部接口设计、甚至数据库密码。这些数据经不起第三方存储的折腾，放在自己硬盘上才是可控的。第二层是可靠性。本地文件你可以随便备份、清理、导入导出，不受任何外部服务的生命周期限制。就算 claude-mem 哪天不维护了，我的记忆数据还用 git 做了存档，随时能把老数据重新加载回来，完全不会锁死。

2. 核心机制拆解

2.1 记忆的“写”：从对话到结构化笔记

要理解 claude-mem 的写入机制，得先看它接入 Claude Code 的方式。它一共挂载了两个通道，一个是 MCP 服务器，一个是 hook 钩子。MCP 服务器提供记忆的读写工具，hook 则负责在对话结束时触发“总结记忆”的动作。

整个写入流程大概是这样的：当我结束一次对话，Claude Code 的 Stop hook 会执行claude-mem onStop命令。这个命令会把本次对话的完整 transcript 抽取出来，发送给大模型做一个总结。总结输出的并不是废话段落，而是非常结构化的 JSON 结果，里面包含三样东西：对话的标题、一段概括性的摘要、以及若干条像 JSON 数组一样的事实列表。

这便是我前面说的“复盘”行为：模型不是把对话原文复制保存，而是把它压缩成记忆。举个例子，如果整场对话都在讨论把某个模块的缓存策略从 Redis 换成本地内存缓存，契约格式里会出现类似“memory/extract_contract”“claude-mem”这样的数据条目。事实列表里就会存下“该模块已改用本地内存缓存，原因是 Redis 增加了不必要的网络延迟”“旧缓存键前缀 tmp_ 已废弃”这类浓缩信息。

每个 chunk 的记忆还会附带文件指纹（file fingerprint）和内容哈希（content hash）。这意味着 claude-mem 不只是记住对话说了什么，还能记住这些对话关联了哪些文件，以及文件的当前状态。当后续对话中同样涉及这些文件时，它能知道“用户上次对着这个文件做过什么决定”，而不是孤立地理解一段对话。

2.2 记忆的“读”：语义检索，而不是翻字典

记忆写进去了，怎么在合适的时机再拿出来用，这是更难的地方。claude-mem 用的不是简单的关键词匹配，而是语义检索。每条记忆在写入时都会生成向量 embedding，然后被索引，存进 SQLite 里。查询时，用户的问题或者当前对话的上下文也会被转成向量，然后在记忆库里做相似度检索，找出最相关的几条。

打个比方，关键词匹配像按题目索引查字典，你得知道确切的词才能找到；而语义检索则像搜索引擎，你输入“给接口加个缓存避免超时”，它能搜到之前讨论过“Redis 连接导致响应过慢最终改成本地缓存”的笔记，虽然这两句话里几乎没有相同的单词。

实际读回记忆的路径也很有意思。我在新对话里提问时，Claude Code 会把 claude-mem 的那些工具暴露给模型。模型会自己判断“哦，这个问题我可能需要历史记忆”，然后调用memory_search工具搜索相关记忆，再把返回的结果作为上下文继续回答问题。也就是说，claude-mem 并不会一刀切地把所有历史记忆都塞进提示词，而是按需取用，这样既节省了 token，又不会让无关历史干扰模型的注意力。

2.3 数据结构：JSONL 与 SQLite 各自扮演的角色

claude-mem 的数据存储有点“双轨制”的味道。SQLite 数据库负责管理记忆的索引、向量 embedding、文件指纹等结构化数据，查询走的是 SQL 和向量索引，效率高。同时，实际的人类可读记忆正文则以 JSONL（JSON Lines）格式存放，每一行是一条独立的记忆记录，带时间戳、类型标签和内容摘要。

为什么还要保留一份 JSONL 而不是全部塞进数据库？我的理解是，JSONL 文件是给“人”看的。数据库里的向量和索引是黑盒，出问题了你很难直接检查；而 JSONL 你可以用 jq、grep 随便查，可以用文本编辑器打开，可以放进 git 做版本管理。排错、审计、迁移都非常直观。我在实际使用中经常直接翻这些文件，确认某条记忆有没有被正确写入，比打开数据库检查舒坦得多。

记忆在 claude-mem 里还分了好几种类型，这是它相当细心的地方。用户事实记录的是用户的偏好或习惯，比如“该开发者喜欢用 Go 写异步任务”；对话事实记录的是某个 session 里达成的结论；文件记忆则和具体文件绑定，记录某个文件是干嘛的、最近改了什么。这样分门别类的设计，让记忆检索能按场景准确命中，而不是一锅炖。

3. 从零到一：完整接入实操

3.1 安装初始化：两种方式任选

接入 claude-mem 不用折磨自己。最简单的方式是用 Homebrew，一条命令就好：

brew install claude-mem

如果你不太喜欢依赖 Homebrew，也可以用 Ruby 的 gem 方式安装，因为 claude-mem 主要的逻辑是用 Ruby 写的：

gem install claude-mem

安装完成后，跑一下初始化命令，它会引导你创建配置目录并检查依赖：

claude-mem configure

它会生成一个配置文件，比如在~/.config/claude-mem/config.yml下。配置文件里核心的字段是确认你的记忆存储目录，以及你希望把记忆绑定到哪个级别——是全局还是按项目。我建议按项目级别开，默认的目录结构通常会放在你当前项目的.claude-mem/下，这样我多个项目的记忆是完全隔开的，互不串味。

3.2 配置 Claude Code：MCP 加 hooks 一起上

装好之后要做的关键步骤是让 Claude Code 认识 claude-mem。需要在 Claude Code 的配置里注册两个东西：MCP 服务器和 hooks。先看 MCP 配置，Claude Code 的 MCP 配置通常在.mcp.json或者项目级配置文件里。核心配置长这样：

{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": ["mcp"], "env": {} } } }

配置好后重启 Claude Code，它就会自动识别 claude-mem 的 MCP 工具，比如memory_search、memory_extract_contract、memory_get_facts这些工具都会暴露给模型去调用。

然后要加 hooks。hooks 是 Claude Code 在特定生命周期触发外部命令的机制，我们要用它来在对话结束时自动执行记忆提取。在 Claude Code 的设置文件里加这样一段：

{ "hooks": { "Stop": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "claude-mem onStop" } ] } ] } }

这个 hook 几乎出现在我每次对话的结尾，它会在对话停止时触发 claude-mem 把刚才的聊天内容进行总结和归档。加完之后，基本配置就完成了。

3.3 第一次完整的“记忆”体验

配置完成后，实际跑一遍流程你才会对这套系统有真正的体感。我用一个模拟场景来说明：我在某个项目里，想让 Claude Code 帮忙写一个 Python 函数，把 CSV 文件按指定列过滤后再转成 JSON。

第一次对话，我照常把任务交代清楚，Claude Code 写好了函数，对话结束。此时我故意不告诉它我的任何偏好——函数风格、变量命名规范、是否用类型注解，通通不说，然后关掉终端重开。

第二次对话，我直接说“把上次那个 CSV 转 JSON 的函数改成异步版本”。注意，任何关于上次函数存在的信息我都没有提供。但这次 Claude Code 的表现会让我惊喜：它不仅记得存在那个函数，还记得文件路径和大概的实现方式，甚至知道我最喜欢用snake_case命名。这是因为它在那次“复盘”里，把函数名、路径、代码风格这些信息全部写进了记忆。

如果你用memory_search工具手动查，还能看到类似这样的 JSON 结构：

{ "query": "CSV to JSON async", "results": [ { "title": "实现 CSV 转 JSON 的过滤函数", "summary": "编写了按指定列过滤 CSV 数据并转为 JSON 的函数，存为 utils/csv_to_json.py", "facts": [ "实现基于 Python 标准库 csv 和 json", "函数使用 snake_case 命名，带完整类型注解", "过滤条件由参数指定，支持多列过滤" ] } ] }

看到这些记忆以文本形式被重现，你会直观感受到，Claude 从“有问必答的搜索工具”变成了“真的懂你代码库的结对同事”。

3.4 调优建议：别让记忆变成残留垃圾

不过，用的时间一长，我慢慢发现记忆如果管不好，也会变成负担。好几条过时的记忆会把模型的注意力带偏。有几个调优方向值得关注。

首先是历史记忆的清理。claude-mem 提供了memory_dismiss_facts之类的工具，你可以主动否定某些不再适用的事实。实际场景里，项目重构之后旧目录结构就完全没意义了，与其让模型下次检索到过期信息，不如直接 dismiss 掉。我之前在一轮大规模重构中，用这个方式把十几条过时的“文件摘要”记忆清掉，后续对话的准确率肉眼可见地回升。

其次是控制记忆提取的触发频率。如果你每天都在跑大量短对话，每条都生成记忆，你的记忆库会膨胀得很快，检索噪音也会上升。我的做法是定期用claude-mem cleanup类似的命令做整理，把重复性、低价值的记忆合并删除。真正的长期记忆应该像人的记忆一样，渐渐只留下那些真正重要的事实。

最后是 embedding 模型的选用。claude-mem 支持配置不同的 embedding 策略，本地默认方案和云端方案在语义检索效果和响应速度上有差异。我在本地模型上遇到过长句子的检索准确率不够理想的情况，换用云端接口之后明显改善，但代价是每次检索会有额外网络延迟。你需要根据自己对隐私和速度的权衡来取舍。

4. 常见问题与排查技巧实录

4.1 高频事故与排查速查表

接入 claude-mem 的这几个月，我遇到过不少问题，很多都是新手最容易踩的。我整理了个速查表，方便你对症下药。

这里头最坑的是 hook 注册不生效的情况。Claude Code 的钩子匹配规则非常严格，如果你配置文件里的 matcher 写得不对或者 hooks 层级写错，它通常会静默失败——对话正常结束，但完全没有触发 claude-mem。我遇到过几次，排查了半天才发现原来是我把一个 JSON 的逗号写漏了，整个配置段被解析成了无效内容。切记改完配置文件后，一定要用claude-mem onStop手动触发一次，确认退出码和输出没有异常，再开始正常使用。

4.2 数据安全：备份、还原与隐私

claude-mem 把数据存在本地，这给了我们相当强的掌控感，但也意味着数据安全的责任在自己肩上。如果你不小心删了 JSONL 文件，或者想换台机器继续用，没有备份方案就会很被动。

好在这些记忆的本质是文本文件，备份极其简单。我的做法是把项目的.claude-mem/目录整个纳入 git 版本库，每次记忆的变更都被自动跟踪。这样既能看历史变更，又能随时回滚到任意时间点。遇到大版本升级前，我会额外用tar打个包扔到移动硬盘，安全问题基本就稳了。

另外要注意的是，claude-mem 提取记忆时会调用大模型来总结对话，这个过程涉及把对话内容发到模型服务端。如果你所在的项目要求极高的保密级别，建议查阅 claude-mem 关于离线模式的配置，确保总结过程和 embedding 生成都完全在本地完成，避免任何对话内容出网。我手上有个敏感业务项目就是这么配置的，实测离线方式只损失了一点总结质量，换来的是完全不出内网环境，这笔交易非常划算。

4.3 资源占用与性能维护

CLI 工具最常见的毛病是资源占用失控。claude-mem 常驻后台的时候，尤其是生成 embedding 索引或批量总结对话时，CPU 和内存会有明显飙升。如果你用的是老一点的笔记本，这体会会更强烈。

我的经验是给 claude-mem 设置合理的触发频率。在初始化配置里可以调低 hook 的超时时间和并发度，也可以把总结的任务改成手动控制。我在日常项目里会把它调成“对话超过 20 分钟才自动总结”，这样短对话不会频繁触发，长对话结束后的总结质量也更高。

还有个小技巧：SQLite 用久了会产生碎片，特别是我这种常年增删记忆的重度用户。定期用sqlite3做一次VACUUM缩库，对检索速度的提升非常明显：

sqlite3 ~/.claude-mem/memories.db "VACUUM;"

这个操作我大概每个月跑一次，数万条记忆的库能瘦身一半以上，检索延迟从可能出现的秒级回落回毫秒级。

5. 一点额外体会

最后我想谈一点自己用了比较长时间以后的真实感觉。claude-mem 最打动我的地方不在于它实现了多少高级功能，而是它改变了我使用 AI 助手的姿势。以前我面对 Claude Code 时，总有一种“要把它当陌生人重新认识一次”的紧张感，每次开对话前都要做心理建设，想想上下文怎么组织才容易让它理解。现在这种紧张感完全消失了，打开新会话几乎像接着昨天的聊天继续一样顺畅。

这种体验的差距不是靠加大模型上下文窗口能解决的，因为模型不是真的“记住”，而是靠每次注入大量历史文本来伪装记忆。claude-mem 的价值恰恰在于，它把记忆变成了真正有结构、可检索、可维护的资产——这其实是对待 AI 生产力工具的一种成熟思路：与其每次喂都给模型更多东西，不如让它自己学会“记什么、忘什么、查什么”。

如果你正在被 AI 编程助手的失忆症困扰，我强烈建议你在一个不重要的项目里先接上 claude-mem 试两天。先体验一下对话结束后自动沉淀记忆的安心感，然后再决定要不要全面推开。按照我个人经验，第一批记忆开始发挥作用的时间点，基本就是你回不去的时候。