给Claude CLI装个“记忆库”：跨会话记忆注入的完整实践

每天跟Claude的CLI工具打交道，最折磨我的不是它回答得不好，而是它永远不记得上一个会话里我们讨论过什么。今天问清楚了接口鉴权的完整方案，明天新开一个会话，它又一脸茫然地从头猜起。这个问题困扰了我很久，直到我写了claude-mem——一个给Claude注入跨会话记忆的轻量扩展。简单说，它做的事情就是在对话之外维护一本“备忘录”，下次会话开始前自动把相关记录翻出来塞给模型看。核心链路只有三步：记录、检索、注入。这篇博文我会把整个设计思路、核心实现细节、接入工作流的方法和排查问题的心得完整写出来。如果你也正在被无状态对话折磨，或者纠结怎么给自己的命令行AI助手做持久化记忆，这篇文章应该对你有用。

1. 失忆的AI与需要记忆的我

1.1 无状态会话到底是个什么状态

先从模型本身聊起。大多数会话式AI，尤其是通过API方式接入的模型，本质上都是一个无状态函数：你给我一段文本，我还你一段文本。它不保存任何“之前发生了什么”。你在同一个客户端界面里看到的上下文连续，是因为客户端在背后把所有历史消息一遍又一遍地重新发给模型。一旦你开了一个新会话，或者切换了项目目录，历史就不存在了。

这听起来像是基本常识，但真正用起来才会感受到它的拧巴。我之前维护一个跨平台同步项目，连续几天都在通过CLI工具排查文件冲突问题。第一天确认了要用“版本向量加本地时间戳”作为冲突判断依据，第二天新开会话，我忘了带上下文，模型就开始给我推“按修改时间覆盖”这种完全相反的方案。倒不是说它错，而是它根本不知道昨天我们已经对比过三种方案，最终排除了这个选择。同样的论证又重新走了一遍，来回浪费了快一小时。

这种场景多了之后，我开始意识到：问题不在模型本身，而在于对话之外没有任何结构化的沉淀机制。聊天记录是流水账，翻起来累，也不能被自动使用。我需要的是一个独立的记忆层，让模型在每次会话开始时，能主动看到“这个项目之前已经确认过哪些结论”。

claude-mem就是奔着这个需求去的。它不试图改变模型的工作方式，也不去做微调，而是在会话和模型之间加一个外部记忆中枢。这个中枢不参与推理，只负责在恰当的时候把恰当的历史结论拿出来。

1.2 哪些场景最适合外挂记忆

不是所有使用场景都需要永久记忆，我用了几个月下来，觉得有几个场景收益特别明显：

• 长期项目维护。架构决策、接口约定、历史bug的根因分析，这些内容一旦确认，短期内不会变。与其每次重新讨论，不如记下来直接复用。
• 个性化风格保持。比如你要求代码输出严格遵守某种命名规范，或者文档必须带使用示例，这种偏好属于全局级记忆，任何会话都应该生而具有。
• 多步骤工作流。今天做到一半的迁移方案，明天接着做，模型需要知道昨天已经完成了哪几步、卡在哪个环节。
• 脚本化批量调用。用命令行工具写自动化脚本时，如果每次调用都无状态，很难让模型在连续多轮任务中保持一致口径。

反过来说，有些内容不适合记忆，比如一次性问答、跟项目无关的闲聊、时效性极强的实时信息。把这些也塞进记忆库，只会让检索噪声变大，反而把真正重要的结论淹没了。这个“记忆边界”的问题，后面专门讲。

2. claude-mem怎么设计才不失控

2.1 先想清楚：外挂记忆不是微调

很多人一听“让模型记住历史”，第一反应是做微调。这个思路方向其实不对。微调适合让模型学习一种稳定的能力模式，比如学会某种代码风格、学会某种文档格式。但要让它记住“昨天我们决定用A方案不用B方案”，微调既慢也不灵活，而且一旦结论变化，你没法让模型快速忘掉旧知识。

外挂记忆最大的优势是实时可写、实时可查、实时可删。它和模型本身完全解耦，今天加一条记忆，下个会话立刻生效；发现记错了，直接改文件或者删除，效果马上纠正。这比重新训练轻量得多，也符合个人工具、小团队工具的定位。

我把claude-mem定位成“第三层”。第一层是模型权重，负责推理能力；第二层是客户端上下文窗口，负责当前会话的连贯性；第三层就是记忆库，负责跨会话的知识沉淀。前两层都不归我管，我只需要把第三层做好。

2.2 存储、检索、注入三段的选型

整个记忆系统拆开看，就是存储、检索、注入三段。

存储端，我一开始在纯SQLite、JSON文件、Markdown文件之间犹豫。纯SQLite的好处是查询方便、索引强大，但坏处是内容不可读，你没法直接打开数据库浏览一条记忆长什么样，手工修改更麻烦。JSON文件结构灵活，但嵌套多了以后人眼很难快速扫描。最后我选了“Markdown文件为主，SQLite索引为辅”的混合方案。记忆正文用Markdown文件保存，每个文件一条记忆，文件名就是记忆的简短标题，文件头部用YAML front matter存元数据。SQLite只用来建全文索引和标签索引，方便快速检索。

这个方案实测下来很舒服。日常浏览记忆时，直接用编辑器打开目录，扫一眼文件列表就知道记了什么。要修改一条记忆，直接编辑Markdown文件。而检索时又可以利用SQLite的FTS全文搜索来提升速度。相当于同时拿到了人类可读性和机器可查性。

检索端，我采用两级策略。第一级是粗筛，用关键词、标签、项目名过滤出一个候选集。第二级是精排，对候选集做相似度打分，把最相关的排到最前面。粗筛保证效率，精排保证质量。后面的章节会详细展开打分公式。

注入端，核心矛盾是token预算。模型上下文窗口是有限的，记忆不能无限制地塞进去。我采用的策略是：给记忆注入分配一个固定预算，比如总上下文的20%，超出预算的部分按权重截断。高重要性、最近更新、与当前问题词面相似度高的记忆优先保留。

2.3 整体架构与模块划分

claude-mem的架构并不复杂，核心就四块：

这个分层的好处是每一块都可以独立替换。比如你今天不想用SQLite，想换成纯文件扫描，只改存储层就行，写入层和注入层完全不受影响。我第一次实现时就因为分层清晰，给检索层换方案只花了不到半天。

3. 核心实现细节逐个拆

3.1 记忆文件：一份人能看懂、机器能检索的Markdown

记忆文件是整套系统的地基，所以格式设计我花了很多心思。先看一下一条记忆的实际文件内容：

--- tags: [接口鉴权, 网关, 限流] project: cross-platform-demo importance: high status: active created: 2025-01-10T14:22:00+08:00 updated: 2025-01-15T09:30:00+08:00 --- # 接口鉴权统一走新网关 在模拟项目X中，联调环境里所有接口鉴权统一走新网关，旧网关只保留灰度流量。 2025年1月起，新接入的服务必须直接对接新网关，不要再单独申请旧网关权限。

为什么用YAML front matter？因为它能把结构化的元数据和正文分开，机器解析起来非常方便。字段的设计是有讲究的：

• tags：检索时的第一道筛子，多打几个标签通常不会错，但要避免过度打标，否则标签本身就失去区分度。
• project：记忆的归属项目，避免多项目内容互相串场。
• importance：优先级标记，high表示关键结论，normal表示一般背景，low表示可记可不记的内容。
• status：记忆的生命周期状态。这个字段很关键，因为不是所有结论都永远成立。方案变更了，旧记忆就应该标记成superseded或者archived，不再参与注入。
• updated：排序时会用到，最近的更新通常意味着当前仍然有效。

我给每条记忆定的原则是“一条记忆只讲一个结论”。听起来简单，执行起来容易犯浑。很多人会把一个会话里的所有讨论塞进一条记忆，结果就是一条记忆里同时包含问题背景、讨论过程、三个方案、最终结论，检索的时候反而抓不到重点。正确做法是拆开，每个独立结论单独成文件。

3.2 写入链路：从对话里提炼出“值得记”的东西

写入链路最忌讳的是把对话记录原样保存。如果你只是把聊天记录转存成文件，那根本不叫记忆，叫日志。记忆是要经过提炼的。

我的写入流程分成三步：

第一步，捕获源材料。在执行命令时，把当前会话的上下文导出为纯文本，我通常只保留最后几轮对话，因为前面的讨论过程已经淹没在细节里了。如果一次会话非常长，我会在会话结束后统一导出。

第二步，提炼候选记忆。有三种方式，最省事的做法是给会话过程加一个自动判断：当对话中出现“我们决定”“最终方案是”“结论是”这类话术时，就标记为候选记忆。这个规则简单粗暴，但经常漏掉重要信息。更可靠的做法是让模型自己抽，导出一段文本，让模型生成“可持久化的结论清单”，对结论逐条打分。我实践下来，两种方式结合最好：规则命中直接收，规则没命中的再让模型判断。

第三步，归并去重并写入。新记忆写入前，要先检索一遍库里是否已经有相同主题的记忆。如果有，判断是新结论覆盖旧结论，还是补充背景。具体到实现，就是比对标题和关键标签，命中后用新版替换旧文件，同时把旧文件移到archived/目录，而不是直接删除。这个习惯帮了我大忙——后来有两次新方案被推翻，需要找回旧结论，归档文件正好还在。

写入链路还有一个非常容易被忽视的点：格式校验。模型在自动生成记忆文件时，偶尔会把front matter写破，或者把正文的Markdown层级弄乱。我所有的写入操作都会过一道校验器，解析YAML失败或者缺少必填字段时直接拒绝写入，避免脏数据污染记忆库。好的记忆库一定是有边界的，宁可不记，也不能记一堆解析不了的东西。

3.3 检索链路：如何在几百条记忆里捞出最相关的

检索是记忆系统的心脏，写得不舒服，整个系统都用不起来。我先后试过纯关键词方案、纯向量方案、混合方案，最后留下的是混合方案。

先说纯关键词。SQLite自带FTS5全文搜索，可以很轻松地实现关键字命中。它的优点是快、透明，缺点是很死板。你说“网关鉴权”，它不会自动匹配到写过“统一入口鉴权”的那条记忆，因为字面不重叠。中文场景下这个问题更严重，同一个意思可能有多种完全不同的表达。

再说纯向量。把每条记忆和当前问题都转成向量，用余弦相似度排序。优点是可以捕捉语义相似，即便字面完全不一致也能命中。缺点是依赖嵌入模型的本地部署质量，而且纯向量检索容易产生“假阳性”——相似度高但实际不是一回事。

混合方案的具体实现可以这样描述：先用关键词和标签做粗筛，拿到候选集，再把候选集和当前问题做向量相似度排序，最后再做加权重排。这个方案在速度和准确率之间取了一个平衡。如果嵌入模型没配好，就直接退回纯关键词，至少还能用。

重排阶段的打分权重，我建议按这个思路走：

• 向量相似度贡献50%权重，解决语义匹配问题。
• 标签命中贡献20%权重，快速对齐主题。
• 重要性贡献20%权重，高优先级的结论应该更容易被想起。
• 时间新鲜度贡献10%权重，最近更新的内容往往时效性更强。

这个比例不是死的，实际用的时候可以根据项目性质调整。比如一个快速迭代的项目，时间新鲜度权重可以调高到20%；一个偏历史沉淀的项目，重要性权重可以再高一点。

检索结果的数量限制同样重要。别贪多，默认取前5条就够了。取太多，注入层塞不下，还会让模型看到一堆互相矛盾的上下文。判断一个检索配置合不合适，最简单的标准是：把检索结果打印出来看一眼，如果其中一半内容和当前问题无关，那就需要收紧。

3.4 注入策略：怎么塞进上下文而不喧宾夺主

检索到记忆之后，下一个问题是怎么注入。

注入的位置很讲究。不能放在最前面，否则模型会把记忆当成交互指令；也不会放在历史消息的最后，那样容易被上下文窗口截断。我采用的方案是放在系统指令块之后、用户消息之前，用明显的标记块包起来，让模型一眼看出“这段是记忆，不是本次对话内容”。具体长这样：

[记忆上下文] <mem importance="high" project="cross-platform-demo"> 接口鉴权统一走新网关，旧网关只保留灰度流量。 </mem> <mem importance="normal"> 控制台日志级别默认设为info，排查连接问题时临时切到debug。 </mem> [/记忆上下文]

标记块的作用就是隔离。模型可以理解“这里的内容是外部记忆，需要结合当前对话一起思考”，而不会误以为你在命令它执行某些操作。

token预算这块，我用了一个动态截断机制。举个例子，如果模型上下文窗口是64K，我会给记忆上下文最多留出8K的预算，也就是12%左右。先把检索到的记忆按权重排序，依次往块里填，填到接近预算限制就停。如果当前对话已经非常长，预算还要进一步压缩，保证记忆块不会挤压到正常的对话推理空间。

有一个细节值得注意：注入记忆之后，模型偶尔会直接照着记忆念答案，缺少对当前问题的主动分析。我会在记忆块后面加一句“记忆仅供参考，请结合本次对话内容判断”，实测下来能明显减少模型机械复读记忆的情况。

4. 把它挂进工作流，跟着我做一遍

4.1 初始化目录与配置

拿一个实际项目来演示。假设我在做一个跨平台网络同步工具，项目代号叫模拟项目X。初始化记忆库后，目录结构是这样的：

~/.claude-mem/ ├── config.yaml ├── memories/ │ ├── global/ │ ├── projects/ │ │ └── cross-platform-demo/ │ │ ├── active/ │ │ └── archived/ ├── index.db ├── logs/ └── export/

配置文件的初始内容：

# config.yaml storage_path: ~/.claude-mem/memories index_path: ~/.claude-mem/index.db default_project: cross-platform-demo inject_budget_ratio: 0.12 importance_default: normal retrieval: top_k: 5 vector_weight: 0.5 tag_weight: 0.2 importance_weight: 0.2 freshness_weight: 0.1

初始化这一步没啥复杂的，就是建目录、建数据库。真正花时间的是配置检索参数，尤其是top_k和权重比例，这两个值直接决定了记忆回读的命中率。

4.2 三种接入CLI工具的方式

接入方式我试过三种，按使用体验排序：

方式一：包装脚本。用一个本地的包装脚本包住命令行工具，用户输入任何问题之前，脚本先调用一次检索接口，把返回的记忆拼接到当前问题上，再发给模型处理。这是最稳定的一种方式，因为它在进程层面就是“先查记忆，再发请求”，完全不需要动工具本身。我日常主要用这种方式。

方式二：管道过滤。如果你的命令行工具支持从标准输入读取文本，可以写一个轻量管道，把历史会话导出文本作为输入源，处理完的结果再传给模型。这种方式的缺点是调试麻烦，管道一旦某个环节输出格式不对，整个链路就断了。

方式三：手动命令。不改变工具的调用方式，而是在需要时手动执行“查询记忆”和“添加记忆”命令，把结果复制到当前对话中。这种方式最灵活，适合不想改任何现有配置的场景，缺点是多了一步手动操作。

三种方式不是互斥的。我实际的使用姿态是：日常用包装脚本做自动注入，遇到复杂问题需要彻查历史时，再手动跑一次记忆查询，把完整结果作为补充材料贴进对话。自动化负责“日常想起”，手动化负责“深度回顾”。

4.3 从一个完整案例看记忆的写入与回读

这里记录一个实际流程，能直观展现记忆的工作方式。

第一次会话中，我处理模拟项目X的接口鉴权问题，讨论到最后明确了结论，手动执行添加记忆命令：

claude-mem add "接口鉴权统一走新网关，旧网关只保留灰度流量" \ --tags "接口鉴权,网关,限流" \ --project cross-platform-demo \ --importance high

添加成功后，记忆库中出现了一个新Markdown文件。第二天，我新开一个会话，直接问“新模块接入鉴权应该走哪里”，包装脚本自动执行检索，命中前一天写下的That条记忆，注入到上下文里。模型给出的回复直接沿用了新网关方案，并且补了一句“旧网关只保留灰度流量，不应新开权限”。

这个案例里让我印象最深的点是：模型回答时的语气就像真的记得这件事一样，完全没有“昨天我们不是聊过吗”的尴尬。这就是外部记忆的价值。

再举一个踩过坑的例子。有一段时间我在记录项目的时候偷懒，把对话里讨论过程也原封不动写进记忆文件，结果检索时经常把“候选方案”当成“已确认结论”注入进去，模型开始一本正经地推荐我们早就否决掉的方案。后来我严格给记忆文件分状态，候选方案一律标记status: candidate，确认过的结论才标记status: active，注入时默认过滤非active状态，问题才消失。

4.4 定期维护：修剪、重建、备份

记忆库不维护，半年之后就变成垃圾场。维护工作有三件：

第一，定期清理过期内容。我习惯每周花十分钟浏览一遍项目目录下的记忆文件，把已经失效的结论移到archived/目录。批量操作时可以直接改状态字段：

claude-mem update old-gateway-plan --status superseded

第二，重建索引。文件结构变动多了以后，SQLite索引可能和磁盘文件不一致。写一个定时任务，每天凌晨把索引重建一次，保证检索结果的准确。

claude-mem reindex

第三，备份。Markdown记忆文件是纯文本，备份很简单，直接把整个~/.claude-mem目录做一次归档压缩。我个人会连同SQLite索引一起打包，这样恢复之后不需要重新建索引。

5. 我踩过坑，直接给你排查速查表

5.1 记忆污染：旧结论压过新事实

这是记忆注入最典型的问题：旧记忆写得太坚定，导致模型在新情况面前仍然照着旧结论回答。我遇到一次，项目里某个接口从自研方案切到了开源方案，但库里还留着一条旧的“接口内部实现说明”，结果模型一直在按旧实现推断，完全无视当前代码已经重构。

解决办法分三层：第一，方案变更后马上把旧记忆标记为superseded，确保默认不参与注入；第二，在检索层过滤状态字段，只把active记忆纳入候选；第三，重要结论变更后，再补一条新记忆覆盖旧主题，让检索排序时新记忆排前面。好记性不如烂笔头，前提是烂笔头要常新。

5.2 Token爆炸：上下文塞太满反而变傻

记忆注入太多会导致两个问题：一个是直接撑爆上下文窗口，请求直接失败；另一个是模型注意力被记忆块吸走，忽略当前的用户问题。我有一次配置了极高的检索数量，一口气注入二十多条记忆，结果模型回答越来越发散，最后甚至开始复读记忆文件里的原文。

现在的固定策略是：先给记忆块分配一个明确预算，超出就截断。宁可少注几条，也要保证注入的每条记忆都和当前问题强相关。对话特别长时，记忆预算还要手动再压缩一半。

5.3 中文语义检索命中差

纯关键词检索在中文场景下表现很不稳定。“鉴权”“认证”“授权”三个词在很多语境下说的是一件事，但字面完全不重叠。如果只做关键词检索，经常捞不到记忆。

我的建议是配置一个本地嵌入模型做语义向量，如果环境限制不能上本地嵌入模型，就退而求其次：手动扩充标签，把同义词、上下位词都打上。比如“认证”相关记忆，就同时打认证, 鉴权, 登录, token多个标签，用规约法弥补语义检索缺失。

5.4 隐私与边界：记忆库就是隐私库

记忆文件里面存了大量项目细节，可能包含密钥、内部架构、个人偏好。这些文件存在本机，默认不做任何网络同步。我有一次把记忆目录顺手放进了云同步盘，意识到之后立刻移出来——记忆库绝不能和公共云盘绑定。

本地安全方面，建议把记忆目录权限设为仅当前用户可读写，如果涉及高敏感内容，可以给目录做一层磁盘加密。备份归档也注意，不要用明文压缩包传到不信任的地方。

5.5 其他高频问题速查

5.6 给新手的三个避坑建议

新手刚开始做这种记忆工具时，最容易犯的思路错误有三个：

第一，一开始就想搭一个“全自动”记忆系统，希望模型自动把什么都记下来。这个目标太难，自动抽取质量很难控制，污染风险很高。我建议先手动添加记忆，等你对什么内容该记、什么不该记形成手感之后，再逐步放开自动抽取。

第二，记忆条目太粗。一条记忆里塞三四个结论，后面检索时根本定位不到。坚持“一记忆一结论”，文件多了不要怕，检索层会帮你搞定排序。

第三，忽略记忆的时效性。今天记下的内容，下周可能就过期了。状态字段不是摆设，项目进入新阶段后，主动把旧记忆标记成过期。记忆库小但干净，比大而杂有用得多。

6. 一段关于“记忆边界”的自我反思

跑了大半年claude-mem之后，我最大的体会是：记忆工具的核心价值不是“记住”，而是“在需要时想起”。把一切对话都存下来不难，难的是在几百条记忆里精准捞出当前需要的那三五条。这就要求记忆库本身保持克制——重要的结论记清楚，候选方案标明白，过时的内容及时归档。

另一个体会是，记忆最好分层。全局记忆放通用的个人偏好和工作习惯，项目记忆放具体的架构决策和踩坑结论，临时内容放短时记忆区并按期清理。层次分开之后，检索的压力会小很多，注入的时候也更容易决定哪部分必须带、哪部分可以省略。

最后提一个扩展方向。我目前做的claude-mem写操作基本靠手动触发和简单规则，下一步我打算加一个异步学习组件：每次会话结束后，自动把新出现的“决策类内容”提取成候选记忆，经过相似度去重和重要性打分后进入待确认队列，我再批量审核。这一步如果能稳定跑通，整个记忆库的维护成本还能再降一个台阶。如果你也在做类似的方向，建议先从手动加记忆开始，跑通一条最小闭环，再谈自动化。