用Claude Code做了几个月实际项目之后我最大的感受不是它能写多少代码而是它太容易失忆了。新开一个会话之前聊过半小时的架构决策、被否决的方案、用户明确表达过的偏好通通归零。你不得不把背景重新粘贴一遍甚至要把已经讨论过一遍的问题再从头解释。后来我找到了 claude-mem 这个开源工具算是把这块短板补上了。这篇文章就围绕 claude-mem 展开把我从安装、配置到日常使用、二次开发过程中积累的经验完整梳理出来。适合那些已经受够了重复交代背景、想让 AI 助手保持上下文连续性的开发者参考。1. 痛点复盘为什么Claude Code需要一套外部记忆1.1 我在实际项目中反复撞上的失忆现场先说一个最典型的场景。上周一我让 Claude Code 帮忙设计一个订单模块的数据库表结构期间明确讨论过不要用外键约束因为后续分库分表会带来迁移麻烦最后敲定了用逻辑关联 应用层校验的方案。到了周三我要继续做订单模块的接口开发打开一个新会话让 Claude 先看一下表结构设计——它立刻开始建议我给订单表加上外键约束来保证数据一致性。那一刻我的血压是有点高的。这不是个例。多文件项目里技术债的来龙去脉、某个函数为什么写成当下这种奇怪的样子、哪些第三方库是经过调研才选进来的这些信息都只存在于某一次会话的上下文中。一旦那个会话结束就什么都没有了。CLAUDE.md 可以放一些长期原则但它毕竟是静态文件需要我手动维护而且项目越大、演进越快维护成本越高。1.2 静态提示词和自动摘要都救不了场很多人会想CLAUDE.md 够用了吧我一开始也这么认为。实际用下来发现两个问题第一CLAUDE.md 里写的是相对稳定的项目规范比如技术栈、目录结构、代码风格它不会记录昨天我们否掉了 Redis 缓存方案这种动态决策第二让 Claude 自己往 CLAUDE.md 里更新内容时它往往会写得过于保守或者过于啰嗦最后文件变成了大杂烩。也有人依赖 Claude Code 自带的会话摘要功能。但那个摘要是跟着单次会话走的无法在下次会话开始时自动注入到上下文中——你去翻历史记录还得先记得那是哪一天的哪个会话。这种手动检索的模式本质上和我自己翻便签没有区别。1.3 claude-mem 解决的是哪一环claude-mem 做的事情说白了就三步把每次对话中值得记的信息自动提取成结构化的记忆碎片存到本地 SQLite下次新会话启动时把相关的记忆重新注入给 Claude用遗忘算法控制哪些记忆保留、哪些过期。它和你自动维护的一本项目回忆录差不多写得好不好不重要重要的是不用你手动去写也不用你手动去翻。它本身是开源工具核心是一个 CLI 加一个 TypeScript SDK通过 hook 机制接入 Claude Code同时也在往其他 AI 编码工具Cline、Roo Code 等扩展。下面我会从架构开始拆因为它好用的原因恰恰在架构设计上。2. claude-mem核心架构记忆从采集到回放的全链路2.1 四个关键组件各司其职claude-mem 不是一个大而全的单一程序而是由几个功能边界清晰的模块拼起来的。理解清楚每个模块负责什么后续用起来才不容易踩坑。第一个是 CLI 管理工具。它负责安装初始化、查看记忆库、删改记忆、运行遗忘清理以及提供交互式 TUI 面板。日常管理基本都靠它。第二个是 TypeScript SDK。如果你想把记忆能力嵌入自己的 Node.js 应用里比如做一个内部工具让每轮处理结果都能沉淀到同一个记忆库就用 SDK 来做。它暴露的是加载记忆、添加记忆、搜索记忆这类底层 API。第三个是插件/hook 体系。Claude Code 提供了 session start、session end、user prompt submit 等生命周期钩子claude-mem 就是通过注册这些钩子实现自动注入记忆、自动提取记忆的。其他工具链比如 Cline、Roo则是通过 memory-tools 插件的方式接入同一套记忆库。第四个是 SQLite 存储层。记忆数据以 JSON 结构存在本地的 SQLite 数据库中每条记忆都带有类型标签、权重、时间戳、来源会话 ID 等信息支撑按相关性和新鲜度排序查询。2.2 一次会话中记忆是怎么流转的我拿一次实际会话给你捋一遍完整流程。会话开始前Claude Code 触发 SessionStart 钩子claude-mem 会从 SQLite 里把当前项目相关的记忆碎片拉出来按权重和新鲜度排序然后注入到系统提示词里。Claude 在生成第一段回复之前就已经看得到之前沉淀过的决策、偏好和待办了。会话进行中它并不只是傻等。Claude 在处理任务时会把一些临时提炼出的结论标记为候选记忆。比如它发现你多次手动修正某个接口的返回格式会产生一条 tool_probability 类型的碎片记录这个用户在这类接口上偏向扁平 JSON 结构后续行为会有意识对齐。这类碎片不一定要等会话结束才保存有些会实时写入。会话结束时SessionEnd 钩子触发claude-mem 对整场对话做一次榨取生成会话摘要并把几条高权重信息正式落库。当然不会全部写入毕竟大部分对话内容对长期记忆没有价值。所以它要经过权重评估用户明确表达的偏好、被否定的方案及原因、关键代码决策、待办事项这些类型的记忆优先级高日常寒暄、临时调试过程、错误尝试基本会被丢弃。2.3 记忆碎片的分类模型claude-mem 的记忆不是一条条大段文本而是一种带类型标签的碎片结构。我把常见类型整理成了表格记忆碎片类型记录内容典型示例insight项目洞察、用户偏好、结论用户明确倾向 pnpm 作为包管理器decision方案权衡与最终决策否决 Redis 缓存原因单机部署无并发瓶颈code关键代码结构与变更auth 模块使用 JWTrefresh token 过期 7 天todo待办与后续计划订单模块联调前需补事务回滚测试tool_probability工具使用倾向与频率调试时习惯开 --verbose 输出session_summary单次会话摘要完成用户模块重构抽出 UserService每条碎片还有权重字段和最后访问时间。权重越高、越是最近被用到下次越容易被注入到新会话里。这样设计的直接好处是不是所有历史记忆都无差别堆给 Claude而是按当下任务相关性读取确实能避免上下文被无关信息污染。3. 接入Claude Code安装、配置与首次实测3.1 环境要求和安装方式先看一下你的 Node 版本。claude-mem 要求 Node 22 及以上这一点我在文档里看到时并不意外它用了一些比较新的运行时特性。如果系统还是 Node 18建议先用 nvm 把版本切上去再装不然会直接报 engine 不匹配的错误。安装很简单全局装即可npm install -g claude-mem我建议全局安装而不是装到项目里原因只有一个记忆库是跨项目共享的一套基础设施。全局安装后不管你在哪个项目目录里跑 claude-mem 命令它都统一从同一个数据库读写。如果你装到某个项目里那这个项目的记忆就和其他项目隔离了跨项目复用反而变得别扭。装完后先看一眼版本确认环境正常claude-mem --version我这边装的是当时最新的稳定版输出正常。3.2 初始化做了什么第一次使用前要跑 init 命令claude-mem init这个命令会做几件事在 Claude Code 的配置文件里注册 hooks、创建本地数据库文件、生成基础目录结构。注册 hooks 时它会把配置写入到类似~/.claude/settings.json。完成之后你可以直接打开这个文件看会看到类似这样的结构{ hooks: { SessionStart: [ { type: command, command: claude-mem load --check-safe } ], SessionEnd: [ { type: command, command: claude-mem store } ] } }SessionStart 的 hook 负责在每次新会话开始时读取记忆SessionEnd 的 hook 负责在会话结束时提取和保存记忆。--check-safe这个参数呢我理解是让加载行为更保守一点避免在某些不安全的上下文中强注入。具体字段可能随版本略有调整但基本逻辑就是这一套。值得提醒的是如果你的 settings.json 里已经有过自定义 hooksinit 不会智能合并而是直接覆盖。我就是吃了这个亏后面会详细说。3.3 配置检查doctor 命令装完之后别急着上手先跑一遍健康检查claude-mem doctor它会检查 Node 版本、数据库是否可读写、hooks 是否正确注册、权限是否正常。我在第一次跑的时候它就提示了一个问题数据库所在目录的权限是 755建议收紧。这个东西虽然不影响使用但它会提醒你注意——记忆库里面存的可能是项目的非公开信息。doctor 通过后再打开 Claude Code随便聊两句然后退出。第二次进入时会发现 Claude 的回复里开始出现一些记忆了。我第一次测试的时候让 Claude 记住我喜欢用 pnpm不用 npm然后新开会话再问它我的包管理器偏好是什么它能答对。那一刻我就确定了这东西不是玩具。4. 日常操作实证CLI命令、TUI面板与记忆编辑4.1 TUI界面比想象中实用不带任何参数运行claude-mem它会进入一个交互式 TUI 面板。界面逻辑有点像邮件客户端左侧是记忆列表右侧是选中记忆的详情。上方有过滤条件可以按项目、按类型、按时间范围筛选。我在这个面板里主要做三件事第一快速浏览当前项目沉淀了哪些记忆第二发现某条记忆明显过期或者记错了直接按快捷键进入编辑模式修改第三对重要记忆打标让它在后续注入时获得更高权重。TUI 操作不需要背命令界面上会直接提示按键。唯一要适应的是它是终端 UI用惯了图形界面的人可能觉得不够现代但对于我们这种整天泡在终端里的人反而是加分项。4.2 高频命令速查除了 TUI日常我也经常直接用命令操作。整理一份高频命令清单命令功能我的使用场景claude-mem list列出当前项目记忆快速扫一眼最近沉淀的内容claude-mem search 关键词全文检索记忆库找某个历史决策claude-mem get id查看单条记忆详情确认一条记忆是否准确claude-mem add --type insight --content ...手动添加记忆补录线上聊过但没被自动提取的信息claude-mem edit id修改记忆内容纠正错误的自动提取claude-mem rm id删除单条记忆清理隐私或过时内容claude-mem export导出全部记忆为 JSON做备份或迁移claude-mem wipe清空记忆库项目翻篇时重置list命令可以加--since指定时间窗口配合--type过滤。比如我周三想看这周沉淀了哪些决策类记忆就会跑claude-mem list --since 2025-06-01 --type decision4.3 手动补录记忆的方法自动提取并不总是完美的有些信息它就是没抓到。比如某个客户明确说过订单号生成规则后续会改这种偏口语化的表达自动提取模块可能会认为它不够项目相关而丢弃。但你知道这句话很重要。这时候就需要手动补录。我的惯用姿势是claude-mem add --type todo --content 订单号生成规则待调整客户明确说过要改优先级别高手动添加的记忆权重默认不高但你可以通过 TUI 面板再给它打标提升权重。补录之后下个会话开始 Claude 就能看到这条 todo 了。实测下来任务类记忆的注入效果比 insight 类型更直接因为它天然是行动导向的。5. 记忆的遗忘与收缩防止记忆库变成垃圾场5.1 为什么全部记住反而是灾难有人可能会想既然要记忆那就把所有对话都存下来不是更好吗在实际使用中这个想法完全行不通。原因有三点。第一上下文窗口有限。Claude Code 单次能承载的上下文就那么多字节如果你把所有历史全塞进去真正处理任务的空间就被挤占了回复质量反而下降。第二记忆的时效性不同。昨天调试时试了 5 个失败的方案和用户明确说订单号要改成雪花 ID这两件事重要性天差地别。前者过了今天就毫无价值后者可能影响两周后的开发。第三旧记忆会和现状冲突。项目演进后几个月前的决策可能已经被后来新决策覆盖了。如果不遗忘Claude 就会在旧记忆和新事实之间来回摇摆行为变得很奇怪。5.2 遗忘算法LRU、TOFU 和按类型遗忘claude-mem 的遗忘机制不是简单的超过 N 天就删而是组合了多种策略。LRU最近最少使用挺好理解长期没被读到的记忆先被淘汰TOFU基于时间的遗忘函数会按时间衰减计算每条记忆的存活分数分越低越优先清理。它还能按类型遗忘。比如 tool_probability 这类记忆更新频率高它的半衰期设得很短可能几天没用到就衰减到很低的权重而 decision 类型的记忆半衰期设得很长因为它代表的是长期有效的项目决策。力度也是可调的。我建议不要上来就用默认值跑大项目先跑两周看看记忆库里残留的都是什么。如果发现很多三个月前的琐碎内容可以把遗忘力度调高如果发现重要的早期决策被误删了就调低力度同时把那些决策手动标记为高权重。5.3 会话压缩与上下文回收claude-mem 还有一个功能对长会话特别有用会话压缩。当单次会话的上下文持续增长接近 Claude 的窗口上限时它会对早期内容做一次压缩把大量对话浓缩成几条关键结论替换掉原来的冗长内容。这样你不需要频繁开新会话项目讨论可以一口气持续很久而重要的结论不会丢失。它的效果我直观感受是长会话的可用里程变长了。以前聊到四五十轮的时候Claude 开始出现忘了前面说过的细节的迹象现在明显延后了。而且压缩动作本身是自动触发的不需要我干预。5.4 数据存在哪、隐私怎么处理记忆数据默认存在本机路径大致在用户目录下的.claude-mem/文件夹里数据库是一个 SQLite 文件。它不会主动把记忆内容上传到远端除非你自己配置了远程模型或额外服务。这一点对很多公司内部项目来说挺重要的——毕竟你不想让代码决策类记忆散落到第三方服务手里。我自己的习惯是每周五用claude-mem export导出一份 JSON 备份到加密盘里相当于给项目大脑做快照。同时跑一遍claude-mem doctor确认磁盘权限没问题。如果某个项目彻底交付了我会直接claude-mem wipe清掉该项目相关记忆避免下一个项目的 Claude 被完全无关的历史信息干扰。6. 扩展与避坑SDK集成路径和我的实测心得6.1 把记忆引擎嵌入自己的 Node 应用如果只把它当成 Claude Code 的附属插件那有点浪费。claude-mem 的 TypeScript SDK 是很干净的可以在你自己的 Node 应用里直接调用。我试过一个场景公司内部有个批量处理代码评审的脚本历史评审结论一直没有沉淀。用 SDK 改写后每次评审完成就把结论写入记忆库。效果就是后续评审遇到类似模式时脚本能自动把上次的结论拉出来提示我省了不少重复判断。核心代码大概长这样import { MemoryStore } from photonicql/claude-mem; import { addMemory, loadMemories } from photonicql/claude-mem; import { fileURLToPath } from url; import path from path; const store new MemoryStore({ dbPath: path.join(process.env.HOME, .claude-mem, memories.db) }); // 写入一条决策记忆 await addMemory(store, { type: decision, content: 评审结论所有对外接口必须显式声明超时时间, project: api-gateway, metadata: { scope: code-review } }); // 读取相关记忆 const memories await loadMemories(store, { project: api-gateway, limit: 10 });SDK 的读写逻辑很直观记忆的过滤、排序这些复杂逻辑都被封装好了。唯一要注意的是如果你同时跑着 Claude Code 的 hook 和这个脚本两边用的是同一个数据库要注意并发写的问题。一般日常场景并发量很低但如果你要写批量任务建议在写入前做一次简单的冲突检测或者幂等处理。6.2 memory-tools插件让其他AI编码工具共享记忆我在一些项目里用 Cline 和 Roo Code之前它们和 Claude Code 的记忆是彼此隔离的。后来发现 claude-mem 有 memory-tools 的插件方案能让这两类工具通过 tool calling 的方式直接读写同一个记忆库。这就带来了一个很舒服的体验早上用 Claude Code 讨论方案下午切换到 Cline 去执行实现两边拿到的是同一套项目记忆。切换工具不再意味着切换大脑。配置方式和 Claude Code 的 hooks 不太一样需要把这些工具接入 claude-mem 提供的 MCP 聚合服务。文档里写的步骤比较清楚照着做就行。6.3 我踩过的一串坑接入过程不算完全顺滑这里把我踩过的坑原原本本列出来你能少走弯路。第一个坑是 hooks 覆盖。我之前在 settings.json 里自定义过 SessionStart hook用于自动加载某个环境变量文件。跑完claude-mem init之后我的自定义 hook 不见了——它直接覆盖了整个 hooks 配置。这个问题的规避方法很简单init 之前先把原配置备份好之后再手动把两个 hook 合并。第二个坑是 Node 版本。有一台工作机系统是 Ubuntu 20.04自带的 Node 是 18装的时候报 engine 不匹配卡了很久才意识到是版本问题。升级 Node 之后就顺畅了。第三个坑是记忆污染。有段时间我同时在弄两个项目其中 A 项目的记忆偶尔会出现在 B 项目的会话里。排查下来发现是因为两个项目共用同一个项目名标签Claude 的 cwd 没变记忆分类混淆了。后来我给记忆碎片都手动加上了项目路径元数据过滤时按完整路径匹配问题就解决了。第四个坑是自动提取的质量。它会把一些临时调试信息当成重要决策来存。比如我为了测试临时写了一段 mock 数据它竟然记成了项目使用 mock 数据方案。这种误判如果没发现后续新会话里 Claude 可能会基于错误记忆给出明显偏离的回答。所以我的建议是定期用 TUI 浏览最近的记忆发现明显错误的直接删掉或者编辑别让坏记忆越积越多。6.4 一些实战建议用了一段时间之后我总结了几条比较务实的经验。大的长期规范还是放 CLAUDE.md比如技术栈、目录结构、代码风格这些稳定的东西动态的决策、偏好、待办放 claude-mem。两者是互补关系不是替代关系。记忆要定期体检。可以给自己定个节奏每两周花十分钟翻一遍记忆库把过时的、错误的清理掉把重要的提升权重。这十分钟花得很值它能保证记忆库长期处于健康状态。陷在上下文里的新鲜记忆和存进库里的长期记忆是有区别的。claude-mem 适合存的是后者如果你今天讨论的某个细节明天就要用那你不用管它何必费这个存储总有一天会清理掉的临时上下文。最后说个我个人的体会。以前我开新会话跟 Claude 协作心里总得先打个腹稿想着那句背景介绍怎么写得足够简短又包含所有关键信息。有 claude-mem 之后这个负担基本没了。我只需要说继续做订单模块它自己就知道前因后果。这种被记住的感觉用多了是真的回不去了。如果你也正在被反复交代上下文的循环折磨我的建议是别犹豫给它一个周末的时间去试你大概率会跟我有一样的结论。