claude-mem 深度解析：为 Claude 构建可检索的长期记忆系统

1. 项目缘起与核心定位

第一次看到claude-mem这个名字，我的直觉是：这大概率是一个围绕 Claude 生态做“记忆层”的项目。事实也确实如此。它要解决的是一个非常具体、也非常痛的问题——大语言模型在长对话、跨会话场景下没有持久记忆。你每次开一个新窗口，之前聊过的偏好、项目背景、技术栈选型、甚至你反复强调过的“不要用某个库”，全部归零。对于偶尔问答的用户来说这不算什么，但对于把 Claude 当成日常开发助手、写作搭档、长期项目顾问的人来说，这种“失忆”是致命的。

claude-mem的核心价值，就是给 Claude 装上一套可检索、可压缩、可跨会话调用的长期记忆系统。它不是一个简单的聊天记录保存工具，而是一套完整的记忆生命周期管理方案：从对话中抽取关键信息，压缩成结构化记忆，存储到本地或远程数据库，再在后续对话中按需召回并注入上下文。适合谁来参考？三类人最值得看：一是每天用 Claude 写代码、做项目的开发者；二是想把 Claude 接入自己工作流、做自动化助手的工程师；三是对“AI 记忆机制”这个方向感兴趣、想自己动手实现一套的研究型玩家。

我之所以对这个项目感兴趣，是因为我自己踩过太多次“重复解释背景”的坑。一个中型项目跟 Claude 聊了三四天，每次新开会话都要重新贴一遍目录结构、技术栈、命名规范，光这部分就浪费大量 token 和时间。claude-mem这类方案的出现，本质上是把“上下文工程”从手动操作变成了自动化流水线。下面我会从设计思路、核心机制、实操落地、问题排查几个维度，把这套东西拆开讲透。

2. 记忆系统的整体设计与思路拆解

2.1 为什么不能只靠“加大上下文窗口”

很多人第一反应是：现在上下文窗口都到 20 万 token 了，直接把历史记录全塞进去不就行了？这个想法在理论上成立，实操中会撞上三堵墙。

第一堵墙是成本。上下文越长，每次请求的输入 token 越多，费用是线性甚至超线性增长的。你不可能每次问一个简单问题都带上十万 token 的历史。

第二堵墙是注意力稀释。这是实测下来非常明显的现象：当上下文里塞了大量无关历史，模型对当前问题的聚焦能力会下降。你问一个具体函数怎么写，它可能被三天前聊的另一个模块带偏。上下文不是越多越好，相关性才是关键。

第三堵墙是信息密度。原始对话里大量内容是“好的”“明白了”“那我试试”这类无信息量的填充。真正有价值的可能就那几句关键决策。把原始记录全存下来，等于把噪音和信号一起保存，召回时还得再过滤一遍。

claude-mem的设计思路正是针对这三点：抽取而非全存、压缩而非堆砌、按需召回而非全量注入。这个取舍是整个项目最核心的架构决策，理解了它，后面的机制就都好懂了。

2.2 记忆的分层模型

我研究下来，这类系统普遍采用三层记忆结构，claude-mem也基本遵循这个范式：

L1 就是 Claude 原生的上下文窗口，不需要额外处理。L2 是claude-mem发力的重点——它在每次会话结束时（或达到一定轮次时）触发一次“记忆固化”，把这段对话压缩成结构化摘要。L3 则是更稳定的知识，比如“这个用户偏好 TypeScript 严格模式”“这个项目用 pnpm 不用 npm”，这类信息一旦写入就长期有效。

为什么要分层？因为不同信息的“保质期”不一样。一次性的调试过程可能过几天就没用了，但用户的编码偏好是长期有效的。混在一起存，召回时就会互相干扰。分层之后，召回策略可以差异化：L3 永远注入，L2 按相关性召回，L1 只在当前会话有效。

2.3 存储选型：为什么本地优先

claude-mem在存储上倾向于本地优先方案，常见的是 SQLite 配合向量扩展，或者轻量级的向量数据库。这个选择背后有几个考量。

本地存储的第一个好处是隐私。你的对话里可能包含公司内部代码、项目架构、甚至一些敏感的业务逻辑。把这些东西传到第三方云服务上，很多团队是不接受的。本地 SQLite 文件，数据不出机器，合规上最省心。

第二个好处是延迟。记忆召回是每次对话都要做的事，如果每次都走网络请求到远程数据库，累积延迟很可观。本地查询通常在毫秒级，体验上无感。

第三个好处是可控性。你可以直接打开数据库文件看里面存了什么，可以手动清理，可以备份，可以做版本管理。这种透明性是云服务给不了的。

当然本地方案也有代价：多设备同步麻烦、团队共享困难。但对于个人开发者和小团队来说，本地优先是性价比最高的选择。如果确实需要同步，可以自己加一层同步逻辑，比如把 SQLite 文件放到同步盘，或者定期导出。

2.4 召回策略：相似度不是唯一标准

记忆召回最朴素的做法是向量相似度检索：把当前问题转成向量，在记忆库里找最相似的几条。但实测下来，纯相似度召回有几个坑。

第一个坑是时间衰减。三个月前的一条记忆和昨天的一条记忆，即使相似度相同，昨天的显然更相关。所以召回打分通常要加一个时间衰减因子，越新的记忆权重越高。

第二个坑是类型优先级。用户偏好类记忆（L3）应该比一次性的调试记录（L2）优先级更高。哪怕相似度略低，偏好类记忆也应该被召回。

第三个坑是去重与合并。同一个事实可能在多次会话中被反复记录，召回时如果返回五条内容几乎一样的记忆，纯属浪费上下文。所以召回后通常要做一次去重和合并。

claude-mem的召回打分大致是这样一个公式：

score = similarity * w1 + recency * w2 + type_priority * w3

其中w1、w2、w3是权重，需要根据实际使用调。我自己的经验是w1占大头（0.6 左右），w2和w3各占 0.2。但这个不是固定的，如果你更看重长期偏好，可以把w3调高。

3. 核心机制解析与关键实现细节

3.1 记忆抽取：从对话里捞出“值得记”的东西

记忆抽取是整个系统里最考验设计的一环。抽多了，噪音大；抽少了，关键信息丢失。claude-mem通常采用“LLM 抽取 + 规则过滤”的混合策略。

LLM 抽取的做法是：在会话结束时，把对话内容喂给一个抽取 prompt，让它输出结构化的记忆条目。这个 prompt 的设计很关键，一般会要求模型按固定 schema 输出，比如：

{ "memories": [ { "type": "preference", "content": "用户偏好使用 pnpm 而非 npm", "confidence": 0.9, "tags": ["tooling", "package-manager"] }, { "type": "project_fact", "content": "项目使用 Next.js 14 App Router 架构", "confidence": 0.95, "tags": ["architecture", "nextjs"] } ] }

规则过滤则是在 LLM 抽取之后做一层清洗：过滤掉置信度低于阈值的、过滤掉内容过短的、过滤掉和已有记忆高度重复的。这一步能显著提升记忆库的质量。

实操心得：抽取 prompt 里一定要明确要求模型“只抽取未来对话中可能用到的信息”。不加这句，模型会把“用户说你好”这种废话也抽出来。我试过不加约束的版本，记忆库里一半是垃圾。

3.2 记忆压缩：把长对话变成短摘要

除了抽取离散的事实，claude-mem还会对整段会话做摘要压缩。这个摘要不是简单的“本文讲了什么”，而是面向未来召回的“情境摘要”——包含这次会话解决了什么问题、做了哪些决策、遗留了哪些待办。

摘要的粒度控制很重要。太粗，召回时定位不到具体信息；太细，又退化成原始记录。我的经验是控制在 200 到 500 字之间，覆盖 3 到 5 个关键点。格式上建议用结构化列表而非大段文字，方便后续检索和展示。

压缩的另一个作用是降低存储成本。原始对话可能几千 token，压缩后几百 token，存储和召回成本都大幅下降。对于长期使用的用户，这个差距会非常明显。

3.3 向量化与索引：让记忆可检索

记忆存进去之后，要能被快速检索到，就需要向量化。claude-mem通常用嵌入模型把每条记忆转成向量，存到向量索引里。查询时把当前问题也转成向量，做近似最近邻搜索。

嵌入模型的选择上，有几个考量维度：维度大小、推理速度、多语言支持、本地可运行性。对于本地优先的方案，通常会选一个中小型的开源嵌入模型，维度在 384 到 768 之间，兼顾效果和速度。

索引结构上，数据量小的时候（几千条以内）暴力搜索就够用。数据量大了之后需要上 HNSW 或 IVF 这类近似索引。不过对于个人使用场景，记忆条数通常不会超过几万条，暴力搜索配合缓存完全能扛住。

注意：向量化是有成本的。如果每条记忆都实时向量化，会话结束时会有一个明显的延迟。建议把向量化做成异步任务，先落库再慢慢算向量，不阻塞主流程。

3.4 上下文注入：把记忆塞回对话

召回之后，怎么把记忆注入到当前对话里，也是有讲究的。最粗暴的做法是把召回的记忆直接拼在 system prompt 后面。这样做的问题是：记忆多了会挤占上下文，而且格式混乱会让模型困惑。

更好的做法是结构化注入。把召回的记忆按类型分组，用清晰的标记包裹，比如：

[长期偏好] - 用户偏好 TypeScript 严格模式 - 项目使用 pnpm [相关历史] - 上次会话讨论了用户认证方案，最终选择 JWT

这样模型能清楚区分哪些是稳定偏好、哪些是历史情境，使用时不会混淆。注入的位置也有讲究，一般放在 system prompt 的末尾、用户消息之前，这样模型对当前问题的注意力不会被记忆冲淡。

3.5 记忆更新与遗忘：不是只增不减

一个健康的记忆系统必须有遗忘机制。只增不减的记忆库，用几个月就会变成垃圾场，召回质量断崖式下降。

claude-mem的遗忘策略通常包含几种：一是时间衰减，超过一定时间未被召回的记忆，权重逐渐降低，低到阈值以下就归档或删除；二是冲突消解，当新记忆和旧记忆矛盾时（比如用户之前说用 npm，后来说改用 pnpm），要标记旧记忆为失效；三是手动清理，提供接口让用户主动删除某些记忆。

冲突消解这块特别值得说。我遇到过用户偏好从“用 Jest”变成“用 Vitest”的情况，如果两条都留着，召回时模型会收到矛盾信息，输出就会摇摆。正确的做法是检测到冲突后，把旧记忆标记为superseded，召回时只返回最新的那条。

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

4.1 环境准备与依赖安装

假设我们用 Python 来实现一套claude-mem风格的记忆系统，基础依赖大致如下：

pip install anthropic sqlite-vec sentence-transformers fastapi uvicorn

这里解释一下每个依赖的作用。anthropic是调用 Claude API 的官方 SDK；sqlite-vec是 SQLite 的向量扩展，让本地数据库支持向量检索；sentence-transformers用来做本地嵌入，不依赖外部 API；fastapi和uvicorn用来起一个本地服务，方便和 Claude 客户端对接。

数据库初始化：

import sqlite3 import sqlite_vec conn = sqlite3.connect("claude_mem.db") conn.enable_load_extension(True) sqlite_vec.load(conn) conn.enable_load_extension(False) conn.execute(""" CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY, type TEXT NOT NULL, content TEXT NOT NULL, tags TEXT, confidence REAL, created_at INTEGER, last_recalled_at INTEGER, status TEXT DEFAULT 'active' ) """) conn.execute(""" CREATE VIRTUAL TABLE IF NOT EXISTS memory_vectors USING vec0(embedding float[384]) """)

这个 schema 里几个字段值得说明。status用来标记记忆状态，active是正常，superseded是被新记忆取代，archived是归档。last_recalled_at用来做时间衰减计算。confidence是抽取时的置信度，召回时可以参与打分。

4.2 记忆抽取的完整实现

抽取函数的核心是把对话内容喂给 Claude，让它输出结构化记忆：

import anthropic import json client = anthropic.Anthropic() EXTRACT_PROMPT = """你是一个记忆抽取器。从下面的对话中抽取值得长期记住的信息。 只抽取未来对话中可能用到的信息，包括： - 用户偏好（工具、风格、习惯） - 项目事实（技术栈、架构、约定） - 关键决策（选型理由、方案取舍） 不要抽取：寒暄、临时调试过程、一次性问答。 按以下 JSON 格式输出： {"memories": [{"type": "...", "content": "...", "confidence": 0.0-1.0, "tags": [...]}]} 对话内容： {conversation} """ def extract_memories(conversation: str) -> list: response = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=2000, messages=[{ "role": "user", "content": EXTRACT_PROMPT.format(conversation=conversation) }] ) text = response.content[0].text # 容错处理：模型可能包裹 markdown 代码块 text = text.strip().removeprefix("```json").removesuffix("```").strip() data = json.loads(text) return data.get("memories", [])

这里有个细节：模型输出 JSON 时经常包裹在 markdown 代码块里，直接json.loads会报错。所以要先做一层清洗。这个坑我踩过好几次，后来干脆写了个通用的清洗函数。

4.3 向量化与存储

抽取出来的记忆要向量化后存入数据库：

from sentence_transformers import SentenceTransformer embedder = SentenceTransformer("all-MiniLM-L6-v2") def store_memory(conn, memory: dict): embedding = embedder.encode(memory["content"]).tolist() cursor = conn.execute( """INSERT INTO memories (type, content, tags, confidence, created_at, status) VALUES (?, ?, ?, ?, ?, 'active')""", (memory["type"], memory["content"], json.dumps(memory.get("tags", [])), memory.get("confidence", 0.8), int(time.time())) ) memory_id = cursor.lastrowid conn.execute( "INSERT INTO memory_vectors (rowid, embedding) VALUES (?, ?)", (memory_id, json.dumps(embedding)) ) conn.commit() return memory_id

all-MiniLM-L6-v2是个 384 维的轻量嵌入模型，本地跑很快，效果对于记忆检索这个场景够用。如果你对中文支持要求高，可以换成paraphrase-multilingual-MiniLM-L12-v2，维度也是 384，但多语言能力更强。

4.4 召回逻辑与打分

召回是每次对话开始时触发的：

def recall_memories(conn, query: str, top_k: int = 5): query_vec = embedder.encode(query).tolist() rows = conn.execute(""" SELECT m.id, m.content, m.type, m.confidence, m.last_recalled_at, v.distance FROM memory_vectors v JOIN memories m ON m.id = v.rowid WHERE m.status = 'active' ORDER BY v.distance LIMIT ? """, (top_k * 3,)).fetchall() now = time.time() scored = [] for row in rows: similarity = 1 - row["distance"] recency = 1 / (1 + (now - (row["last_recalled_at"] or 0)) / 86400) type_priority = 1.0 if row["type"] == "preference" else 0.7 score = similarity * 0.6 + recency * 0.2 + type_priority * 0.2 scored.append((score, row)) scored.sort(reverse=True, key=lambda x: x[0]) results = [r for _, r in scored[:top_k]] # 更新召回时间 for r in results: conn.execute("UPDATE memories SET last_recalled_at = ? WHERE id = ?", (int(now), r["id"])) conn.commit() return results

这里先取top_k * 3条候选，再用综合打分排序取前top_k。为什么要多取？因为纯向量距离排序可能把一些时间久但很相关的记忆排前面，综合打分后顺序会变，多取候选能保证最终结果质量。

4.5 注入到 Claude 对话

最后一步是把召回的记忆格式化后注入：

def build_context(memories: list) -> str: if not memories: return "" grouped = {} for m in memories: grouped.setdefault(m["type"], []).append(m["content"]) parts = [] type_names = { "preference": "长期偏好", "project_fact": "项目事实", "decision": "关键决策" } for t, items in grouped.items(): name = type_names.get(t, t) parts.append(f"[{name}]\n" + "\n".join(f"- {i}" for i in items)) return "\n\n".join(parts)

调用 Claude 时，把这段 context 拼在 system prompt 末尾即可。整个流程串起来就是：会话开始 → 召回记忆 → 注入上下文 → 正常对话 → 会话结束 → 抽取记忆 → 存储。

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

5.1 记忆召回不准确怎么办

这是最常见的问题。表现是：明明之前聊过某个话题，但新会话里 Claude 完全没反应。排查思路按顺序来：

先确认记忆是否真的存进去了。直接查数据库：SELECT * FROM memories WHERE content LIKE '%关键词%'。如果查不到，说明抽取环节漏了，需要调整抽取 prompt。

如果存进去了但召回不到，检查向量维度是否一致。嵌入模型换了但数据库里的向量还是旧维度，会导致检索报错或结果错乱。这种情况需要重建索引。

如果召回结果不相关，调打分权重。把similarity的权重调高，或者降低recency的影响。我遇到过时间衰减太强导致老但重要的记忆召不回的情况，把recency权重从 0.3 降到 0.15 就正常了。

5.2 记忆库膨胀太快

用了一两周发现记忆库几千条，召回质量下降。这时候要做几件事：

一是提高抽取的置信度阈值。低于 0.7 的直接丢弃，能砍掉大量低质量记忆。

二是做去重。相同或高度相似的记忆只保留最新的一条。可以用向量相似度做去重，相似度超过 0.95 的视为重复。

三是定期归档。超过 30 天未被召回的 L2 记忆，状态改为archived，不再参与召回但保留数据。

5.3 冲突记忆导致输出摇摆

用户偏好变了，但新旧记忆都在，模型收到矛盾信息。解决办法是在存储新记忆时做冲突检测：新记忆入库前，先检索相似度高的旧记忆，如果相似度超过阈值且内容矛盾，把旧记忆标记为superseded。

判断“矛盾”这块，简单做法是让 LLM 判断两条记忆是否冲突。虽然多一次调用，但准确性比规则判断高很多。这个调用可以异步做，不阻塞主流程。

5.4 隐私与数据安全

本地存储虽然相对安全，但也要注意几点。数据库文件不要放在同步盘的公开目录；如果做多设备同步，传输过程要加密；记忆内容里如果包含密钥、密码这类敏感信息，抽取阶段就应该过滤掉。

实操心得：在抽取 prompt 里加一句“不要抽取任何包含密钥、密码、token 的内容”，能挡掉大部分敏感信息。但这不是万无一失的，关键项目还是建议人工定期审查记忆库。

5.5 性能优化经验

记忆系统用久了，性能问题会逐渐显现。几个优化点：

嵌入计算是最耗时的环节。可以批量处理，一次编码多条记忆，比逐条编码快好几倍。另外嵌入模型可以常驻内存，不要每次调用都重新加载。

数据库查询要加索引。status、type、created_at这几个字段经常用于过滤，加上索引查询快很多。

召回结果可以加缓存。相同或相似的查询在短时间内可能重复出现，缓存命中能省掉向量检索的开销。

6. 扩展方向与个人实践体会

这套系统跑通之后，能扩展的方向其实不少。比如加一个记忆可视化面板，用 Web 界面展示记忆库内容、召回历史、打分分布，调试起来直观很多。再比如做多项目隔离，不同项目的记忆分库存储，避免互相污染。还可以接自动摘要，每天定时把当天的记忆汇总成日报，方便回顾。

我自己用下来最大的体会是：记忆系统的价值不在于技术多复杂，而在于抽取质量和召回精度这两个环节。这两个环节做不好，存再多记忆也是负担。所以前期不要贪多，先把抽取 prompt 调好，确保存进去的都是精华，再慢慢优化召回。

另外一点是，不要指望一次做到完美。记忆系统是个需要持续调优的东西，用一段时间就要回头看召回效果，该删的删，该调的调。我现在的做法是每周花十分钟扫一眼记忆库，手动清理明显没用的条目，保持库的干净。这个习惯坚持下来，召回质量一直很稳定。

最后分享一个小技巧：在抽取 prompt 里让模型给每条记忆打标签，召回时可以按标签过滤。比如当前对话是关于前端的，就只召回带frontend标签的记忆。这个简单的过滤能显著提升召回的相关性，实测效果比单纯调权重好得多。