给Claude装一个外挂记忆：从零构建claude-mem持久化记忆系统-平芜编程栈

1. 为什么我要自己动手做一个 claude-mem

用 Claude 做长对话或者复杂项目的人，大概都遇到过同一个尴尬：聊到一半，上下文窗口快满了，要么被迫开新会话，要么眼睁睁看着早期那些关键决策、代码片段、需求约束被一点点挤出去。开新会话之后，之前积累的上下文全丢，得重新解释一遍项目背景，效率直接砍半。claude-mem这个项目，就是冲着这个痛点去的——它想给 Claude 装一个“外挂记忆”，把对话里值得留存的信息抽出来、存下来，下次需要的时候再精准地喂回去。

我自己是从去年开始重度依赖 Claude 做代码审查、架构讨论和文档撰写的，前后踩过不少坑。最开始用的是最土的办法：手动把重要结论复制到一个 Markdown 文件里，每次开新会话就粘贴进去。这个方法能用，但极其费手，而且随着项目推进，那个文件会膨胀到几千行，粘贴进去反而把上下文又占满了。后来试过一些现成的记忆方案，要么太重、要么依赖特定平台、要么抽取质量不稳定。折腾了几轮之后，我决定自己搭一套轻量的记忆层，也就是这篇要聊的claude-mem的核心思路。

这篇文章适合三类人看：一是天天和 Claude 打交道、被上下文限制折磨的开发者；二是想给自己的 AI 工作流加一层持久化记忆、但不知道从哪下手的人；三是对“记忆抽取 + 检索增强”这套组合拳感兴趣、想看看具体怎么落地的人。我会把整体设计思路、核心模块拆解、实操步骤、参数选择依据，以及我踩过的坑，全部摊开讲。你不需要有很深的机器学习背景，只要会写点 Python、能跑命令行，就能跟着复现一套属于自己的版本。

需要先说明一点：claude-mem不是一个官方产品，它更像是一类“给对话式 AI 加持久记忆”的项目模式的代称。市面上叫这个名字或者类似名字的实现有好几种，思路大同小异。我下面讲的，是我自己实际跑通、并且稳定用了一段时间的那套方案，细节上会带上我个人的取舍，你可以根据自己的场景调整。

2. 整体设计思路：记忆到底该怎么存、怎么取

2.1 核心问题拆解：不是“存下来”就完事

很多人对“AI 记忆”的第一反应是：把对话记录存进数据库不就行了？这个想法对了一半。存下来确实是最基础的一步，但真正的难点在于存什么和怎么取。

先说存什么。一整段对话里，有价值的信息密度其实很低。大量的“好的”“明白了”“那我试试”这类寒暄和确认，对后续没有任何参考价值。如果无脑全存，检索的时候噪声会淹没信号，你搜“数据库选型”，结果返回一堆“好的我看看”。所以claude-mem的第一个核心动作是抽取：从原始对话里识别出值得长期保留的片段，比如技术决策、代码片段、需求约束、待办事项、关键结论。

再说怎么取。存了几百条记忆之后，新会话开始时你不可能全塞回去，上下文窗口扛不住。所以需要一套检索机制，根据当前对话的主题，动态挑出最相关的几条记忆注入进去。这就涉及向量化、相似度计算、排序、截断这一整套流程。

我一开始图省事，直接全量存、关键词搜，结果就是检索质量惨不忍睹。后来改成“抽取 + 向量检索 + 重排序”三段式，效果才稳定下来。下面这张表是我对三种常见方案的对比，也是我最终选型的依据：

方案	存储方式	检索方式	优点	缺点	适用场景
全量存储	原始对话全文	关键词匹配	实现简单，零信息损失	噪声大，检索差，占空间	对话量极小、临时用
摘要存储	每轮对话摘要	关键词/向量	体积小，噪声低	摘要会丢细节，代码片段易失真	以讨论为主的场景
抽取+向量	结构化记忆条目	向量相似度+重排	精度高，可控性强	实现复杂，需要调参	长期项目、代码密集型

我选的是第三种。原因很直接：我做的大部分是代码和架构相关的工作，代码片段、函数签名、配置参数这些东西一旦被“摘要”掉，基本就废了。必须原样保留，同时又要能精准检索到。

2.2 记忆的生命周期：从产生到消亡

一套完整的记忆系统，记忆是有生命周期的。我在设计claude-mem的时候，把它拆成了四个阶段：

捕获：从对话流里实时或批量提取候选记忆。
抽取与结构化：把候选内容整理成统一格式，打上类型标签、时间戳、来源会话 ID。
存储与索引：写入持久化存储，同时生成向量索引。
检索与注入：新会话根据当前上下文，检索相关记忆并注入。

这四个阶段里，最容易出问题的是第一阶段和第二阶段。捕获太激进，会把垃圾也抓进来；抽取规则太死，会漏掉有价值的隐性信息。我的经验是：宁可稍微宽松一点捕获，然后在抽取阶段用规则+模型双重过滤。因为漏掉一条关键记忆的代价，比多存几条垃圾要大得多——垃圾可以在检索排序阶段被压下去，但漏掉的东西永远找不回来了。

2.3 为什么不用现成的向量数据库全家桶

这里要解释一个选型上的取舍。很多人一上来就想上 Pinecone、Weaviate 这类专业向量数据库。我一开始也这么想，后来放弃了，原因有三个：

第一，规模不够。个人或小团队的记忆条目，撑死几千到几万条。这个量级用 FAISS 或者干脆用 numpy 做余弦相似度，性能完全够，根本不需要分布式向量数据库。

第二，依赖太重。引入一个外部服务，意味着多一个部署、多一个故障点、多一份维护成本。我想要的是一套能塞进现有工作流、随手就能跑起来的东西，而不是再养一个服务。

第三，可控性。记忆检索的质量，很大程度取决于元数据过滤和重排序策略。自己用 FAISS 加一层业务逻辑，比在向量数据库的黑盒里调参要透明得多。

所以最终的技术栈是：SQLite 存结构化记忆 + FAISS 存向量索引 + 一个轻量的重排序层。全部本地化，零外部依赖，单文件数据库方便备份和迁移。这套组合我在多个项目里验证过，稳定性和检索质量都够用。

3. 核心模块拆解与关键实现细节

3.1 记忆抽取：怎么判断一段话值不值得记

抽取是整个系统的入口，也是最考验设计的地方。我的做法是规则优先、模型兜底。

规则部分，我定义了几类高价值信号：

包含代码块的内容（``` 包裹的片段）
包含明确决策词的句子，比如“决定用”“最终选”“改成”“放弃”“确定方案”
包含约束条件的句子，比如“必须”“不能”“限制在”“要求”
包含待办或未完成事项的句子，比如“待确认”“下次要”“TODO”
包含具体参数、版本号、路径、命令行的内容

这些规则用正则和简单的启发式就能覆盖大部分场景，速度快、成本低。但规则有个天然缺陷：它抓不住那些“没有明显关键词、但信息量很大”的句子。比如“这个方案在并发超过 500 的时候会出问题”，这句话里没有“决定”“必须”这类词，但它是一条极其重要的经验记忆。

所以我在规则之后加了一层模型判断：把规则没命中的句子，批量丢给一个轻量模型，让它判断“这句话是否包含值得长期保留的项目信息”。这里我用的是本地跑的小模型，避免每次都调用外部 API 增加延迟和成本。判断结果是一个二分类，命中的进入抽取流程。

注意：模型兜底这一层不要做得太重。我一开始用了一个 7B 的模型逐句判断，结果抽取一条记忆要等好几秒，体验极差。后来换成更小的模型 + 批量推理，速度才上来。抽取是高频操作，延迟必须控制在可接受范围内。

抽取出来的原始片段，还要经过一次结构化：统一成 JSON 格式，字段包括content（内容正文）、type（类型：code/decision/constraint/todo/insight）、source_session（来源会话）、timestamp（时间戳）、tags（自动打标）。这个结构决定了后面检索和过滤的灵活性。

3.2 向量化与索引：选对嵌入模型比调参更重要

记忆条目存好之后，要能被语义检索到，就得做向量化。这一步的选型，我的观点很明确：嵌入模型的质量，比后面所有的调参都重要。

我试过好几种嵌入模型，从早期的通用句向量模型，到后来专门针对检索优化的模型。差异非常明显。同一个查询“数据库连接池配置”，用差的模型，返回的可能是“数据库备份策略”；用好的模型，能精准命中“连接池最大连接数设为 20”这条记忆。

选嵌入模型的时候，我关注三个指标：

检索精度：在中文技术语境下的表现。很多模型英文很强，中文拉胯，一定要用你自己的数据测。
维度：维度越高表达力越强，但存储和计算成本也越高。我最终选的是 768 维，在精度和成本之间比较平衡。
推理速度：记忆条目可能成千上万，批量向量化的时候速度很关键。

向量生成之后，用 FAISS 建索引。这里有个细节：我建的是IVF 索引而不是暴力索引。暴力索引检索精确但慢，IVF 用聚类做近似检索，速度快很多，精度损失在可接受范围内。对于几千到几万条记忆，IVF 的nlist参数我一般设成sqrt(N)左右，nprobe设成 10 到 20，实测召回率能到 95% 以上。

3.3 检索与重排序：让最相关的记忆浮上来

检索这一步，我采用的是两阶段策略：先粗排，再精排。

粗排用向量相似度，从索引里捞出 Top-K（我一般取 20 到 30 条）候选。这一步追求的是召回率，宁可多捞一些，别漏掉相关的。

精排才是决定最终质量的关键。我在精排阶段综合了多个信号：

向量相似度：基础分。
记忆类型权重：代码和决策类记忆权重高，寒暄类权重低。
时间衰减：越新的记忆权重越高，但衰减不能太激进，否则早期的重要决策会被埋没。我用的是半衰期 30 天的指数衰减。
标签匹配：如果当前对话的主题标签和记忆标签有重叠，加分。
来源会话相关性：如果当前会话和某条记忆来自同一个项目，加分。

这几个信号加权求和，得到最终排序。权重是我反复调出来的，下面这张表是我目前用的配置，你可以作为起点：

信号	权重	说明
向量相似度	0.5	基础分，归一化到 0-1
类型权重	0.2	code/decision 为 1.0，insight 为 0.8，todo 为 0.7
时间衰减	0.15	半衰期 30 天
标签匹配	0.1	重叠标签数 / 总标签数
来源相关	0.05	同项目为 1，否则为 0

精排之后，取 Top-N（我一般取 5 到 8 条）注入到新会话的上下文里。注入的位置也有讲究：我放在系统提示之后、用户第一条消息之前，并且加一个明确的分隔标记，比如“以下是来自历史会话的相关记忆”。这样模型能清楚知道这部分是背景信息，而不是当前对话内容。

3.4 存储层设计：SQLite 的字段与索引

存储层我用 SQLite，表结构设计得比较克制。核心表就一张memories，字段如下：

CREATE TABLE memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, type TEXT NOT NULL, source_session TEXT, project TEXT, tags TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, vector_id INTEGER, access_count INTEGER DEFAULT 0, last_accessed TIMESTAMP );

几个设计上的考虑：

vector_id关联 FAISS 索引里的位置，检索时先查 FAISS 拿到 ID，再回表取内容。
access_count和last_accessed用来做热度统计。被频繁检索到的记忆，说明它确实重要，可以在排序时额外加分。
project字段用来做项目隔离。不同项目的记忆混在一起检索，会互相干扰。有了这个字段，检索时可以限定范围。

索引方面，我在type、project、created_at上建了普通索引，tags因为是多值字段，单独建了一张关联表。这些索引在数据量上来之后，对检索速度的提升很明显。

4. 完整实操流程：从零跑通一套 claude-mem

4.1 环境准备与依赖安装

先把环境搭起来。我用的是 Python 3.10，依赖不多，核心就几个：

pip install faiss-cpu sentence-transformers sqlite-utils numpy

如果你有 GPU，把faiss-cpu换成faiss-gpu，向量化速度会快很多。sentence-transformers用来加载嵌入模型，sqlite-utils是我个人习惯用的 SQLite 操作库，你也可以直接用标准库的sqlite3。

嵌入模型我选的是一个中文检索效果不错的多语言模型，首次运行会自动下载，大概几百 MB。下载慢的话可以提前手动下载好放到缓存目录。

提示：模型文件建议固定版本号，不要用latest。我有一次因为模型静默更新，导致新旧向量不在同一个语义空间，检索结果直接乱掉，排查了半天才发现是模型版本变了。

4.2 记忆抽取模块的实现

抽取模块的核心是一个函数，输入是一段对话文本，输出是结构化的记忆列表。我把它拆成三步：

第一步，按段落切分对话，过滤掉过短的片段（少于 15 个字的直接跳过）。

第二步，对每个片段跑规则匹配。规则我用一个配置列表管理，方便增删：

RULES = [ {"name": "code", "pattern": r"```[\s\S]*?```", "type": "code"}, {"name": "decision", "pattern": r"(决定|最终选|改成|放弃|确定方案|采用)", "type": "decision"}, {"name": "constraint", "pattern": r"(必须|不能|限制在|要求|禁止)", "type": "constraint"}, {"name": "todo", "pattern": r"(待确认|下次要|TODO|待办|还没做)", "type": "todo"}, ]

第三步，规则没命中的片段，批量送给小模型判断。这里我用的是一个二分类的小模型，输入是片段文本，输出是 0 或 1。为了控制延迟，我设置了批量大小 16，一次推理处理 16 条。

抽取出来的片段，统一走一个normalize函数，生成标准 JSON。这个函数还负责自动打标：用关键词提取算法从内容里抽 3 到 5 个标签，存进tags字段。

4.3 向量化与入库的完整代码

向量化和入库是连在一起的。核心逻辑是：对每条新记忆，生成向量，写入 FAISS 索引，拿到vector_id，再把记忆内容和vector_id一起写入 SQLite。

import faiss import numpy as np from sentence_transformers import SentenceTransformer model = SentenceTransformer("your-embedding-model") dimension = 768 index = faiss.IndexIVFFlat(faiss.IndexFlatL2(dimension), dimension, 100) index.train(np.random.random((1000, dimension)).astype("float32")) def add_memory(content, mem_type, project, tags): vector = model.encode([content])[0].astype("float32") index.add(vector.reshape(1, -1)) vector_id = index.ntotal - 1 # 写入 SQLite db["memories"].insert({ "content": content, "type": mem_type, "project": project, "tags": ",".join(tags), "vector_id": vector_id }) return vector_id

这里有个坑要提醒：FAISS 的 IVF 索引必须先train才能add。训练数据我用的是随机向量，实际项目里最好用真实的记忆向量来训练，聚类效果会更好。如果记忆量还小（不到几千条），可以先用IndexFlatL2暴力索引，等数据量上来再切换到 IVF。

4.4 检索注入的完整流程

检索注入是每次开新会话时触发的。流程是：

拿当前会话的第一条用户消息作为查询。
生成查询向量。
在 FAISS 里检索 Top-30 候选。
回表取内容，跑精排打分。
取 Top-8，格式化成注入文本。
拼接到系统提示之后。

精排打分的代码大概长这样：

def rerank(candidates, query_vector, current_project): scored = [] for mem in candidates: sim = cosine_similarity(query_vector, mem["vector"]) type_weight = TYPE_WEIGHTS.get(mem["type"], 0.5) days_old = (now - mem["created_at"]).days time_decay = 0.5 ** (days_old / 30) tag_score = compute_tag_overlap(mem["tags"], current_tags) project_score = 1.0 if mem["project"] == current_project else 0.0 score = (0.5 * sim + 0.2 * type_weight + 0.15 * time_decay + 0.1 * tag_score + 0.05 * project_score) scored.append((score, mem)) scored.sort(reverse=True, key=lambda x: x[0]) return [m for _, m in scored[:8]]

注入文本的格式我固定成：

[历史记忆] - (决策) 数据库选型确定为 PostgreSQL，理由是... - (代码) 连接池配置：max_connections=20, timeout=30s - (约束) 接口响应时间必须控制在 200ms 以内

这个格式清晰、紧凑，模型能快速理解。我试过用更花哨的格式，比如带 JSON 结构的，效果反而不好，模型容易把注意力放在格式解析上而不是内容本身。

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

5.1 检索结果不相关怎么办

这是最常见的问题。排查顺序我一般是这样的：

先看嵌入模型。用几条你熟悉的查询手动测一下，看返回的向量相似度是否符合直觉。如果明显不对，八成是模型选错了，或者模型版本变了。

再看切分粒度。如果一条记忆太长，里面混了好几个主题，向量就会变得“模糊”，检索时什么都沾一点，什么都不精准。我的经验是单条记忆控制在 50 到 300 字之间，超过就拆。

最后看精排权重。如果向量相似度没问题，但排序不对，那就是权重配置的问题。可以先把权重简化成只用向量相似度，确认基础检索没问题，再逐步加回其他信号。

下面这张表是我整理的常见症状和对应排查方向：

症状	可能原因	排查方向
返回结果完全不相关	嵌入模型不匹配	换模型，用中文技术语料测试
相关结果排不到前面	精排权重失衡	简化权重，逐步加回
检索不到某条记忆	抽取阶段漏掉了	检查规则和模型判断阈值
结果重复度高	切分粒度过细	合并相邻的相似记忆
新记忆检索不到	索引未更新	检查 add 后是否持久化

5.2 记忆膨胀怎么控制

用久了之后，记忆条目会越来越多。我遇到过数据库涨到几万条、检索变慢的情况。控制膨胀有几个手段：

一是去重。新记忆入库前，先和已有记忆做相似度比对，超过阈值（我设的是 0.95）就判定为重复，不重复入库，只更新last_accessed。

二是归档。超过 90 天没被访问过的记忆，移到归档表，不参与常规检索。需要的时候可以手动召回。

三是合并。同一主题下的多条碎片记忆，定期用模型合并成一条更完整的记忆。这个操作我一般一个月跑一次，放在低峰期。

注意：归档和合并都要留后路。我一开始直接删，结果误删了一条关键决策记录，找不回来。后来改成归档，数据还在，只是不参与检索，心里踏实多了。

5.3 注入记忆后模型反而变笨了

这个坑我踩过。原因是注入的记忆太多、太杂，把上下文窗口占满了，模型没有空间处理当前对话。解决办法很简单：控制注入条数和总长度。我现在硬性限制注入不超过 8 条、总字数不超过 1500 字。超了就按分数截断。

另一个原因是注入位置不对。如果记忆放在用户消息之后，模型可能会把它当成当前对话的一部分来回应。一定要放在系统提示之后、用户消息之前，并且用明确的分隔标记。

5.4 跨项目记忆串味怎么解决

如果你同时做多个项目，记忆混在一起检索，会出现“A 项目的记忆被注入到 B 项目对话里”的情况。我的做法是项目隔离 + 全局兜底：检索时优先在project匹配的记忆里找，如果结果不足，再从全局记忆里补充。这样既保证了项目内的精准，又不会完全丢失跨项目的通用经验。

6. 我实际用下来的一些体会

这套claude-mem我跑了大概半年，最大的感受是：记忆系统的价值不在于“记得多”，而在于“记得准”。早期我追求把所有东西都存下来，结果检索质量一塌糊涂，反而拖累了对话体验。后来把抽取收紧、检索做精，虽然存的少了，但每次注入的记忆都恰到好处，效率提升非常明显。

还有一个体会是关于维护成本的。任何记忆系统都需要定期维护：去重、归档、合并、调权重。如果你指望搭好就一劳永逸，那大概率会失望。我现在是每个月花半小时做一次维护，检查一下检索质量，调整一下规则和权重。这个投入是值得的，因为记忆质量直接决定了 AI 助手的“聪明程度”。

最后分享一个小技巧：我会定期把高质量的记忆导出成一个 Markdown 文件，作为项目的“决策日志”存档。这样即使记忆系统本身出了问题，核心信息也不会丢。而且这个日志本身对团队协作也很有价值，新人接手项目的时候，看一眼决策日志就能快速了解来龙去脉。这个习惯我坚持了半年，现在回头看，那些日志比任何文档都管用。