claude-mem：给AI编程助手装上持久化记忆，告别会话失忆

说实话，我最早把 AI 编程助手当主力开发工具用的那段时间，最让我抓狂的不是它写不出能跑的代码，而是它永远记不住事。昨天刚跟它敲定的接口规范，今天新开一个会话，它就跟失忆了一样，继续按老一套来写；上周复盘时明确下来的技术选型，这周再问它，它又能列出一堆理由把自己推翻。这不是模型能力的问题，而是会话本身就是一次性的。我也试过把常用约定写进项目说明文件，但那种静态文本只能记结论，记不了过程，更做不了“当时我们讨论到一半、最后锁定了哪几个嫌疑点”这种上下文还原。claude-mem 就是冲着这个痛点来的。

它本质上是一个给 AI 编程助手用的持久化记忆层。装好之后，它会在每个会话开始、每次工具调用、每次会话结束时自动做记录，把散落在对话里的事实、偏好、决策、踩坑结论沉淀到一个本地数据库里；下次会话开始前，它再把相关记忆主动拉回来，当作“开工简报”喂给助手。同时它还以 MCP 服务的形式暴露了一组记忆工具，让助手在对话途中可以自己动手存、查、整理。整个过程不需要你手动维护文档，数据也全部留在本地。

这篇就围绕 claude-mem 这个项目，把我实际用下来的理解、配置方式、踩过的坑和排查思路完整拆开讲一遍。适合谁看？如果你正在用 AI 编程助手做长期项目，被“每次会话都从头开始”折磨得够呛，或者单纯想让助手记住你的代码风格和偏好，这篇应该能帮你少折腾好几个晚上。

1. 为什么需要一块“记忆硬盘”：AI 助手的失忆症

1.1 静态文件方案的三个短板

很多人第一反应是：不是有项目说明文件吗？把目录结构、代码规范、常用命令写进去不就行了。这个方法能用，但实际用起来有三个明显的短板。

第一，静态文件需要人肉维护。你改了一个模块的职责边界，得记得去更新说明；你昨天临时决定放弃某个方案，今天如果忘了改文档，助手还是会按旧方案给你建议。文档和代码之间的同步完全依赖人的纪律性，而人的纪律性在赶进度的时候是最先崩掉的。

第二，过程性信息表达不了。说明文件适合记“是什么”，不适合记“为什么”。比如“这个服务的重试逻辑我们改过三次，最后一次是因为下游接口超时率太高”，这种带有因果链条的信息，很难用几条 Markdown 列表说清楚，但它在后续调试里恰恰是最值钱的。

第三，兄弟会话之间完全隔离。你开三个窗口并行处理同一个项目，A 窗口里确认的结论，B 窗口完全不知道。你只能手动复制粘贴，而且复制来复制去，很快就不知道哪份是最新的。

1.2 claude-mem 的定位：把记忆变成基础设施

claude-mem 和上面这些方案最大的区别在于，它把“记忆”从一份文档变成了一个服务。这个服务自己负责记录、索引、检索、去重和归纳，AI 助手和人都只是它的使用方。

记录是自动的。它通过挂钩子监听 AI 助手的整个生命周期：会话开始、工具调用、会话结束，每一步都有对应的捕获动作。不需要你在对话里手动说“请记住”，它自顾自就能把关键动作沉淀下来。

检索是语义的。它存的不是简历式的关键词条目，而是带向量索引的文本。你下次问“之前那个超时问题我们最后怎么处理的”，哪怕你的措辞和当时完全不一样，它也能依靠语义相似度把相关记忆找出来。

归纳是持续的。同一件事在多次会话里反复出现，会产生大量重复记忆，它会在会话结束时做去重和合并，把碎片化的记录捏成一条更完整的结论。这个“整理归档”的动作，恰恰是普通文档方案里最没有的东西。

1.3 哪些场景收益最大

以我用下来的体感，下面四类场景收益最明显。

跨会话的长期项目。项目周期超过一周，每天开新会话继续干活，助手还能记得昨天的进度、待办和结论，这是最核心的价值。

个人偏好类信息。比如你习惯用土耳其式缩进、喜欢给测试函数按业务模块分组、坚持错误处理用自定义异常而不是裸抛。这些偏好分散在对话里时很难每次都重新交代，沉淀成记忆后助手会自己照着做。

多分支多任务并行。同时维护两三个功能分支，每个分支的开会上下文互不串味，靠的是记忆的会话隔离能力。claude-mem 会区分不同会话，不会让 A 分支的结论污染 B 分支的判断。

团队场景下的经验交接。同一台机器上有多个用户在使用，记忆按用户隔离，每个人的偏好和结论互不干扰。这个后面配置部分会细讲。

2. 三条链路看懂核心架构

2.1 Hook 链路：当个不问自取的记录员

claude-mem 的自动记录能力，依赖 AI 编程助手的钩子机制。你可以把钩子理解成事件回调：某个事件发生的时候，系统帮你执行一段外部命令。它不会打断对话，而是旁路触发，所以不会拖慢主流程。

我这边实际用到的钩子事件主要是三个：会话开始、工具调用结束、会话结束。配置在 AI 助手的设置文件里，大致长这样：

{ "hooks": { "SessionStart": [ { "matcher": "", "hooks": [ { "type": "command", "command": "claude-mem capture-session-start" } ] } ], "PostToolUse": [ { "matcher": ".*(Bash|Edit|Write|MultiEdit).*", "hooks": [ { "type": "command", "command": "claude-mem capture-tool-use --tool \"$TOOL_NAME\" --input \"$INPUT\" --output \"$OUTPUT\"" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "claude-mem capture-session-stop" } ] } ] } }

会话开始的钩子做两件事：一是把当前项目相关的历史记忆按相关度排好序，拼成一段简报注入到助手的上下文里；二是给这一次会话开一个新的记录上下文。工具调用结束的钩子负责捕捉具体动作——执行了哪些命令、改了什么文件、拿到了什么输出，这些是判断“这次对话产生了什么实质进展”的素材。会话结束的钩子则做收尾，把这次会话里值得沉淀的结论统一写进数据库。

这段配置我建议你把它当作一个演示模板，不要对着原样抄。不同版本的 claude-mem 有不同的初始化命令，正常情况下你执行一次初始化脚本，它自己会把钩子写进去。我后面会讲为什么我后来放弃了手动改这个文件。

2.2 MCP 链路：让助手自己动手查记忆

光有自动记录还不够。记录是单向的，助手在对话途中如果需要主动调取某一段记忆，就得靠 MCP 这一条链路。

MCP 你可以理解成一套给 AI 应用用的插件总线协议。claude-mem 在这条总线上注册成一个服务端，向 AI 助手暴露一组记忆相关的工具。助手经过授权后，就能像调用普通函数一样调用这些工具。

以我安装的版本为例，常用的工具大概有下面这些：

有一个细节很值得注意：AI 助手的大部分记忆读取行为，其实发生在会话开始前的“简报注入”阶段，那是 hook 链路做的，不走 MCP。MCP 工具更多是让助手在对话过程中做“超纲检索”。这两条链路一被动一主动，配合起来才不会出现“该想起来的没想起来，想查的时候又查不到”的情况。

这里再补充一点我的理解：为什么要把显式工具交给助手而不是全部用 hook 自动完成？因为自动捕获很难判断什么值得记。让模型在对话中遇到明确约定、关键决策时主动调用 memory_store，能显著提高记忆的精度。自动记录负责全量兜底，主动存库负责质量筛选，两者缺一不可。

2.3 存储与检索链路：SQLite 加向量检索

底层存储用的是 SQLite，这是 claude-mem 设计上非常讨喜的一点。它不要求你部署独立的数据库服务，就是一个本地文件，备份、迁移、删除都极其省事。

记忆表的结构大致是这么个形态：

CREATE TABLE memories ( id TEXT PRIMARY KEY, user_id TEXT, session_id TEXT, memory_type TEXT, content TEXT, created_at TIMESTAMP, updated_at TIMESTAMP );

每条记忆都归属于一个用户和一个会话，这就实现了前面说的隔离。检索的时候，除了传统的关键词匹配，它还通过 sqlite-vec 这个本地向量检索扩展做语义搜索。写入记忆时会把文本转成嵌入向量一起存下来，查询时把问题同样向量化，然后按余弦相似度召回最接近的几条。

这种“SQLite 单文件加向量扩展”的组合，带来的直接好处是零外部依赖。不需要调远程的检索服务，不需要维护向量数据库集群，所有数据都留在你自己的磁盘上。对隐私敏感的项目来说，这是比云服务方案舒服得多的选择。

但也要注意它的边界：本地向量检索的效果，很大程度上取决于所选嵌入模型的维度是否和扩展匹配，以及相似度阈值调得是否合理。这两个问题我在常见问题部分会专门说，因为它们是我实际踩过的最多的坑。

3. 从零跑通：安装、配置与上手

3.1 安装与初始化

先说安装。因为我这边常用的是 Python 发行版，所以走的是 pip 这条路径，大致是下面这几步。如果你的环境是其他方式打包的版本，具体命令以你拿到的仓库文档为准，但思路是一样的。

pip install claude-mem claude-mem --version

装完之后执行初始化：

claude-mem init

这一步会自动帮你做三件事：检测当前项目是否已经存在记忆目录；把钩子配置写入 AI 助手的设置文件；注册好 MCP 服务端。执行完之后，它会打印出一份摘要，告诉你它改了哪些文件，我建议你把这份摘要保存下来，后面排查问题全靠它。

初始化完成之后，最好先开一个新的会话验证一下。在对话里问一句“你能看到之前会话的记忆吗”，正常情况下助手会通过简报或者 MCP 工具给你一个肯定的答复。如果没有，先不要开始干活，直接翻到后面的常见问题部分排查，否则你会带着一个半残的配置用很久。

3.2 核心配置逐条解读

claude-mem 的配置是一个 TOML 文件，全局配置在用户目录下，项目配置则会覆盖全局配置。这个“项目覆盖全局”的优先级设计，让不同项目可以有自己的记忆策略，比如某个项目严格不存任何敏感信息，另一个项目可以放宽阈值。我自己的配置文件大致长这样：

[memory] recall_limit = 8 similarity_threshold = 0.7 deduplicate_on_stop = true consolidate_on_stop = true max_memory_age_days = 90 [hooks] session_start = true post_tool_use = true pre_tool_use = false [privacy] min_chars_to_store = 20 sensitive_patterns = ["password", "token", "api_key", "secret"]

recall_limit 控制每次会话开始往上下文里塞多少条历史记忆。这个值不是越大越好——塞太多会稀释真正重要的信息，还会白白占用上下文窗口。我个人的经验是 5 到 10 条是一个比较舒服的范围，除非你的项目特别庞杂，否则不建议超过 15。

similarity_threshold 是语义检索的相似度门槛。它决定了什么样的记忆会被当作“相关”。这个值的脾气比较倔，太严了查不到东西，太松了召回一堆噪音。我后面在排查部分会单独讲怎么用实测数据去校准它，而不是拍脑袋调。

deduplicate_on_stop 和 consolidate_on_stop 控制会话结束时的整理行为。一个负责把重复记忆合并掉，一个负责把零散记忆归纳成概括性条目。两个都建议开着，否则记忆库会像没人收拾的邮箱一样迅速膨胀。

privacy 这一段是很多人容易忽略但很重要的。min_chars_to_store 低于这个长度的记录一律不存，能过滤掉大量“嗯嗯”“好的”之类的口水话。sensitive_patterns 是敏感词模式列表，命中这些模式的文本会被拦截，不进入记忆库。存储口令、密钥这种内容，对于本地记忆工具来说是非常危险的，因为这个库会定期被召回并直接喂给模型，一旦模型把密钥当成上下文去回答问题，那就彻底失控了。

3.3 会话中的三种用法

配置好之后，日常使用无非是三种形态。

第一种是让助手显式帮你存。对话里说“记住，这个项目的构建产物统一放在 dist 目录”，助手识别到这是一个需要长期保留的约定，就会调用 memory_store 写入记忆。这里有个小技巧：存的时候把“为什么”也带上，比如“放着 dist 是因为部署脚本默认从那里取物”，这样以后召回的时候，助手能理解的不只是一个孤零零的事实。

第二种是会话开始时的自动简报。新会话打开，claude-mem 通过 SessionStart 钩子把相关记忆注入。你不需要做任何事，助手开口说话的时候，就已经带着过去的上下文了。这种“无声无息但你明显感觉它不一样了”的体验，是这套方案最值钱的地方。

第三种是主动检索。你直接在对话里问“我们之前讨论过的那个缓存失效方案，最后结论是什么”，助手会去调用 memory_recall，把相关记忆捞出来回复你。比起自己翻聊天记录、翻文档，这个查询方式明显更接近人的思维习惯。

3.4 用户、会话与项目隔离

目录结构上，claude-mem 会在项目里创建一个隐藏的记忆目录，里面放着对应项目的数据库和配置。这就实现了项目级隔离：你在 A 项目里积累的记忆，不会被 B 项目召回，因为两边用的是不同的数据库。

用户级隔离靠的是 user_id。同一台机器上多个人使用，每个人的记忆通过 user_id 区分开，互不串味。这一点在团队共用开发机或者一台机器上同时处理个人项目和公司项目时特别实用。

会话级隔离则是天然的，每条记忆都带有 session_id。不过要注意，会话结束后的记忆是可以被后续召回查询的——这正是它存在的意义。如果你想明确不让某次会话的内容被记住，可以在对话开始时先跟助手说清楚，或者临时把对应会话的钩子行为关掉。

我建议你在项目刚开始接入时，先把 user_id 配置好，并且让团队里每个人都用自己的 ID。这个决定越早做越好，因为中途再拆数据会比一开始就隔离麻烦得多。

4. 常见问题与排查实录

4.1 问题速查表

我把这段时间踩过的坑整理成了一张表，按症状、原因、处理方式排列，排查的时候照着看就行。

4.2 一次真实的排查过程

挑一个我印象最深的实战案例讲讲。前阵子我发现，记忆目录里明明已经有几百条记录了，但新会话里的助手完全没提过这些记忆，好像简报根本没生效。

我先确认了钩子在设置文件里存在，配置也没问题。然后去查统计信息，发现记忆确实在持续写入。这说明数据链路是通的，问题出在“读取”这一端。我逐条检查 SessionStart 钩子的输出日志，发现钩子命令每次执行都报错，提示找不到某个基础依赖。

为什么开头没发现？因为这个报错被吞在了后台，会话照样能正常开，只是简报注入失败了。我搜了一下才发现，是我后来装的一个终端美化工具改了环境变量，导致会话启动时钩子进程的 PATH 不完整，Python 模块加载不出来。最后在初始化的时候显式指定了解释器路径，问题才解决。

这个案例想说明两件事：第一，memory_stats 这类统计工具不只是好看的仪表盘，它是排查链路哪一段断了的第一个抓手；第二，钩子进程运行在什么环境下，比你想象中更容易被影响，排查时不要只盯着 claude-mem 自己的配置，也看看有没有其他工具动了你的环境变量。

4.3 隐私边界与记忆污染

本地存储不等于绝对安全，这点必须说清楚。SQLite 文件是单文件的明文数据库，任何能读取你磁盘的程序都能读它。所以敏感信息这一关，不能只靠 sensitive_patterns 的字符串过滤。更稳妥的做法是约定一个团队纪律：密钥、令牌、个人隐私数据，任何时候都不要在对话里出现，而不是指望记忆层帮你拦截。

还有一个容易被忽略的安全问题是记忆污染。记忆是通过语义召回注入上下文的，如果某条被污染的记忆看起来和当前问题高度相关，模型会把它当作事实采信。举个极端的例子，如果某个会话里被注入了“这个系统的 API 密钥是 abc123”，这条记忆以后被召回时，模型可能会直接在新会话里引用它。所以凡是涉及到权限、密钥、内部地址这类信息，我建议你在敏感词表里多加几组模式，宁可误杀也不要放进库里。

另外，要养成定期清理的习惯。记忆库不是越大越好，它需要和人的大脑一样定期“断舍离”。我一般每周用一次 memory_stats 看分布情况，把那些类型重复度高、内容已经过时的记忆手动清一下。实在懒得管的，至少把 max_memory_age_days 设成 90，让太老的东西自动过期。

5. 实测心得与扩展方向

5.1 用了一个月之后的真实体感

我在某个跨部门协作的模拟项目上连续用了一个多月，最明显的感觉是：助手终于像一个“跟了你一段时间”的同事，而不是一个每次见面都要重新自我介绍的实习生。它知道项目里哪几个模块是历史遗留的坑，知道我对测试用例的命名习惯，知道上个月定下的接口规范现在执行到了哪一步。

这个体感上的提升，不是某个单点的功能带来的，而是自动记录、语义召回、定期整理这三件事配合出来的综合效果。自动记录保证信息不漏，语义召回保证用得起来，定期整理保证库不腐烂。三者缺一个，体验就会明显下降。

当然也有不习惯的地方。最早期记忆库出现过一阵“什么鸡毛蒜皮都存”的时期，助手会为了一句“好的谢谢”也建一条记忆。后来我调高了最小存储长度，再配合去重，情况才好转。回头想，这其实暴露了一个调参方向上的教训：记忆系统刚开始宁可少记，也不要多记。少记最多是查不到，多记是查到了也分不清哪条重要。

5.2 记忆不是越多越好

我见过有人把记忆工具的存储上限调得很大，觉得反正磁盘便宜。但真正限制记忆价值的不是磁盘空间，而是召回质量。一个装满噪音的记忆库，召回结果里全是“今天讨论了什么”这类口水话，真正有价值的结论反而被淹没了。

所以我在实际使用里给自己定了三条规矩。一是一条记忆只说一件事，把“事实”“原因”“结论”合并成一条尽可能完整的句子，而不是记成零散的几个词。二是不怕重复，但要让去重机制去管重复——人不需要在对话里反复说“这条要记住”。三是每隔一段时间回看统计里的类型分布，如果某个类型的记忆特别多但很少被召回，说明它要么不重要，要么检索词和存储措辞对不上。

这三条看起来很简单，但它们直接决定了记忆系统的长期健康度。很多人在部署完工具后觉得“怎么还是想不起来”，最后发现不是工具坏了，而是记忆库里塞满了不值得被想起来的东西。

5.3 值得尝试的扩展玩法

用顺手之后，我逐渐给它加了几个外部联动，效果都不错。

一个是把记忆导出成周报。claude-mem 的数据都落在本地 SQLite 里，写个小脚本把本周新增的记忆按类型聚合，生成一份 Markdown 摘要，周五下午跑一次，就能当项目周报的素材。这个扩展几乎零成本，但价值非常直接。

另一个是把记忆和自动测试流程联动。每次测试失败，让 AI 助手先查一下历史记忆里有没有类似问题的处理记录，再决定是重新排查还是直接沿用旧的临时方案。这个“先查旧账再看新问题”的习惯，能省掉大量重复定位时间。

还可以做跨工具的上下文桥接。比如把某个关键会议会话整理出来的结论，通过脚本批量写入记忆库，让后续写代码的会话也能捞到会议里的决策。这一步本质上是把“开会”和“写码”两件通常割裂的事，用记忆串成了一条线。

最后再分享一个小技巧，也是我这段时间最受益的一个用法：每个周末我会抽十分钟，用命令行把本周的记忆过一遍，把过时的标记掉，把重要的提炼成一条更完整的长期记忆。这个动作听起来很土，但它比任何参数调优都更能延长记忆系统的寿命。因为再好的自动整理机制，也替代不了人对“什么东西对自己真正重要”的判断。