1. 从零理解 claude-mem：它到底在解决什么问题
第一次看到 claude-mem 这个名字，很多人会以为它只是某个记忆插件的小玩具。但真正在长会话场景里折腾过的人都知道，上下文窗口再大，也扛不住几十轮对话之后模型开始“失忆”——前面聊过的技术选型、命名规范、接口约定，到了后面全被稀释掉。claude-mem 要干的事情很直接：给对话式 AI 装一套可持久化、可检索、可分层调用的记忆系统，让它在跨会话、跨任务的场景下依然记得住关键信息。
我把它理解成给 AI 配了一个“外挂笔记本”。模型本身的上下文是短期记忆，会话一关就清空；claude-mem 负责把值得留存的内容抽出来，落到本地或指定存储里，下次需要时再按相关性召回。它解决的核心痛点有三个：一是长对话中的信息衰减，二是跨会话的上下文断裂，三是重复交代背景带来的 token 浪费。适合谁来参考？如果你在做 AI 助手类产品、个人知识管理工具、或者只是想让自己日常用的对话助手更“懂你”，这套思路都值得拆一遍。
需要先说明的是，claude-mem 并不是一个官方标准组件，更像是一类“记忆中间层”方案的代称。不同实现细节会有差异，但核心架构思路是相通的。下面我基于常见的工程实践，把这套东西从设计到落地完整讲一遍，涉及具体参数和代码的地方，都是可以直接抄作业的形态。
2. 整体架构设计：记忆系统为什么必须分层
2.1 为什么不能把所有内容都塞进上下文
很多人第一反应是：既然上下文窗口有 100K 甚至 200K token，那我全塞进去不就行了？实测下来这条路走不通，原因有三层。第一层是成本，每次请求都带上几万 token 的历史，费用会线性膨胀，长期跑下来账单很难看。第二层是注意力稀释，模型对超长上下文的中间部分召回率明显下降，业内俗称“lost in the middle”，你塞得越多，关键信息反而越容易被淹没。第三层是噪声，历史对话里大量寒暄、试错、废弃方案，这些内容会干扰模型判断当前任务的真实意图。
所以 claude-mem 的核心设计哲学是：不是记住所有，而是记住该记的，并且在需要时才调用。这就要求系统具备筛选、压缩、索引、召回四个能力，缺一不可。
2.2 三层记忆结构的设计逻辑
我在实际搭建时采用的是三层结构，这套分层在多个项目里验证过比较稳：
| 层级 | 名称 | 存储内容 | 生命周期 | 调用频率 |
|---|---|---|---|---|
| L1 | 工作记忆 | 当前会话最近 N 轮原文 | 会话内 | 每轮必带 |
| L2 | 情景记忆 | 会话摘要、任务结论、决策记录 | 跨会话持久 | 按相关性召回 |
| L3 | 语义记忆 | 用户偏好、领域知识、长期事实 | 长期持久 | 按需注入 |
L1 就是常规的对话历史，保留最近 6 到 10 轮即可，保证当前对话的连贯性。L2 是重点，每次会话结束或达到一定轮次时，触发一次摘要抽取，把“这次聊了什么、得出了什么结论、有哪些待办”结构化存下来。L3 则是更稳定的用户画像和知识沉淀，比如“这个用户偏好 Python 而不是 Java”“项目用的是 PostgreSQL 不是 MySQL”，这类信息一旦确认就长期保留。
提示：三层不是越多越好。我见过有人搞五六层，结果召回逻辑复杂到自己都维护不动。三层足够覆盖 90% 的场景，先把这三层跑通再考虑扩展。
2.3 存储选型：为什么我最终选了 SQLite 加向量索引
存储这块踩过不少坑。最早用纯 JSON 文件，简单是简单，但一旦记忆条目超过几百条，检索就变成全表扫描，慢得离谱。后来试过纯向量数据库，语义检索确实强，但精确查询（比如“上周三那条关于接口超时的记录”）反而不好使，而且部署成本高。
最终方案是SQLite 存结构化字段 + 向量索引存语义向量的混合模式。SQLite 负责时间、标签、类型、会话 ID 这些可精确过滤的字段，向量索引负责语义相似度召回。查询时先用 SQLite 做粗筛（比如限定时间范围和记忆类型），再用向量做精排，这样既快又准。对于个人项目和小团队，这个组合的性价比是最高的，零额外服务依赖，一个文件就能带走。
3. 核心细节解析：记忆的写入、压缩与召回
3.1 写入时机：什么时候该触发记忆抽取
写入时机选错，整个系统就废了。如果每轮对话都写，会产生大量碎片化、重复的记忆，检索时全是噪声；如果只在会话结束写，中途崩溃就全丢了。我的做法是双触发：
- 轮次触发：每积累 8 到 12 轮对话，触发一次增量摘要，把这段内容压缩成一条情景记忆。
- 事件触发：检测到关键事件时立即写入，比如用户明确说“记住这个”“以后都这样”，或者出现了明确的决策结论、配置参数、待办事项。
这里有个细节很关键：抽取不是简单截断，而是要让模型做一次结构化输出。我用的 prompt 模板大致是这样的：
EXTRACT_PROMPT = """ 从以下对话片段中抽取值得长期记忆的信息，按 JSON 输出： { "summary": "一句话概括这段对话的主题", "decisions": ["明确的决策或结论"], "facts": ["确认的事实，如技术栈、偏好、约束"], "todos": ["待办事项"], "tags": ["用于检索的标签"] } 只输出 JSON，没有内容则对应字段留空数组。 对话片段： {dialogue} """这样抽出来的记忆是结构化的，后续检索和注入都好处理。实测下来，结构化抽取比存原文摘要的召回准确率高出一大截。
3.2 压缩策略：摘要不是越短越好
压缩这块有个反直觉的经验：摘要太短反而更费 token。因为摘要过短会丢失关键限定条件，导致召回后模型理解偏差，你还得再补充说明，来回反而更贵。我的压缩比例控制在原文的 15% 到 25% 之间，保留“谁、做了什么、为什么、结论是什么”这四个要素。
具体操作上，我分两步走。第一步做去噪，把寒暄、重复确认、试错过程删掉，只留有效信息。第二步做结构化压缩，按上面那个 JSON 模板输出。两步分开做的好处是，去噪可以用规则加轻量模型，成本低；结构化压缩用能力强的模型，保证质量。如果一步到位让大模型直接压缩，成本高且容易漏掉细节。
3.3 召回逻辑：相关性排序的三个维度
召回是记忆系统里最考验工程能力的一环。只按语义相似度排，会漏掉时间相关和重要性相关的记忆。我的排序公式是三个维度的加权：
score = 0.5 * 语义相似度 + 0.3 * 时间衰减因子 + 0.2 * 重要性权重语义相似度用向量余弦距离，时间衰减因子按exp(-λ * 天数)计算，λ 取 0.05 左右，意味着两周前的记忆权重衰减到约一半。重要性权重在写入时由模型打分，1 到 5 分，决策类和事实类通常给高分，普通对话给低分。
召回数量也要控制，我一般取 top 5 到 top 8 条注入上下文。太多会挤占当前对话空间，太少又可能漏关键信息。这个数字可以根据你的上下文窗口大小调整，窗口大就多召回几条，窗口小就精简。
注意：召回时一定要做去重。同一件事可能在多次会话里被反复记录，如果不去重，注入时会重复占用 token。我用的方法是按 summary 的向量相似度做聚类，相似度超过 0.9 的只保留最新一条。
4. 实操过程：从零搭一个可用的记忆系统
4.1 环境准备与依赖安装
先把基础环境搭起来。我用的是 Python 3.10 以上，核心依赖就三个：向量计算、SQLite 操作、以及调用模型的 SDK。向量这块我推荐用轻量的本地嵌入模型，避免额外 API 调用成本和延迟。
pip install sqlite-utils numpy sentence-transformers如果你不想装 sentence-transformers 那么重，也可以用 API 方式做嵌入，但本地模型在隐私和成本上更有优势。SQLite 是 Python 内置的，不用额外装。数据库文件建议放在项目目录下的.memory/文件夹里，方便版本管理和备份。
4.2 数据库表结构设计
表结构设计要兼顾查询效率和扩展性。我用了三张表：
CREATE TABLE memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, memory_type TEXT NOT NULL, -- episodic / semantic summary TEXT NOT NULL, content TEXT NOT NULL, -- JSON 字符串 importance INTEGER DEFAULT 3, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, accessed_at TIMESTAMP, access_count INTEGER DEFAULT 0 ); CREATE TABLE embeddings ( memory_id INTEGER PRIMARY KEY, vector BLOB NOT NULL, FOREIGN KEY (memory_id) REFERENCES memories(id) ); CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, started_at TIMESTAMP, last_active TIMESTAMP, turn_count INTEGER DEFAULT 0 );access_count和accessed_at这两个字段很多人会忽略，但它们对优化召回很有用。被频繁访问的记忆说明价值高，可以在排序时加权；长期没被访问的可以归档或清理。
4.3 记忆写入的完整实现
写入流程分四步：接收对话片段、调用模型抽取、生成向量、落库。核心代码如下：
import json import sqlite3 import numpy as np from sentence_transformers import SentenceTransformer model = SentenceTransformer('all-MiniLM-L6-v2') def write_memory(conn, session_id, dialogue, memory_type='episodic'): # 1. 抽取结构化信息 extracted = extract_with_llm(dialogue) if not extracted.get('summary'): return None # 2. 生成向量 vector = model.encode(extracted['summary']) # 3. 落库 cur = conn.cursor() cur.execute(""" INSERT INTO memories (session_id, memory_type, summary, content, importance) VALUES (?, ?, ?, ?, ?) """, ( session_id, memory_type, extracted['summary'], json.dumps(extracted, ensure_ascii=False), extracted.get('importance', 3) )) memory_id = cur.lastrowid cur.execute( "INSERT INTO embeddings (memory_id, vector) VALUES (?, ?)", (memory_id, vector.tobytes()) ) conn.commit() return memory_id这里有个实操细节：向量存成 BLOB 比存成 JSON 数组省空间，读取时用np.frombuffer还原即可。几百条记忆用这种方式，数据库文件也就几 MB。
4.4 召回与注入的完整流程
召回时先做粗筛再做精排，最后组装成注入文本：
def recall_memories(conn, query, top_k=5, days_limit=30): query_vec = model.encode(query) # 粗筛：限定时间范围 cur = conn.cursor() cur.execute(""" SELECT m.id, m.summary, m.content, m.importance, m.created_at, e.vector FROM memories m JOIN embeddings e ON m.id = e.memory_id WHERE m.created_at >= datetime('now', ?) """, (f'-{days_limit} days',)) rows = cur.fetchall() scored = [] for row in rows: mem_vec = np.frombuffer(row[5], dtype=np.float32) sim = float(np.dot(query_vec, mem_vec) / (np.linalg.norm(query_vec) * np.linalg.norm(mem_vec))) days_old = (time.time() - parse_time(row[4])) / 86400 time_factor = np.exp(-0.05 * days_old) score = 0.5 * sim + 0.3 * time_factor + 0.2 * (row[3] / 5) scored.append((score, row)) scored.sort(key=lambda x: x[0], reverse=True) return [r[1] for r in scored[:top_k]]注入时把召回的记忆拼成一段带标签的文本，放在系统提示或用户消息前面：
[相关记忆] - 用户偏好使用 Python，项目数据库为 PostgreSQL - 上次讨论确定接口超时阈值设为 3 秒 - 待办：补充单元测试覆盖边界情况这样模型就能自然地把这些信息纳入当前推理，而不需要你重新交代一遍。
5. 常见问题与排查技巧实录
5.1 记忆污染：错误信息被反复强化
这是最头疼的问题。如果某次抽取把错误信息记进去了，后续每次召回都会强化它，模型会越来越“确信”这个错误。我的解决办法是引入记忆校验机制：重要记忆（importance >= 4）在写入前做一次交叉验证，让模型判断这条信息是否与已有记忆冲突。如果冲突，标记为待确认，不直接注入，而是在下次相关对话时主动向用户求证。
5.2 召回不相关：语义相似度失灵
有时候明明有相关记忆，却召回不出来。排查下来通常是两个原因：一是嵌入模型对领域术语不敏感，二是摘要写得太抽象。前者可以换更专业的嵌入模型，后者要在抽取 prompt 里强调“保留具体名词和数值”。我踩过的坑是摘要写成“讨论了性能优化”，这种太泛的摘要向量相似度对谁都高，等于没筛。
5.3 性能瓶颈：记忆多了之后变慢
记忆超过几千条后，全量计算相似度会明显变慢。这时候要上近似最近邻检索，或者用 SQLite 的 FTS5 做关键词预筛，把候选集缩小到几百条再算向量。另一个优化是给created_at和memory_type建索引，粗筛阶段能快很多。
| 问题现象 | 可能原因 | 排查方向 | 解决手段 |
|---|---|---|---|
| 召回结果不相关 | 摘要过泛/嵌入模型不匹配 | 检查摘要具体性 | 优化抽取 prompt，换嵌入模型 |
| 记忆重复注入 | 缺少去重逻辑 | 查 summary 相似度 | 加聚类去重，阈值 0.9 |
| 写入变慢 | 向量计算阻塞 | 看嵌入耗时 | 异步写入，批量处理 |
| 数据库膨胀 | 无清理机制 | 统计条目数和访问频率 | 定期归档低价值记忆 |
5.4 隐私与安全：本地存储的边界
记忆系统会沉淀大量用户信息，这块必须谨慎。我的原则是敏感信息不落库，在抽取阶段就过滤掉密码、密钥、个人身份信息。另外数据库文件要加密存储，至少做文件系统层面的权限控制。如果是多用户场景，记忆必须按用户隔离，查询时强制带上用户 ID 过滤，避免串号。
6. 进阶优化：让记忆系统真正好用
6.1 记忆的主动遗忘机制
记住该记的，也要忘掉该忘的。我设计了一个衰减清理策略：超过 90 天未被访问、且 importance 低于 3 的记忆，自动归档到冷存储；超过 180 天的直接删除。这样数据库不会无限膨胀，召回质量也能保持。归档不是删除，需要时还能捞回来，但不再参与日常召回。
6.2 记忆的关联图谱
单条记忆是孤立的，但真实知识是网状的。我在记忆之间加了关联字段，比如“这条决策依赖于那条事实”。召回时如果命中一条，可以顺带把关联的几条一起带出来，上下文更完整。实现上用一张关联表存memory_id_a和memory_id_b以及关系类型，查询时做一跳扩展即可。这个优化对复杂任务场景提升很明显。
6.3 与工作流的结合
记忆系统单独跑价值有限，真正发挥威力是和工作流结合。比如在代码助手场景里，把项目规范、命名约定、架构决策存成语义记忆，每次生成代码前自动注入，输出的一致性会好很多。在客服场景里，把用户历史问题和解决方案存成情景记忆，新问题进来先召回相似历史，响应速度和准确率都能提升。
我在实际项目里体会最深的一点是：记忆系统的价值不在于技术多复杂，而在于抽取质量和召回精度这两个环节。这两块打磨好了，哪怕存储用最简单的方案，效果也远超预期。反过来，抽取和召回做得糙，堆再多花哨功能也是白搭。所以如果你准备动手，建议先把抽取 prompt 和召回排序这两件事做扎实，其他的都可以后面慢慢加。
