用 Claude Code 连续做了快一个月的长线项目之后我对它最大的意见不是能力而是“记忆断片”。每天一开新会话它对我昨天做了什么一无所知我得把项目背景、当前进度、关键决定重新粘贴一遍有时候还要翻聊天记录去捞一个函数名。CLAUDE.md 这种静态方案我也试过但它只适合放固定规则根本装不下“我们当时为什么这么选”的动态结论。claude-mem 就是在这一步冒出来的。它是一套面向 Claude Code 的持久记忆工具原理不复杂在会话结束的时候扫描历史把技术选型、用户偏好、踩坑结论这类关键信息抽取出来存成本地结构化文件下一次会话开始时再把相关记忆自动注入上下文。用下来的体感最接近一句话——我终于不需要每次都做自我介绍了。这篇文章不打算写官方文档式的工具说明。我把自己从安装、配置到用了三周的真实过程、原理推测、踩坑细节都整理出来给同样在长线项目里用 Claude Code 的朋友一个参考。无论你是刚听说它还是已经装了但没用好应该都能从这里拿到一些能落地的操作思路。1. Claude Code 的会话记忆困境为什么长线项目总是需要重新自我介绍1.1 会话隔离是特性也是长线作战的短板Claude Code 的每次会话都是一个独立的上下文窗口。它在单个会话里非常“能记住”你随手丢给它的一段报错、一个函数签名它都能贯穿整个对话使用但一旦关掉窗口、开新会话之前聊过的内容就像没发生过一样。这种设计本身有道理。上下文窗口有长度上限如果每次会话都背着全部历史跑不了一两天就会膨胀到无法处理。可对于长线项目来说这就是个实实在在的痛点。举个我自己的例子某天下午我花了两个多小时定位一个诡异的缓存失效问题结论是某个服务里Cache-Control头写死了no-store处理逻辑和绕过方式全都聊明白了。第二天早上新开会话想继续优化性能它连这个结论的影子都没有我又从看日志开始复现了一遍排查过程。这种感觉很像每次开会都换一个没参加过前几次会议的新同事。新同事能力强但完全不知道团队已经讨论过什么、排除了哪些方案。你不能说他不行你只能说协作成本太高。1.2 CLAUDE.md 只是静态备忘录撑不起动态决策很多人第一个想到的替代方案就是 CLAUDE.md。Claude Code 原生支持这个文件每次会话开始时模型都会读取它相当于一份项目级提示词。我也会用而且现在还在用但它解决的是“稳定的规则”不是“动态的结论”。拿我的项目举例CLAUDE.md 里适合写这些项目使用 pnpm workspace、目录结构长什么样、代码风格规范、禁止直接改src/core下的文件。这些内容写一次能管几周手工维护成本低。但像“权限模块决定采用 RBAC ABAC 的混合模型引擎选 Casbin理由是后续要支持数据级权限”这类决策你要么记得改文件要么它就一直不在。问题在于真到了高强度开发的时候人不会记得去更新备忘录。讨论是在会话里发生的决策也是在会话里形成的CLAUDE.md 不会自己更新。时间一长要么这份文件变成又臭又长的流水账读它本身就吞掉大量 token要么它逐渐过时反而给模型喂了错误信息。1.3 claude-mem 到底补上了什么claude-mem 补的不是简单的“聊天记录保存”而是一整套记忆生命周期生成、筛选、持久化、检索、遗忘。生成靠 Hook 自动扫描会话把散落在对话里的结论抽出来筛选靠类型和重要度分级把“临时闲聊”和“最终决定”分开持久化靠本地 JSON 文件按时间分片存下来检索靠会话开始时的摘要注入和对话过程中的按需调取遗忘靠prune清理和forget手动删除。后面几章我会逐一拆解这些环节。你只要先记住一个判断claude-mem 的价值不在于“存了多少”而在于“该记住的记住了该忘的也能忘掉”。2. claude-mem 的工作原理从扫描会话日志到注入结构化记忆2.1 记忆是怎么被捕获的先说触发时机。安装 claude-mem 之后它会往 Claude Code 的配置文件里写入两组 Hook一组在会话结束时触发另一组在会话开始时触发。会话结束的 Hook 做的是扫描与抽取。它会读取本次会话的完整 transcript让模型识别里面的关键信息——比如哪些是技术选型、哪些是你明确表达的偏好、哪些是排查出来的根因、哪些只是随口一提的点子。然后把这些信息提炼成结构化条目追加到本地记忆库。我最初以为它会像数据库一样记录全文后来翻了记忆文件才发现它默认保存的是“提炼结果”而不是原文。比如会话里聊了二十行关于为什么弃用 webpack、转向 Vite 的讨论最后记忆库里只会留下类似“前端构建工具从 webpack 切换为 Vite冷启动速度提升明显”这样一条结论。这个设计很关键它同时解决了两个问题一是节省存储空间和后续注入的 token二是避免把大量无关的聊天噪音也留在库里面。2.2 记忆最终长什么样我手上的版本记忆条目默认存在用户目录下的~/.claude-mem/memories/文件夹里每个条目是一个 JSON 文件长这样{ id: mem_20250115_decision_001, type: decision, importance: crucial, timestamp: 2025-01-15T10:23:00Z, content: 前端构建工具从 webpack 切换为 Vite原因是冷启动速度提升约 4 倍, context: 构建速度优化讨论, tags: [前端, 构建, Vite] }结构化 JSON 带来的直接好处是“可检索、可筛选、可清理”。你可以按type只查决策按importance只取重要结论甚至写个小脚本把近一周的决策全部导出来。如果它只存纯文本 Markdown想做这些操作就得用字符串匹配很快会乱。文件不是越攒越大而是按时间段分片存储避免单文件无限膨胀。我本地跑了两周多memories 目录下大概也就几十个文件单个文件体积很小整体占用可以忽略不计。需要说明的是不同版本的存储目录和字段命名可能有差异但总体思路是一致的。2.3 记忆怎么回到新会话里这部分是 claude-mem 的核心设计。如果新会话一开始就把记忆库里所有条目一股脑塞进上下文几千条记忆直接就能把一个上下文窗口撑爆。所以它的注入是分两步走的。第一步在 SessionStart 时注入一段“摘要”告诉你上次做到哪里、有哪些关键决定。这段摘要很紧凑可能只有几百个 token作用是让你和模型都能快速进入状态。第二步是在会话进行中按需检索。当你的问题涉及某个主题时它会根据当前输入里的关键词、标签从记忆库里挑出最相关的几条注入进去。这个检索策略不需要多么智能的向量数据库基于本地文件的索引就够了。我在实际使用中感知到的注入时机基本就是我提到某个旧项目或者某个老函数名的那一瞬间它会把对应该主题的历史决策带进来。会话过程中你还可以手动用斜杠命令干预注入行为。我常用的有mem:info注入紧凑摘要和mem:auto按当前问题自动检索相关记忆不同版本的默认命令名可能有差异但思路就是对注入内容做人工确认。毕竟自动筛选再准也比不过你自己清楚现在最需要哪条背景。3. 安装与初始化全流程从 npm 到 Hook 落地的记录3.1 环境要求和安装命令安装 claude-mem 的前提是你本机已经装好了 Claude Code并且版本不要太旧。我自己用的环境是 Node.js 版本比较新的长期支持版Claude Code 通过 npm 全局安装。在这个基础上再装 claude-mem 就很简单npm install -g dmnemonic/claude-mem claude-mem --version装完之后需要执行一次初始化让工具自己把 Hook 写进 Claude Code 的配置claude-mem install这一步做完可以打开 Claude Code 的配置文件检查。我手上这个版本安装后自动添加了SessionStart和SessionEnd两组 Hook核心命令分别是 claude-mem 的 session-start 和 session-end。如果之前手动改过 Claude Code 配置install 过程大概率不会动到你原来的其他设置但保险起见我还是建议先备份一下配置再执行。3.2 验证安装是否真正生效装完之后别急着直接开干先做一轮五分钟的验证。我的做法是这样的先跑一个普通会话在里面明确说一句“记住这个项目的配置文件入口是config/entry.ts”然后正常结束会话。接着去~/.claude-mem/memories/目录看一眼正常情况下会出现一个包含刚才那条信息的 JSON 文件。然后新开一个会话输入mem:info看它输出的摘要里是否包含“配置文件入口在 config/entry.ts”这条记忆。如果能看到说明写入和注入两个方向都通了。如果文件没生成第一反应先看 Hook 是否真的写进去了。有些版本在 npm 升级之后会把配置里的 Hook 覆盖掉重新执行一次claude-mem install就能解决。我把这种情况记成了第一个需要注意的点。3.3 目录结构与权限注意默认数据目录是~/.claude-mem/里面大致分几个区域memories存记忆条目、session_logs存会话处理日志、config存工具自身的配置。这里有个容易翻车的细节尽量别用其他脚本或者编辑器批量乱改这个目录里的文件。我有一次想自己写个脚本给历史记忆批量打标签直接改了 JSON 的字段名结果 claude-mem 在读取时跳过了所有修改过的文件等于这批记忆暂时失效了。后来才反应过来它对条目里的必填字段有校验改坏了宁可删掉该文件让它重新生成也不要强行保留。3.4 升级、卸载和重置升级直接走 npmnpm update -g dmnemonic/claude-mem升级后记得重新执行一次claude-mem install因为新版可能调整 Hook 命令参数。卸载则相反claude-mem uninstall它会尝试恢复 Claude Code 的原生配置。我的建议是如果只是临时不想要记忆功能先把 Hook 停掉即可不必一整条命令卸载干净因为重装再初始化也有一点成本。4. 记忆的类型与重要度让工具分清楚该记住什么、该忘记什么4.1 六类记忆背后的逻辑claude-mem 会把抽取出来的信息分门别类。我手上版本里常见的分类有这些我建议你拿到工具后先对着一份记忆库看一眼理解每个分类的用途比背诵分类名更重要类型含义例子decision技术选型、方案取舍“权限模型采用 RBAC ABAC 混合”preference你的偏好、习惯“代码注释用中文不做强制风格校验”fact代码库的客观事实“网关服务的主入口是gateway/main.go”issue踩坑记录、根因结论“缓存失效是因为响应头写死了 no-store”progress项目进度摘要“权限模块已完成引擎接入待补充数据级策略”uncategorized暂时无法归类的信息跨领域的零散备忘分类看起来只是元数据但它真实影响使用体验。因为在会话开始注入摘要时工具可以按类型决定优先级——decision和preference几乎每次都会出现而issue只在讨论到相关主题时才被检索出来。如果所有信息都混成一大类模型就分不清哪条是必须遵守的结论哪条只是顺手记录的背景。4.2 重要度分级crucial、standard、details、noisy除了类型每条记忆还有一个重要度字段。默认大致是四个档位crucial关键决定几乎必须注入、standard普通背景、details细节信息按需取用、noisy噪音默认不注入。这套分级的价值要放到“Token 预算”这个背景下看。claude-mem 的注入不是无限度的如果记忆库里存了上千条一股脑全给模型看光背景阅读就能吃掉大量上下文。有了重要度字段它可以在预算不足时先保crucial再考虑standarddetails和noisy直接靠后站。我自己的经验是不要把所有看着有用的信息都标成crucial。重要度拉满之后模型在新会话里每次都会读到这条过于频繁反而让它分不清主次甚至把一次性的临时方案当成持续约定。真正值得crucial的通常是那种“反直觉”或者“绕了很多弯路才确认下来”的结论。4.3 用 remember 和 forget 主动干预自动抽取不是百分百准确它可能会漏掉一句很重要的口头结论也可能会把一句临时的调侃当成偏好记下来。所以我非常依赖主动写入和主动删除这两个操作。remember的作用是直接把当前讨论的关键结论写进记忆库不依赖会话结束时的自动抽取。我现在几乎形成了肌肉记忆每次讨论出一个最终方案、一个根因结论我都会在会话里直接追加一句rememberxxx确保它立即生效。从结果看主动写入的条目比自动抽取的条目质量高得多因为经过我自己一遍筛选。forget则负责删掉那些已经被证明是错误或者过时的记忆。比如某天我们讨论过“要不要用 Redis 做消息队列”结论是否定的但自动抽取可能把它记成一条候选决策。这时候直接forget掉比留着它让模型每次纠结要好得多。4.4 查询已经记住的内容最后是核验。记忆库不是黑盒它允许你用命令直接查询。类似mem:query 权限模型这样按关键词检索工具会把命中的条目列出来你一眼就能看出哪些是垃圾、哪些确实有用。我建议每周做一次“记忆盘点”。打开终端把关键词粗略扫一遍重点看有没有已经过时的决策、有没有互相冲突的条目。这个动作耗不了几分钟但它能防止记忆库像垃圾堆一样累积最终侵蚀新会话的判断力。5. 实测三周后的真实变化跨会话上下文连续性提升了多少5.1 测试场景一个两周的权限模块重构为了验证它到底有多大用我专门挑了一个跨时较长、依赖大量历史决策的任务来测——权限模块重构。这个模块涉及 RBAC 角色、数据级 ABAC 策略、网关鉴权、前端路由守卫决策点多、信息链条长特别适合用来检验记忆持久化。第一周我在会话里讨论了整体架构确认了“RBAC ABAC 混合模型”和“选用 Casbin 作为引擎”两个关键决策。这两个结论当时只存在于会话里。装好 claude-mem 之后它们被自动抽取进记忆库并标记为decisioncrucial。到了第三天我新开了一个会话想继续推进数据级策略的设计。我故意没粘贴任何背景只是输入了一句“继续上次权限模块的事”。结果它直接给出了上次讨论的模型结论、为什么选 Casbin、当前卡在哪一步。那一刻我确实有点意外因为这种感觉非常接近一个跟了很久项目的人对你说“我记得我们之前聊到这儿了”。5.2 从对比里看到的提升如果量化一下变化之前每开一个新会话我需要用大约 800 到 1000 字去介绍背景、当前进度、遗留问题现在这个数字基本降到了 50 字以内——一句话说明继续哪个任务即可。省下来的时间不只是几分钟更重要的是思路不用反复切换不会在“重新描述需求”的过程中丢掉上下文里的细节。还有一个容易被忽略的提升记忆注入会影响模型提问的质量。它知道自己“知道”哪部分背景就不会反复问已经讨论过的问题而是直接往下一步推理。这种感觉有点像带新人预先把以往会议纪要给他看他会少问很多基础问题讨论密度一下子就上去了。5.3 两个需要警觉的副作用好用归好用但我也注意到两个副作用。第一个是记忆注入会改变模型的表达密度。记忆多了以后它在回答问题时引用历史结论的次数明显增加这在决策类问题上是好事但如果你只是想快速验证一个小点子它反而会先拉一堆背景铺垫显得啰嗦。我的解法是用mem:info替代自动全量注入先拿到紧凑摘要再按需展开。第二个是旧记忆会像“锚”一样影响新判断。如果记忆库里有一条已经被推翻的旧结论而你没及时删掉新会话中它可能和最新结论同时出现导致模型在两条记忆之间摇摆。这让我更坚定了每周清理一次记忆库的习惯。6. 踩坑与调优误判、重复和 Token 开销怎么处理6.1 会话里的“假决策”也会入库自动抽取最容易产生的问题是把讨论过程中随口冒出、还没有被采纳的方案误判成“决策”。我有一次在会上聊了三四种权限模型的候选其中“顺便说一句其实也可以用 OPA 试试”这种话被记成了一条decision。结果后面两天的会话里模型总是莫名其妙提到 OPA而实际上我们根本没有选择它只是讨论了一下。这种情况的解法分两步。第一在会话末尾主动收个尾明确说清“最终结论是什么、哪个方案只是候选”第二定期用查询命令把可疑条目找出来该降重要度的降重要度该删的删。自动抽取只能做“尽力推断”真正决定记忆质量的还是使用者愿不愿意花一分钟做确认。6.2 重复条目同一个主题被反复记录另一个常见问题是重复。同一个主题如果在多个会话里被反复讨论比如性能优化、依赖升级自动抽取可能会在每次会话后都追加一条相似内容的记忆。两周下来“考虑使用 pnpm workspace 管理 monorepo”这种话我能看到好几条虽然不算致命错误但确实会让检索结果变模糊。我的处理方式是定期做一次合并。因为 JSON 文件是结构化且可编辑的我写了一个很短的脚本按tags字段把同主题条目合并保留时间最近的、内容最完整的一条其余归档。如果你不擅长写脚本也可以直接用文本编辑器打开记忆文件手动合并数量不多时手动反而更快。6.3 Token 开销永远不能忽视记忆注入不是免费的它占用的是上下文窗口。我粗略估算过一条标准记忆折合几十到一百多个 token如果工具默认注入 5 条左右会话开始时的额外开销在 500 token 以内这个量级完全可以接受。但如果你在长会话中反复触发mem:full让工具把整个记忆库都塞进去那 token 消耗就不可控了。我第一次用的时候因为好奇打开full模式结果上下文窗口迅速被填满后面讨论问题都没空间了。我的建议是日常用auto或info并把注入数量上限控制在一个较小的值。这类参数通常在 claude-mem 的配置文件里能找到比如max_memories、注入重要度阈值等按自己项目的上下文需求调整即可。6.4 隐私与团队安全的边界记忆文件会记录项目里真实的路径名、模块名、变量名甚至你在会话里提到的内部系统代号。如果这个项目是个人项目还好说但放到团队协作里就需要注意边界。我现在的做法是个人项目随便用团队项目只在本地启用记忆库绝不让~/.claude-mem出现在公开仓库里如果非要团队共享记忆内容也先导成脱敏后的 Markdown 摘要再分发。CI 环境我不会安装这类工具因为流水线里的会话通常是一次性的留下持久记忆没有意义反而可能产生足迹安全风险。7. 进阶玩法手动修记忆库、团队共享与决策审计7.1 手动编辑记忆文件从“翻车”到“修正”记忆条目虽然是自动生成的但它本质就是普通 JSON 文件手动编辑完全可行。我试过一次手动修改context字段把一条原本模糊的“构建工具讨论”改成“对比 webpack 和 Vite 之后做切换”结果后续检索的命中率明显提升——因为关键词更具体了更容易碰上新会话里的输入。手动改文件有个前提改完需要重启会话让注入逻辑重新加载。改坏了也不用太紧张删掉那条文件让 claude-mem 下次重新抽取即可。但要注意别把字段名改得面目全非前面说过校验失败的文件会被直接跳过。7.2 把记忆库变成团队共享的检索源团队场景下最稳妥的做法是把记忆库放进一个独立的仓库作为“只读检索源”。每个人本地生成自己的短期记忆同时定期拉取团队共享记忆库里的长期结论。这样可以避免多人同时写入同一个文件引发的冲突问题。更轻的替代方案是——每周导出一份 Markdown 格式的决策摘要发到团队文档里。claude-mem 的结构化条目很容易转成这种摘要你只需要把近一周的decision和preference抽出来按时间排序即可。这个方案虽然没有自动化那么优雅但胜在不会引入新的协作复杂度。7.3 记忆库也是项目的决策日志用了一两周之后我才意识到记忆库其实是一份被自动维护的“项目决策日志”。把条目的timestamp按时间排序整个项目从开始到现在做过哪些选择、踩过哪些坑、拒绝过哪些方案全部一目了然。这个价值在做月度复盘或者项目交接时特别明显比翻聊天记录高效太多。我现在每周五会做一件事把本周自动积累的记忆条目快速扫一遍挑出几条最有代表性的直接作为周报素材。以前我写周报总要回忆半天现在相当于每天都有助手在帮我记笔记。7.4 后续还可以怎么扩展我下一步打算做的事是把记忆库的tags统一成一套固定词表从“前端、构建、Vite”这种自由词改成项目内部约定好的模块名和主题名。这样后续不管是用脚本统计还是导出文档一致性都会好很多检索命中率也能再提一档。我用了一段时候后的感受是claude-mem 真正解决的问题不是“给模型加记忆”而是“让基于 Claude Code 的长期项目协作变得可持续”。自动抽取补上了 CLAUDE.md 的时效性问题主动写入把人的判断力加进记忆筛选流程而结构化存储让记忆库本身变成可以被检查和维护的工程资产。对于一个已经开始依赖 AI 编程助手的开发者来说这种感觉踏实得多了。