claude-mem 记忆系统架构解析：让大模型跨会话记住上下文

1. 项目概述与核心定位

1.1 这个项目到底在解决什么问题

claude-mem这个名字，第一次看到的时候我下意识以为是某个 Claude 的周边小工具，直到真正上手跑了一遍才发现，它解决的是一个非常具体、非常痛的场景：让 Claude 这类大语言模型在跨会话、跨任务的时候，能够记住之前发生过什么。

做过 AI 应用开发的人都知道，大模型本身是"无状态"的。你这次跟它聊了三个小时，把项目架构、命名规范、踩过的坑全讲清楚了，关掉窗口再开一个新会话，它对你一无所知，一切从头再来。这在单次对话里还能忍，但一旦你要做的是持续几周甚至几个月的项目，这种"失忆"就是灾难。

claude-mem的核心价值就在这儿：它给 Claude 装了一套外部记忆系统。你可以把它理解成给模型配了一个随身笔记本，每次对话的关键信息会被结构化地存下来，下次需要的时候再按需取回，塞进上下文里。这样模型就能"记得"你上周定的接口规范、上个月讨论过的技术选型、甚至你随口提过的一个偏好。

1.2 适合谁来用

我梳理了一下，这个项目主要面向三类人：

• 重度 Claude 使用者：每天要跟 Claude 来回几十轮，做代码、写文档、做分析，受够了每次都要重新交代背景。
• AI 应用开发者：正在做基于 Claude 的 Agent、工作流、知识助手，需要一套可复用的记忆层，不想从零造轮子。
• 技术团队：希望把团队的知识沉淀和 Claude 的对话历史打通，让 AI 真正成为"了解项目上下文"的协作者。

如果你只是偶尔问 Claude 一两个问题，那这东西对你意义不大。但只要你的使用频率上来了，或者你在做的是有延续性的工作，claude-mem这类记忆层就是刚需。

1.3 它和"把历史对话粘回去"有什么区别

很多人第一反应是：我直接把之前的对话复制粘贴进去不就行了？我一开始也这么想，实测下来问题一大堆。

第一，上下文窗口是有限的。你把几万字的对话全塞进去，token 消耗爆炸，而且真正有用的信息可能只占 5%，剩下 95% 都是噪音，反而干扰模型判断。

第二，原始对话是非结构化的。模型要从一堆闲聊里自己提炼出"用户偏好用 TypeScript 严格模式"这种结论，效率很低，还容易漏。

第三，没有检索能力。你粘回去的是"全部"，而不是"相关的那部分"。当项目积累到几十次对话后，你根本不知道该粘哪一段。

claude-mem的思路是把记忆结构化 + 可检索：存的时候做提炼和分类，取的时候按相关性召回。这是它和"暴力粘贴"的本质区别，也是它值得单独拿出来讲的原因。

2. 核心架构与设计思路拆解

2.1 记忆分层：为什么不能只有一层

我在实际搭建类似系统的时候，最大的体会是：记忆不能只有一层。claude-mem的设计里，记忆是分层的，这个思路非常关键。

大致可以分成这么几层：

为什么要这么分？因为不同信息的"保鲜期"和"复用频率"完全不同。你随口说的一句"这个变量名先这么叫"，可能只对当前会话有效；但你定的"所有 API 返回统一用{code, data, msg}结构"，那是要管几个月的。混在一起存，检索的时候就会互相污染。

提示：分层不是越多越好。我见过有人分了七八层，结果维护成本爆炸，检索逻辑复杂到没人看得懂。三到四层对绝大多数场景足够了。

2.2 存储选型：为什么是向量库 + 结构化存储的组合

claude-mem这类系统，存储层通常不会只用一种方案。我实测下来，比较稳的组合是向量数据库 + 关系型/文档型数据库双写。

向量库负责什么？负责语义检索。你把每条记忆转成 embedding 存进去，检索的时候把当前问题也转成 embedding，算余弦相似度，召回语义上最接近的几条。这样即使用户问的措辞和当初存的时候完全不一样，也能命中。

结构化存储负责什么？负责精确过滤和元数据管理。比如你想找"上周关于数据库选型的决策"，光靠语义相似度可能召回一堆不相关的技术讨论，但如果你在结构化库里给每条记忆打了topic: database、type: decision、timestamp这些标签，就能先过滤再排序，精度高很多。

我踩过的一个坑是：只上向量库，不做元数据。结果检索出来的东西"看起来相关"，但经常不是用户真正要的那条，因为语义相似不等于意图匹配。后来加了标签过滤，命中率肉眼可见地提升。

2.3 写入时机：什么时候该记，什么时候不该记

这是整个系统里最容易被低估的设计点。很多人以为"记得越多越好"，实际上记忆的质量比数量重要得多。

claude-mem的写入策略，我理解核心是两条：

• 触发式写入：不是每句话都存，而是识别出"值得记"的信号才写。比如用户明确说"记住这个"、出现了决策性语句（"我们决定用 X"）、出现了可复用的结论（"这个报错的根因是 Y"）。
• 压缩式写入：存进去的不是原始对话，而是提炼后的摘要。一段 2000 字的讨论，可能压缩成 50 字的事实条目。

为什么这么设计？因为如果什么都存，检索的信噪比会迅速恶化。你存了 10000 条记忆，其中 9000 条是废话，那检索系统再强也救不回来。记忆系统的天花板，取决于写入时的筛选质量。

2.4 检索策略：召回、重排、注入的三段式

检索这块，claude-mem走的是经典的三段式：

1. 召回（Recall）：用向量检索 + 关键词检索，快速从海量记忆里捞出候选集，比如 top 50。
2. 重排（Rerank）：用一个更精细的模型或规则，对候选集重新打分排序，选出真正相关的 top 5。
3. 注入（Inject）：把选出的记忆格式化成一段简洁的上下文，拼进发给 Claude 的 prompt 里。

这个流程里，重排是最容易被省掉但最不该省的一步。我试过直接拿向量相似度 top 5 就注入，效果明显不如加了重排。因为向量相似度是"粗筛"，它分不清"语义相关"和"真正有用"。重排环节可以用交叉编码器，也可以用简单的规则（时间衰减、类型权重、来源可信度）组合，成本不高但收益很大。

3. 核心细节解析与实操要点

3.1 记忆条目的数据结构设计

要让记忆系统跑得顺，第一步是把"一条记忆"长什么样定义清楚。我参考claude-mem的思路，整理了一个比较通用的结构：

{ "id": "mem_20240115_001", "content": "项目 API 统一返回结构为 {code, data, msg}", "type": "decision", "topic": "api-design", "tags": ["backend", "convention"], "source_session": "sess_abc123", "created_at": "2024-01-15T10:30:00Z", "last_accessed": "2024-01-20T14:00:00Z", "access_count": 7, "confidence": 0.95, "embedding": [0.012, -0.034, ...] }

这里面几个字段值得单独说：

• type：区分记忆类型。decision（决策）、fact（事实）、preference（偏好）、error（错误记录）等。不同类型在检索时的权重不一样，决策类通常优先级更高。
• confidence：置信度。用户明确说的记 0.95，模型自己推断的记 0.6。检索时可以按置信度加权，避免把模型的猜测当成事实。
• access_count / last_accessed：访问统计。用得越频繁、越近期的记忆，权重越高。这是模拟人类记忆的"遗忘曲线"。
• embedding：向量表示，检索的核心。

注意：content字段一定要短。我建议控制在 100 字以内。太长的记忆条目检索精度会下降，而且注入上下文时占 token。如果一条信息确实很长，拆成多条。

3.2 记忆提炼的 prompt 设计

写入环节的核心是"怎么把一段对话提炼成一条记忆"。这步通常靠 Claude 自己来做，所以 prompt 设计很关键。我实测下来，一个有效的提炼 prompt 大概长这样：

你是一个记忆提炼器。请从以下对话片段中，提取出值得长期记住的信息。 提取标准： 1. 用户明确表达的偏好、决策、约定 2. 可复用的技术结论、根因分析 3. 项目的关键背景信息 不要提取： - 闲聊、寒暄 - 一次性的临时信息 - 已经过时的内容 输出格式（JSON 数组）： [{"content": "...", "type": "...", "topic": "...", "confidence": 0.0-1.0}] 对话片段： {conversation}

这个 prompt 里有几个细节是我反复调出来的：

• 明确"不要提取"的清单：只告诉模型"提取什么"不够，它会过度提取。加上负面清单，精度明显提升。
• 要求输出 JSON：方便程序解析，避免还要再解析自然语言。
• confidence 让模型自己打分：虽然不完美，但比不给强，至少能过滤掉一批低置信度的。

3.3 检索时的上下文注入格式

检索出来的记忆，怎么塞进 prompt 也有讲究。我见过两种做法，效果差别很大。

做法 A（不推荐）：直接把记忆条目罗列进去。

相关记忆： - 项目 API 统一返回结构为 {code, data, msg} - 用户偏好 TypeScript 严格模式 - 数据库选型确定为 PostgreSQL

做法 B（推荐）：加上来源、时间、类型，让模型知道怎么用。

以下是与当前任务相关的历史记忆，供参考： [决策 | 2024-01-15] 项目 API 统一返回结构为 {code, data, msg} [偏好 | 2024-01-10] 用户偏好 TypeScript 严格模式 [决策 | 2024-01-08] 数据库选型确定为 PostgreSQL 请结合以上背景回答，如与当前需求冲突，以用户最新指令为准。

做法 B 的好处是：模型能区分"这是历史决策"和"这是当前指令"，不会盲目遵循旧记忆。最后那句"以用户最新指令为准"很重要，否则模型可能被过时记忆带偏。

3.4 记忆的更新与冲突处理

记忆系统跑久了，一定会遇到新旧记忆冲突的情况。比如三个月前记的是"用 MySQL"，现在改成了"用 PostgreSQL"。如果两条都留着，检索时可能同时召回，模型就懵了。

claude-mem这类系统的处理思路，我总结了几种：

• 覆盖式：新记忆直接标记旧记忆为失效。简单，但会丢失历史。
• 版本式：保留所有版本，检索时只取最新。适合需要追溯决策历史的场景。
• 合并式：把冲突的记忆合并成一条，注明"从 X 改为 Y"。信息最全，但实现复杂。

我个人的选择是版本式 + 时间衰减：旧记忆不删，但检索时按时间加权，越新的权重越高。这样既保留了历史，又不会让旧信息干扰当前判断。实测下来这个方案在大多数场景下够用，实现也不复杂。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

假设你要从零搭一套claude-mem风格的记忆系统，我按实际跑通的流程给你捋一遍。先明确技术栈：

• 语言：Python 3.10+（生态最全，调试方便）
• 向量库：本地开发用 Chroma 或 FAISS，生产环境可以考虑更成熟的方案
• 结构化存储：SQLite 起步，需要并发就上 PostgreSQL
• 模型调用：Claude API（用于提炼和重排）

安装依赖：

pip install anthropic chromadb sqlite-utils numpy

这里我特意选了 Chroma 而不是更重的方案，原因是本地开发阶段，启动速度和零配置比性能更重要。你不需要为了跑通一个记忆系统先去搭一套分布式向量库，那是过度工程。

4.2 记忆写入的完整实现

写入流程分四步：接收对话 → 提炼 → 生成向量 → 双写存储。

import anthropic import chromadb import sqlite3 import json import hashlib from datetime import datetime client = anthropic.Anthropic() chroma = chromadb.PersistentClient(path="./mem_db") collection = chroma.get_or_create_collection("memories") conn = sqlite3.connect("memories.db") def extract_memories(conversation: str) -> list: prompt = f"""从以下对话中提取值得长期记住的信息。 输出 JSON 数组，每项包含 content, type, topic, confidence。 不要提取闲聊和临时信息。 对话： {conversation} """ resp = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=1000, messages=[{"role": "user", "content": prompt}] ) text = resp.content[0].text # 容错处理：模型可能带 markdown 代码块 text = text.strip().removeprefix("```json").removesuffix("```").strip() return json.loads(text) def write_memory(conversation: str, session_id: str): memories = extract_memories(conversation) for m in memories: mem_id = "mem_" + hashlib.md5( (m["content"] + session_id).encode() ).hexdigest()[:12] # 写入结构化库 conn.execute( """INSERT OR REPLACE INTO memories (id, content, type, topic, session_id, created_at, confidence) VALUES (?, ?, ?, ?, ?, ?, ?)""", (mem_id, m["content"], m["type"], m["topic"], session_id, datetime.now().isoformat(), m["confidence"]) ) conn.commit() # 写入向量库 collection.add( ids=[mem_id], documents=[m["content"]], metadatas=[{"type": m["type"], "topic": m["topic"]}] )

这段代码里有几个我踩过坑的地方：

• removeprefix/removesuffix处理代码块：模型输出 JSON 时经常裹一层 markdown，不处理会解析失败。
• INSERT OR REPLACE：防止重复写入同一条记忆。
• id 用内容哈希：这样相同内容不会重复存，天然去重。

4.3 记忆检索与注入的实现

检索流程：查询 → 向量召回 → 元数据过滤 → 重排 → 格式化注入。

def retrieve_memories(query: str, top_k: int = 5) -> list: # 第一步：向量召回，多召回一些候选 results = collection.query( query_texts=[query], n_results=20 ) candidates = [] for i, mem_id in enumerate(results["ids"][0]): candidates.append({ "id": mem_id, "content": results["documents"][0][i], "distance": results["distances"][0][i], "metadata": results["metadatas"][0][i] }) # 第二步：从结构化库补充时间、访问次数等信息 for c in candidates: row = conn.execute( "SELECT created_at, access_count, confidence FROM memories WHERE id=?", (c["id"],) ).fetchone() if row: c["created_at"] = row[0] c["access_count"] = row[1] or 0 c["confidence"] = row[2] or 0.5 # 第三步：重排打分 now = datetime.now() for c in candidates: # 时间衰减：越新越高，半衰期 30 天 age_days = (now - datetime.fromisoformat(c["created_at"])).days time_score = 0.5 ** (age_days / 30) # 访问热度 heat_score = min(c["access_count"] / 10, 1.0) # 语义相似度（距离转分数） sim_score = 1 - c["distance"] c["final_score"] = ( 0.5 * sim_score + 0.2 * time_score + 0.15 * heat_score + 0.15 * c["confidence"] ) candidates.sort(key=lambda x: x["final_score"], reverse=True) return candidates[:top_k] def build_context(query: str) -> str: memories = retrieve_memories(query) if not memories: return "" lines = ["以下是与当前任务相关的历史记忆，供参考：\n"] for m in memories: date = m["created_at"][:10] lines.append(f"[{m['metadata']['type']} | {date}] {m['content']}") lines.append("\n请结合以上背景回答，如与当前需求冲突，以用户最新指令为准。") return "\n".join(lines)

重排的权重0.5 / 0.2 / 0.15 / 0.15不是拍脑袋定的，是我调了几轮的结果。语义相似度占大头是合理的，但纯靠它不够，时间和热度能有效过滤掉"语义相关但已经过时"的记忆。

4.4 参数选择背后的计算逻辑

上面代码里有两个参数值得展开说，因为很多人直接抄但不知道为什么。

半衰期 30 天：这个数字来自一个经验判断——大多数项目的技术决策，有效期大概在一到三个月。半衰期设 30 天意味着，一条 30 天前的记忆权重降到 0.5，60 天前降到 0.25。这样既不会让旧记忆立刻失效，也不会让它长期霸占检索结果。如果你的项目节奏更快，可以调到 14 天；如果是长期研究型项目，可以调到 90 天。

召回 20 条、注入 5 条：召回数要明显大于注入数，给重排留出空间。20 这个数字是平衡——太少重排没得选，太多重排成本高。注入 5 条是因为上下文窗口宝贵，5 条记忆大概占 300-500 token，性价比最高。实测超过 8 条后，边际收益就很小了，反而稀释了关键信息。

4.5 数据库表结构

结构化库的表结构，我用的比较简单：

CREATE TABLE IF NOT EXISTS memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, type TEXT, topic TEXT, session_id TEXT, created_at TEXT, last_accessed TEXT, access_count INTEGER DEFAULT 0, confidence REAL DEFAULT 0.5 ); CREATE INDEX idx_topic ON memories(topic); CREATE INDEX idx_type ON memories(type); CREATE INDEX idx_created ON memories(created_at);

索引建在topic、type、created_at上，因为这三个字段最常用于过滤。别小看索引，记忆量上到几万条之后，有没有索引查询速度差一个数量级。

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

5.1 检索结果不相关怎么办

这是最高频的问题。我遇到过的原因和解法，整理成一张表：

我印象最深的一次，是检索"数据库配置"却召回了一堆"数据库设计讨论"。根因是 embedding 模型对"配置"和"设计"区分度不够。后来我在检索时加了topic过滤，先按主题缩小范围再算相似度，问题就解决了。元数据过滤是提升检索精度的低成本利器，别只依赖向量。

5.2 记忆越存越多，检索越来越慢

这是系统跑一段时间后的必然问题。我的处理经验是：

• 定期归档：超过 90 天且access_count为 0 的记忆，移到归档表，不参与日常检索。
• 合并相似记忆：定期跑一次去重，把语义高度相似的记忆合并。我一般用相似度 0.95 作为阈值。
• 分层检索：先检索近期记忆，不够再检索归档。大部分查询其实只需要近期记忆。

提示：归档不等于删除。归档的记忆在需要时仍可检索，只是不参与默认召回。这样既控制了检索规模，又不丢信息。

5.3 模型不遵循历史记忆

有时候记忆明明检索出来了，模型却不用。我排查下来，主要是两个原因：

第一，注入位置不对。记忆如果放在 prompt 最前面，模型容易被后面的当前指令"覆盖"。我一般把记忆放在系统提示和用户指令之间，效果最好。

第二，记忆表述太模糊。比如"用户对代码风格有要求"这种记忆，模型不知道怎么用。改成"用户要求所有函数必须有类型注解"，模型就能直接执行。记忆要写成可执行的指令，而不是模糊的描述。

5.4 记忆污染与错误传播

这是个隐蔽但危险的问题。如果某次提炼出了错误记忆，它会在后续检索中反复被召回，导致模型持续犯错。我踩过一次：模型把"用户不喜欢 X"错误提炼成了"用户喜欢 X"，结果后面几次对话全反了。

防御手段：

• 置信度门槛：低于 0.6 的记忆不参与检索。
• 人工审核入口：关键记忆（type 为 decision）允许人工确认。
• 定期审计：每周抽检一批记忆，发现错误及时清理。

5.5 常见问题速查表

6. 进阶优化与扩展方向

6.1 记忆的主动遗忘机制

人类记忆会遗忘，AI 记忆系统也应该会。我理解的"主动遗忘"不是简单删除，而是降低权重直到自然淘汰。具体做法是给每条记忆一个"衰减分"，长期不被访问就持续下降，降到阈值以下就归档。这样系统能自动保持"记忆新鲜度"，不需要人工干预。

6.2 多用户与多项目的隔离

如果你要把这套系统用在团队场景，隔离是必须的。我的做法是在记忆条目上加user_id和project_id两个字段，检索时强制过滤。这样不同人、不同项目的记忆不会串。别小看这个，我见过因为没隔离导致 A 项目的决策被 B 项目检索到的尴尬情况。

6.3 记忆的可视化与调试

系统跑起来之后，你需要一个能"看见"记忆的界面。我一般会做一个简单的查询页面，支持按 topic、type、时间筛选，还能手动删除错误记忆。调试阶段这个界面能帮你快速定位问题，比翻日志高效得多。

6.4 与工作流的深度集成

claude-mem真正的价值，是嵌入到日常工作流里。比如：

• 每次代码 review 后，自动提炼评审意见存为记忆。
• 每次需求讨论后，自动记录决策和待办。
• 每次排障后，自动沉淀根因和解决方案。

这样记忆系统就不是一个孤立的工具，而是团队知识的自动沉淀器。我在实际项目里试过这套，几个月下来积累的记忆库，比任何文档都更贴近真实决策过程。

最后分享一个我自己的小习惯：每次开始一个新任务前，我会先手动查一下相关记忆，看看之前有没有踩过类似的坑。这个动作花不了几秒钟，但经常能避免重复劳动。记忆系统的价值，一半在系统本身，一半在你愿不愿意用它。