claude-mem：给Claude Code装上跨会话长期记忆的开发者助手

如果你每天都在用 Claude Code 写代码，大概率遇到过这样的场景：上午刚告诉它“我们这个服务用 Go 写的，数据库是 PostgreSQL，部署走 Kubernetes”，下午新开一个会话，它又一脸茫然地反问项目的技术栈是什么。不是它笨，而是 Claude Code 的每个会话都是独立上下文，聊完即焚。今天要聊的 claude-mem，就是为了根治这种“失忆”问题而生的。

claude-mem 是一个给 Claude Code 增加长期记忆能力的开源工具，本质是在会话之外维护一个本地记忆库，用 Claude 自己来总结对话、抽取关键事实，并在下次会话开始时自动注入上下文。它能解决的问题很明确：让 AI 助手跨会话记住你的偏好、项目背景和技术决策，省掉每次反复交代的沟通成本。适合所有重度依赖 Claude Code 写代码、做重构、跑脚本的开发者，尤其是同时维护多个项目、经常切换上下文的人。

1. Claude 会话失忆的根源与 claude-mem 的破局思路

1.1 为什么 Claude Code 总是“记不住事”

要理解 claude-mem 做了什么，得先明白 Claude Code 的会话机制。Claude Code 是一个命令行 AI 编程助手，它每一次启动都会创建一个全新的会话窗口，这个会话内的“对话历史”只在这个会话内有效。一旦你关闭终端、结束会话，所有上下文——包括你刚才贴的报错日志、你决定的命名规范、你解释过的业务逻辑——全部清空。

这本身是一个安全设计，避免用户数据被持久化在服务端，但对于高频使用 AI 编程的人来说，代价是效率。我自己的体会是，一个稍微复杂的项目，跟 Claude 交代上下文的时间往往要占到整次交互的 10% 到 20%。项目越大、切换越频繁，这种“重复自我介绍”的痛感越强。后来我看到有人用 CLAUDE.md 文件来固化项目说明，但这只能解决静态信息，解决不了“上次会话里讨论出的结论”“刚才确认过的技术选型”这类动态记忆。

1.2 claude-mem 的破局思路：会话外记忆库 + 自动摘要

claude-mem 的核心设计很简单，就三步：提取、存储、注入。

• 在会话结束时（session-end hook），把当前会话的完整对话交给 Claude 进行总结，抽取出值得长期记住的关键信息。
• 将这些信息以“记忆条目”的形式写入本地的 SQLite 数据库，并带上标签、时间戳和维度分类。
• 在下次会话开始时（session-start hook），把这个记忆库中相关的条目注入到 Claude 的系统提示词里，让 Claude 一上来就“想起”了你和项目的事情。

这个思路解决了一个关键问题——记忆不是靠原始日志堆出来的，而是靠摘要提炼的。如果把所有历史对话都塞回去，上下文窗口很快会被撑爆；claude-mem 让 Claude 自己判断什么是重要的，只把精华留下来。我第一次跑通这个流程时，感觉就像给 AI 助手装了一个外部硬盘，原来它只有一块用一次就清零的内存，现在终于有了可以长期读写的工作记忆。

2. 安装与初始化：三分钟把记忆层挂到 Claude Code 上

2.1 安装 claude-mem：用 Rust 工具链编译

claude-mem 的安装方式不算复杂，但它是一个 Rust 项目，需要你本机有 Rust 工具链。如果你之前装过cargo，直接执行：

cargo install claude-mem

如果没装过 Rust，先装 Rust 工具链（官网 rustup.rs 有脚本），或者直接去项目的 GitHub Releases 页面下载对应平台（macOS / Linux / Windows）的预编译二进制，解压后放到 PATH 目录里。我个人建议直接用 cargo 方式，后面升级也方便。安装完成后，在终端执行claude-mem --version，能输出版本号就说明装好了。

提示：安装过程可能因为网络原因比较慢，尤其是国内用户拉 crates.io 的依赖。如果卡住了，可以配置 Rust 的镜像源，或者耐心等一等，这个项目依赖项不算多，编译一般不会超过几分钟。

2.2 配置 hooks：让 Claude Code 自己触发记忆读写

装好二进制只是第一步，真正的关键是把 claude-mem 挂到 Claude Code 的声明周期事件上。Claude Code 支持 hooks 机制——你在配置文件里定义某些事件发生时，系统自动执行什么命令。claude-mem 提供了自动配置命令，执行：

claude-mem install

它会自动修改 Claude Code 的配置文件（一般在~/.claude/settings.json），写入两个 hook：SessionStart和SessionEnd。SessionStart时执行claude-mem --inject注入记忆，SessionEnd时执行claude-mem --extract提取并存储新记忆。

你也可以手动检查配置文件里是不是多了类似这样的内容：

{ "hooks": { "SessionStart": { "command": "claude-mem --inject --json" }, "SessionEnd": { "command": "claude-mem --extract --json" } } }

手动写也完全可以，关键是命令别写错。hook 配置完成后，重启 Claude Code，第一个会话开始前它就会去读取记忆库，会话结束后自动总结记忆。

2.3 初始化与验证：确认记忆真的在写入

配置好之后，我建议先跑一轮“冒烟测试”。打开 Claude Code，随便聊几句，比如“我主要负责后端开发，喜欢用 Python 和 FastAPI”，然后退出会话。接着执行：

claude-mem stats

如果输出里出现了类似 “Found XX memories” 或 "database size" 的统计，说明 session-end 的挂钩生效了，刚才的对话已经被总结入库。还可以执行：

claude-mem search --term "Python"

看能不能搜到刚才那个会话里提到的信息。我实测的结果是，默认配置下整个流程是全自动的，不需要手工干预。所谓“三分钟跑通”，大部分时间其实花在装 Rust 上。

3. 命令手册：那些比“自动记忆”更实用的 CLI 操作

很多人以为 claude-mem 就是个后台服务，装完就不用管了。其实它的命令行工具本身提供了不少实用操作，日常折腾起来相当顺手。

3.1 search 命令：精确、模糊还是语义搜索

记忆存下来之后，怎么快速找到它比记忆本身更重要。claude-mem search是这个工具最高频的命令：

claude-mem search --term "数据库迁移方案" claude-mem search --term "项目架构" --search-type fuzzy claude-mem search --term "k8s 部署" --search-type semantics

--search-type参数有三个选项：exact（精确匹配）、fuzzy（模糊匹配）、semantics（语义近似）。默认是语义搜索，它会调用 Claude 对查询词和记忆条目做语义匹配，所以哪怕你忘了当时是怎么描述的，只要意思接近也能搜出来。模糊搜索适合按关键词定位，精确搜索适合查技术名词这类强信号词。我自己的使用习惯是：准确记得某个词就用 fuzzy，记不清了只想“找那个感觉”就用 semantics，查 ID 或标签用 exact。

3.2 stats 与维度管理：先搞清楚记了什么

跑一段时间后，记忆库会积累很多内容。用claude-mem stats可以查看总的记忆数量、数据库大小、按维度分类的统计。维度（dimension）是 claude-mem 对记忆做的分类，默认有coder（编码）、work（工作）、personal（个人）三类。每个记忆条目在提取时都会被归类，方便你按维度筛选和搜索，避免把个人偏好和工作决策混在一起。

3.3 wipe 与日志：该清理时别手软

记忆库不是越大越好。如果你的工作内容高度碎片化，摘要质量参差不齐，时间久了库里可能充满噪声，反而会影响注入时的上下文质量。这时候有两个选择：

claude-mem wipe # 清空整个记忆库 claude-mem wipe --dimension coder # 只清空某个维度

我建议平时多用--dimension做定点清理，而不是动不动整体清空。另外，调试时用claude-mem logs查看运行日志，或者设置CLAUDE_MEM_DEBUG_FILE环境变量把详细日志写到文件里，排查 hook 是否正常执行非常有用。

3.4 定时提醒：把记忆变成主动服务

claude-mem 还有一个容易被忽略的功能：提醒（reminder）。你可以给某条记忆挂一个时间标签：

claude-mem remind --tag "重构计划" --time "2025-03-01 10:00"

到了时间点，Claude Code 在 session-start 时会把这条提醒注入上下文，相当于一个由 AI 驱动的待办事项提醒。这个功能我用来追踪跨周的开发计划，比如某个技术债需要在两周后处理，记下来就不用自己惦记了。

4. 把 claude-mem 嵌入日常 coding 工作流

4.1 会话开场：让 Claude 带着“记忆”来上班

安装好之后，我调整了自己的工作习惯。以前开一个新会话，第一件事是贴项目结构、贴技术栈、贴需求背景，现在这些都不用了。Claude Code 启动时，claude-mem 会把相关记忆注入系统提示词，Claude 会主动“回忆起”我的偏好。

比如我之前的记忆库里有一条“用户偏好：代码注释用中文，提交信息按 Conventional Commits 规范”，新会话里我让它写一段代码，它会自动按这个风格来，完全不需要我重新交代。这个体验带来的效率提升是立竿见影的，从“人教 AI”变成“AI 记得人”。

4.2 会话收尾：关键结论自动沉淀

session-end hook 会在每次会话结束时运行提取逻辑。但这里有一个细节：提取质量高度依赖会话本身的内容质量。如果你在会话里跟 Claude 聊了一堆临时调试日志，或者来回试错了几十次，摘要可能抓不住真正的结论。

我的做法是，在会话临结束前，明确跟 Claude 说一句“把我们这次确定的方案总结一下，包括选型理由和注意事项”。这句话会让对话末尾出现结构化的总结文本，claude-mem 提取时更容易抓到关键结论。说白了，claude-mem 是“最后一道提炼工序”，你给它什么质量的对话原料，它就产出什么质量的记忆。

4.3 与 CLAUDE.md 的分工：静态文档与动态记忆

很多人会拿 claude-mem 和 CLAUDE.md 做对比，我个人的结论是：两者是互补关系，不是替代关系。

• CLAUDE.md 是项目仓库里的静态文件，记录项目结构、开发规范、环境要求这类相对固定的信息，随代码库版本管理。
• claude-mem 是用户本地的动态记忆库，记录的是跨项目的个人偏好、会话中临时做出的决策、阶段性结论。

实际用下来，我会把最核心的、需要团队共享的信息放 CLAUDE.md，把自己私人的、跨项目的偏好和临场结论交给 claude-mem。这样队友也能共享项目级别的上下文，而 claude-mem 专注于服务你个人的 AI 使用体验。

4.4 多项目切换：从“重新认识项目”到“无缝续接”

我手上经常同时维护三四个项目，每天在它们之间来回切换。以前每次切换，都要花好几分钟回忆上次在这个项目里做到哪一步、决定了什么。用了 claude-mem 之后，切项目变成了一件很轻松的事：新会话开始后，Claude 会根据记忆库自动识别出“哦，你在搞这个项目”，接着上次的讨论继续。

这种“无缝续接”的体验，是 claude-mem 最让我上瘾的地方。它改变了我的工作节奏——从一个一个孤立的会话，变成一条连续的工作流。你可以在早上用一个会话做一个项目的需求分析，下午切到另一个项目写代码，两个会话之间不需要任何人工交接。

5. 实测中的失败模式与排查经验

5.1 上下文膨胀问题：记忆注入过多反而有害

我刚用 claude-mem 时踩过一个坑：跑了一两个星期后，发现 Claude Code 的响应速度变慢了，而且早期会话开头会突然冒出一堆无关的旧记忆。排查下来是记忆库累积了太多条目，session-start 时全部注入导致上下文被大量占用，还干扰了 Claude 对当前任务的理解。

这个问题有两个解法。一是定期用claude-mem wipe --dimension清理无关内容，保持记忆库精炼。二是注意看自己的记忆条目质量——如果某条记忆本身信息密度低，比如“用户今天开了三个会”，这种条目留着只会增加噪声。claude-mem 官方也提供了环境变量来做阈值控制，比如CLAUDE_MEM_SESSION_CUTOFF可以只注入最近一段时间内的记忆，避免老旧的过时信息干扰当前决策。这个变量默认不是完全限定所有时间的，我建议根据自己会话频率设一个合理值，比如"24h"或"7d"，让注入的记忆更贴近当前工作上下文。

注意：记忆注入是每一句话都会伴随的上下文，所以记忆数量一定不是越多越好。宁可少而精，不要多而杂。

5.2 hook 失效：最隐蔽的配置问题

有一次我调整了 Claude Code 的配置，之后发现 claude-mem 罢工了——session-end 不再执行，记忆库停在旧状态。检查很久才发现，是 Claude Code 版本升级后 hooks 配置项的位置变了，旧配置被新版本忽略。这种情况不会报错，只是静默失效，最坑的是你根本不知道它失效了。

排查方法是：执行claude-mem check，它会检查当前环境配置是否正确、hook 是否注册成功，并提示问题所在。另外，平时可以偶尔跑一下claude-mem stats，如果发现自己已经工作了两三天记忆库却没有任何变化，大概率 hook 已经失效了，而不是“没什么值得记的”。

5.3 语义搜索不准：不是工具的问题，是记忆的问题

有一段时间我觉得search --term "xxx" --search-type semantics搜出来的结果很离谱，跟想找的记忆八竿子打不着。后来仔细看才发现，问题出在记忆条目本身——很多历史对话被摘要后，存储下来的叙述很模糊，比如“讨论了一些优化方案”，语义向量自然不精准。

这时候应该提升源头质量，在会话中让 Claude 把结论写得具体一些，而不是指望搜索端“变魔法”。另外，结合精确搜索（exact）按关键词定位，比纯语义搜索更可靠。说到底，claude-mem 的语义搜索是“锦上添花”，前提是记忆本身得是“锦”。

5.4 信息安全边界：本地明文存储的注意事项

claude-mem 的记忆存储在~/.claude-mem目录下，格式是 SQLite 明文数据库，没有任何加密。这意味着本机有读取权限的进程都能看到你的记忆内容。如果你是存量敏感信息比较多的人，比如内部 API Token、客户数据、个人隐私，入口前要想清楚——哪些话不该让 claude-mem“记下来”。

我自己的处理原则是：涉及密钥、密码、Token 的内容，刻意不在 Claude Code 会话里贴，或者贴完马上在记忆库里把对应条目删掉。另外，如果你在团队共用的机器上工作，用之前先想好隐私边界。这不是 claude-mem 独有的问题，所有本地记忆工具都一样，但它值得被重视。

6. 更进一步：自定义记忆维度与生态对接

6.1 维度设计：给记忆建立自己的分类体系

默认的三维度（coder work personal）对大多数人够用，但如果你希望记忆更精准，可以自己造维度，也很简单——在~/.claude-mem/dimensions/目录下新建一个 md 文件，文件名就是维度名，比如project-notes.md。然后在对话中明确告诉 Claude “这个信息记录到 project-notes 维度”，claude-mem 提取时就会尝试归入对应维度。

我个人的维度设计是一个learned-commands维度，专门记录不同项目里的特殊命令和脚本用法。以前经常忘记某个项目的冷门命令，现在直接claude-mem search --term "xxx" --dimension learned-commands，一搜一个准。自定义维度的好处是，你在不同项目、不同工作类型之间的记忆边界是清晰的，不会互相污染。

6.2 在 Cline 或其他 AI 编码工具里复用

claude-mem 的官方支持重点是 Claude Code，但它的 CLI 本身足够通用：提取逻辑（--extract）和注入逻辑（--inject）都是独立命令，理论上任何支持 hook 机制的 AI 编码工具都能接上。比如 Cline 也有类似的 hook 配置，只要把相同命令挂到对应事件上就行。

我自己试过在一个支持 custom instruction 的编辑器插件里手动拼接 claude-mem 的输出，效果虽然不如原生 Claude Code 无缝，但也够用。这种“复用”的本质是：claude-mem 是一个独立的记忆服务，而不是 Claude Code 的专属功能。想接入其他工具时，只要搞明白对方的事件触发机制，就能把同样的命令接进去。

6.3 环境变量调优：让记忆更贴合你的工作节奏

claude-mem 有不少环境变量可以调节行为，我挑几个实际作用最明显的列在下面：

这些变量通常在 shell 的 rc 文件里 export 出来，或者在 Claude Code 的环境配置里设置。注意每个人的工作负载不一样，别人的参数组合未必适合你，建议用默认值跑一周，观察哪些地方让你觉得“多此一举”或“不够用”，再针对性调节。

6.4 项目维护视角：社区的活跃度与迭代速度

claude-mem 是一个开源项目，版本迭代速度相当快，我在使用的这两个月里就经历了两次功能更新。关注它的 GitHub Releases，升级前先看 changelog，因为有些版本会引入配置格式的改动（比如维度定义文件的兼容性）。我遇到过升级后旧维度失效的情况，虽然不急，但提醒我养成了一个习惯——升级前查一下自己的 claude-mem 版本，先备份~/.claude-mem目录，再动手。

备份命令也简单：

cp -r ~/.claude-mem ~/.claude-mem.bak

一个目录的事，整个记忆仓库都在里面，备份习惯值得养成。

claude-mem 这类工具的核心价值，不是让 AI“记住”，而是让 AI 变成真正了解你工作方式的长期伙伴。它在你和模型之间加了一层常驻的“工作记忆”，把碎片化的会话串联成一条完整的项目时间线。用了两个月之后，我最直观的感受是：它能让我更愿意把一个念头细化成真实工作，因为每一步决策都不怕丢，AI 始终带着“我们上次怎么商量”的上下文，跟我继续往下走。如果你也在高频使用 Claude Code，建议今天就装上试试，先跑通自动记忆，再根据自己的使用节奏去调维度、做清理——你会明显感到，那个“每次都要重新认识的 AI”，终于开始真正懂你了。