claude-mem 实战：为 Claude 构建外挂式长期记忆系统

1. 从零认识 claude-mem：它到底解决什么问题

第一次看到claude-mem这个名字，很多人会以为它又是一个套壳的对话客户端。实际上它做的事情要底层得多——它是一套给 Claude 这类大模型对话补上“长期记忆”能力的方案。说白了，就是让模型在跨会话、跨项目的时候，还能记得你之前说过什么、做过什么、偏好是什么，而不是每次开新窗口都像失忆一样从头问起。

我接触这个方向，是因为自己日常用 Claude 写代码、整理资料、做方案，最烦的就是上下文一断，前面聊了半天的项目背景、命名习惯、技术栈偏好全部清零。每次都要重新贴一遍需求文档，或者把关键结论手动复制到新对话里。claude-mem这类工具的核心价值，就是把这层“记忆”从模型内部剥离出来，做成一个可持久化、可检索、可管理的独立层。它不依赖模型本身是否支持超长上下文，而是用外部存储加检索的方式，把相关历史片段在需要的时候重新喂给模型。

它适合谁？我觉得有三类人最值得关注。第一类是重度使用 Claude 做开发的工程师，尤其是那种一个项目要持续几周甚至几个月、每天都要和模型来回沟通的人。第二类是内容创作者和研究者，需要模型记住大量素材、观点和写作风格。第三类是团队协作场景，多人共用一套记忆库，让模型对项目的理解保持一致。哪怕你只是偶尔用用，理解这套机制也能帮你更高效地组织自己的提示词和资料。

需要先说明一点：claude-mem并不是官方内置功能，它更像是一个围绕 Claude 生态构建的第三方记忆管理思路。不同实现版本细节会有差异，但核心逻辑是相通的——存储、检索、注入这三步。下面我会按这个主线，把设计思路、关键细节、实操过程和踩坑经验一层层拆开讲。

2. 整体设计思路：为什么记忆要外挂而不是塞进上下文

2.1 上下文窗口的硬限制与成本账

很多人第一反应是：既然模型支持长上下文，那我直接把所有历史都塞进去不就行了？这个想法在理论上成立，实际用起来会撞上两堵墙。

第一堵墙是窗口上限。即便模型标称支持很长的上下文，真正能稳定利用的部分往往打折扣，而且随着对话变长，模型对中间内容的注意力会下降，出现“中间遗忘”现象。你贴了几万字的背景，模型可能只记住了开头和结尾。

第二堵墙是成本。上下文越长，每次请求消耗的 token 越多，费用和时间都线性上涨。假设你每天和模型交互 50 次，每次都带上 2 万 token 的历史，一天就是 100 万 token 的输入量。这个开销长期下来非常可观，而且大部分历史内容跟当前问题根本无关，属于纯浪费。

claude-mem的思路正好反过来：不把所有记忆都带上，只在需要时检索出最相关的几条。这就像你不需要把整座图书馆背在身上，只需要在需要的时候去书架取对应的那本书。存储放在外部，检索按相关性排序，注入时只带最关键的片段，token 消耗能压到原来的几分之一甚至更低。

2.2 存储、检索、注入三段式架构

把claude-mem拆开看，它本质上是一条流水线，分三个阶段。

存储阶段负责把对话中有价值的信息抽取出来，转成结构化或半结构化的记录，写进持久化存储。这里的关键是“什么值得记”。不是每句话都要存，而是抽取事实、决策、偏好、结论这类高信息密度的内容。

检索阶段在每次新对话开始时触发，根据当前用户输入去存储里找相关记录。检索质量直接决定记忆有没有用。找得太宽，注入一堆无关内容反而干扰模型；找得太窄，又漏掉关键信息。

注入阶段把检索到的记忆片段按一定格式拼进系统提示或用户消息里，让模型在生成回复前就“看到”这些背景。注入的位置和格式都有讲究，放错了模型可能忽略，放对了效果立竿见影。

提示：三段式里最容易做砸的是检索。存储和注入相对机械，检索涉及语义匹配，需要根据你的实际使用场景反复调参。

2.3 为什么选择外挂式而非微调

有人会问，既然要让模型记住东西，为什么不直接微调一个专属模型？这个问题我认真权衡过。

微调的成本高、周期长，而且每次有新信息都要重新训练，完全不现实。更麻烦的是，微调会把知识固化进权重，你没法单独删除某条错误记忆，也没法审计模型到底记住了什么。外挂式记忆则完全可控——每条记录都能查看、编辑、删除，检索逻辑可以随时调整，存储可以备份迁移。

从工程角度看，外挂式还有一个巨大优势：与模型解耦。今天用 Claude，明天换别的模型，记忆库照样能用，只要改一下注入格式就行。微调方案则被死死绑定在特定模型上。所以对于个人和小团队来说，外挂式是性价比最高、最灵活的选择。

3. 核心细节解析：记忆怎么存、怎么找、怎么用

3.1 记忆的粒度设计：从整段对话到原子事实

存储粒度是第一个要拍板的决策。我试过三种粒度，各有优劣。

最粗的是整段对话存储，把每次会话完整存下来。实现简单，但检索时噪音极大，一条记录里可能混着寒暄、跑题和真正有用的结论，注入时浪费大量 token。

最细的是原子事实存储，把每个独立事实拆成一条记录，比如“用户偏好用 TypeScript”“项目使用 PostgreSQL”“部署环境是 Docker”。检索精准，但拆解过程需要额外处理，而且丢失了事实之间的关联。

我最终采用的是中间粒度：以“决策单元”为单位存储。一个决策单元包含一个主题、相关背景、最终结论和必要的上下文。比如“数据库选型”作为一个单元，里面记录候选方案、取舍理由和最终选择。这样既保留了关联性，又不会太臃肿。实测下来，这种粒度在检索准确率和 token 效率之间平衡得最好。

3.2 向量检索与关键词检索的取舍

检索环节主流有两种方案：向量语义检索和关键词检索。很多人一上来就all in向量检索，觉得语义匹配更高级。我的经验是，两者结合才靠谱。

向量检索擅长处理“意思相近但用词不同”的情况。你问“数据库用的啥”，它能找到记录里写“存储层选型”的条目。但它有个毛病：对专有名词、代码标识符、版本号这类精确信息不敏感。你搜PostgreSQL 14，它可能给你返回一堆讲数据库的泛泛内容。

关键词检索（比如 BM25）正好相反，精确匹配强，但不懂同义表达。所以我的做法是混合检索：先用关键词召回一批精确命中的记录，再用向量检索补充语义相关的记录，最后合并去重、按综合得分排序。这个组合拳打下来，召回率和准确率都比单用一种明显提升。

3.3 注入格式：让模型真正“读进去”

检索出记忆只是第一步，怎么注入决定了模型会不会用。我踩过的坑是：把记忆当成一堆散乱文本直接拼在开头，结果模型经常忽略，或者把记忆和当前问题搞混。

后来我改成结构化注入，每条记忆带上明确的标签和来源，比如用“已知背景”“历史决策”“用户偏好”这样的分类标题隔开。模型对结构化信息的敏感度明显更高。另外，注入位置也有讲究——放在系统提示里比放在用户消息末尾效果好，因为系统提示在生成全程都保持较高权重。

还有一个细节：记忆要标注时间。模型对“最新”的信息更敏感，如果两条记忆冲突，标注了时间戳能让模型倾向于采用较新的那条。这个技巧在处理需求变更时特别有用。

3.4 记忆的去重与冲突处理

用久了必然遇到重复和冲突。同一个偏好你可能在不同时间说过好几次，措辞还不一样；某个决策后来被推翻了，但旧记录还在。如果不处理，注入时模型会收到自相矛盾的信息，输出质量直线下降。

我的处理策略分两层。写入时去重：新记忆入库前先做相似度检查，如果和已有记录高度重合，就更新旧记录的时间戳而不是新增一条。读取时消解冲突：检索出多条相关记忆后，按主题分组，同组内保留时间最新的一条，或者把冲突点显式标注出来让模型自己判断。

注意：冲突消解不要做得太激进。有些看似冲突的记录其实是不同场景下的不同选择，强行合并反而丢信息。我一般只在主题和条件都高度一致时才判定为真冲突。

4. 实操过程：从零搭一套可用的记忆系统

4.1 环境准备与依赖选型

动手之前先把技术栈定下来。我的选型逻辑是：够用、好维护、可迁移。

存储层我选了 SQLite 加向量扩展的方案。SQLite 胜在零配置、单文件、随处可跑，备份就是复制一个文件。向量检索用轻量的本地索引库，不依赖外部服务，隐私和延迟都可控。如果你数据量特别大，可以换成专门的向量数据库，但个人使用 SQLite 完全够。

嵌入模型的选择上，我倾向用本地能跑的小模型做向量化，避免每次存储都调用外部接口。虽然精度比大模型略低，但胜在免费、快、离线可用。检索质量对嵌入模型没那么敏感，因为还有关键词检索兜底。

# 初始化项目结构 mkdir claude-mem && cd claude-mem # 创建虚拟环境 python -m venv venv source venv/bin/activate # 安装核心依赖 pip install sqlite-utils sentence-transformers rank-bm25

4.2 记忆写入流程的实现

写入流程我设计成一个独立函数，输入是一段对话或一条结论，输出是入库结果。核心步骤有四步。

第一步是抽取。如果输入是原始对话，先用模型抽取其中的关键信息，输出结构化的候选记忆列表。这一步的提示词要写清楚：只抽取事实、决策、偏好，忽略寒暄和过程性内容。

第二步是归一化。把抽取结果统一成固定字段：主题、内容、类型、时间戳、来源。主题用于后续分组，类型用于分类检索。

第三步是查重。拿新记忆的主题和内容去已有库里做相似度比对，超过阈值就判定为重复，走更新逻辑。

第四步是写入。同时写入原文、向量和关键词索引，保证两种检索方式都能命中。

def add_memory(topic, content, mem_type, source): # 查重：同主题下找相似内容 existing = find_similar(topic, content, threshold=0.85) if existing: update_memory(existing.id, content, timestamp=now()) return "updated" # 新增：写入原文、向量、关键词索引 mem_id = insert_raw(topic, content, mem_type, source) insert_vector(mem_id, embed(content)) insert_keywords(mem_id, tokenize(content)) return "created"

4.3 检索与注入的完整链路

检索链路是整套系统的核心，我把它拆成召回、排序、组装三步。

召回阶段并行跑两路：关键词检索用 BM25 打分，向量检索用余弦相似度打分。两路各取前 20 条候选。

排序阶段把两路结果合并，用加权公式算综合分。我的权重设置是关键词 0.4、向量 0.6，这个比例可以根据你的查询习惯调。如果经常搜精确术语，就提高关键词权重。

组装阶段把排好序的记忆按类型分组，拼成结构化文本。每组加一个小标题，每条记忆带时间戳。最后整段注入到系统提示里。

def retrieve_and_inject(query, top_k=5): kw_results = bm25_search(query, top_k=20) vec_results = vector_search(query, top_k=20) merged = merge_and_rank(kw_results, vec_results, w_kw=0.4, w_vec=0.6) top = merged[:top_k] return format_memories(top)

4.4 参数调优的实测记录

参数不是拍脑袋定的，我做了几轮对比测试。测试方法是准备 50 个查询，人工标注每个查询应该命中的记忆，然后看不同参数下的召回率和准确率。

相似度阈值我试过 0.7、0.8、0.85、0.9。0.7 太松，把不相关的也判成重复；0.9 太严，同一件事换个说法就漏判。0.85 是甜点，实测重复识别准确率最高。

top_k 注入条数我试过 3、5、8、10。3 条经常漏关键信息，10 条又引入噪音拖慢生成。5 条是平衡点，覆盖大多数场景。如果查询特别复杂，可以动态放宽到 8 条。

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

5.1 模型忽略注入的记忆怎么办

这是最高频的问题。表现是记忆明明注入了，模型回复却完全没参考。排查顺序我总结成三步。

先看注入位置。如果放在用户消息末尾，模型容易把它当成普通输入忽略。挪到系统提示里，权重立刻不一样。

再看格式。纯文本堆砌不如结构化标签。给记忆加上“背景”“决策”“偏好”这样的分类标题，模型识别率明显提升。

最后看内容长度。单条记忆太长，模型抓不住重点。把长记忆拆成短句，或者把关键结论前置，效果立竿见影。

5.2 检索结果不相关的排查思路

检索出一堆无关记忆，通常是三个原因。一是嵌入模型不匹配，你用的模型对中文或专业术语支持差，换个更适合的。二是查询太短，几个字的查询语义信息不足，可以先把用户输入扩写成完整问句再检索。三是权重失衡，向量权重过高导致语义漂移，调低它、提高关键词权重试试。

我一般会加一个相关性下限，综合分低于某个值的记忆直接丢弃，宁可少注入也不注入噪音。这个下限设 0.3 左右比较合适。

5.3 记忆库膨胀后的性能问题

用几个月后记忆条数可能上千，检索变慢。解决办法分两个方向。

索引优化：给关键词索引和向量索引都建好，别每次全表扫描。SQLite 的向量扩展支持近似最近邻搜索，开启后速度提升明显。

冷热分离：把超过一定时间没被检索到的记忆标记为冷数据，检索时默认跳过，需要时再手动唤醒。我设的阈值是 90 天，实测能砍掉一半以上的检索量，对准确率几乎没影响。

5.4 多项目记忆串味的处理

如果你同时维护多个项目，记忆容易串。A 项目的技术选型被注入到 B 项目的对话里，输出就乱了。

我的做法是给每条记忆打上项目标签，检索时先按项目过滤，再做相关性排序。项目标签可以在写入时自动识别，也可以手动指定。如果两个项目有共享的通用偏好，就单独建一个“全局”标签，检索时全局记忆和项目记忆都带上。

提示：项目标签的粒度别太细。按代码仓库或工作流划分就够了，分得太细反而增加维护负担。

5.5 常见问题速查表

6. 进阶玩法：让记忆系统越用越聪明

6.1 记忆的自动摘要与压缩

记忆库用久了，同一主题下会积累很多条记录。与其全部保留，不如定期做主题级摘要：把某个主题下的所有记忆喂给模型，让它生成一条浓缩版，替换掉原来的多条。这样既保留核心信息，又控制总量。

我一般每周跑一次摘要任务，针对记录数超过 5 条的主题触发。摘要后的记忆标注“已压缩”，原始记录归档不删除，需要追溯时还能查到。

6.2 基于使用反馈的检索优化

检索质量可以自我进化。做法是记录每次检索后模型的实际使用情况——哪些记忆被引用了，哪些被忽略了。被频繁引用的记忆提高权重，长期被忽略的降低权重。跑一段时间后，检索排序会越来越贴合你的实际需求。

这个机制实现不复杂，给每条记忆加一个使用计数，检索排序时把计数作为加权因子之一就行。关键是别让它主导排序，否则会形成马太效应，新记忆永远没机会冒头。我一般把使用计数的权重控制在 0.1 到 0.2 之间。

6.3 跨设备同步的轻量方案

如果你在多台机器上用，记忆库需要同步。最轻量的方案是把 SQLite 文件放在同步盘里，但要注意并发写入冲突。更稳妥的是搞一个简单的同步服务，每台机器本地写，定期推送到中心节点合并。

合并时的冲突处理按时间戳走，新的覆盖旧的。向量和关键词索引在合并后重建一次，保证一致性。这套方案我跑了大半年，没出过数据丢失。

7. 我踩过的坑与实战心得

先说最大的一个坑：一开始我把所有对话都存了。结果记忆库迅速膨胀到几万条，检索又慢又不准，注入的全是噪音。后来改成只存抽取后的决策单元，数据量降到原来的十分之一，效果反而更好。这件事让我明白，记忆系统的核心不是“记得多”，而是“记得准”。

第二个坑是过度依赖向量检索。有段时间我搜代码相关的记忆，总是搜不准，排查半天才发现是嵌入模型对代码标识符不敏感。加上关键词检索后问题立刻解决。所以别迷信单一方案，混合才是王道。

第三个心得是注入格式值得反复打磨。我前后改了五六版注入模板，从纯文本到 Markdown 到带标签的结构化文本，每一版效果都有提升。这个投入产出比极高，建议你多花点时间在这上面。

最后一个建议：从小规模开始。别一上来就追求完美架构，先用最简单的方案跑起来，存几十条记忆，观察检索和注入效果，再逐步迭代。我见过太多人卡在设计阶段，结果一行代码没写。记忆系统这东西，用起来比设计好更重要。

关于后续扩展，我觉得有两个方向值得尝试。一是把记忆和任务管理打通，让模型不仅记得你说过什么，还能主动提醒你待办事项。二是做记忆的可视化面板，把记忆库当成一个可浏览的知识图谱来管理，查找和编辑都会方便很多。这两个方向我都在摸索，有进展再单独写一篇分享。