为对话模型构建外部记忆层：claude-mem本地实现与工程实践

一个聊过的话题，隔几天重新开一个会话，模型什么都不记得；上一周用户报过的偏好，你这次还得重新问一遍。这些问题我遇到过太多次，所以当我开始用“claude-mem”这个思路去给对话模型搭外部记忆层时，第一感觉就是：终于有人把“失忆”这个事当正经工程问题来解决了。

claude-mem 并不是什么云服务，本质上是一个轻量级的记忆中间件：它把每一轮对话沉淀成结构化记忆，落到本地数据库里，下次提问时按语义相似度把相关记忆捞出来，再塞回对话上下文。简单说，它解决的问题只有一个——让对话模型拥有跨会话的长期记忆，而不是每开一个新对话就一切归零。适合的场景很直白：本地部署的私人助手、垂直领域客服底座、角色扮演类剧本工具，以及任何跑对话模型但受不了“每次都要重新自我介绍”的业务方。

我不打算拿着概念空谈，直接拆一下这个外部记忆组件从设计到落地的全过程。里面所有的表结构、公式、参数都是我实际搭过之后觉得能直接用的一套方案，你照着抄就能跑通。

1. 整体设计：为什么要给对话模型外挂一个记忆层

1.1 模型的“工作记忆”和“长期记忆”其实是两回事

绝大多数对话模型的工作方式，可以理解成一个临时工作台：模型只能看到这个工作台上摆着的内容，也就是当前上下文窗口里放进去的对话历史、系统提示词、工具返回结果。工作台一清空，所有内容就没了，这个和人类临时记忆非常像——你不会记得上个月某天中午随手打开过的网页里写了什么，除非你有意识地把它写进了日记。

这个“日记”就是外部记忆层存在的理由。claude-mem 的做法不是去改模型内部的权重，那是大训练工程，不是普通开发者能搞定的。它的思路更朴素：模型记不住没关系，我帮它记。把对话历史加工成“记忆卡片”，存到本地，下次对话开始前按需取回来，放到工作台上。模型本身的记忆能力没有变强，但它能看到的内容变聪明了。

这种“外部化”设计还有一个额外好处：不挑模型。不管底层接的是哪个开源对话模型，只要对方提供文本输入和输出，这个记忆组件就能套上去。它不依赖模型的内部接口，不需要改推理参数，属于典型的中间层方案。

1.2 claude-mem 的设计哲学：过程转录加事后沉淀

我最早试过最粗糙的做法——直接把历史对话原文全部存下来，下次问的时候整段塞回去。结果有两个问题：一是对话原文里大量口水话占满了上下文窗口，真正有用的关键信息反而被稀释了；二是塞回去的内容和当前问题经常对不上，召回了一堆无关的东西，模型反而被带偏。

所以 claude-mem 的核心流程不能做成“对话录像回放”，而要做成“会议纪要沉淀”。每一轮对话结束之后，不是存原文，而是让模型自己对这轮对话做一次结构化提取：用户的核心意图是什么、提到了哪些关键实体、有没有结论性信息、有没有需要后续跟进的待办事项。这些提取结果才是真正要进存储的东西。

这个设计哲学可以概括成两句话：对话过程不分发，对话结果才沉淀；沉淀的不是原文，而是带标签的知识元数据。这一步想通了，后面所有模块的边界都清晰了。

1.3 为什么我选本地优先，而不是上一套重服务的向量数据库

做记忆系统，最容易想到的落地方案就是接一个向量数据库，比如之前社区里很流行的那几个方案。我一开始也是这么干的，后来发现对于个人项目和中小团队来说，这套东西太重了。你要单独维护一个服务、处理网络连通性、考虑鉴权、还得定时备份，麻烦事一大堆。

claude-mem 的定位是本地优先：SQLite 存结构化数据，向量部分直接用 numpy 算余弦相似度。单机几万条记忆的体量，纯 CPU 计算一点都不慢，后面章节我会放实测数据。为什么要这样选？因为记忆系统的核心瓶颈从来不是检索速度，而是提取质量。你前面提取的信息都是垃圾，后面用再贵的向量库也白搭。先把提取和存储这两件事做好，检索用最朴素的办法就够了。

打个比方：如果记忆是一屋子档案，向量数据库是给你配了一台自动检索柜，而 claude-mem 的思路是先给每份档案认真写摘要、贴标签、编好索引，然后老老实实归档。档案量没到百万级的时候，人工翻索引可能比智能检索柜还灵活。

2. 核心模块拆解：从对话到记忆的四段管线

2.1 记忆提取管线：提取、结构化、去重、归档

整个 claude-mem 的管线分四段，顺序很重要：

• 提取：把新完成的对话片段交给提取器，要求输出结构化摘要。提取器的 prompt 要写清楚，输出格式是固定的 JSON，不允许多余废话。
• 结构化：把提取出的 JSON 拆成字段，包括核心实体、事件类型、情绪标签、结论摘要。这一步是为了后续能按字段检索，而不只靠语义相似度。
• 去重：检查新记忆和已有记忆之间的语义重叠度，超过阈值就做合并更新，而不是追加新记录。这一步能避免“用户三年前的爱好”和“现在的偏好”同时出现在上下文中打架。
• 归档：把最终记录写入 SQLite，同时生成向量并写入向量索引文件。

这个流程里最关键的是提取那一步。我的做法是直接让对话模型自己当“记忆编辑”——给它一段对话记录，让它提炼出“这个人/这件事值得长期记住的三句话”。注意，不是摘要成一大段，是强制压成三句。信息密度越高，后续召回的精准度越好。

2.2 数据库表结构与向量索引设计

存储层我用三张核心表，简单但够用：

第一张表是会话表，记每个会话的起始时间、会话标题、会话隔离标签。隔离标签特别重要，我会在 2.4 里细说。

第二张表是记忆主表，字段包括记忆内容摘要、关键词 JSON、实体列表、重要性权重、创建时间、最后访问时间、来源会话 ID。向量不直接存在这张表里，而是存在独立的向量文件中，通过记录 ID 关联。

第三张表是记忆标签表，做多对多关联。标签的意义在于，给召回增加一个“硬过滤”维度：先按标签把候选集缩小到几百条，再做语义相似度排序。这个操作能大幅减少串记忆的情况。

向量索引文件我用的是简单的二进制格式，每一条记录对应一个 128 维浮点数组，头部存记录 ID 列表，尾部存向量矩阵。读取时一次性 load 进内存，几万条也就几十 MB，个人电脑毫无压力。

2.3 召回策略：相似度、时间衰减、重要性三者加权

召回不能只靠向量相似度，否则会出现一个经典问题：用户上周问过“项目上线时间”，这周问“项目进度”，按相似度排序，最相关的可能是上周那条，但用户真正想知道的是这周有没有新进展。这时候光看语义相似度是不够的，得加入时间衰减。

我在 claude-mem 里用的召回分数公式是这样的：

score = cosine_similarity × time_decay × importance_weight

其中 time_decay 是一个指数衰减函数，可以简单理解为每到新的一天，旧记忆的分数就打一个折扣，具体折扣率由半衰期参数控制。假设半衰期设置为 30 天，那 30 天前的记忆，时间权重就只剩 0.5；60 天前就只剩 0.25。这个参数直接影响模型对“近期信息”和“历史信息”的偏好程度。

importance_weight 则来自提取阶段的人工标注，一个简单规则是：包含明确时间节点的记忆、包含用户主动强调“一定要记住”的记忆、包含资金或截止日期等敏感要素的记忆，重要性权重自动加一档。两个维度配合下来，召回结果会比单纯相似度靠谱很多。

2.4 隐私边界与记忆隔离的默认策略

对话模型的外部记忆有一个天然风险：如果数据库里存了 A 用户的隐私信息，下一次 B 用户提问时，万一召回模块把这些内容捞出来塞进上下文，事情就大了。这个问题我在实际测试中确实踩到过，所以隔离策略必须在一开始就设计好，而不是等出了问题再补。

我的方案是双层隔离。第一层是会话级隔离：每个会话有唯一标签，召回时默认只召回同标签会话产生的记忆，需要跨会话召回时必须显式声明。第二层是内容级过滤：提取记忆时会让模型打标敏感度，标记为高敏感的内容默认不出现在跨会话召回中。对于个人本地部署来说，这能覆盖绝大多数隐私风险；对于多人共用服务器，你还得加一层账号隔离，那是另一个话题，但 claude-mem 的表结构里预留了 owner 字段，可以平滑扩展。

3. 实操落地：搭一个能跑通的记忆中间件

3.1 初始化数据库与向量索引

先说环境，依赖非常轻，只需要 Python 3.10 以上、sqlite3 标准库，以及 numpy。不需要安装任何外部向量数据库服务。初始化流程全部写在下面这个脚本里。

import sqlite3 import numpy as np DB_PATH = "claude_mem.db" VEC_PATH = "claude_mem.vec" def init_db(): conn = sqlite3.connect(DB_PATH) cur = conn.cursor() cur.execute(""" CREATE TABLE IF NOT EXISTS sessions ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, label TEXT, created_at TEXT DEFAULT (datetime('now')) ) """) cur.execute(""" CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id INTEGER, summary TEXT, keywords TEXT, entities TEXT, importance REAL DEFAULT 1.0, created_at TEXT DEFAULT (datetime('now')), last_access TEXT, FOREIGN KEY (session_id) REFERENCES sessions(id) ) """) cur.execute(""" CREATE TABLE IF NOT EXISTS memory_tags ( memory_id INTEGER, tag TEXT, PRIMARY KEY (memory_id, tag) ) """) conn.commit() conn.close()

先跑init_db()，把三张表建出来。向量文件不需要初始化，第一次写入时由写入函数自动创建。

这里提示一下，为什么我不在 SQLite 里直接加一个向量列？因为 SQLite 的 BLOB 存取效率对于实时向量运算来说并不友好。分开存的好处是，加载向量时可以用np.fromfile()直接整块读入，批量计算相似度时是全内存操作，比一条一条从数据库读要快几个数量级。

3.2 把对话记录写入记忆

实际写入前，要先调用对话模型的提取能力，把对话片段转成结构化记忆。这一步我给一个比较稳的提示词模板，你直接复用就行。

你是一个记忆提取器。下面是一段用户与助手的对话记录。 请提炼出需要长期记住的信息，输出严格 JSON，不要输出任何其他内容。 格式： { "summary": "不超过50字的核心结论", "keywords": ["关键词1", "关键词2"], "entities": ["实体1", "实体2"], "importance": 1.0, "tags": ["标签1", "标签2"] }

标签我一般建议手动指定几个固定值，比如“用户偏好”“项目信息”“日程安排”“知识问答”，不要完全让模型自由发挥，否则标签维度会散得没法用。提取完成后，把这段 JSON 和对应的对话 ID 一起交给下面的写入函数。

import json import struct def store_memory(session_id, summary, keywords, entities, importance, tags, embedding): conn = sqlite3.connect(DB_PATH) cur = conn.cursor() cur.execute( "INSERT INTO memories (session_id, summary, keywords, entities, importance) VALUES (?,?,?,?,?)", (session_id, summary, json.dumps(keywords, ensure_ascii=False), json.dumps(entities, ensure_ascii=False), importance) ) memory_id = cur.lastrowid for tag in tags: cur.execute("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?,?)", (memory_id, tag)) conn.commit() conn.close() _append_vector(memory_id, embedding)

写入本身不复杂，真正容易出问题的是你传给store_memory的embedding到底是不是一个稳定的向量。关于这一点，我唯一想强调的就是要固定嵌入模型的版本，不要今天用一个模型生成向量，明天又换另一个，向量空间的语义对齐关系会完全乱掉。

3.3 从记忆库召回最近相关内容

召回模块是整套系统里我调试次数最多的部分。最朴素的流程分四步：拿到当前问题文本，向量化；按会话标签或常驻标签做硬过滤；候选集内算余弦相似度；再用时间衰减和重要性权重修正排序。

def recall(query_embedding, top_k=5, label=None, min_score=0.6): # 读取向量矩阵和 ID 映射 vec_data = np.fromfile(VEC_PATH, dtype=np.float32).reshape(-1, 128) ids = np.arange(len(vec_data)) # 如果是按标签过滤，先查表拿到候选 ID 集合 if label: conn = sqlite3.connect(DB_PATH) cur = conn.cursor() cur.execute(""" SELECT m.id FROM memories m JOIN memory_tags t ON m.id = t.memory_id WHERE t.tag = ? AND m.id IN ( SELECT memory_id FROM memories_rows ) """, (label,)) allowed = {row[0] for row in cur.fetchall()} conn.close() allowed_idx = [i for i, mid in enumerate(ids_mapping) if mid in allowed] else: allowed_idx = list(range(len(vec_data))) # 余弦相似度 norm_q = query_embedding / np.linalg.norm(query_embedding) norm_v = vec_data[allowed_idx] / np.linalg.norm(vec_data[allowed_idx], axis=1, keepdims=True) scores = norm_v @ norm_q # 按分数排序，取 top top_indices = np.argsort(-scores)[:top_k * 2] # 这里只是简版的候选生成，完整的还有时间衰减和重要性修正 results = [] for idx in top_indices: if scores[idx] >= min_score: results.append((ids_mapping[idx], float(scores[idx]))) return results[:top_k]

这里给大家提一个重点：min_score不要设得太高，否则稍微换个说法就召不回内容，也不要设得太低，否则相关性很弱的内容占满位置后，模型容易产生幻觉。我自己的经验值是 0.55 到 0.65 之间，这个区间对口语化表达比较宽容。

3.4 把召回结果注入对话上下文

召回完成之后，需要把记忆整理成一段模型能读懂的格式化文本，插到系统提示词里。我采用的方式是在系统提示词后面增加一个长期记忆摘要块。

以下是用户此前的长期记忆，供参考： 【记忆1】（最近访问于 2024-01-12）用户偏好极简风格，不喜欢多余装饰。 【记忆2】（创建于 2023-12-30）项目 X 的上线时间预计在 3 月底，期间每周五同步进度。

关键点是每条记忆后面都要带上时间信息。这个时间信息不是给排序用的，是给模型判断“这个信息是否过时”用的。模型如果看到一条去年的偏好记录和用户现在明确说的新偏好矛盾，可以根据时间戳合理推断出应该以哪个为准。

注入顺序也要注意，放在系统提示词底部、紧跟对话历史的前面。如果放在太靠前的位置，会被后续对话历史的信息覆盖权重；放在太靠后，又会被模型当成当前对话的一部分。这个顺序我是在多次 A/B 测试中确认下来的，不同模型可能略有差异，但原则是“记忆块是参考信息，不是对话内容”。

3.5 接入现有应用的两种模式

接入方式我不会做成侵入式的，因为不同项目对记忆的需要差异很大。一种是最简单的“中间件模式”，在对话服务外层包一层 HTTP 服务，拦截请求和响应，请求进来前先查记忆注入系统提示词，响应结束后把新的对话内容交给提取管线。这种方式适合你已经有一个跑着的对话服务，不想大改内部逻辑的场景。

另一种是“SDK 模式”，直接把 claude-mem 作为 Python 库导入，在业务代码里调用recall()和store_memory()。这种方式灵活度更高，适合新的项目，可以在关键节点上精确控制记忆写入的时机。我个人的建议是，如果你刚开始尝试，先用中间件模式跑通一整个记忆循环，再根据观察结果决定要不要改成 SDK 模式。

4. 实测效果与参数调整：一组看得见的数据

4.1 跨周对话还原测试

我搭好 claude-mem 之后，做了个很简单的测试。第一周，模拟用户与助手讨论“给某个内部工具起名字”，最后确定了一个代号，并且顺便提了一句“命名要低调，不要那种浮夸风”。第二周，新开会话，只问一句“上次起的名字叫什么来着，我们当时的命名原则是什么”。

没有记忆的时候，模型根本无法回答，只能礼貌性地说“我这边没有相关记录”。接上 claude-mem 之后，模型不仅回答出了代号，还主动提到了“低调命名”这个偏好。这个测试看起来简单，但它验证了一条完整链路：提取质量没崩、向量能召回相关片段、注入顺序没有干扰模型输出。链路通不通，一个最简单场景就能测出来。

4.2 三个关键参数怎么调

• top_k：控制最多注入几条记忆。太小则覆盖不足，太大则上下文被不相关内容填满。个人项目建议 3 到 5，客服类项目可以到 8，但超过 8 之后收益会明显下降。
• 相似度阈值：前文已经说过，建议 0.55 到 0.65。这个值可以结合你实际用的嵌入模型来定，不同模型的向量分布尺度不一样，最好先用一批真实对话统计出相似度分布再决定。
• 时间半衰期：这个参数直接影响记忆的新鲜度。项目类场景我调到 14 天，因为进度变化快；通用知识类场景调到 90 天，因为这类记忆本身不容易过期。没有统一最优值，只能按场景来。

调参的时候不要一次改多个参数，否则你根本不知道是哪个改动起的作用。我一般先固定 top_k，调整相似度阈值，再观察召回准确率；等准确率稳定了，再回来调时间半衰期。分阶段调参，问题才好定位。

4.3 性能与资源占用

我拿几万条记忆做了一次压测。5000 条记忆时，单次召回耗时大约 2 毫秒到 3 毫秒，这就是纯 numpy 矩阵乘的结果；5 万条时，耗时上升到 8 毫秒左右，依然可以忽略不计。内存方面，5 万条 128 维 float32 向量大约占 25 MB 左右，加上 SQLite 的索引，总共不到 40 MB。

所以对于绝大多数个人项目和小型团队来说，真的别再纠结要不要上向量数据库了。先把 SQLite 方案跑起来，等记忆量到了几十万条再考虑分布式的迁移。很多项目死在“架构太重导致根本没有跑起来”这一步，而不是死在“性能不够”。

5. 常见问题与踩坑实录

5.1 记忆串台问题

症状：用户问一个偏冷门的问题，结果模型扯出了另一个完全不相关话题里的信息。

原因大概率是标签过滤没做好。我最初只在召回时用相似度做软匹配，结果就是只要语义有一点点关联，就把别的话题记录捞进来了。解决办法是把“会话标签硬过滤”作为召回第一步，先把候选集缩小，再做语义匹配。宁可漏召回，也不要错召回；漏召回只是答不出来，错召回是答非所问，后者对体验的伤害大得多。

5.2 向量召回结果一阵好一阵坏

说实话，这个问题的排查难度最高。我遇到过的情况是：昨天同一个问法召回得很准，今天改了嵌入模型的版本之后所有相似度分数都下降了。这就是典型的向量空间漂移。

所以我再次强调：嵌入模型版本要锁死，模型文件要固定，不能用“哪个顺手用哪个”的心态去换。如果确实要升级嵌入模型，就得把全量记忆重新向量化一遍，没有捷径。

5.3 记忆膨胀导致注入内容混乱

很多用户反馈，用一段时间之后，模型说话风格好像“变啰嗦了”。查了半天，最后发现是记忆库膨胀了，每次召回都携带了大量低价值的重复记忆。解决手段是加一条去重规则：提取新记忆之前，先对已有的高相似记忆做检查，超过阈值就替换更新，而不是新增一条记录。

比如用户前后说过两次“我喜欢简洁的回答”，第一次存了一条，第二次又存一条，第三次再存一条，这样就是三条几乎一模一样的记忆。正确做法是让第二次的回答更新第一条的时间戳，同时把重要性微调一下，不让信息无限膨胀。

5.4 问题与排查速查表

下面这个表格是我整理排障时常用的对照表，很适合贴到项目文档里。

5.5 数据备份与迁移

既然记忆是落地的宝贵资产，备份必须安排上。SQLite 文件小的时候直接整体复制即可，但向量文件是二进制格式，备份时要特别注意文件头是否写入了向量数量。我出现过一次只复制了数据库、没复制向量文件，结果召回模块启动后疯狂报错。建议写一个简单的导出脚本，统一把数据库和向量文件打包成一份带版本号的文件，恢复时检查版本一致性。

另外，如果以后想迁移到真正的向量数据库，千万别手动去搬二进制文件。设计 claude-mem 时，每一份向量都带了记录 ID，就是为迁移做准备的。迁移前先在目标库建外表，再按照记忆 ID 逐条回填向量，这样中途断掉也能续传，不用重来。

最后说几句实在话

我实际用下来的最大感受是：给对话模型加记忆，难度不在技术实现，而在信息管理。提取质量、去重策略、隔离标签这三个地方的打磨，占了我整个开发周期七成以上的时间。向量计算那些东西反而是最省心的部分。所以如果你想复刻这个方案，别一上来就追求召回算法多花哨，先老老实实把提取 prompt 调明白，把标签体系定清楚。记忆的质量决定了整个系统质量的上限，召唤术摆得再好看，仓库里存的全是破铜烂铁也一样白搭。

最后再补一个很实用的小技巧：给记忆数据库定期做一次“主动复盘”很有帮助。我每个月跑一次统计算法，把长期没有被召回的记忆列出来，要么降权，要么标记为可清理项。这个过程就像定期整理日记本，看着没什么技术含量，但能让整个记忆系统长期保持干净。