claude-mem：为Claude Code构建跨会话记忆层的深度教程

我大概花了三个星期折腾 claude-mem，才真正搞明白它跟“给 AI 塞一段 prompt”完全是两码事。最开始的场景特别实在：用 Claude Code 写一个多模块的项目，上一轮聊完目录结构、约束条件，下一轮开新会话，模型全忘了。文件名、依赖关系、哪些地方有坑，全部要重新讲一遍，一天里有半天时间都浪费在重复描述背景上。claude-mem 解决的就是这个——把会话间的记忆单独抽出来，让 Claude 在每次对话前自动“想起来”之前聊过什么。

这东西适合谁？如果你不是偶尔玩一下 AI 助手，而是天天拿 Claude Code 写代码、管项目、维护一堆配置，那你迟早会遇到“上下文断层”的问题。愿意花 20 分钟配好这个记忆层，后面每天的对话效率能提升一大截。下面我会把 claude-mem 的设计思路、安装配置、核心原理和排障经验完整过一遍，内容以我实际测试的版本为准，配置细节会有一些我的个人调整，但整体流程是可以直接照着做的。

1. 这项目到底解决什么问题

1.1 会话隔离的痛，比你想象的更严重

先拆一下最核心的需求。大模型的上下文窗口再怎么长，也救不了“跨会话记忆”这件事。你可以用 20 万 token 的上下文把整个项目塞进去，但新开一个会话，上下文就是空的。Claude Code 这类工具本身有 CLAUDE.md 这种项目记忆文件，但它更多是静态规则，不会因为你昨天在对话里说了一句“这个模块用 Python 重写”就自动更新。

claude-mem 做的事情，是把“对话历史”变成“可检索记忆”。它不只是存聊天记录，而是从对话里提取关键信息，比如项目偏好、技术决策、用户习惯、命令别名，然后把这些信息结构化地存起来，在下一次会话开始的时候，自动注入到系统提示词里。

这解决的是一个非常高频的痛点：同一个项目、不同会话、不同日期，你反复跟 AI 确认同一个约束。比如“测试数据库不要用生产环境的 IP”，这句话你在会话 A 里说了三遍，在会话 B 里又得说一遍，在会话 C 里还得说。有了长期记忆层，这些话只需要说一次，后续所有会话都默认知道。

1.2 claude-mem 的三条记忆管线

用了一段时间之后，我发现 claude-mem 其实不是单个功能，而是三条并行的管线在跑。

第一条是“对话摘要管线”。每次对话结束，它会调用一次模型，把本次会话的核心信息总结成结构化条目。这个摘要不会搞成完全按时间倒序的流水账，而是提取“决策”、“偏好”、“事实”三类信息。比如你在对话里说“以后所有新脚本都用 Python 3.11 写”，这会被归到“偏好”；你说“auth 模块已经重构完了，旧接口保留兼容层”，这归到“项目事实”。

第二条是“记忆注入管线”。这是最关键的。每次 Claude 启动新会话，claude-mem 会把之前所有相关的记忆内容拼接成一页“回顾”，以系统提示的方式塞进上下文。这样 Claude 一开始就知道你之前的偏好，不用你重新讲一遍。

第三条是“记忆过期与清理管线”。记忆不是越多越好，过期的信息如果一直留在里面，反而会误导模型。claude-mem 会根据记忆的访问频率和时间戳做权重计算，太久没用到且不再适配当前上下文的记忆，会逐步降权，甚至清理掉。

这三条管线配合起来，才叫真正的“记忆”，而不是一块只会堆积数据的硬盘。

2. 工具选型与核心架构解析

2.1 为什么用 SQLite + JSON，而不是向量数据库

我一开始以为 claude-mem 会靠 embedding 加向量检索来实现记忆召回，毕竟现在聊记忆就绕不开向量数据库。但实际看它的实现，核心存储用的是 SQLite，记忆内容以 JSON 结构化字段存进表里，检索是基于关键词和元信息过滤，而不是语义向量。

这个选型我是琢磨过一阵子的。对日常对话记忆来说，向量检索固然能解决“语义相近”的问题，但它有三个痛点：第一，需要额外维护 embedding 服务，部署成本和调用延迟都会增加。第二，向量召回的结果不一定解释得清楚，出问题了很难排查。第三，对话记忆里很多信息本来就是强结构化的，比如“语言偏好”、“项目路径”、“技术栈”，这些用关系型查询反而又快又准。

所以 claude-mem 走了一条更务实的路。记忆条目保留了结构化字段，包括主体、属性、上下文出处，适合用 SQL 做精确匹配。同时它也保留了一段原文 summary 文本，在做全文匹配时用 SQLite 的 FTS 机制，速度和精度都不错。实际测试下来，几千条记忆的检索响应在毫秒级，完全满足需求。

2.2 记忆注入的时机和方式

记忆注入是整个项目里最讲究设计的地方。注入太早，干扰 Claude 理解当前用户的首条消息；注入太晚，可用的上下文信息就错过了首次推理。claude-mem 选择在对话初始化的 hook 阶段完成注入，把记忆内容和 Claude Code 自带的系统提示词放在同一层级，而不是混在用户消息里。

这种设计的好处是，Claude 会把记忆视作“稳定的背景设定”，而不会误以为那是用户新提出的要求。如果记忆文本是放在用户消息里的，模型可能会认为你正在给它下达新指令，行为就会飘。放在系统层就能规避这个问题，模型对这类内容的置信度处理也比较可控。

另外一个关键点是注入上限。不是所有记忆都往上下文里塞，claude-mem 在生成回顾内容时会做一次裁剪，默认保留跟当前项目路径匹配最紧密的 8-12 条记忆，多余的部分只保留标题供按需展开。这个设计非常务实，不然记忆攒多了以后，每轮对话光记忆就要吃掉几千 token，成本直接失控。

2.3 项目路径与记忆作用域

claude-mem 对记忆做了一个“作用域”的概念，不是所有记忆都会跨项目全局生效，它分了三层。

第一层是全局限时记忆，覆盖所有项目，比如你个人的代码风格偏好、常用工具链。第二层是项目级记忆，绑定了具体的项目目录，只有在该目录下启动 Claude 时才会注入。第三层是会话级记忆，只对当前会话有效，相当于短期工作记忆。

这个分层能够避免一个让人抓狂的问题：你在 A 项目里说“这个项目不用 TypeScript”，结果跑到 B 项目去写代码，Claude 把这句话也当背景板给记住了，导致 B 项目里所有前端代码都被迫绕开 TS。这种跨作用域污染在简单的聊天机器人记忆方案里非常常见，claude-mem 用作用域过滤就干净了很多。

存储结构上，每条记忆记录都打上了 scope 标签，用 JSON 字段存作用域类型和路径，查询时先用 SQL 做一次粗筛，匹配作用域范围，再做精排。

3. 从安装到落地，完整实操

3.1 环境准备与安装

先说环境。claude-mem 是 Node.js 生态的工具，以 CLI 方式随项目运行，不是常驻后台服务。所以前提条件很简单：机器上有 Node.js 18 及以上版本，安装了 Claude Code CLI，同时你本地有可用的 Claude API 凭证。

这里我直接给安装命令，npm 全局方式实测最省事：

npm install -g claude-mem

安装完后验证一下版本号：

claude-mem --version

如果输出版本号，说明核心程序已经就位。接着需要让它和你本地的 Claude Code 配置对接。安装过程会自动检测 Claude Code 的配置文件目录，但你最好手动确认一下路径，因为不同版本、不同操作系统的配置目录并不完全一样。我这边是 macOS，路径在~/.claude/。Linux 上通常是~/.config/claude/，Windows 上则在%USERPROFILE%\.claude\。

注意：如果你之前自定义过 Claude Code 的配置文件，装完 claude-mem 之后要检查一下 hooks 配置有没有被覆盖。实践中有遇到过安装器把原配置整段替换的情况，务必在安装前备份~/.claude/settings.json。

3.2 初始化：把记忆仓库建起来

安装完成还差最后一步，初始化记忆仓库。这个动作会创建一个 SQLite 数据库文件，以及配套的记忆索引目录。

claude-mem init

命令执行后会问两个问题，一个是数据库存放路径，默认放在用户目录下的.claude-mem/文件夹；另一个是默认记忆作用域，选“项目级”通常比较稳妥。

初始化完成后，数据库文件会出现在指定目录，文件名一般是memory.db。这不只是一个简单数据库文件，claude-mem 还会创建一个config.json来记录工具自身的配置，比如注入记忆条数的上限、摘要调用的模型参数。

建议你打开这个 config.json 看一眼，里面有两个参数值得提前改：

{ "maxMemoriesToInject": 10, "summaryModel": "claude-3-5-haiku" }

maxMemoriesToInject控制每次注入多少条记忆，默认 10 条。如果你的项目特别复杂，上下文窗口够大，可以小幅调到 15，但别贪。summaryModel控制生成摘要用哪个模型，如果你不差钱、希望摘要质量更高，可以换更强的模型，但对大多数使用场景来说，轻量模型就够了。

3.3 核心命令实战：手动记一条笔记

claude-mem 并不是完全靠自动摘要，它也支持手动写入关键记忆。这些笔记会立即生效，不需要等对话结束后再异步处理。

比如你在跟 Claude 聊方案的时候，突然想起来一个硬约束“生产服务器不允许直接 FTP 上传”，你可以直接记下来：

claude-mem add "生产服务器不允许直接 FTP 上传，所有部署必须走 CI/CD 流水线"

执行完这条命令，这条记忆会立即写入数据库，并打上当前项目作用域的标签。后续只要在同一个项目目录下开新会话，这条约束就会被自动注入到 Claude 的上文里。

如果你想知道当前项目已经积累了哪些记忆，直接查一下：

claude-mem list

输出会按“最近更新时间”排序，每条记忆带一个 ID，方便后续删除或修改。我用过一段时间之后发现，手动记录这个能力才是整个工具的核心用法——AI 自动摘要偶尔会抓到一些不重要的事实，而你手动记下的东西，一定是你真正在乎的约束。

删除一条不需要的记忆也很简单：

claude-mem delete 123

123 就是 list 输出里的记忆 ID。

4. 核心机制实现原理

4.1 对话里发生了什么：注入与追加

要深入理解 claude-mem 的工作方式，得从一次完整对话的链路说起。

当你执行claude进入一个项目目录时，Claude Code 会加载项目配置和 hooks。claude-mem 在PreToolUse这个 hook 阶段做了一次记忆注入。它会先检查当前工作目录哈希，匹配对应作用域，然后从 SQLite 里拉取记忆列表，经过相关性排序和条数裁剪后，替换掉默认注入的空白上下文，把记忆文本以“项目历史回顾”的形式交到 Claude 手里。

这个动作在用户跟 Claude 说第一句话之前就已经完成了。所以你几乎感觉不到它的存在，但 Claude 的表现确实不一样了，因为它的“背景知识”里已经有了你之前沉淀的约束和偏好，回答问题时天然会把它们考虑进去。

对话过程中，claude-mem 会持续监听消息流。每当用户消息发送时会标记一条时间戳，在收到 Claude 的回应之后，会把这一段对话的文本暂存在内存里。这个临时记忆不是每轮都写数据库，而是攒到一定长度或者对话结束的时候，才触发一次摘要。

4.2 摘要生成的完整步骤

摘要生成的过程大致是这样的：

1. claude-mem 把本次对话的完整文本按 token 分段。
2. 每一段丢给摘要模型，让它提取“用户明确表达偏好”、“项目技术决策”、“下一步待办事项”三类信息。
3. 提取结果与数据库已有记忆做一次去重比对。如果发现某条信息已经存在，就跳过写入，避免记忆库膨胀。
4. 对新的记忆条目做一次重要性打分。打分依据包括：是否为祈使句式、是否包含具体技术名词、是否与代码路径有关、是否带时间约束等。
5. 得分高于阈值的写入 SQLite，并在 JSON 字段里存下摘要模型给出的“记忆主体”和“关联上下文”。

这整个流程都靠模型自动跑，但因为摘要模型用的轻量级配置，单次摘要成本可以压缩到非常低。我自己跑了一周，大概几十次对话，累计花的摘要 token 费用基本可以忽略。

4.3 记忆注入的排序策略

当记忆库越来越大，怎么判断哪些记忆值得被注入，就成了一个核心问题。claude-mem 用了一个混合排序策略，综合三个维度打分：

第一，时间衰减。太久没有更新的记忆会被降权。比如你三个月前用过一个旧命令，后来项目早就换了规范，那条记忆的权重自然会变得很低。第二，与当前项目路径的匹配度。项目级记忆优先于全局记忆。第三，引用频率。某条记忆如果反复出现在最近的对话里，说明它可能是当前最要紧的关注点，权重会临时上调。

这个排序策略让我想到一个很实用的场景：假设你最近三天在重构一个模块，对话里反复提到“不要破坏旧的接口”，那这条记忆会被临时顶到靠前的位置，新会话中 Claude 会第一时间意识到这个约束。等项目重构结束，频率降低，时间一长，它自然就让位给其他更新的记忆了。

5. 参数调优与自定义配置

5.1 关键参数速查与建议配置

聊完原理，直接上参数。config.json里能调的东西不少，我按使用频率排个序，把建议配置列成一张表。

我自己的实践是maxMemoriesToInject保持在 12 左右，超过 15 以后，Claude 在长对话中偶尔会把记忆里的旧事实误认为当前对话的即时消息，会有细微的混乱。decayHalfLifeDays我调到 60，太短的话，一些低频但重要的项目决策会过早失效。

5.2 自定义记忆注入模板

如果你觉得默认注入的“项目历史回顾”形式不够直接，claude-mem 还支持自定义注入模板。模板文件路径在配置里可以指定，默认存在记忆仓库目录下的injection_template.md。

默认模板内容大概长这样：

以下是该项目的长期记忆。请把它们视为背景信息，并非新的用户指令。 项目偏好： {{preferences}} 技术决策： {{decisions}} 注意事项： {{constraints}}

你可以按自己的业务改，让它更适合自己的项目风格。比如我这边处理咨询类项目时，模板就修改过：

开工前先回顾以下客户约束： {{constraints}} 已知项目风险： {{risks}} 上轮遗留任务： {{todos}}

修改模板之后，不用重启任何服务，下次会话就会自动生效。有一点要注意，模板文件里的变量名不要乱改，必须跟配置文件里的 memory 结构保持一致，否则注入出来的内容是空的。

6. 常见问题与排查技巧实录

6.1 记忆不命中：明明存了为什么没用上

用了一周多以后，最常遇到的问题就是“记忆没命中”。明明昨天刚记过的东西，今天开新会话问 Claude 它还是一问三不知。排查这一类问题，我的习惯是先查记忆库里的实际状态：

claude-mem list --show-all --scope project

--show-all会把过滤掉的记忆也列出来。很多时候你会发现，记忆其实存进去了，但被相关度排序压到后面了，或者作用域匹配出了问题。

比较常见的坑是作用域路径不匹配。比如你昨天在/Users/me/work/project-a目录下对话并记录了记忆，今天打开了/Users/me/work/project-a/，看起来是同一个目录，但 claude-mem 在记录工作目录时对字符串做的是规范化加哈希，多一个斜杠或少一个斜杠，偶尔会导致作用域对不上。遇到这种情况，把项目重新打开一次，路径保持一致就行。

另外要检查的是注入条数限制。如果你最近在某条记忆上频繁更新，旧记忆的时间衰减会把新记忆顶掉，这是正常现象。如果你希望某条记忆一直保持高优先级，就直接手动加，并且在开头加前缀[PINNED]，claude-mem 对带这个前缀的记忆会跳过衰减排序，始终优先注入。

6.2 SQLite 锁定和并发问题

因为 claude-mem 用的是 SQLite，并发写入时偶尔会遇到database is locked的报错。一般在快速连续开多个会话、或者手动批量写入记忆时容易出现。

我的实践经验是：如果遇到 database is locked 报错，不用急着删数据库，99% 的情况是之前的进程还没释放写锁。可以等几秒，或者在命令行执行一下：

claude-mem flush

这个命令会强制把缓存中的写入动作落库。如果 flush 之后还报错，才需要考虑是不是有长连接进程卡住了。

更保险的做法是，不要手动频繁执行claude-mem add，尽量依赖自动摘要。自动摘要的写库频率被刻意控制在较低的节奏上，就是为了减少锁冲突。

6.3 记忆内容过时或错误怎么修正

记忆是模型生成的，必然会出错的。有些摘要模型会把对话里的不确定性描述当作确定结论记录下来，比如你说“这个接口可能要重构”，它可能直接记成“接口需要重构”，过了几天就变成误导信息。

修正记忆的正确思路不是删掉重写，而是更新这条记录的置信度。claude-mem 的命令行支持一个比较隐蔽的 flag：

claude-mem update 123 --content "新的正确描述" --confidence high

更新之后，旧的文本会被标记为“已修正”，不会再参与注入。不要因为一条记忆错了就把整条删掉，因为“旧结论被推翻”这件事本身也是有价值的上下文，如果后续对话再问到，Claude 能看到修正历史，就不会再犯同样的错。

6.4 排查工具速查表

最后整理一个我实际排障时用得最多的速查表，覆盖了 90% 的操作：

prune和factory-reset这两个命令都要谨慎。prune --dry-run会先输出“如果执行清理会删除哪些记忆”的预览列表，我建议永远先跑 dry-run 再决定。factory-reset 是把整个数据库推倒重来，非必要别用，重建记忆库确实很快，但丢失的历史关联信息会直接影响后面很多轮对话的连贯性。

7. 进阶用法：让记忆从“存储”变成“思考的一部分”

7.1 项目周报自动生成

claude-mem 的记忆结构是高度结构化的，这意味着你可以通过脚本二次加工这些记忆，让它从“给 Claude 看的上下文”变成“给你的运营数据”。

我实际做过一个最满意的事情：每周五下午从 claude-mem 数据库里导出这一周的项目决策和注意事项排序，然后用模板生成一份周报。实现方式不难，就是查数据库里时间戳字段和决策类型字段，按频率排序，最后渲染成 markdown 表格。

这个用法本质上是在复用 claude-mem 已经做好的“提取结构化信息”能力。你不用自己写 Agent 去读聊天记录，因为摘要已经对话语料里的关键事实提炼出来了。

7.2 多项目全局偏好沉淀

前面说过全局记忆和项目记忆的隔离，这一点在同时维护多个项目时价值巨大。我自己的习惯是把个人的代码风格偏好全部记录为全局记忆，比如“变量命名优先用描述性长名，不要缩写”、“注释要写清楚为什么而不是写是什么”。这些偏好一旦写入全局记忆，每个项目里的 Claude 都会自动遵守。

而且我发现一个细节：全局记忆的优先级默认低于项目记忆，这意味着项目里如果有特殊要求，可以覆盖全局规则。这保证了个性化和规范化的平衡。

7.3 实验 Agent 工作流的记忆回放

最近我在尝试更进阶的玩法：把 claude-mem 当作轻量 Agent 工作流的状态存储层。当 Claude 需要在一个多步任务中记住“用户登录模块已完成 30%、数据库表结构已最终确认为 v3”这类半路状态时，我可以手动把这些中间态写进记忆库，然后让 Agent 在下一步开始时自动读取。

这种用法已经超出了“跨会话记忆”的原始定位，变成了 Agent 工作流的纵切面。不过我建议先等基础记忆功能稳定跑上一周，再来搞这些复杂场景，否则中间态一旦被自动摘要逻辑误改，反而会打乱整个工作流。

8. 我踩过的坑与最终建议

8.1 三个容易翻车的细节

第一，不要把所有东西都记成全局记忆。全局记忆跨项目生效，偶尔会出现“上下文污染”的隐性事故。我刚开始贪方便，把所有项目规范都设为全局，结果在 A 项目写下的规范在 B 项目里也生效了，B 项目的代码风格就开始混。现在我的铁律是，技术栈相关的一切都走项目级记忆，只有纯个人习惯和通用工具偏好才进全局级。

第二，自动摘要不是即时的。它会在对话结束或 token 阈值触发时异步执行。如果你刚在对话里说了个关键约束，马上开新会话测试，有概率发现 Claude 还不知道，这是正常的。给摘要留几十秒时间落库，或者直接用claude-mem add手动记录高优先级的约束。

第三，记忆条数是需要养护的。我用了一个多月之后，记忆库变得非常庞大，最终明显感觉到 Claude 的对话质量在轻微下降，因为旧记忆和当前任务的关联变弱了。定期执行 prune 维护记忆库，比省那些 token 重要得多，过期无效信息对模型回答的干扰是真实存在的。

8.2 什么时候你不要用 claude-mem

这工具不是万能药。如果你的使用场景是纯闲聊、一次性的问题解答、或者每次会话都和项目背景无关，那记忆层反而会成为干扰。尤其是全局记忆里积累了不合适的内容之后，模型的回答风格会被拖偏。

另外，对隐私高度敏感的代码库和对话，在引入任何记忆工具之前都要三思。claude-mem 的数据库文件默认是明文 SQLite，里面存的就是你全部对话的摘要。如果你在本机单用户环境，问题不大，但如果你有同步目录或多用户共享的工作区，建议把数据库目录和配置文件加入.gitignore，并考虑对数据库文件整体加密。

8.3 最后的私有建议

根据我个人这一段时间的实操体会，如果你打算认真用 claude-mem，我只有一个建议：从第一天起，就把手动记录当成一等公民。自动摘要是记忆的“下限”，人工添加才是记忆质量的“上限”。你需要积累一段时间才能形成自己的维护节奏——什么时候该手动加约束、什么时候该清理旧记忆、什么时候该调整注入条数。这个节奏一旦建立起来，Claude 在工作流里的表现就不再是“每次从零开始”，而是带着你整个项目的发展脉络在思考。

顺手再分享最后一个小技巧：给常用规范类的记忆加[PINNED]前缀，让它们始终持有高注入优先级，这样即使记忆库在持续增长，最核心的那几条约束也不会被冲散。