用 Claude Code 写了不少项目之后，我最大的困扰是：它每次开新会话都不太记得我。明明上个星期刚跟它讨论过这个项目的整体架构，今天再开会话，它又问一遍这个问题是不是第一次遇到。你要是有过这种体验，就明白我接下来说的这个东西有多重要了——claude-mem。
claude-mem 是个给 Claude CLI 加“长期记忆”的开源工具，核心解决的就是 AI 编程助手跨会话失忆的问题。它不是让你手动把上下文文件拖进对话框，而是自动接管会话记录、自动做摘要、下次开聊自动把记忆注入进来。说人话就是：给 Claude Code 装一个大脑皮层，让它在会话之间保持记忆。如果你是 Claude Code 的日常重度用户、团队里负责维护 AI 工具链的工程师、或者正在折腾 AI 自动化工作流的人，这篇文章基本就是为你写的。
我会直接把我的使用思路、踩过的坑、配置方案和几个不太容易在文档里看到的心得完整写出来，尽量让你读完就能自己搭一套跑起来，而不是又收藏一个“看起来不错”的工具。
1. 为什么需要 claude-mem：AI 对话的“失忆”困局
1.1 没有记忆的 AI 助手有多痛苦
先说说场景。用 Claude Code 干活的人都知道，这工具本身已经很强了，能读代码、能改文件、能执行命令，但每次新会话都相当于换了个完全不认识你的“新同事”。你上周跟它敲定的技术选型、模块边界、甚至你惯用的代码风格，它全都不记得，一切要从头解释。
比如我维护一个中型微服务项目，里面有好几个模块的命名规则是跟业务绑定的，不熟悉的人看代码会觉得莫名其妙。我每次都必须在新会话开头花一大段文字去铺背景：这是什么项目、目录结构怎么分布的、命名规则是什么、最近在做哪一块。等解释完，上下文已经被吃掉不少了。如果对话稍微长一点，继续深入之后 Claude 还容易把前面铺垫的东西忘掉，因为上下文窗口是有限的——旧的信息会被截断或者注意力被稀释。
这个问题的本质，是 Claude Code 的会话状态是短时记忆，会话一关就没了。你关终端前它可能还在陪你重构一个函数，第二天打开终端，它一脸无辜地问你“这个文件是做什么的”。这不是它笨，是设计如此。
1.2 claude-mem 的定位：给 Claude CLI 装上长期记忆
claude-mem 就是冲着这个问题来的。它通过 Claude Code 自带的 hooks 机制，在会话启动前注入记忆、在会话结束时触发摘要生成，把“短时记忆”转成长久的“工作记忆”。
我不是说用上下文管理工具或者手工写 AGENTS.md 之类的规范文档没用，但那是静态方案，需要你手动维护，内容很快就过期了。claude-mem 是动态方案，它自动从你的对话历史里提炼要点，像是一个贴身记录员，实时帮你把重要的决定、目标、偏好记到小本子上。下次你再打开会话，这个记录员会把小本子上的内容摊在 Claude 面前：“这些是你们之前聊过的，别忘。”
它适合什么人？我觉得至少有三类：第一类是长期用 Claude Code 写同一个项目、厌倦了反复自我介绍的人；第二类是管着好几个项目、希望 AI 在各个项目之间切换时都能“记得对”的人；第三类是团队里带着新人用 AI 工具、希望把项目上下文沉淀成可传承资产的人。
2. 核心原理拆解：自动摘要、分层记忆与上下文注入
2.1 会话记录的捕获与过滤
claude-mem 底层依赖 Claude Code 的 hooks 能力。Claude Code 提供了一系列生命周期钩子，比如 UserPromptSubmit 在你发送提示时触发，Stop 在响应结束时触发，PreToolUse 在调用工具前触发。claude-mem 就是利用这些钩子自动捕获会话分片。
我在实际配置时发现，它并不是把所有的原始对话文本都一股脑写进记忆，而是先做一轮过滤。每次会话结束后，它会读取这次会话的转储数据，从中提取用户消息、助手消息、使用的工具和关键文件路径，过滤掉纯噪音——比如连续试错导致的重复命令、无意义的中间输出、超长的报错堆栈。这一步很关键，如果不过滤，记下来全是垃圾。
另外它会按会话聚合成“session”级别的临时记录，多个 session 再经由摘要流程沉淀成长期“memory”。相当于分了两层：短期会话记录，和服务于长期跨会话的摘要记忆。
2.2 摘要机制：把几百行对话压成几条记忆
这一步是整个工具的精华所在。claude-mem 不是直接存原文，那样记忆文件会无限膨胀；它是用一个摘要模型把长对话翻译成少量结构化条目。默认用 Claude 3 Haiku，这个模型便宜、快，处理摘要任务绰绰有余；你要是愿意，也可以配置成 Sonnet 甚至 Opus，摘要质量会更高，但成本也会上来。
我一开始不太理解为什么要单独用模型做摘要，后来一看就明白了：如果你的项目会话每天产生几百条消息，直接存原文，用不了多久记忆文件就能把上下文窗口占满，反而压制了正事。摘要把一百条对话压成三五条记忆——比如“用户决定用 Postgres 做持久化，废弃原本的 JSON 文件方案”“拒绝引入 OAuth 库，要求自研最小实现”——既保留了决策，又控制了体积。
这里补充一个涉及取舍的小点：摘要模型的质量直接决定记忆有效性。如果你发现 Claude 新会话里偶尔“想不起来”关键信息，先别急着怪 claude-mem，很可能是摘要阶段把细节弄丢了。我在后面的排查章节会展开讲。
2.3 记忆文件结构与存储位置
claude-mem 默认会在你项目的根目录下生成一个 .claude-mem 目录，里面按 Markdown 文件存记忆。打开看过一次，你会发现结构相当友好，基本是“项目背景”“目标与决策”“偏好与风格”“已完成的改动”“待办与下一步”这类分区，每条记忆就是一个小段落，带时间戳。这个设计很聪明，Markdown 文件人类可读，可编辑，可 diff，甚至可以随手 git commit 保持历史。
按项目还是全局存储，claude-mem 也做了区分配置。你在项目根目录初始化，它生成的就是项目级记忆，只对这个项目生效；你如果配置了全局模式，它会把你多个项目的习惯、偏好跨项目保存。我强烈建议新手上来只开项目级记忆，全局限在一些“通用编码偏好”，否则项目之间内容互相污染，Claude 容易把 A 项目的背景带到 B 项目去。
2.4 启动时自动加载：以结构化方式注入上下文
新会话开始的时候，claude-mem 是怎么把记忆塞给 Claude 的？答案还是在 hook 上。它注册了一个 UserPromptSubmit 钩子，在你发送第一条提示之前，就把相关信息拼接进提示词。具体拼接哪些，取决于当前目录所属的项目、记忆文件的条数、以及你配置的 claude-mem 参数。
值得注意的一个坑是：注入的记忆条数不是越多越好。初始版本如果一股脑把几百条记忆全部塞进去，不仅浪费 token，还容易造成信息过载，导致 Claude 抓不住重点。所以 claude-mem 提供了 max-memories 之类的配置项，让你控制单次注入量。这是实践里非常重要的一步——我一开始没调这个参数，长会话里 Claude 反而表现得比没有记忆时更混乱，就是因为注入的背景信息太杂了。
3. 从 0 到 1 部署 claude-mem：实操全流程
3.1 环境准备：Node.js 版本与全局安装
claude-mem 是 Node.js 写的 CLI 工具，安装前提是环境里有 Node.js 环境。官方建议 Node 18 以上版本，我实测 20 和 22 都没问题。先检查一下版本，太旧的话建议顺手升级，省得后面装依赖报一堆错。
安装非常简单，一条命令：
npm install -g claude-mem全局安装之后，它提供一个claude-mem命令，你可以先跑一下claude-mem --help看看支持哪些子命令。这里我提醒一下：全局安装的目录要确认在 PATH 里，否则后续 Claude Code 的 hook 脚本会找不到命令。我在 macOS 上安装完，位置是在/opt/homebrew/bin/claude-mem，一般不会有问题；如果用的 nvm 管理 Node，要注意 hook 执行时环境变量可能没带全。
3.2 安装核心流程：配置 hooks 与初始化项目
装完工具不等于装完“记忆”，核心是配置 Claude Code 的 hooks。这一步不同版本菜单路径略有差异，但思路一致——你要在 Claude Code 的配置文件里，把特定事件绑定到 claude-mem 的对应命令上。
我的实操步骤如下：
- 在项目根目录运行
claude-mem init，它会在本地生成 .claude-mem 目录和基础配置。 - 打开 Claude Code 的配置文件（它会在 init 时提示你是否自动写入 hooks 配置，选 yes 即可）。
- 确认 hooks 配置里出现了关键事件绑定，主要是“会话结束/停止”时触发
claude-mem backup，以及“用户提示提交”时触发claude-mem injection。前者负责在会话结束后把对话转储处理进记忆，后者负责在新会话里注入记忆。
第一次配置完，最好先开一个会话随便聊两句再退出，然后去 .claude-mem 目录里看 backup 结果。如果出现了记忆文件，说明流程通了。如果啥也没有，多半是 hook 配置没生效，往下看常见问题部分。
3.3 关键命令与参数配置：记忆上限、摘要模型与输出格式
claude-mem 提供了一套命令供手动操作：claude-mem status查看当前项目记忆状态；claude-mem remember [message]手动追加一条记忆；claude-mem forget [id]删除某条记忆；claude-mem list查看所有记忆。我平时用得最多的是 list 和 remember，前者用于检查它到底记了什么，后者用于会话里临时产生的关键决定主动补记一条。
配置项里最值得关注的是三个：
CLAUDE_MEM_MAX_MEMORIES：控制每次注入的记忆条数上限。我建议从 8~10 开始，不要贪多。CLAUDE_MEM_MODEL：控制摘要模型。默认是claude-3-haiku-20240307，追求摘要质量的话可以换claude-3-5-sonnet-20241022之类的新模型。- 记忆输出格式：我文章前面提到的分区格式是可以调整的，官方模板默认就够用，除非你有强定制需求，否则不用动。
我踩过最大的坑之一，就是只配了命令、没调参数。结果会话日志全被原样存进去，记忆文件里重复信息爆炸，注入时还把低价值内容塞给 Claude，效果反而比没开记忆时更差。后来我把摘要模型调高、把注入条数降到 8，并手动 forget 掉几条垃圾记忆，整个体验立刻上升了一个台阶。
3.4 结合实战：一次完整的记忆生命周期
为了让你有个直观理解，我描述一次典型的使用流程：
你在终端里进入项目目录，启动 Claude Code，问它“帮我看下当前订单模块的代码，我想加一个折扣计算功能”。因为 claude-mem 配置好了，你发送这条消息之前，hook 已经把之前沉淀的“项目背景”“订单模块采用策略模式”“禁止改动核心定价逻辑”这类记忆注入进去了。Claude 看到你有上下文，直接就能入题，而不是问东问西。
聊了一阵子，你们确定了折扣方案的实现方式，并且约定“折扣规则要可配置化，不硬编码”。这时候你可以用claude-mem remember "折扣功能采用配置化方案，规则放 YAML，不硬编码"手动把这条决定写进记忆——其实 claude-mem 也会自动摘要，但主动写能保证准确性。
会话结束，hook 触发 backup，这次会话的关键内容被摘要模型压缩之后，存进 .claude-mem 的记忆文件。下一次你再开新会话，它就能记住这个决定，不必重新讨论。
4. 实际使用场景与效果复盘
4.1 跨会话续写项目：从“你是谁”到“我们继续”
我用的最频繁的场景，就是跨会话续写。以前做一次大改动通常需要拆成好几个工作段落，每个段落开新会话把背景重新贴一遍，特别浪费 token 也浪费时间。有 claude-mem 之后，新会话直接进入主题，Claude 甚至能说出“刚才提到要改的 xx 文件我看了，接口影响到模块 A、B、C”，这种待遇以前完全不敢想。
当然，它也不是万能记忆，本质上还是会受摘要质量影响。如果某个会话信息密度特别高，摘要模型没处理到位，那么下一次会话里 Claude 可能只记得“聊过某件事”，不记得细节。所以遇到特别重要的决策，我都会手动 remember 一遍，做到双保险。
4.2 多项目仓库管理：项目和全局记忆的隔离实践
我工作电脑上同时维护四五个项目，如果让 claude-mem 把这些项目记忆全部打通，那是一件很危险的事。好在它支持多级作用域，项目根目录初始化之后默认只在当前目录下生效。我特意测过，在 A 项目里产生的记忆，回到 B 项目后不会有任何注入。
如果要跨项目共享通用风格偏好，比如“函数注释一律中文写清楚入参和出参”“面对不确定的需求先列方案再写代码”，你可以把这类内容放在全局记忆层。配置方式是在项目目录里指定scope: global之类的选项。我的经验是：全局记忆只放普适规则，不放具体业务，否则两个项目业务风格一旦有冲突，Claude 会非常迷惑。
4.3 团队协作场景：把记忆文件作为项目资产
还有一个比较隐藏的价值适合团队场景。因为记忆是 Markdown 文件，天然适合入库管理。我在团队里推行过一种玩法：把项目里的 .claude-mem 目录加入 Git，团队成员 clone 项目之后，大家的 Claude Code 都共享同一份项目记忆。新加入的同事不需要花两三天去熟悉项目背景，直接让 Claude 带着项目记忆回答问题。
不过团队协作也会引入一个新问题：如果 A 成员和 B 成员对这个项目的认知有偏差，或者某条记忆是 A 基于错误理解写的，那份错误会被复用到整个团队。所以如果真想共享记忆文件，建议定期审阅。我们实际操作起来，是不定期把记忆文件的关键条目贴在项目 Wiki 里一起审，能纠掉不少问题。
5. 常见问题与排查技巧实录
5.1 hook 没生效或完全不产生记忆
现象是新会话里没有任何记忆注入，.claude-mem 目录也半天没动静。第一步先看 Claude Code 配置文件里的 hooks 段是否真的写进去了，尤其要注意 claude-mem 命令的实际路径在 hook 进程里是否能正确解析。我用 nvm 的时候踩过这个坑：hook 是由另一个 shell 触发的，PATH 里没有~/.nvm的路径，导致 claude-mem 命令找不到，同类的还有全局 Node 路径不在系统 PATH 里的场景。
解决办法是给 hook 里的命令写全路径，或者安装命令用软链放到/usr/local/bin这种常用目录。改完一定要重启 Claude Code 再验证。
5.2 记忆内容太杂太乱怎么办
我的原始配置跑了一周后，曾经出过一次比较严重的问题：记忆文件里什么都有——日志级别的输出、某一个一次性 bug 的排查过程、某段 e-mail 式的客套话，让记忆检索效率很低。后来我复盘出三条规定：
第一，遇到不太重要但有一定讨论价值的内容，不用管，交给 claude-mem 自己爱记不记；第二，只有真正影响项目方向、架构、重大取舍的决定，才手动claude-mem remember补一条；第三，定期执行claude-mem list梳理，能删就删。
5.3 隐私与安全考量：哪些内容不该进入记忆
claude-mem 默认会将项目下所有会话内容做摘要，这里有个边界需要你心里有数。比如一次性结论里带着敏感数据、内部讨论时的加密密钥、某个用户的个人隐私信息，这些都不该被摘要成记忆长期保存。虽然记忆文件在你的磁盘上相对安全，但钩子会调云端模型做摘要——也就是说：你在本地跟 Claude 的对话，会被摘要模型再过一遍。
这一条我没在常见文档里看到过强调，但真踩过。有个不想提的项目就是因为怕敏感内容落盘，直接放弃了 claude-mem。如果你有类似顾虑，可以用它的过滤能力配置忽略词，把包含特定关键词的会话内容不做摘要存储；或者干脆设立一条铁律，敏感项目禁用记忆功能，只在纯业务代码项目里开。
5.4 注入记忆过多导致上下文被抢占
前面提过，max-memories 这个配置如果设得过高，记忆内容会占据大量上下文窗口，导致 Claude 实际可用于逻辑推理的空间变少，表现出来就是回答变“笨”。我试过把它调到 20，结果 Claude 的回答明显开始套话，因为你塞的“背景”比“问题”还多。降回 8 之后一切恢复正常。这里我的建议是：小项目 4~6 条就够，中大型项目 8~12 条足够，超过 20 条基本是负收益。
5.5 记忆内容过时或冲突的迭代策略
最后说一个长期使用才知道的问题：记忆文件会随着时间推移产生“过时冲突”。比如你们项目中期变更了数据库方案，之前的记忆里还留着“用 Postgres”的决策，新会话里 Claude 看到旧记忆之后，可能会在讨论新方案时产生犹豫。claude-mem 的 forget 命令这时就是你的救命稻草；另一个我觉得比较顺滑的策略是在项目配置里定期用 clear 重开一套记忆，或者把过时记忆单独挪到一个 backburner 目录，别影响 active 记忆。
我现在的实践路径是，每个迭代周期开始前花十分钟做一次记忆体检：把已完成目标挪走、把过时决策删掉、把新目标用 remember 手动写进去。这个习惯让我用 claude-mem 的稳定度好了非常多。
6. claude-mem 的局限与我的应对心得
先说结论：claude-mem 能解决“跨会话失忆”这个大问题，但它不是让 Claude 记住一切的神器，它只是帮你把短期对话转成可检索、可控制、可编辑的长期记忆。它的价值在于把记忆这件事从“不可控”变成“可控”。摘要模型的选择、记忆条数的管理、上下文的取舍，这些变量仍然需要你自己把握。
我个人在实际操作中体会到的最重要一件事，是别指望它替你判断哪些内容值得记。它是大众化的摘要器，不懂你项目的核心价值，所以主动管理记忆——尤其是主动忘了那些不该记得的东西——才是用好它的关键。初始化的时候可以先跑默认配置，用两周之后再逐步调参，你会在某个时间点突然发现，新会话开起来之后，Claude 已经知道这个项目它该干什么了。
如果你跟我一样沉迷于折腾这些“让 AI 更懂我”的工具，我建议你给 claude-mem 一个机会。它不完美，但它真实解决了我的痛点，也极大概率能解决你的。
