1. 每次新会话都要重新"自我介绍"：Claude Code 的失忆症
聊 claude-mem 之前，先说一个让我头疼了很久的问题：Claude Code 每开一个新会话，就像喝了孟婆汤，完全不记得上一个会话里我们聊过什么项目背景、定过什么技术方案、改过什么代码约定。我在项目里反复解释"这个模块我们约定用函数式写法""数据库迁移文件放在 migrations 目录""测试跳过网络相关用例"，解释到我自己都快背下来了。
如果你也用 Claude Code 做过稍微大一点的项目，大概率也遇到过这种"前缀诅咒"——每次会话开头都要先灌一大段上下文，把项目结构、约束条件、历史决策重新讲一遍。讲得不够细，AI 就开始自由发挥；讲得太细，宝贵的上下文窗口全被占掉，真正要干的活反而没地方放了。这个问题不是模型能力不够，而是会话本身没有长期记忆的载体。
我当时试过官方的项目记忆文件机制，也就是 CLAUDE.md。它确实能存一些跨会话的项目说明，但它的定位更像"项目说明书"，需要我手动维护，而且只能覆盖静态约定。真正的动态记忆——比如"上个月我们决定把日志中间件从 morgan 换成自研的 trace 链路""前端小张说过这个接口的返回格式以后要改成 camelCase"——这类发生在对话过程中、事后就容易被遗忘的信息，CLAUDE.md 根本管不过来。我总不能每聊一句就手动更新一次说明书，这不现实。
所以当我看到 claude-mem 这个工具的时候，第一反应是"这不就是我需要的东西吗"。简单说，它挂在 Claude Code 的会话结束钩子上，自动把整个会话的对话内容喂给模型做提炼，把值得留存的决策、偏好、项目事实提取出来，写进一个结构化的记忆文件。下次会话一启动，这些记忆就能被自动加载，相当于给 Claude Code 装了一个"长期记忆皮层"。
这篇分享我会从工作机制、安装配置、记忆文件设计、踩坑记录几个角度展开，最后聊聊我怎么用它重构了自己的日常开发流。不管你是刚接触 Claude Code 的新手，还是已经在生产环境里重度使用 AI 编程工具的老手，这套思路应该都能给你一些参考。
1.1 为什么会失忆：原生记忆机制的边界
先理解 Claude Code 原生的记忆是怎么工作的。它在每个项目的根目录下认一个 CLAUDE.md 文件，启动会话的时候把这文件的内容塞进上下文里，相当于一份"项目守则"。你可以把线程数限制、代码风格、目录结构、部署命令都写进去。这个文件我前前后后维护过很多版本，也总结出两条硬经验：
- 它只适合放"静态事实"，不适合放"动态结论"。静态事实是：后端用 FastAPI、测试用 pytest、数据库迁移放在 alembic/versions。动态结论是：这次重构按 @wang 的建议只保留两个核心路由、生产环境回滚方案已改为直接切流量至旧集群。后者往往才是踩过的坑、做过的重要选择，反而最容易被漏掉。
- 你必须在干活之前手动更新它。人一忙起来就顾不上，等你想起来更新的时候，那个"重要决策"已经在对话历史里翻不到了。
Claude Code 其实还有一个用户级的全局记忆机制，放个人偏好，比如"永远不要把我还没确认的代码直接写入文件"。这个和 CLAUDE.md 一样，都是靠手动填充。也就是说，原生的记忆是一个"人肉维护的静态配置文件"体系，而不是"AI 自动沉淀的经验库"。
这带来的直接问题就是：凡是会话中临时产生的、有上下文依赖的重要信息，全凭缘分。你今天下午跟 Claude Code 讨论了三个小时的权限模型，最后敲定用 RBAC 方案、管理员角色独立建表。会话一关，换个新会话，它又开始给你推 ABAC。你当然可以怪它不懂事，但根因是，那段讨论没有被任何机制沉淀下来，它整个模型里没有这段"记忆"。
1.2 claude-mem 到底解决了什么具体问题
claude-mem 要填的，正是"动态记忆"这个空白。它提供的不是又一个手动维护的文件，而是一条自动的流水线：会话结束后自动复盘、提取要点、写入记忆文件、下次会话自动加载。
用我自己的日常来举例，过去我开一个新会话处理同一件事，至少要花五到十分钟"重新初始化 AI"：把项目背景讲一遍、把上次讨论的结论重申一遍、把代码规范和队友配置强调一遍。这套流程不但慢，而且容易漏，经常是我讲完一大段，它还是理解偏了。挂了 claude-mem 之后，新会话直接继承上次沉淀下来的记忆，我只要说"继续昨天的重构"，它就知道昨天聊到哪个文件、定了什么取舍、下一步做什么。这不是省几分钟的问题，整个工作流的连贯性都不一样了。
当然，我不是说 claude-mem 能完全替代 CLAUDE.md。它俩是互补关系：CLAUDE.md 负责"项目宪法"，claude-mem 负责"战地日记"。宪法是稳定框架，日记是鲜活经验。两者结合，Claude Code 才既懂规矩又懂人情。
2. claude-mem 的工作路径：从会话结束到记忆落盘
用 claude-mem 之前，先搞明白它在原理层面做了什么。理解了机制，后面配 hook、调参数、排问题的时候才不会瞎猜。
2.1 hook 是整个机制的发动机
Claude Code 本身提供了生命周期钩子（hooks），比如会话启动时有 PreToolUse、PostToolUse，会话结束时有 SessionEnd。claude-mem 最关键的一步，就是注册在 SessionEnd 这个钩子上。
会话结束时，Claude Code 会调用你注册的命令，把整个会话的对话记录传给 claude-mem。这相当于在 AI 下班回家之前，安排了一个"复盘专员"，把它今天做了什么、聊了什么、定了什么，全部记录在案。SessionEnd 钩子是同步执行的，也就是说，Claude Code 会等 hook 跑完才真正结束会话。所以如果 claude-mem 处理的时间太长，你是能感知到的，后面我会讲怎么避免超时。
这个设计最妙的地方在于，不需要改动 Claude Code 本身，不用装插件、不用打补丁，只需要在配置文件里声明一条 hook 命令。这也是我敢把它用在日常工作流里的原因，挂载方式足够轻量，卸载也就改一行配置的事。
2.2 对话内容如何被"提炼"成记忆
拿到对话记录之后，claude-mem 做的事情不是原样存盘，而是用模型把"流水账"变成"要点纪要"。我第一次看它生成的记忆文件时最直观的感受是：它真的很懂取舍。指令、方案讨论、踩坑记录，会被识别为高价值信息；"你好""帮我看看这个报错"这类过程性对话，会被过滤掉。
具体来说，提炼环节通常会做这几件事：
- 提取明确的决策句。比如"我们决定用 SQLite 暂代 PostgreSQL，等数据量上来再迁移"，这类带结论性的句子几乎都会进记忆。
- 提取项目结构相关的信息。比如"下个版本会把 monorepo 拆成三个独立包"，这种会影响后续操作的规划也会被记住。
- 记录用户偏好。我经常说"错误信息用中文输出""提交信息按 conventional commits 规范写"，这类偏好会被单独归类，成为个人画像的一部分。
- 去重。如果同一个决策在一段对话里反复出现，只会留一条。
这个阶段相当于"记忆编码"，它决定哪些短期工作记忆能转成长期记忆。和人类记忆一样，不是每件事都值得记住，claude-mem 的记忆筛选标准是：对未来的会话有没有复用价值。
2.3 记忆文件如何在下一次会话被读取
记忆落盘之后，下一次会话怎么用？这里有两种常见的接入方式，取决于你用的 claude-mem 版本和配置方式。
第一种是把记忆文件路径加入到 CLAUDE.md 的引用里，启动会话时模型自动读取。你需要维护一段内容，类似于在 CLAUDE.md 里写"项目历史与决策记录见 .claude-mem/memory.md"。这种方式最直接，Claude Code 自己能读，不需要额外的插件介入。
第二种是通过会话启动钩子，在每次新会话创建时把记忆内容注入上下文。也就是设置 PreToolUse 或会话启动时的 hook，让 claude-mem 把沉淀好的记忆动态塞给对话。这种方式的好处是记忆内容不需要手写索引，坏处是如果记忆文件太大，会挤占上下文窗口。我实际用下来，50 到 200 行的记忆文件，注入成本几乎可以忽略。
无论哪种方式，本质上都是"把历史经验变成新会话的输入"。Claude Code 本身是一个没有记忆的对话引擎，claude-mem 等于给它外挂了一个记忆检索器，通过文件系统把跨会话的信息持久化下来，再用上下文注入的方式让模型"想起来"。
3. 安装配置与首次运行实测：我的具体接入步骤
聊完原理，说说动手。以下步骤是我在自己机器上的实际操作过程，不同版本的 claude-mem 命令和参数可能会稍有差异，我会把关键配置项讲清楚，你按自己安装的版本做适配即可。
3.1 安装与版本要求
claude-mem 的安装本身不复杂，一般依赖 Node.js 运行时和 Claude CLI。如果你的机器上已经能正常使用 Claude Code，环境基本就满足要求了。安装时先确认 Node 版本不要太旧，我用的版本是 18，更老的版本有兼容风险。
安装完成后先跑一遍版本命令，确认 claude-mem 本体可用。这一步别跳过，后面配置 hook 出问题的时候，你至少能判断是 hook 没触发，还是 claude-mem 本身坏了。
3.2 settings.json 里的 hook 注册
Claude Code 的配置入口是 settings.json，路径分两级：
- 用户级配置，在用户主目录下的 .claude 目录里；
- 项目级配置，在项目根目录的 .claude 目录里。
claude-mem 的 hook 建议注册在项目级配置里，因为记忆通常是跟着项目走的。如果你想给所有项目统一启用全局记忆，也可以放用户级配置，但我更推荐先用项目级实验，跑通了再决定要不要全局开。
配置的核心是往 settings.json 的 hooks 字段里加一个 SessionEnd 事件，命令指向 claude-mem 的某个子命令，把会话信息作为参数传入。具体命令格式长什么样，建议直接看项目仓库的 README，因为不同版本改过好几次。关键点有两个：
- SessionEnd 钩子触发时要能拿到对话记录的访问方式，否则 claude-mem 没有输入源；
- hook 命令要能正确识别当前项目路径，避免把 A 项目的记忆写进 B 项目。
我自己的习惯是先配好文件路径的映射，也就是明确记忆文件放在哪个目录、命名规则是什么。这个后面章节会细讲。
3.3 第一次实测：对话、结束、重启、验证
配置完成后，验证流程我建议严格按这个顺序走：
- 开一个新会话，在项目根目录下随便聊点有实际内容的话题。比如让 Claude Code 分析当前代码库的模块结构，并在对话中明确说一个偏好："以后所有新模块的入口文件必须命名为 index.ts"。
- 正常结束会话，留意终端是否有 hook 执行的迹象，通常会有短暂延迟或输出。
- 去记忆文件里检查，"必须命名为 index.ts"这条偏好有没有被提取并归类。
- 开一个新会话，直接问"这个项目的入口文件命名有什么约定"。如果 claude-mem 生效，它应该能答上来，即使你这次什么都没有提。
我第一次实测时，前面两次都失败了。检查下来分别是 hook 命令路径写错、以及记忆文件的目录没有提前创建。这两类问题都比较好定位，终端会报命令找不到或者目录不存在的错误。后面踩坑章节我会展开讲更隐蔽的情况。
这个验证流程我没法给你一个放之四海而皆准的"成功输出模板"，因为 claude-mem 生成的记忆内容取决于对话质量和模型提炼策略。但有一条标准是稳定的：新会话里，它记得住你没说过的约定。记住这一条就够了。
4. 记忆文件设计：分类、去重与防膨胀
claude-mem 是会积累的。跑一个月之后，记忆文件可能从几十行膨胀到几百上千行。如果不做设计，它最终会变成一个冗长的杂物堆，反而拖累每次会话的上下文效率。这一节分享我踩过并用到现在的一套文件组织方式。
4.1 我采用的记忆文件结构
我不建议把所有记忆塞进一个文件，即使 claude-mem 默认只写一个文件，我也会在配置里把它拆开。目前我项目里用的是这样的目录布局：
- .claude-mem/decisions.md：存项目关键决策和取舍，每条记录带日期。
- .claude-mem/preferences.md：存用户编码偏好和协作习惯。
- .claude-mem/facts.md：存项目的客观事实，比如技术栈、目录说明、部署要点。
- .claude-mem/gotchas.md：存踩过的坑和对应的规避方案。
这个结构的好处是可以控制注入粒度。如果某次会话只是写业务逻辑，我只需要加载 facts 和 decisions；如果涉及代码风格调整，再加载 preferences。不过要注意，文件拆得太碎，钩子配置和加载规则也会跟着变复杂，小项目没必要一上来就拆五个文件。我的经验是：项目记忆超过两百行时再动手拆分。
4.2 什么样的信息值得写入记忆
claude-mem 会自动提炼，但自动提炼不等于什么都记。我自己总结了一个"记忆三问"：
- 这条信息对未来会话有复用价值吗？临时性的报错排查过程，通常不提；
- 它是稳定事实还是临时状态？"当前正在重构 payment 模块"是临时状态，记忆价值低；"payment 模块计划拆成单独服务"是稳定规划，值得记；
- 如果下个会话不知道这条信息，会做错事吗？这是最高标准，会做错事的必须记。
用这个标准回头去看 claude-mem 生成的记忆，你会发现它偶尔会提取一些"热闹但不重要"的东西。比如它可能会把"用户说这个按钮颜色太丑"记成一条偏好，但这条信息对未来会话几乎无用。这种时候我一般直接删掉，并且逐步用更精确的提示词约束提炼方向。
4.3 记忆文件膨胀了怎么办
记忆文件不控制，三个月就会变成一本流水账。我的处理手段有三层：
第一层，定期人工修剪。每周花十分钟过一遍新追加的内容，删掉已经失效的信息。比如"我们正在评估框架 A 和框架 B"，等选型结束只剩框架 A，这条讨论记录就没用了。
第二层，利用 claude-mem 的去重能力。同一句话在多个会话里反复被说，让模型生成记忆时只保留最早最完整的一条。这依赖提炼模型的能力，也依赖记忆查询时做的相似度判断。
第三层，超过一定规模就归档。把 200 行以内的近期事实放在主文件里，历史完整记录移到 .claude-mem/archive/ 下面，启动会话时不加载归档内容。这样既保留了完整痕迹，又不影响日常上下文的干净程度。
记忆文件的质量，决定了 claude-mem 是帮手还是拖累。我的体感是，保持文件在 100 行左右时，稳定性和注入成本最平衡。
5. 踩坑记录：hook 不触发、重复写入、敏感信息泄漏
所有自动化工具都有"看起来很美，配起来想哭"的阶段。claude-mem 最大的坑集中在这三个方向：hook 不触发、记忆重复写入、敏感信息进了记忆文件。逐个讲我排查的链路。
5.1 hook 不触发的完整排查链路
最常见的现象是：会话都结束大半天了，记忆文件里啥也没有。别急着怀疑工具坏了，按这个顺序查：
- 先查 settings.json 的格式。手写 JSON 很容易漏逗号或多括号，Claude Code 静默忽略非法配置是常有的事。用 JSON 校验工具过一遍。
- 确认 hook 作用域。项目级配置只在对应项目目录下生效，如果那个项目根本没有 .claude 目录，你配到用户级或者配错路径，就不会触发。检查当前会话加载的是哪个配置文件，可以在 Claude Code 里用状态命令查看。
- 确认 SessionEnd 事件名称没写错。Claude Code 的 hook 事件名区分大小写，SessinEnd、SessionEnd 这类拼写差异会无声失败。
- 手动执行一遍 hook 里的命令，看 claude-mem 有没有报错。很多时候不是 hook 没触发，而是触发了之后命令崩溃了。比如路径不对、环境变量没传、对话记录文件读不到。
一套查下来，九成问题都能定位。我唯一一次排查很久的情况，是当时开了多个 Claude Code 进程，hook 挂载的进程和实际会话进程不一致，导致看起来"没触发"。重启终端和 Claude Code 之后解决。
5.2 同一信息被反复写入的根因
第二个高频问题是重复写入。同一条决策，三四个会话之后出现在记忆文件里三四遍，又占空间又显得蠢。
我仔细对比过重复内容的上下文，发现根因通常不在 claude-mem 本身，而在于"提取得不够晚"。比如某个决定从讨论、到确认、到最终实施，横跨了三个会话。每个会话结束时的复盘都可能把"当前讨论结论"当成"最终决策"提取一次。这其实是正常的，因为三个会话里它确实都是一条有效信息。
我的解决方式是给记忆文件加上"最终态覆盖"的约定。在 claude-mem 提炼之后，再做一道后处理检查：如果新提取的条目和已有条目指向同一个主题，标记为"更新"而不是新增，保留时间戳最新的一条。你也可以在提示词层面约定，让 claude-mem 在写入前主动做语义去重，但完全靠模型判断会有漏网之鱼，后处理脚本更可靠。
5.3 敏感信息过滤与隐私边界
这点我必须单独强调：claude-mem 会把会话内容交给模型做提炼，涉及密钥、内网地址、客户敏感数据的对话，要格外谨慎。
claude-mem 一般会提供敏感信息过滤的配置，比如敏感词列表、正则表达式，命中后直接打码或跳过。我的配置里会预置几类规则：
- 私钥和 token：类似
sk-、ghp_、AKIA开头的字符串； - IP 和域名：内网 IP 段、内部服务域名；
- 姓名与工号：团队成员的姓名组合模式。
但这些规则只能挡常规的，真正管用的是使用习惯。涉及生产环境机密时，我根本不会和 Claude Code 展开聊太多细节，尤其是 key 和密码这类绝对敏感的东西。我宁可让记忆里少一条"技术事实"，也不愿意让敏感信息落到任何日志或记忆文件里。
这类问题没有一劳永逸的方案，只能靠配置规则加使用纪律双重兜底。如果你是团队里推进 claude-mem 的人，建议先在本地跑一两个星期，把过滤规则调到位再推广。
6. 把记忆变成团队资产
claude-mem 在单机单项目上跑通后，我很快开始想一个问题：一个人有了记忆，团队能不能共享记忆？毕竟 Claude Code 很多时候不是我一个人在用，队友也会开会话，大家读同一个代码库，但各自的记忆各自攒，等于每次交接都要重新解释一遍。
6.1 多项目隔离与共享的平衡
最简单的做法，是把 claude-mem 的记忆文件提交到 Git 仓库里，让它跟代码一起走。这样每个克隆项目的人都能享受之前沉淀的记忆。前提是记忆文件里不含敏感信息，这也是我在上一节强调隐私过滤的另一个原因。
但直接提交也有一点麻烦：多人使用同一个记忆文件，内容会相互覆盖或冲突。"我删掉的一条过时决策，队友的会话又把它写回来了"，这类冲突很常见。我的处理方法是，把记忆文件分成"公共层"和"个人层"：
- 公共层放项目事实和稳定决策，随仓库走，人人可读，较少改动；
- 个人层放个人偏好和操作习惯，留在本地，不提交，比如"我习惯错误信息输出中文"这种。
这样既保留了团队共识，又允许每个人的 AI 助手有各自的脾气。
6.2 整理记忆的节奏
记忆文件是需要整理的，不是写了就完事。我和团队现在约定了一个节奏：每个迭代结束时，花 10 到 20 分钟清理记忆文件。清理的核心动作就三个：删掉失效决策、合并重复条目、把值得长期留存的决策标记成"重要"。
这个整理过程和写周报有点像，但比周报务实得多。因为它的直接收益是下一个迭代的 AI 协作效率。你会发现，记忆文件越干净，新会话里 AI 的"进入状态"速度越快。
6.3 我现在的日常工作流
跑顺之后，我日常的开发流已经和 claude-mem 深度绑定了。大致是这样：
早上到工位，打开项目终端，开一个新的 Claude Code 会话，先不急着说需求，问一句"基于现有记忆，我们今天最应该推进什么事情"。它会按记忆文件里的规划给出建议，有时候比我自己的判断还准。接着我让它继续昨天没完成的重构，它会直接打开对应文件，不需要我再翻聊天记录。
遇到突发问题，比如某个接口报错，我会在排查过程中让它记录完整的分析链路。问题解决后，把最终结论沉淀成 gotchas 条目。下次再有人遇到同样的报错，新会话直接就能给出修复方案。
这套流程最大的变化，是我不再担心"这个决策过了三天就忘了"。"忘了"的成本已经被 claude-mem 降到了很低。该记得的它会一直记着，该忘的我会定期清掉。
如果你也想搭一套类似的流程，我的建议是从小处开始：先只在一个项目里跑通 claude-mem，只记录 decisions 和 gotchas，跑两周，感受一下会话连贯性带来的变化。等确实适应了，再逐步扩展到偏好、事实、团队共享。工具本身不复杂，真正需要花心思的是你愿不愿意建立"记忆整理"这个习惯。有习惯，AI 才是越用越懂你的老搭档；没习惯，再好的工具也只是个自动写备注的脚本。
