1. 先说说我为什么给 Claude Code 配了个记忆外挂如果你也重度依赖 Claude Code 写代码、改脚本、维护项目一定有这种感觉每次开新会话它都像失忆了一样。你在上个会话里交代过的背景、偏好的命令、项目目录结构、代码规范统统要重新说一遍。我一度以为是自己的提示词写得不够好直到试了试 claude-mem才发现问题不在我而在于 Claude Code 本身就没有跨会话长期记忆的能力。claude-mem 是个命令行小工具专门给 Claude Code 补上这块短板。它的思路不是记住你说了什么而是观察你实际怎么操作然后自动总结成一份份 Markdown 记忆文件存进一个叫memp.d的目录。下次 Claude Code 启动时通过CLAUDE.md里的memp.d导入这些记忆它就像突然想起了你所有的习惯连你习惯用 pnpm 而不是 npm、喜欢把测试文件放在tests/还是__tests__/这种事都门儿清。我花了两周时间把 claude-mem 完整接到日常开发流程里期间也踩了不少坑。这篇文章不打算讲太多官方 README 里已经有的东西而是把它的工作方式、完整落地步骤、我在真实项目里遇到的坑以及最终沉淀下来的一套配置一次性说清楚。适合这几类人看重度使用 Claude Code 的开发者、维护多个项目想要统一上下文的团队、以及所有对给 AI 配外置记忆这件事感兴趣的人。2. 失忆的根源Claude Code 的会话隔离机制在介绍 claude-mem 之前得先把 Claude Code 为什么记不住事这件事聊透。这不是它的缺陷而是它的设计选择。理解了这个你才能明白 claude-mem 到底在补哪个洞也才知道后续那些配置为什么是那个样子。2.1 每个会话都是第一次见面Claude Code 的每个会话默认是互相隔离的。它只带着系统提示词、项目里的CLAUDE.md、以及你当前对话里的上下文在运行。你在这个会话里告诉它这个项目的构建命令是make build不要用 vite它会很听话但只要关掉终端重开一个新会话它就什么都不记得了。更尴尬的是--resume的恢复能力。它确实能找回之前的对话记录但如果你换了台电脑、清了.claude目录、或者隔了太久这些记录基本就靠不住了。我自己就试过出差换电脑之后想--resume之前的会话结果什么都没恢复。这意味着任何跨会话的知识都必须靠外部化来解决——也就是在会话之外把信息落成文件每次启动时重新喂给模型。2.2 官方记忆功能的边界Claude Code 本身也有一些记忆机制比如项目里的CLAUDE.md以及存储在用户目录下的全局配置。但这里有个绕不开的问题这些都是显式记忆你必须自己主动写。而大多数人的习惯是——在对话里用自然语言说了需求就期望它能记住根本不会想到去改CLAUDE.md。我一开始也是这样。后来我把CLAUDE.md当成了记事本遇到什么写什么结果它变得越来越臃肿里面充满了过时的、互相矛盾的信息。模型每次启动都要读一大堆无关内容反而降低了响应质量。这就暴露了核心矛盾显式记忆要靠人维护而人是最不可靠的维护者。2.3 claude-mem 的定位一个行为观察器claude-mem 的解法非常聪明。它不要求你主动写任何记忆而是放到事后去挖掘。它扫描你在终端里留下的操作记录、Claude Code 会话的历史日志用模型分析出你的行为模式比如这个用户习惯用pnpm exec eslint --fix而不是npx eslint --fix这个项目里用户总是把类型定义放在src/types/然后把观察到的模式整理成候选记忆再交给你审阅确认。它的本质像一个行为观察器加记忆编译器从垃圾数据里提炼出可复用的知识把隐式的习惯变成显式的记忆文件。这样既补上了会话隔离的洞又不需要你付出太多维护成本。我第一次跑完扫描看到它把我自己都没意识到的命令习惯列出来时确实被惊到了。3. 记忆是怎么炼成的扫描来源与生成逻辑知道了它要解决什么问题接下来看它具体怎么干活的。这一节我会拆开 claude-mem 的内部流程聊聊它到底扫描了哪些数据又是怎么通过 OH CODES 统计和行为分析把操作记录变成记忆的。3.1 三条扫描来源终端历史、会话日志、文件系统痕迹claude-mem 的信息来源主要有三个。第一是终端的 shell 历史比如.zsh_history、.bash_history。这里面记录着你敲过的每一条命令是判断命令习惯最直接的依据。第二是 Claude Code 自己的工作日志默认存放在~/.claude/projects/项目路径哈希/*.jsonl记录了你每次会话中跟模型的完整对话。第三是文件系统的变更痕迹比如最近改动的文件、新增的目录这些能反映项目当前的活跃区域和组织习惯。这三类数据拼在一起基本就能还原你最近的操作全貌。我第一次跑 scan 的时候它甚至能从对话日志里发现我让 Claude Code 写单测时用 Node 内置的node:test别用 Jest然后把这条规则纳入候选记忆。这比单纯看命令历史要深入得多因为很多偏好只存在于对话里从终端历史里根本看不出来。3.2 OH CODES 到底是什么接触 claude-mem 的人应该都见过它日志里的OH CODES字样官方文档对这块的解释比较抽象。我按自己的理解说人话这是一套把人类操作编码成可统计模式的方法。它会观察你在一段时间内默认最近 7 天高频出现的指令模板、参数风格、操作节奏然后给每种行为打上标签形成一组行为编码。比如它会统计你在命令里是更倾向用--长参数还是-短参数遇到报错之后的下一步动作是重新运行还是先搜索这些在传统统计里看起来很琐碎的东西组合起来却能相当准确地刻画一个人的操作画像。通过 OH CODES 的统计结果它能给每条候选记忆计算一个置信度置信度不够的就不推荐给你。这个机制过滤掉了大量一次性操作留下的基本都是稳定的习惯。我在测试时发现它不会因为我某一次临时用了npx就下结论说用户弃用了 pnpm这点做得挺克制。3.3 从模式到 Markdown记忆文件的生成过程分析完之后claude-mem 会把高置信度的模式交给语言模型生成结构化的记忆文件。每个记忆文件都是一个独立 Markdown包含三部分触发条件、推荐行为、理由说明。看一个它生成的实际例子# 命令习惯包管理器 ## 触发条件 当需要安装依赖、运行脚本或添加 npm 包时 ## 推荐行为 优先使用 pnpm不要使用 npm 或 yarn。 - install 依赖时pnpm add package - 执行项目脚本时pnpm run script ## 理由 用户在过去 14 天的 87 条命令中有 74 条使用了 pnpm 且在多轮对话中明确要求别用 npm。这种格式对 Claude Code 非常友好它读取之后能直接形成一条条件反射式的规则。你注意看最后一部分理由它把统计事实写进去了这让模型在采纳规则时不是死记硬背而是理解背后的行为倾向遇到边界情况时反而更灵活。3.4 记忆的承载体memp.d 目录与 CLAUDE.md 的配合所有生成的记忆文件最终都会放进一个叫memp.d的目录里。目录结构大致是这样memp.d/ ├── README.md ├── 00-user-preferences.md # 用户通用偏好 ├── 01-project-conventions.md # 项目约定 ├── 02-command-patterns.md # 命令习惯 └── 03-workflow-rules.md # 工作流规则关键一步在这里你要在项目的CLAUDE.md里加上一行memp.d。这一行是 Claude Code 的导入指令会让它在每次会话启动时把整个memp.d目录下的 Markdown 全部读进上下文。如果你不想让所有项目共享同一份记忆也可以把memp.d建在项目内部形成项目级隔离。4. 从安装到第一份记忆完整落地实操理论讲完了下面进入动手环节。我把一套完整操作流程拆成五步按顺序走完你就能在真实项目里用起来。我要提前说一句claude-mem 迭代很快命令细节可能跟你本地的版本略有出入遇到不确定的用npx claude-memlatest --help看当前版本的实际参数。4.1 安装与前置检查前置条件只有一个本机要有 Node.js 环境。这不是 claude-mem 的特殊要求而是它本身就是个 npm 包需要通过 Node 运行。确认版本时注意一下太老的 Node低于 18可能会跑不起来我建议直接上 LTS 版本。装命令很简单# 临时运行不污染全局环境 npx claude-memlatest # 或者全局安装 npm install -g claude-mem我个人的建议是刚开始先别全局装用npx跑一个交互式版本看看它到底能扫出什么。等你确定这东西对你的工作流确实有用再装成全局命令。跑完上面的npx命令之后它会进入一个交互式菜单问你要不要初始化仓库这时候选 Yes 就行。4.2 初始化记忆仓库初始化这步很关键别跳过。它会帮你做三件事第一创建memp.d目录结构和示例文件第二检查当前项目有没有CLAUDE.md没有的话会提示你创建第三往CLAUDE.md里写入memp.d导入指令如果之前没有的话。这里遇到第一个实际坑如果你的CLAUDE.md已经写了不少内容初始化工具可能会把memp.d加在文件末尾。我建议你手动检查一下位置——最好把它放在文件靠前但不是最前面的位置最开头留给项目的核心指令。因为 Claude Code 读取文件时虽然有优先级逻辑但一个清晰的排版顺序会让后面的维护舒服很多。另外提醒一句如果你用的是 monorepo或者一个目录里装了多个子项目建议在你想让记忆生效的那个根目录进行初始化。子项目里单独放CLAUDE.md会让记忆碎片化反而增加后续整理的负担。4.3 跑第一次扫描初始化完成之后正式扫描# 带项目名扫描便于记忆分类 npx claude-memlatest scan --project my-project # 或者限制分析范围只看最近 3 天的数据 npx claude-memlatest scan --days 3第一次扫描往往是最耗时的因为它要消化三个数据源里的历史记录。我测试过一个已经跑了半年的项目第一次 scan 花了接近三分钟输出内容非常长。这里有个建议第一次先别用--days拉满用--days 30试水看看生成的候选记忆质量如何再决定要不要放宽到 90 天。扫描完成之后命令不能直接写入记忆文件还需要进入审核环节。4.4 交互式采纳不是每条建议都值得带走现在进入我眼中 claude-mem 最精华的环节——交互式审阅。运行npx claude-memlatest interactive它会一条一条展示候选记忆每条包含行为描述、置信度、以及它观察到的证据。你有几个选择采纳、跳过、或者修改后采纳。我强烈建议第一次至少认真过一遍别全盘接受。因为我第一次跑的时候里面确实混进了一些过度概括的建议比如它根据我一两次操作就把所有错误处理必须用try-catch包裹当成强烈偏好推荐给我这显然太绝对了。在采纳时我会顺手做一件事给记忆文件加一个## 适用范围小节明确写下这条规则只在 xxx 项目中生效。这会让你后续维护时省掉很多困惑。编辑完按确认工具会把它写进memp.d对应的文件里。4.5 验证记忆真的生效采纳完记忆最重要的一步是验证。开一个新的 Claude Code 会话随便问它一个问题比如帮我跑一下测试或者故意踩一个记忆中明确说过不要这样做的坑看它的反应。理想情况下它会在动手前主动说一句按照你的习惯我用 pnpm 跑测试或者这个项目里你一般不用 Jest我按 node:test 写。我第一次验证的时候惊喜了一把但也发现一个现象模型有时候会把记忆文件里的规则背得很死比如我明明在记忆里写了测试文件放tests/目录它遇到一个应该放到__tests__/作快照的测试用例时仍然机械遵守了旧规则。这说明记忆文件不是越多越细就越好而是要给模型留出判断空间。后来的维护中我在记忆文件里刻意增加了一些例外情况的描述效果立刻好很多。5. 让记忆自动保鲜定时扫描与项目隔离claude-mem 最怕的一件事是记忆过期。你三个月前习惯用 webpack这周已经切成 vite 了如果记忆不更新老规则就会一直误导模型。这一节讲我如何让记忆保持新鲜以及多项目场景下的隔离方案。5.1 用 cron 跑定时扫描最朴素的保鲜手段就是定时扫描。我每周一上午跑一次全量扫描生成新的候选记忆再花五分钟审阅确认。手动跑几次之后我发现这事儿可以自动化思路是让 cron 定时执行扫描并把结果输出到日志文件里# 每周一早上 9:30 扫描 30 9 * * 1 cd /path/to/project /usr/bin/npx claude-memlatest scan --project my-project --auto-accept-low-confidence false /tmp/claude-mem-scan.log 21这里有个参数需要说明--auto-accept-low-confidence默认我设置成 false宁可不接收低置信度建议也不要让垃圾规则混进memp.d。定时扫描的价值在于让记忆里的规则跟着你当前的真实操作走而不是停留在三个月前的 snapshot 上。跑一个月之后回头看我memp.d里约四分之一的规则都被新规则替换掉了这是非常健康的更新频率。5.2 项目级记忆隔离--project 的正确用法我同时维护四五个项目一开始用的是全局memp.d结果发现 A 项目的规则污染了 B 项目比如这个项目用 pnpm被套到另一个实际用 yarn 的老项目上模型给出建议时明显错乱了。后来我把记忆拆分到项目层才解决这个问题。推荐的做法是项目根目录建自己的memp.d让记忆文件跟代码仓库走。这样换电脑、换协作者记忆都能跟着仓库走。实现方式是每个项目单独初始化一次运行 scan 时用--project 项目名打标签。命令后面接的项目名不仅是给你看的分类它还会影响记忆文件里适用范围的元数据让 Claude Code 在跨项目时自动降低旧规则的权重。5.3 记忆文件的版本管理与冲突处理记忆文件既然是纯 Markdown就应该纳入 Git 管理。我把memp.d直接提交到代码仓库跟着每次 commit 一起走。这带来两个好处第一历史记忆有迹可循哪天新规则把项目搞崩了可以快速 diff 出是哪条记忆导致的第二多人协作时大家都能看到项目沉淀下来的行为规范新成员上手会快很多。冲突处理是这里最需要留意的。最常见的情况是新生成的规则和旧规则打架比如旧的写提交代码前跑全量测试新的写提交前置跑增量测试即可。claude-mem 并不会自动帮你分辨新旧它只负责把两者都写进文件。我在 interactive 阶段遇到这种冲突通常遵循一个原则如果旧规则曾经真实指导过项目决策就先保留旧规则但加上注意新趋势是小范围增量测试的补充说明让模型根据场景自己拿捏。如果你直接删掉旧规则下次扫描很可能会再次生成它反而更麻烦。5.4 自动提交与团队共享的边界如果你想让整个团队共享一套 claude-mem 记忆最稳妥的方式是定好一个记忆维护人。这个人负责每周审核候选记忆、处理冲突、推送更新。其他成员拉代码的时候也就同步拉到了记忆的更新。但我不建议在团队协作时开--share这类直接把未审阅建议推送出去的模式。机器生成的东西未经人眼确认就进入共享上下文等于把你个人的操作习惯强加给整个团队很容易引起混乱。我在团队里试过一周最后还是回到单人审核、其他人只读的模式协作反而更顺畅。6. 踩坑实录三条让我印象深刻的教训这一节专门写给正在上手的朋友全是实际跑出来的教训我按遇到的顺序讲。每一条都曾让我困惑过希望你不用再踩一遍。6.1 扫描范围过大记忆噪音失控我第一次扩大到--days 90之后生成的候选记忆激增到 47 条里面充斥着大量一次性行为比如某天我手动改了一个配置文件被它总结成用户习惯直接在配置文件里改参数。这类规则不仅没用还会干扰模型对真实习惯的判断。后来我把扫描窗口控制在 14 到 30 天候选记忆数量降到 10 条左右质量的提升非常明显。这背后的逻辑是习惯的稳定性取决于重复频率。30 天窗口足够覆盖一个完整的功能迭代周期又能过滤掉那种只出现过一两次的临时操作。如果你的项目迭代极快可以缩短到 7 天如果是维护一个稳定老项目30 到 60 天都没问题。关键是别贪宁可漏掉一些新习惯也别让噪音淹没真信号。6.2 敏感信息被写进记忆这个问题最隐蔽也最危险。claude-mem 扫描的是终端历史和会话日志这些数据里大概率包含数据库连接串、API key、内网路径、甚至是同事的姓名。我在一次审阅中发现候选记忆里赫然出现了一条用户习惯通过psql postgresql://admin:passwordxxx连接数据库的记录。我当场把它删了然后就盯上了一个新问题怎么防止这类信息被重复生成。我想到的解法是两层第一在记忆文件的模板里加一个禁止记录敏感信息的头部规则让模型在生成候选时就有意规避第二定期抽查memp.d的 diff一旦出现可疑内容立刻清理。如果你对安全要求更高可以更进一步在扫描之前先对历史文件做脱敏处理把连接串替换成占位符。这听起来麻烦但真出一次事故就知道值了。6.3 记忆文件膨胀后token 消耗明显上升每份记忆文件在会话启动时都会被 Claude Code 读进上下文这意味着它会占用 token 额度。记忆文件不是免费的也不是越多越好。我见过有人把memp.d养到超过 2 万 token结果每次会话光读取记忆就要花不少钱而且因为上下文被大量没什么用处的规则占满模型的判断力反而下降。控制 token 的方法其实就一句话定期断舍离。我每隔两周会手动过一次memp.d把那些已经内化成项目常规、并不需要在对话中反复提醒的规则删掉或者合并。比如用 pnpm这种已经写进项目 README 的规则就不需要再占一份记忆了。留下来的核心原则控制在 3000 token 以内效果最好。7. 我最终沉淀下来的 claude-mem 工作流前面讲了机制、实操和坑最后分享一下我目前的完整配置算是给你一个可以直接抄作业的模板。7.1 记忆文件的结构与模板示例我的每个项目memp.d里固定包含四类记忆文件每个文件的头部都有一段使用说明。以其中一份为例# 项目约定目录结构与命名 ## 触发条件 当新增文件、创建组件、组织模块时 ## 推荐行为 - 页面组件放在 src/pages/业务组件放在 src/components/ - 工具函数放在 src/utils/文件名使用 camelCase - 测试文件与源码同目录命名 *.test.ts - 仅在跨页面复用时创建 components 下的目录 ## 例外情况 - 第三方接入相关代码放 src/external/不要强行归到业务目录 ## 适用范围 只在本项目生效我在描述里刻意增加了例外情况区块这比单纯列规则有用得多。模型在实际执行时面对规则和现实冲突的情况不会直接硬套而会优先检查例外描述。这是我在反复踩了规则过于僵硬的坑之后摸索出来的写法。7.2 我的每周维护节奏按周维护我已经持续了两个多月节奏基本稳定周一cron 自动扫描并输出日志 周二花 10 分钟查看候选记忆interactive 模式审阅 周三处理冲突、清理过时规则、检查敏感信息 周四git commit 并推送 memp.d 更新这个节奏听起来很频繁但实际每天占用时间极少。真正费时的是前两周的梳理等记忆库稳定之后每周新增的候选记忆也就三五条散碎时间就能处理完。它换来的是每次开新会话时Claude Code 对项目和我的了解都是最新、最准确的这个收益在长期使用中会被放得很大。7.3 最终判断claude-mem 适合谁不适合谁用到现在我的结论是claude-mem 不是每个人都需要但两类人用了会非常受益。一类是每天大量依赖 Claude Code 写代码的重度用户这类人积累的会话习惯最多记忆消除的重复沟通也最值钱。另一类是带团队的人团队项目规范可以通过记忆库慢慢沉淀让 AI 助手自动对齐团队风格。反过来说如果你只是偶尔让 Claude Code 写几个脚本平时对话量很少那它的价值就很有限了——因为样本太少生成的记忆质量会差很多反而增加维护负担。另外对于隐私零容忍、无法接受本地操作日志被分析的人我也不建议用因为它的底层逻辑就是把你的终端行为交给模型去总结。最后再分享一个小技巧我实际使用中给 claude-mem 加了 shell alias直接mem就能启动配合fzf做项目切换扫描目标体感上已经完全不亚于一个熟练的结对程序员了。工具本身不难用真正决定它能发挥多大价值的是你有没有耐心在前两周把记忆库的质量基础打好。打好了后面全是省时间的复利打不好它也就是个会写 Markdown 的噪音生成器。