如果你已经用 Claude Code 写过超过一周的真实项目我相信你迟早会冒出同一个念头这工具怎么每次都像个第一次见面的同事上周刚跟它敲定好的技术决策这周新开一个会话它照样拿 npm 装依赖、照样往不该动的模块里塞代码你只能翻聊天记录把背景重新讲一遍。这时候就轮到 claude-mem 出场了。简单说claude-mem 是一个给 Claude Code 增加长期记忆的开源工具。它会把每次会话里产生的有效信息——比如你的编码偏好、常用命令、历史决策、踩坑记录——自动抽取并保存下来下次你启动会话时它再把相关记忆注入到 Claude 的上下文里让 AI 真的“记得”你们之前是怎么配合的。这篇文章不是官方文档翻译是我自己把 claude-mem 装进日常工作流之后对它的完整拆解和实战记录它靠什么机制记住东西、怎么在 5 分钟内配好、CLI 命令怎么用、以及我在真实项目里踩过的坑和排查思路。适合正在重度使用 Claude Code、同时被“无状态”折磨得没脾气的开发者。不管你是第一次听说这个工具还是已经装上但觉得效果不理想这篇应该都能给你些用得上的东西。1. claude-mem 到底在解决什么问题1.1 没有记忆的 AI 编程助手有多难用先还原一个真实场景。我维护的一个前端 monorepo约定好了依赖管理必须用 pnpm workspace不用 npm更不能提交 package-lock.json。头一天我跟 Claude Code 说得好好的它也答应得痛痛快快。结果第二天打开终端新会话里让它装个依赖它直接给我 npm install还在 lockfile 上产生了 200 多行的 diff。问题不在 Claude Code 本身。它确实是我用过的编程助手里上下文理解能力最强的一个但它的设计哲学是“每会话无状态”——会话一关上下文归零。这不是 bug而是有意为之保证每次请求的上下文干净、可控、不串味。可放到真实项目里这就很让人抓狂。因为一个项目的“积累”恰恰是长期碎片化决策的总和数据库连接池配多大算合理、为什么这个服务不能用 HTTP 轮询、测试框架为什么定了 Vitest 而不是 Jest。这些信息散落在几十个历史会话里根本不可能每次都完整重述一遍。有些人的解法是把项目说明文档越写越长然后每次会话开头从 CLAUDE.md 里读。这有效但维护成本高。你想想看一个活跃的项目每周新产生的决策就有好几条光靠人肉更新文档很难坚持而且文档是结构化的静态文本AI 读起来效率也低——它不知道该重点看哪一段。1.2 claude-mem 的架构思路记录、加工、回放claude-mem 的做法很有意思它本质上是在 Claude Code 与文件系统之间插了一个记忆层这个层自己干三件事记录、加工、回放。先说记录环节。claude-mem 不做全局键盘监听这种脏活而是利用了 Claude Code 自身的hooks钩子机制。简单理解hooks 就是在 Claude Code 执行某些生命周期事件时让你有机会运行一段自定义命令。claude-mem 主要挂三个钩子PostToolUse每次工具调用结束后、Stop会话生成结束时、PreToolUse工具调用开始前。第一个和第二个用来“记录”——把当前会话的输出内容导给 claude-mem第三个用来“回放”——在 Claude 干活之前把相关记忆塞回它的上下文。接着是加工环节。这里我最初以为是简单的日志累积实际用下来发现不是。claude-mem 拿到原始会话文本后会跑一轮抽取逻辑只留下有“记忆价值”的信息。举几个例子你在对话里说“以后都用 pnpm 别用 npm”这是一条偏好你跟 AI 讨论了半个小时最终确定用事件驱动架构而不是定时轮询这是一条决策你纠正了 AI 生成的某段代码里的命名规范这是一条纠正信号。至于那些“谢谢”“好的”“继续”之类的交互草稿压根没人内存。最后是回放环节。当你再次开启会话、claude-mem 准备注入记忆时它也不是把全部历史一股脑倒进去。它是基于当前的项目路径从记忆库里做一次检索筛出跟当前任务高度相关的记忆条目生成一份精炼的“记忆简报”注入到系统提示里。这有点像你开工前翻一眼自己的旧笔记本只看跟今天要干的活有关的那几页。生活化一点你可以把它理解成 AI 领域的“交接文档自动生成器”。1.3 记忆类型设计不是所有内容都配被记住我观察 claude-mem 对记忆的分类大致有这么几类项目偏好工具链选择、编码风格、目录约定、常用命令与操作模式部署命令、测试命令、代码生成方式、历史决策与绕过方案为什么不用某个库、遇到某个报错怎么解决的、用户纠正信号AI 做错了什么、正确的做法是什么。为什么要分类因为不同类型的信息在检索时的权重不一样。“项目偏好”几乎任何时候都该被看到它是 AI 行为准则的一部分“历史决策”只需要在相关任务出现时才调用“用户纠正信号”则类似于即时反馈优先级最高但要留时间窗口防止 AI 纠正完转头就忘。分类设计直接决定了记忆的召回质量——如果所有信息混在一个平铺的池子里检索出来的内容很容易“相关性有余、针对性不足”。我还试过把 claude-mem 强加到某些非编程场景比如写技术文档。结果发现它抽取逻辑里的“命令”“纠正”这些类型就不太适用留下来的大多只是泛泛的背景描述。这也说明它的记忆抽取不是通用 NLP 摘要而是面向开发场景的定向提炼用错了领域效果会打折扣。2. 安装与首次配置5 分钟让 claude-mem 跑起来2.1 两种安装方式按需选择claude-mem 的安装方式有两种我都试过简单分享一下取舍。第一种是自动安装器用 npx 直接拉起来npx claude-memlatest install这种方式的好处是省事。它会自动探测 Claude Code 的配置文件把 hooks 配置、可执行权限、初始化目录一次性搞定适合第一次接触、想快速看效果的人。不夸张地说装完就能用。第二种是手动安装适合你已经有自己的 hooks 配置、不想让它“擅自”改动的情况npm install -g claude-mem claude-mem init手动安装的好处是每一步都在你掌控之下全局装二进制文件然后执行init生成记忆库目录和默认配置之后 hooks 这一层你完全可以自己手写只挑自己需要的钩子加。代价是你得知道 hooks 配置写在哪儿、写什么格式这个下面我会展开。建议先用自动安装器验证可行性然后看它给你写了什么配置再决定要不要改成手动维护。对于工具类的配置我个人的原则是可以先让它自动搞但搞完之后你必须能看懂它搞了什么否则将来出问题排查会非常被动。另外提个前置条件claude-mem 是基于 Node.js 的本地得有 Node 环境。我用的项目本身跑在 Node 18所以没有额外折腾。如果你的项目是纯 Python 或 Go 环境记得装个 Node LTS光是让 claude-mem 跑起来用不了多少系统资源。2.2 关键一步配置 hooks 接入点如果你走手动路线最核心的文件是 Claude Code 的settings.json。它通常位于~/.claude/settings.json全局或项目根目录.claude/settings.json项目级。claude-mem 的 hooks 配置大意如下{ hooks: { PostToolUse: [ { matcher: Bash, hooks: [ { type: command, command: claude-mem record \$CLAUDE_PROJECT_DIR\ --from-stdin --reason \tool-use\ } ] } ], Stop: [ { hooks: [ { type: command, command: claude-mem record \$CLAUDE_PROJECT_DIR\ --from-stdin --reason \stop\ } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: claude-mem build --ttl 0 \$CLAUDE_PROJECT_DIR\ 2/dev/null || true } ] } ] } }逐个说下设计意图。PostToolUse监听的是 Bash 工具调用后的输出——AI 跑了一条命令产生了结果这个结果里往往藏着很多有价值的信息比如报错、成功提示、测试通过率所以这个钩子负责把输出喂给claude-mem record。Stop钩子是会话结束时触发的目的是把整段对话内容也记录一次毕竟很多决策是在对话中间产生的不能只靠工具输出覆盖。PreToolUse则是在每次 AI 准备执行 Bash 命令前触发调用claude-mem build把当前记忆打包注入保证它在做下一步操作之前能看一眼“过去的自己”。几个细节值得说。第一$CLAUDE_PROJECT_DIR是 Claude Code 提供的环境变量自动指向当前项目根目录务必保留这是 claude-mem 区分项目记忆的依据。第二record 命令里的--from-stdin表示从标准输入读取内容所以整个命令在 hooks 里是以管道形式工作的。第三build 命令后的2/dev/null || true是经验之谈——PreToolUse 阶段如果记忆构建失败不应该影响主任务执行静默失败是最安全的行为。还有个小坑要提醒macOS 用户要确保 claude-mem 命令在 Claude Code 的 PATH 里可见且 node 脚本有执行权限。我遇到过一次 hook 触发失败排查半天发现是 npm 全局 bin 目录没在 PATH 里shell 里能跑但 Claude Code 的 hook 环境里找不到命令。2.3 首次会话验证怎么确认记忆真的生效配置好之后不要急着开干先跑一遍验证流程。我会按下面这个清单走终端执行claude-mem doctor检查安装状态它会把配置文件、数据目录、可执行权限逐项列出来有问题会直接标红。这一步能筛掉 80% 的安装问题。随便在项目里让 Claude Code 跑一条简单的 Bash 命令比如ls -la然后立刻执行claude-mem view看有没有新的记忆条目生成。正常情况下你会看到一条记录内容是刚才那次工具执行的概况。新开一个会话让 Claude 执行同样的命令。接着在PreToolUse触发时理论上记忆简报已经注入上下文了。怎么验证最直接的办法是看 Claude 的回答里有没有体现它“记得”之前的事——比如你昨天设定过“测试用 Vitest”今天问它“跑测试”它直接用了 vitest 而不是 jest。我自己的经验是第 1 步基本必过第 2 步偶尔会因为 record 权限或路径问题失败第 3 步是最容易误判的因为 Claude Code 在同一会话内本来就有上下文能力你很难分清它是因为 claude-mem 的回放还是因为当前上下文还在。所以验证第 3 步的最好方式就是等一个比较长的间隔再测比如第二天早上新开会话直接问一个只有“长期记忆”才知道答案的问题比如“我昨天让你记住的那个目录命名规范是什么”。它能答出来说明回放链路真正通了。3. 记忆管理实战CLI 命令、配置项与避坑经验3.1 常用 CLI 命令速查每天都用得上的几条claude-mem 装上之后除了 hooks 自动调用它之外你完全可以把它的 CLI 当日常工具来用。我把常用的命令整理成了一张速查表命令作用典型使用场景claude-mem doctor体检安装状态首次装完或怀疑配置被改动时claude-mem record记录一段会话文本正常由 hooks 自动调用也可手动喂内容claude-mem build生成并注入记忆简报正常由 PreToolUse 调用也可手动预览claude-mem view列出当前项目已保存的记忆查看积攒了哪些记忆、有没有脏数据claude-mem search 关键词语义搜索记忆“我们之前为什么不用 Jest”这类问题claude-mem stats查看记忆条数、存储体积定期观察记忆增长情况claude-mem forget id删除指定记忆清理错误或过时的记忆条目我最常用的是search。你回想一下过去你查“当初为什么这么设计”是要翻 Git 提交记录或者去问写过这段代码的同事现在直接对记忆库做语义搜索就行而且是基于你自己项目的真实语境不是泛泛的百科解释。比如我敲claude-mem search 为什么不用 jest返回的结果就是当时那次会话里关于测试框架选型的讨论碎片比翻聊天记录高效太多。forget也是高频命令用途很明确记忆库也会积累垃圾。比如我有一阵子在给一个临时脚本写测试那种一次性需求产生的记忆对主项目完全无用甚至会在后续检索时干扰判断。发现之后直接用forget删掉毫不心疼。你不需要把所有记忆都当成宝贝保留那些对长期开发有指导价值的就好。3.2 配置项与隐私开关根据使用场景调整不同版本 claude-mem 的配置键可能略有差异但整体上你会遇到下面这些核心配置。我按自己本地版本的实际配置给你一份参考{ storage: { engine: sqlitechroma, path: ./.claude-mem }, capture: { preferences: true, commands: true, decisions: true }, injection: { maxMemories: 8, maxTokens: 1600 }, privacy: { excludePatterns: [password, api_key, secret, token] } }storage.path决定记忆库存哪里。我建议默认用项目本地目录.claude-mem/这样记忆跟仓库走换机器、换同事协作都自然但要注意别把包含敏感信息的记忆提交到公共仓库。如果你有 CI 环境要从头构建这个目录还得加进.gitignore避免把个人语境带到团队仓库里产生混乱。injection.maxMemories和injection.maxTokens是控制记忆注入预算的这两个参数特别关键。每次会话开始claude-mem 注入的记忆要占用上下文窗口的 token 配额。如果设置得太贪婪比如把 50 条记忆全部塞进去你会发现 Claude 的注意力被大量历史信息淹没反而忽略了你当前指令设置太少比如只给 2 条关键记忆可能被挤掉。我实测下来中型项目 8 条左右、控制在 1600 token 以内是一个比较均衡的值。预算这个东西没有标准答案你项目越复杂、上下文窗口越大这个值可以适当调高反过来简单小项目完全可以再调小。privacy.excludePatterns是敏感信息过滤。说实话claude-mem 记录的本来就是 AI 会话的输出里面出现 API key、数据库口令的概率不高但以防万一这类正则过滤建议打开。我见过有人的记忆库里存了测试环境的连接串虽然没泄露出去但看着总觉得不太踏实。能在源头挡住就别等事后再清理。3.3 如何提高记忆质量真正有用的几个习惯用 claude-mem 头两天我的感受是“什么都记不住”用了一周以后变成“记了一堆没用的”。这个变化很典型因为工具默认的抽取策略是保守的宁缺毋滥等到它积累了一定数据量噪音也会同步增加。所以记忆质量不是装完就能一劳永逸的它需要你用几个习惯去养。第一个习惯会话结束前主动总结。Claude Code 的 Stop 钩子会自动记录会话但自动记录是“照单全收”它的抽取逻辑虽然能过滤一部分但不如你在会话末尾主动说一句“总结一下本次会话里我做的关键决策”来得精准。AI 会在这条总结里把散落的决策点集中表达claude-mem 抽取时自然更容易命中高质量信息。说白了它是干提炼的而你有责任给它喂浓度更高的原矿。第二个习惯定期用 search 回查记忆。我安排了一个每周五的例行动作claude-mem search 项目规范看看这一周积攒的记忆里有没有过时或者错误的。尤其是那些“当时为了快速解决临时这么写的”决策一旦写进了长期记忆AI 在后续会话里就会把它当成既定规范反复引用误导性极强。发现问题直接 forget 掉。你甚至可以把这个当成每周代码评审的一部分成本很低但对后续 AI 协作质量的提升非常明显。第三个习惯区分“项目级记忆”和“全局级记忆”。claude-mem 支持按项目目录隔离记忆数据。如果很多项目共用一个全局记忆库那么 A 项目里关于 Java 的决策会在 B 项目比如一个 Python 项目里被检索出来那种违和感相当严重。我自己的策略是长期维护的项目用本地目录、独立记忆临时脚本和一次性实验干脆不启用记忆层或者用默认的全局目录但装完就跑不做精细维护。对于工具类的东西克制地使用比粗暴地全开要好。4. 常见问题与排查指南我踩过的那些坑4.1 记忆不生效或注入失败先查 hooks再查路径我碰到过最玄学的情况是“view 里能看到记忆但新会话里 Claude 就像失忆了一样”。排查顺序建议这样来现象排查顺序我遇到过的实际原因整体没记忆1.claude-mem doctor2. hooks 配置是否存在settings.json 写到了错误的作用域有记忆但没注入1. PreToolUse 是否触发 2. build 命令退出码2/dev/null掩盖了真实报错记忆串项目1.$CLAUDE_PROJECT_DIR是否传对 2. 存储路径是全局还是本地全局默认路径被多个项目共用record 执行失败1. 标准输入是否为空 2. hook 命令权限macOS 下 node 脚本执行权限受限第一次遇到记忆不注入时我傻乎乎地在settings.json里换了各种参数组合全都没用。后来才意识到我改的是项目级.claude/settings.json但 Claude Code 实际加载的是用户级~/.claude/settings.json两个文件的作用域和优先级不同。你如果同时维护多个项目这个很容易踩。先确认你改的文件是不是 Claude Code 真正读的那个。还有一次记忆注入内容大量缺失我把2/dev/null去掉手动跑了一遍 build 命令才发现是 SQLite 的 WAL 文件权限问题导致读取失败。这个经验也提醒我在排查阶段别急着加|| true和2/dev/null先让错误暴露出来等稳定了再静默。不要为了日志好看而牺牲可观测性。4.2 记忆污染与误注入如何给记忆做减法记忆污染是比“没记忆”更隐蔽的问题。它的症状是记忆确实生效了但 Claude 引用的记忆内容是错的、过时的或者跟当前项目八竿子打不着。比如我某次让 Claude 优化一个 Python 脚本的循环逻辑它突然仿照记忆里一个旧 Go 项目的 goroutine 模式来给我建议理由是“你之前说过并发用这个写法”。你说它有错吧它确实记得你说它对吧这完全是张冠李戴。这种问题的根源一是记忆库全局混用二是错误记忆没及时清理。我后来做了三件事。第一把不同项目的记忆库彻底分隔开——每个项目独立配置存储路径尽量不共享全局记忆。第二把injection.maxMemories调低逼迫 claude-mem 只注入最相关的记忆提高精度减少噪音。第三养成随手 forget 的习惯看到明显错误或者过时的记忆条目当场删掉绝不姑息。另外还有一个思路利用记忆的元数据做人工约束。比如记忆条目里带了会话创建时间你可以定期批量清理某个时间段之前的所有记忆给记忆库做一次“归档”。开发项目的技术栈半年就可能换代三年前的决策未必能用到现在适度断舍离是必要的。4.3 存储膨胀与隐私安全SQLite 会爆炸吗Token 够用吗有朋友问过我claude-mem 用 SQLite 存结构化记忆、用向量库做检索长期跑下去存储会不会爆炸这个我可以给个实测参考一个中型项目每天高强度使用 Claude Code 4~6 小时跑了两个月记忆条目大概一千多条存储体积在几 MB 到十几 MB 这个量级。SQLite 单文件对这种体量毫无压力ChromaDB 的向量索引也不大存储膨胀在正常使用强度下基本不用焦虑。真正需要关注的是上下文 Token 开销。每次PreToolUse注入记忆简报都会占用上下文窗口。如果你用长上下文模型比如 200k 上下文塞进去 1600 token 的记忆简报问题不大但如果你的应用场景上下文本身就很挤或者你经常在接近上限的长对话里工作就得小心了。我的调法是监控claude-mem stats看记忆总量配合injection.maxMemories和maxTokens做限制让记忆注入始终维持在一个“够用但不抢戏”的水平。至于隐私安全我的立场是不要在记忆库里放任何你不希望别人看到的东西。claude-mem 的本质是把私人开发语境持久化它本地存储、不上传这个没问题但如果你的项目里本身有敏感信息而你又开着全局抓取那段内容就可能被 AI 引用到后续会话里甚至出现在你提交的代码注释或文档中。用privacy.excludePatterns做关键词过滤只是兜底更靠谱的是你从源头上避免让 Claude 在会话中接触敏感凭据。这是我用这类工具时给自己定的铁律。最后聊点个人体会用 claude-mem 一个多月之后我最明显的感觉是Claude Code 不再像一个每次上岗都忘光培训内容的新人而更像一个能调用“自己经验库”的熟练工。它会自动沿用我早前定下的技术决策会在动手前主动检查是不是走了一条以前已经否定过的老路甚至在我无意识违反自己的规范时它还会提醒我一句。这种感觉很难量化但工作效率的提升是实打实的。如果让我给第一次上手的人一个建议那就是安装只花 5 分钟养成维护记忆的习惯才花功夫。别指望它装上就能完美运转把它当成一个需要你花点耐心调教的新人它会越来越懂你的项目。最后再分享一个小技巧每周用claude-mem stats看一眼记忆增长曲线再花几分钟claude-mem search抽查几条记忆条目。这个动作本身也是一个很好的项目回顾方式——你会发现过去一周自己哪些决策是真正重要的、哪些只是临时的应急处理。顺着记忆回忆一遍项目进展比翻 Git log 直观多了。祝你也早日拥有一套真正懂你项目历史的 AI 工作流。