你有没有遇到过这种场景让 Claude Code 改了半天代码第二天再打开项目它完全记不得昨天说过什么又把同样的问题问了一遍。我刚用 Claude Code 的前两周几乎每天都要重复一遍项目背景、代码规范、甚至自己的技术偏好耐心就是这么一点一点被耗没的。直到我发现了 claude-mem 这个开源工具才彻底解决了这个“金鱼记忆”问题。claude-mem 是给 Claude Code 增加长期记忆能力的命令行工具。它会在每次对话结束后自动提取值得记住的信息比如你的编码风格、项目里的关键决策、常用命令然后在下次会话开始时把这些记忆重新注入上下文让 Claude 真正“记得你”。如果你和我一样是在用 Claude Code 做长周期项目、或者每天开多个会话来回切换那这个工具几乎是刚需。这篇就从一个普通使用者的角度把它的工作原理、安装步骤、实操配置和踩坑记录完整过一遍。1. claude-mem 是什么为什么需要它1.1 Claude Code 的“金鱼记忆”痛点先说清楚问题根源。Claude Code 本身是一个会话式编码工具每次启动新会话时上下文窗口里只有系统提示词、当前目录的文件信息和你这次输入的对话内容。也就是说昨天你和它讨论过的模块划分、今天上午刚定下的命名规范只要会话一关统统归零。这不是缺陷而是当前大模型交互的基础设计——无状态。但放到真实工作流里这个无状态特性会带来很实际的效率损耗。[ANTHROPIC_NAME_LITERAL] 我自己统计过一个中型项目里我每天大概有 20% 的提问是在重复过去已经确认过的信息。比如“这个订单模块的状态字段到底用 int 还是 string”“测试环境部署命令是什么来着”“数据库连接串放在哪个配置文件”。这些问题本身不难但每次都让 Claude 从零开始理解上下文既浪费时间又容易产生前后不一致的回答。更麻烦的是如果两个会话对同一个问题给出了不同答案你还得花精力去判断哪个才是对的。1.2 claude-mem 的定位与核心工作方式claude-mem 做的事情本质上就是给 Claude Code 装一块“外置硬盘”。它利用 Claude Code 自带的 Hooks 机制在每次对话的关键节点触发后台任务对话结束时提取重要信息下次启动时注入记忆。整个过程中不需要你手动复制粘贴任何内容所有记忆的读写都是自动完成的。它的工作流可以拆成三个环节。第一是提取Extract在会话进行中或结束时claude-mem 会读取本次会话的对话记录调用 Claude 的 API 对内容做一次摘要式分析把用户偏好、项目约定、技术决策、常用工具链等结构化信息抽出来存到本地的记忆库里。第二是整理Housekeeping随着记忆越攒越多它会定期合并重复项、剔除过期内容避免记忆库变成一个垃圾场。第三是注入Inject每次新会话启动时把记忆库中与当前项目相关的高价值内容通过修改 CLAUDE.md 或启动注入的方式重新塞回对话上下文。这里有个关键设计值得多说一句claude-mem 不是简单地把你所有对话原文都存下来再一股脑倒回去那样上下文窗口早就爆了。它做的是“精炼提取”只保留那些有长期价值的信息。比如你的代码风格偏好、项目的架构取舍、你反复使用的命令。这也是为什么我叫它“记忆”而不是“记录”——它像人一样记住的是要点而不是逐字逐句的原文。2. 安装与初始化配置2.1 环境要求与安装步骤claude-mem 是一个 Python 命令行工具安装方式非常简单。在开始之前你需要确认几个前置条件Claude Code 已经安装并能正常使用系统里有 Python 3.10 以上版本pip 可以正常访问 PyPI同时你需要有可用的 Anthropic API Key注意这里用的是 API Key不是 Claude Code 的登录订阅因为记忆提取过程会直接调用 API。pip install claude-mem装完之后先跑一下版本检查和环境自检claude-mem --version claude-mem doctordoctor这个命令会检查 hooks 是否配置、API Key 是否生效、记忆目录是否可写。新装完一般不会全绿因为它还没往 Claude Code 的配置文件里写东西这是正常的。接下来做初始化配置。2.2 注册 Hooks让 Claude Code 认识 claude-memclaude-mem 的核心功能都依赖 Claude Code 的 Hooks 机制。所谓 Hooks简单理解就是事件回调——Claude Code 在执行某些操作时会先调用你指定的外部命令等命令完成后再继续原来的流程。claude-mem 需要注册两组 hook一组是工具调用后的提取 hook另一组是会话结束时的整理 hook。初始化命令会帮你完成这些配置claude-mem init执行完成后它会自动修改 Claude Code 的配置文件。在 macOS 和 Linux 上这个文件通常位于~/.claude/settings.json。如果你之前手动改过这个文件建议先备份一下。init 命令会写入类似下面的配置{ hooks: { PostToolUse: [ { matcher: Read|Write|Edit|KillShell|Bash, hooks: [ { type: command, command: claude-mem extract --mode auto } ] } ], Stop: [ { hooks: [ { type: command, command: claude-mem housekeeping --silent } ] } ] } }这段配置的意思是当 Claude Code 调用了 Read、Write、Edit、Bash 这些关键工具之后自动运行claude-mem extract提取记忆当对话停止Stop 事件时自动运行一次记忆整理。这里的matcher字段用的是正则表达式你可以按需调整比如只保留Read|Bash来减少触发频率。初始化完成之后在任意一个项目目录里启动 Claude Code就应该能看到 claude-mem 开始工作了。你可以在对话里输入/mem来确认集成是否成功——如果返回记忆管理菜单说明 hook 链路已经通了。2.3 记忆目录结构与数据存放位置claude-mem 把数据默认存储在~/.claude-mem/目录下目录结构是这个样子~/.claude-mem/ ├── CLAUDE.md ├── memories/ │ ├── raw/ │ ├── events/ │ ├── permanent/ │ └── duplicates/ ├── files/ └── logs/CLAUDE.md是注入入口文件claude-mem 会把精选后的记忆写入到这里Claude Code 在启动时会自动加载全局 CLAUDE.md从而让记忆生效。memories/raw存放每次提取的原始记忆events是经过整理后的事件化记忆permanent是你手动标记为永久保留的内容duplicates则是去重处理时的临时缓存。files目录会在记忆内容较长时使用用于保存大段文本的原始文件避免所有东西都塞进 JSON。需要特别提醒的是claude-mem 的 CLAUDE.md 是自动生成的不要手动改这个文件。你手写的项目规范应该放在项目根目录自己的 CLAUDE.md 里claude-mem 会在注入时把两份内容合并处理。我刚开始用的时候就犯过这个错手动改了自动生成的 CLAUDE.md结果下次 housekeeping 跑完改的内容全被覆盖了白忙活一场。3. 记忆沉淀机制详解从对话到长期记忆3.1 记忆提取到底是怎么触发的很多第一次用 claude-mem 的朋友都会有个疑问它到底在什么时候提取记忆是每句话都提取吗如果每句话都提取那消耗的 API 费用岂不是很夸张实际不是的。默认配置下claude-mem 的提取动作是搭配 Hooks 事件触发的。在PostToolUse事件里注册的 hook 会在每次关键工具调用完成后执行一次提取。但这里的“提取”不是把整段对话发给 API 做总结而是它内部有自己的一套逻辑它会读取当前对话上下文中是否有值得记录的信息比如出现了新的项目路径、用户表达了明确的偏好、或者某个命令被重复使用。判断的依据包括信息的新颖度、与既有记忆的关联度、以及是否满足预设的提取规则。[ANTHROPIC_NAME_LITERAL] 不过说句实话默认的自动提取其实还是有些保守。用了一段时间之后我更喜欢主动补充一些手动记忆。你可以通过/mem菜单里的“添加记忆”选项或者直接命令行claude-mem set 项目规范 后端接口统一使用 /api/v1 前缀错误码格式为 {code, message, detail} claude-mem set 用户偏好 代码注释用中文commit message 用英文这种手动写入的记忆我会叫它“种子记忆”质量非常高。因为它完全是你深思熟虑后确定的规则不会像自动提取那样偶尔抓偏重点。自动提取负责收集增量信息手动写入负责锚定核心规则两者配合效果最好。3.2 记忆整理housekeeping 的工作原理记忆光提取不整理很快就会出现两个问题一是重复内容堆积比如你每次改测试用例它可能都会提取一条“用户正在修改测试文件”这样的低价值事实二是信息过期比如项目初期确定用 MySQL两周后迁移到了 PostgreSQL但 MySQL 那条记忆还躺在库里面。claude-mem 的 housekeeping 机制就是专门解决这两件事的。默认在每次会话结束后自动运行也会在 init 时生成一个可选的 cron 定时任务。整理分为几个阶段第一把散落在 raw 目录里的短期记忆聚合成事件。比如 “用户提到了订单表”“用户确认了订单表字段类型”“用户添加了索引”这三条短期记忆会被合并成一条完整的事件“订单表设计确认完成字段包含 id、user_id、amount、status并添加了 created_at 索引”。这个环节通常会调用一次 Claude API因为合并操作需要语义理解。第二去重。它会扫描整个记忆库找出语义相似或重复的记忆条目保留信息最完整的那条其余的移入 duplicates 目录。这一步很重要否则记忆库会在长期使用后越来越膨胀最终导致注入时上下文被塞满低质量内容。第三过期与降权。如果一个记忆条目的最后一次引用时间超过设定阈值比如 30 天它会被标记为低优先级超过更长周期比如 90 天且从未被引用就会被移出主记忆库。这套机制保证了注入时始终优先推送最近最有价值的信息。3.3 记忆注入Claude 是怎么在会话开始时“想起来”的整个流程里最有技术含量的部分是注入环节。claude-mem 的注入并不是简单地把所有记忆拼成一段文字塞进系统提示而是做了一次分层处理。启动时claude-mem inject命令会执行以下操作读取当前项目的目录信息确定项目身份然后从记忆库里筛选出与该项目相关的记忆再根据记忆的优先级标签permanent、event、raw做排序permanent 最高raw 最低最终把筛选结果写入全局 CLAUDE.md 的特定区块并控制在合理长度内。注入的内容大致分为三部分项目级记忆比如技术栈、目录结构、常用命令用户级记忆比如编码风格、沟通偏好以及最近的重要事件比如“昨天已完成用户认证模块重构下一步是编写单元测试”。这三部分组合在一起Claude 才会在会话一开始就进入状态而不是像个刚入职的新人一样等你逐项交代背景。[ANTHROPIC_NAME_LITERAL] 多说一句如果你需要更精细的控制可以在项目根目录建一个.claude-mem/config.json文件通过include和exclude字段指定某些目录或标签的记忆是否参与注入。比如你手上同时有公司项目和个人项目可以通过配置实现完全隔离互不干扰。4. 实操日常使用中我常用的几个操作4.1 用 /mem 菜单完成日常管理在 Claude Code 会话里输入/mem会弹出 claude-mem 的管理菜单。这个菜单提供查看记忆列表、搜索记忆、添加手动记忆、标记永久记忆、删除记忆等功能。日常用得最多的是前两个查看最近记录和搜索特定内容。如果发现某条自动提取的记忆明显是错误的比如把前一个项目的路径记到了当前项目下面直接在列表里选中删除就行。这个操作很值得养成分习惯因为自动提取毕竟是基于模型判断偶尔会抓偏。我个人的习惯是每天早上开工前先跑一遍claude-mem list --limit 20扫一眼昨天的记忆提取情况顺手清掉几条明显不该记的。这个小习惯让记忆库长期保持良好的精度。4.2 命令行管理适合批量操作的场景虽然/mem菜单已经很方便但涉及批量操作时命令行其实更高效。常用命令我整理了一个速查表命令作用使用场景claude-mem list --limit 50列出最近 50 条记忆快速浏览提取结果claude-mem search 数据库全文搜索记忆内容找历史决策细节claude-mem set 标签 内容手动添加记忆写入确定的规则和偏好claude-mem tag id permanent标记为永久记忆防止被自动清理claude-mem delete id删除单条记忆清理错误提取claude-mem forget 关键词按关键词批量删除清理大范围过时内容claude-mem export --format json导出全部记忆备份或迁移比如说当我要把一套记忆从开发机迁到新电脑直接claude-mem export导出 JSON然后在新机器上claude-mem import导入五分钟搞定比重新训练一遍模型还快。4.3 多项目隔离避免记忆串味claude-mem 默认会为每个项目分配独立的记忆作用域。第一次在某个目录里启动 Claude Code 时它会自动标记这个目录对应的项目标识之后在这个目录下的会话只注入该项目相关的记忆。但有个细节容易踩坑如果你经常在多个相似目录之间复制项目比如~/work/project-a和~/work/project-a-copyclaude-mem 有可能会把它们识别成同一个项目导致记忆互相污染。解决办法是在项目根目录手动创建.claude-mem/config.json并在里面显式设置project_name{ project_name: project-a-main, include_tags: [项目规范, 数据库], exclude_tags: [临时草稿] }这里project_name相当于给项目定了一个唯一标识include_tags和exclude_tags则控制哪些标签下的记忆可以参与注入。我一般在接手新项目时都会第一时间写这个配置文件把标签范围圈定清楚后续的记忆管理会顺畅很多。5. 常见问题与排查技巧实录5.1 记忆不注入先查这几处这是最常遇到的问题。装好 claude-mem 后第二天打开 Claude Code发现它还是完全不记得之前的对话内容。排查思路其实很简单从上游到下游逐一检测。先用claude-mem doctor确认整体链路状态它会提示 hooks 是否注册成功API Key 是否有效记忆库是否有数据。如果提示 hooks 未注册则大概率是配置文件被其他工具覆盖了。很多 Claude Code 的第三方插件也会改写~/.claude/settings.json如果安装顺序不对后装的插件可能把 claude-mem 的 hooks 配置冲掉。这时候备份好你的记忆目录重新跑一遍claude-mem init即可。如果 hooks 正常就检查注入结果。手动执行claude-mem inject然后查看全局 CLAUDE.md 文件确认记忆区块是否被写入。如果文件里什么都没有说明记忆库为空或保存的条目不匹配当前项目作用域。这时再看一下claude-mem list的输出如果确实有记忆但没有注入多半是标签过滤条件把内容全部排除了回看一下 4.3 里的 include_tags 配置即可。5.2 记忆库膨胀太快怎么办我印象最深的一次危机是在连续高强度使用一周后记忆库从不到 100 条飙升到了 2000 多条。不仅注入变慢还经常把一些无关紧要的历史记录推给 Claude导致回答失误增多。后来分析原因主要是自动提取的频率太高每次 Bash 工具调用后都会生成一条“用户执行了命令 xxx”的原始记忆这类记录本身价值不高却占了大量空间。现在的做法是两招并用。第一招在初始化配置时调整 hook 的 matcher只保留Read|Write|Edit把Bash那个高频触发源去掉。第二招手动写一个定时任务每天深夜跑一次claude-mem housekeeping --aggressive强制整理过期内容。如果发现记忆库里重复率依然偏高可以用forget命令批量清掉那些低价值关键词下的内容。5.3 两个容易忽略的日常问题还有一个比较容易踩的坑是提取过程中 API 报错。claude-mem 的提取和整理都依赖 Anthropic API如果你的 API Key 余额不足或触发了速率限制提取会静默失败。具体表现是对话一切正常但记忆库好几天没有新增内容。建议设置环境变量把 claude-mem 的日志打开一旦发现 catch 不到记忆直接去~/.claude-mem/logs/下面翻日志报错原因都会写在那里。另外格式兼容问题。有同事和我抱怨 claude-mem 注入的记忆经常挤掉他项目自己写的 CLAUDE.md 内容。这其实是注入配置问题——claude-mem 默认会在原文件末尾追加记忆区块但如果项目的 CLAUDE.md 本身非常长叠加之后超出了上下文的高效区表现上就像是“挤掉”了。解决办法是精简自带 CLAUDE.md或者把 claude-mem 的全局注入改成按需模式只注入高优先级记忆。6. 一些真心话与后续玩法断断续续用了两个多月 claude-mem 之后我现在已经把它列为 Claude Code 的必备搭档。最直观的变化是以前每天开场那句话是“我先给你说下项目背景”现在已经变成直接说需求Claude 基本都能接住。那种不需要反复交代上下文的感觉确实能让人把精力集中在真正的编码上。有几个使用建议供参考。第一自动提取很重要但手动写种子记忆更重要。我每次接手新项目都会花十分钟把项目技术栈、目录约定、部署流程这些基础信息用claude-mem set写进去。这十分钟的投入会让之后每一轮对话都更顺畅。第二定期审视记忆库是个好习惯。记忆中不只有“正确”的信息还有“过期”的信息。一个长时间维护的项目技术选型发生变化是很正常的但你如果不主动清理旧记忆Claude 就可能在新的决策中引用旧的上下文导致前后矛盾。我开始每周跑一次 review 之后这类问题基本没再出现过。第三如果你有多台工作设备记得把记忆库纳入同步或定期导出备份。我对记忆备份的态度和对代码备份是一样的——这些记忆本质上是你和 AI 协作积累出来的“项目上下文财富”丢一次成本还是挺高的。后续如果想继续折腾可以研究的方向包括写一份自定义脚本每天定时把当天提取的记忆转成 Markdown 周报或者针对不同项目配置不同的注入策略更复杂一点的甚至可以基于 claude-mem 的历史记忆数据做一个小型的决策记录分析看看哪些技术决策是在什么背景下做出的。不过这些都是锦上添花了对于大部分人来说先把基础的安装、配置、注入跑通日常使用就已经能获得非常明显的体验提升。