为Claude Code赋予持久记忆：claude-mem原理、安装与实战指南

最近我在重度使用 Claude Code 帮自己写代码遇到了一个特别拧巴的场景昨天刚跟它交代清楚的偏好——包管理器用 pnpm、测试走 Vitest、格式化交给 Biome 并且别乱动 import 顺序今天新开一个终端窗口它全忘了。这就是无状态会话的代价。Claude Code 每次对话都是全新上下文它不记得你昨天说过什么也不记得上上个项目里踩过的坑。于是我从 GitHub 上翻到了 claude-mem 这个开源项目目的很直接给 Claude Code 加一层真正持久的记忆。用了一段时间之后我想把它的工作原理、安装步骤、实际效果和那些文档里不会写的坑完整梳理一遍。1. 先搞清楚Claude Code 为什么“不记事”以及 claude-mem 补的到底是个什么位置1.1 无状态会话是默认设计也是日常使用的最大痛点如果你只是偶尔用一次 Claude Code无状态其实没什么感觉。但如果你像我一样把它当成日常编码搭档每天要在同一个项目里开好几个终端窗口甚至跨好几天维护同一个分支这个问题就会被无限放大。我举个例子上周我在改一个迁移脚本连续三天都在跟 Claude 讨论“这个数据库字段千万别动”“那个 API 的响应结构里data字段可能要拆”。每次新开对话我都得像念咒语一样把这些前置条件重新打一遍。更尴尬的是有时候我忘了交代Claude 就按它的“默认常识”去处理直接把我辛辛苦苦定好的规则给绕过去了。从技术上讲这不是 Claude 的 bug而是当前会话机制的正常行为。每个会话上下文隔离模型不会自动继承之前的对话历史。这种设计保证了轻量和隐私但在持续工程场景里它就是最大的效率杀手。1.2 claude-mem 的解决思路把“记忆”从会话里剥离出来落成本地文件claude-mem 做的事情直观概括就是它站在会话旁边“偷听”把值得记住的东西写到本地文件里下次新会话开始时再把这些记忆重新喂给 Claude。它没有去改 Claude Code 的内部实现也没有要求 Anthropic 开放什么额外的记忆 API。它的思路非常“工程化”Claude Code 本身会把每次会话的完整对话记录以 JSONL 格式落到本地磁盘通常在用户目录下的.claude/projects里claude-mem 就负责扫描这些日志提取出有长期价值的信息存到自己的记忆仓库中。然后在 hook 触发的时间点比如一次会话结束时、一个子任务停止时把这些记忆注入回去。这个设计为什么聪明因为它完全不侵入核心对话流程风险可控。你装它、卸它都不会影响 Claude Code 本身的运行。它更像是给命令行工具加了一个“外挂笔记本”而不是给模型加了一层幻觉式的自我认知。1.3 谁适合用谁可以先等等我对身边朋友的建议是如果你只是偶尔让 Claude Code 写个一次性脚本装不装无所谓反而可能因为额外的记忆注入让上下文变长、变慢。但如果你是下面这几类人claude-mem 基本是刚需长期维护一个或几个项目跨会话、跨天、跨周都在跟 Claude 协作你有一套自己的代码风格、工程约定、命令习惯希望模型每次都自动遵守你需要让 Claude 记住“这个项目里不能用那个库”“这个服务必须走代理”“测试必须带覆盖率”这类反复交代的规则你经常开多个终端窗口希望它们共享同一套“对项目的理解”。反过来说如果你刚接触 Claude Code连 hook 是什么都没概念我建议先裸用一段时间等确实感觉到“重复交代”烦了再上也不迟。工具是服务于痛点的别为了装而装。2. claude-mem 的记忆体系四类记忆与本地存储结构2.1 记忆仓库里到底有什么目录结构先混个脸熟装好 claude-mem 并跑过几轮对话后它会默认在用户目录下建一个~/.claude-mem文件夹。不同版本的具体结构会略有差异但核心骨架基本是这样的~/.claude-mem/ ├── memory/ # 长期记忆正文Markdown 格式按主题/域组织 ├── sessions/ # 会话归档压缩后的对话摘要 ├── cache/ # 扫描日志的缓存可以随时清掉 └── index/ # 检索用的索引数据我特意提这个结构是因为它能帮你理解 claude-mem 的记忆模型它不是一个“黑盒数据库”而是用人类可读的 Markdown 文件存记忆。这意味着你可以直接打开阅读、手动编辑、批量删除甚至可以把这个目录纳入 git 仓库做版本管理。我第一次看到memory/里生成的文件时觉得像在看一个项目 wiki 的草稿每条记录都是自然语言的短句例如“此项目使用 pnpm 作为包管理器”“部署到 staging 时需要先执行 migration”。2.2 四类记忆direct、auto、droid 压缩与主题归档claude-mem 在记忆的组织方式上做了几个层次这也是它跟“简单地把日志灌回去”的本质区别。按我的理解它可以分成下面四类记忆类型触发方式典型内容我的使用感受直接记忆用户明确说“记住”“记住以后都用 pnpm”最可靠基本指哪打哪自动记忆工具扫描会话时自动识别代码风格、约定、技术选型有惊喜也有噪音droid 压缩会话结束或变长时自动总结整个会话的浓缩摘要、关键决策适合追溯不适合直接引用主题记忆手动或自动按主题归类跨会话的主题化知识如测试策略、部署流程检索效率最高直接记忆最好理解你在对话里明确要求“记住这件事”claude-mem 就把它标记为高优先级记忆。自动记忆就有意思了。它并不仅仅复制你的话术而是会尝试抽取“值得长期保存”的信息比如你多次提到某个约定、使用某个工具的固定偏好它会自动沉淀。缺点是信噪比不稳定后面我在实测部分会展开讲。droid 压缩是让我比较惊喜的一层。会话一旦拖得很长或者一次 Stop 事件触发时claude-mem 会把整个会话压缩成一个类似“会议纪要”的摘要存到归档里。这个东西的价值在于几个月后你想回溯“当时为什么决定用方案 A 而不是方案 B”不用翻海量聊天记录了直接查会话摘要就行。主题记忆则是偏手动的一层。你可以把相关记忆组织成带主题标签的条目之后按主题索引恢复。我的习惯是按项目或者按领域建主题比如backend-api、frontend-styles、deploy-runbook。2.3 记忆如何被“想起来”扫描、检索与注入理解完存储再来看触发链路。claude-mem 的核心不是存储而是在恰当的时机把记忆塞回上下文。它通过 Claude Code 的 hook 机制工作。简单说Claude Code 允许在特定事件发生时执行外部命令claude-mem 主要监听的是Stop和SubagentStop这类“对话暂停/结束”事件。每当这些事件触发claude-mem 就被唤起扫描最新的 JSONL 会话日志更新缓存和记忆库。同时在新会话启动时它会根据当前项目路径匹配相关记忆把命中结果注入到新会话的上下文里让 Claude 一开始就知道“这个项目里有哪些约定”。有个细节值得注意claude-mem 不会把所有记忆一股脑全塞进去那样 token 会爆炸。它有一套检索逻辑优先找“当前项目相关”“高置信度”“近期更新”的记忆。这也是我建议你不要完全依赖自动记忆的原因——如果库里塞满了无关内容检索命中率会明显下降。3. 安装与激活从 npx 一键安装到手动验证记忆落盘3.1 前置条件先确认自己的环境再动手claude-mem 是用 Node.js 写的所以第一件事是确认你的机器上有 Node且版本不能太低。我的经验是 Node 18 以上比较稳如果你还在用 16 或者更老建议先升级。其次你得已经装好 Claude Code并且至少跑通过一次完整会话——因为只有跑过会话本地才会有日志可供扫描。检查命令很简单node -v npm -v claude --version如果这三行都能正常输出基本就具备安装条件了。3.2 两步装好一键安装和 hook 配置检查官方推荐的方式是直接用 npx 一键安装npx claude-memlatest install这条命令会帮你做两件事一是把 claude-mem 的命令行工具装好/更新到最新的可用版本二是自动往 Claude Code 的配置文件里写入 hook。装完之后我强烈建议你手动打开配置文件看一眼别只信那个 Success 提示。常见的位置有两个用户级~/.claude/settings.json项目级.claude/settings.json优先级更高我机器上的用户级配置里hook 部分大致长这样不同版本生成的内容可能略有差异但结构上是这个套路{ hooks: { Stop: [ { hooks: [ { type: command, command: claude-mem on_stop } ] } ], SubagentStop: [ { hooks: [ { type: command, command: claude-mem on_subagent_stop } ] } ] } }这里的关键是command字段必须指向你实际安装的 claude-mem 可执行位置。如果用 npx 装的有时它会被解析成一长串路径。如果这里写错了hook 不会报错只是静默失败Claude Code 看起来一切正常但记忆始终不会更新。另外一个容易忽略的点如果你在项目级配置里也写了 hooks且内容和用户级冲突项目级会覆盖用户级。所以当某一天记忆突然失效先检查是不是某个项目自己的.claude/settings.json里把 hook 顶掉了。3.3 验证安装故意让 Claude 记住一件事装完不要急着正常使用我建议专门做一次“记忆验证”确保链路是通的。方法很简单在一个项目目录下启动 Claude Code明确说一句话“记住这个项目的包管理器是 pnpm以后所有安装命令都用 pnpm不要用 npm”正常聊几句然后退出会话等几秒再重新打开一个新会话问“这个项目用什么包管理器”。如果新会话里 Claude 能直接回答出“pnpm你在之前的对话里交代过”说明记忆注入链路已经打通。如果它答不上来不要急着怀疑工具先执行一次检查我一般用这一步诊断claude-mem status这个命令会告诉你当前的记忆仓库状态、最近一次日志扫描时间、hook 配置是否被识别。我最常遇到的问题就是“最近扫描时间”停留在几天前那基本意味着 hook 没触发。3.4 交互式 CLI日常记忆管理的基本操作记忆装好之后管理入口就是claude-mem命令本身。它提供一个交互式终端界面你可以在里面浏览记忆、按关键词搜索、编辑内容、删除条目。不用背太多命令但如果想写脚本批量操作下面几个子命令是高频率用的# 查看所有记忆 claude-mem list # 按关键词搜索 claude-mem search pnpm # 按主题过滤 claude-mem list --topic deploy-runbook # 删除指定 ID 的记忆 claude-mem delete memory-id # 查看运行状态 claude-mem status我的建议是至少每周手动跑一次claude-mem list快速扫一眼自动记忆生成了什么。别让记忆库变成垃圾场这一步的收益非常大。4. 实测两个月自动记忆、droid 压缩与主题归档的真实体验4.1 自动记忆的信噪比哪些值得留哪些是噪音用了一段时间后我必须诚实地说自动记忆是双刃剑。好的方面是它确实捕捉到了一些我没主动要求记、但很有价值的信息。比如有一次我在多个会话里反复让 Claude 修改同一个 Lua 模块的接口它自动记下了“该模块的导出函数命名风格是下划线式”这个隐性约定。之后新会话里再聊到这个模块Claude 直接按这个风格写代码不用我再纠正。但噪音也相当明显。我印象最深的一次自动记忆记下了“用户今天想用 Fira Code 字体”这完全是个一次性偏好根本不值得长期保存。更麻烦的是如果这种噪音堆积多了你做关键词检索时前面几页可能全是这种“当日热点”真正重要的项目约定反而沉到下面去了。所以我用的策略是把自动记忆当草稿把主题记忆当正式成果。定期把 auto 类型里真正重要的条目整理进主题记忆然后删掉那些一次性的噪音。有个小技巧是如果你发现自己反复删除某一类自动记忆可以把这个信息记在项目说明文档里让 Claude 和 claude-mem 的自动提取“知道”这类内容不需要记。4.2 droid 压缩会话结束后的归档流程以及我遇到的一次“压缩失败”droid 层是我最初没抱期待、后来觉得最值的一个功能。它会在会话结束时生成一版“浓缩摘要”把本次对话里涉及的关键决策、变更文件、遗留问题整理成一段结构清晰的 Markdown归档到 sessions 目录。我经常在一两天后回翻这些摘要比翻原始聊天记录省力得多。但我也踩过一次坑。有一回我开了个特别长的会话大概覆盖了四五个子任务全程估计刷了几百条消息。会话结束后我照例去看归档发现摘要迟迟没生成。排查之后发现原因大概是会话结束时 Claude Code 的Stop事件正常触发了但 claude-mem 在处理那个超大会话时耗时太长接口响应超时hook 被系统中断了。那次我手动跑了一次扫描才补上。这段经历给我的教训是不要指望 claude-mem 对超大规模会话也能“秒级压缩”它的 droid 压缩本质上也是一个 LLM 调用会话越长耗时越长。如果你也碰到类似问题先不急着报 bug耐心等几分钟或者手动执行一次扫描大概率能补上。4.3 主题记忆跨项目、跨场景的“唤醒词”主题记忆是我用下来觉得最像“第二大脑”的一层。它的思路很简单把记忆按主题分类需要的时候按主题整体恢复。我实际操作中的例子我有一个deploy-runbook主题里面存了“上线前必须先跑迁移脚本”“staging 域名是 xxx”“回滚时要先摘流量”这一类的部署约定。只要某次会话聊到部署相关的内容我就会手动触发这个主题的注入Claude 就能直接基于这套 runbook 来干活而不是每次都对着一张白纸猜。怎么触发最直接的方式是在对话里引用主题名例如说“按 deploy-runbook 里的约定来”。claude-mem 在检索记忆时会优先匹配当前对话中出现的主题关键词把这些条目注入上下文。我自己是习惯在项目根目录放一个CLAUDE.md里面写一句“部署相关操作参见 claude-mem 的 deploy-runbook 主题”这样 Claude 自己在动手前就会去拉。4.4 另一个进阶玩法把记忆仓库挂给 Claude 主动检索除了默认的自动注入之外claude-mem 目前还提供了一种更主动的模式把记忆仓库作为可检索的外部资源挂给 Claude相当于让 Claude 在对话中用工具实时查记忆。这个模式下Claude 不是被动等待记忆注入而是自己判断“这个问题需要翻历史记录”然后主动去搜索。这个玩法对“旧项目突然要改个小需求”特别有用。我有个三个月没碰的项目重新打开时 Claude 自己就去翻记忆库里这个项目的技术栈和关键约定然后给了我一份“根据历史记忆这个项目应该注意这些点”的摘要。那一瞬间确实有点“老兵归队”的感觉。需要提醒的是这个模式对上下文 token 的开销会更敏感因为它允许 Claude 在会话中途多次发起检索。如果你的对话已经很长再叠加检索结果有可能触发上下文窗口上限。我一般只在需要翻老项目时会手动开启日常新项目就保持默认注入模式。5. 必须知道的边界token 开销、隐私、多机同步与版本兼容5.1 记忆膨胀带来的 token 开销清理比记忆更重要记忆不是越多越好。每次新会话注入相关记忆都会挤占上下文窗口。如果你的记忆库很臃肿尤其是自动记忆里堆满了“那天想换图标库”这种垃圾检索出来一堆低价值条目反而会让 Claude 的注意力被带偏生成质量下降。我的做法是建立一个简单的“清理节奏”每天结束工作前跑一次claude-mem list扫一眼每周做一次深度整理把有价值的 auto 条目转成 topic 条目删掉一次性噪音每次项目结束后把已经不再相关的旧记忆归档或删除。另外claude-mem 的目录里cache/是可以直接清的它只是扫描缓存不影响最终记忆。如果你发现它太大占磁盘直接删就行下次扫描会自动重建。5.2 隐私边界记忆库是明文别把密钥喂给它这一点必须单独说。claude-mem 把所有记忆都以 Markdown 明文存储在本地这意味着任何能读取你磁盘的程序都能看到记忆内容。我在实际使用中确实遇到过记忆文件里出现代码片段的情况——还好没有包含密钥但也够吓一跳的。所以我的建议非常明确不要在对话里让 Claude 把密钥、token、内网 IP、客户敏感信息写进“记住”范畴。比如“记住这个 API key”是绝对不能干的事。如果确实需要管理密钥请使用专门的密钥管理工具别指望 claude-mem 帮你加密保管。它是个便利工具不是安全工具。对于开发机多用户共用的场景我还会建议把~/.claude-mem的权限收紧一下至少保证只有你自己能读写这个目录。命令行下可以执行chmod 700 ~/.claude-mem5.3 换电脑或者换环境了记忆怎么跟着走claude-mem 默认把记忆存在本机换一台电脑、换一个 CI 容器记忆不会自动跟随。我的解决方案是把~/.claude-mem做成一个 git 仓库或者纳入已有的 dotfiles 仓库同步。但注意不要整目录同步。我只同步memory/和sessions/忽略cache/和index/因为后两者是本地缓存不同机器重新生成就好。同步方式我见过有人用 git 私有仓库也有人用网盘软链接。我自己习惯用 git 私有仓库原因是它还附带历史版本功能哪次把记忆改坏了可以直接回溯。5.4 Claude Code 升级后 hook 失效的处理方案最后一个坑也是很多人问我的某次 Claude Code 升级之后记忆功能突然不生效了。大部分情况不是 claude-mem 坏了而是升级过程中配置文件被改写了或者是 Claude Code 调整了 hook 事件的名称旧版配置里的字段不再被识别。我的排查步骤很简单跑一次claude-mem status看 hook 是否被识别如果没识别检查~/.claude/settings.json的 hooks 段是否还在如果 hooks 段还在对比一下项目级.claude/settings.json是不是有覆盖都不对的话直接重新执行一次npx claude-memlatest install。还有个更隐蔽的问题如果你的 Claude Code 是通过代理、容器或者包管理器装的命令路径可能和 claude-mem 自动写入配置文件时的路径不一致。遇到 hook 命令找不到的情况优先确认claude-mem在命令行里能不能直接执行不能的话就用绝对路径写在配置里。5.5 一些随想用了 claude-mem 快两个月我对它的评价是它不是一个“装了就变聪明”的玄学工具而是一个需要你花心思维护的工程组件。它的下限很低装完直接能用自动记忆会帮你沉淀一些东西它的上限完全取决于你怎么维护有没有定期清理噪音有没有把重要知识整理成主题记忆有没有跟团队共享一套记忆体系。对我来说最舒服的瞬间不是它记得我昨天说过什么而是它在新会话里主动说出“这个项目你之前定过规则”的那一刻。那种不用重复交代自己的感觉才是这类工具真正的价值所在。如果你也正在被“与新会话重新互相介绍”折磨不妨装一个然后从今天开始认真对待那个~/.claude-mem目录——它现在是一张白纸三个月后会变得无比值钱。