1. 项目缘起与核心定位

第一次看到claude-mem这个名字，我的直觉是：这大概率是给 Claude 这类大模型做“记忆层”的东西。事实也确实如此。它要解决的是一个所有长期用大模型干活的人都绕不开的痛点——模型本身没有跨会话的持久记忆。你这次跟它聊完一个项目的架构决策，关掉窗口，下次再开，它对你、对你的项目、对你们之前达成的共识一无所知，一切从头再来。

claude-mem就是冲着这个来的。它本质上是一套面向 Claude 的持久化记忆系统，把对话中产生的关键信息抽取、存储、组织起来，在后续会话里按需召回，重新注入上下文。你可以把它理解成给模型外挂了一个“笔记本 + 检索器”：模型负责思考和生成，笔记本负责记住“你是谁、你在做什么、上次聊到哪”。

这套东西适合谁？我梳理了三类人。第一类是重度依赖 Claude 做长期项目的开发者，比如连续几周迭代同一个代码库，每次都要重新解释项目背景，效率损耗极大。第二类是把 Claude 当知识助手用的研究者或写作者，需要它记住自己的偏好、术语体系、已确认的事实。第三类是想自己动手搭一套记忆系统的技术爱好者，claude-mem的架构思路本身就很有参考价值，哪怕你不用 Claude，换成别的模型，这套“抽取—存储—召回—注入”的范式照样能迁移。

需要先说明一点：claude-mem这类项目在社区里有多种实现形态，有的偏命令行工具，有的偏 MCP 服务，有的直接做成 SDK。下面我讲的架构和实操，是基于这类记忆系统最常见的工程实践来展开的，具体到你手上的版本，接口名和配置项可能有差异，但核心逻辑是通的。这也是我一贯的建议——先吃透设计思想，再对着具体实现调参数，不然换个版本你就懵了。

2. 记忆系统的整体架构拆解

2.1 为什么不能简单粗暴地“把历史全塞进去”

很多人第一反应是：记忆嘛，把之前所有对话拼起来一起发给模型不就行了？我一开始也这么想过，实测下来根本行不通，原因有三个，而且一个比一个致命。

第一是上下文窗口的硬约束。哪怕现在窗口开到几十万 token，你连续用一个月，历史对话轻松突破这个量级。全量拼接迟早撑爆，而且撑爆之前，成本已经先爆了——token 是按量计费的，每次请求都带上几万 token 的历史，账单会让你怀疑人生。

第二是信噪比崩塌。历史里大量内容是“好的”“明白了”“那我们来试试”这种废话，真正有价值的决策、结论、事实可能只占百分之几。全塞进去，模型注意力被稀释，反而更容易抓错重点，回答质量下降。

第三是冲突与过期。你上周说“数据库用 MySQL”，这周改成了“PostgreSQL”，全量历史里两条都在，模型到底听谁的？没有一套机制去标记“哪条是最新的、哪条已作废”，记忆就会自相矛盾。

所以claude-mem这类系统的核心价值，不在于“存”，而在于有选择地存、有策略地取。存的时候做压缩和结构化，取的时候做相关性排序，这才是关键。

2.2 四层架构：抽取、存储、召回、注入

我把这类系统的骨架归纳成四层，claude-mem基本也是这个路子。

抽取层负责从原始对话里“提炼记忆”。它不是无脑存原文，而是让模型自己判断：这段对话里哪些是值得长期记住的？通常抽取的是几类东西——用户的事实性信息（身份、偏好、技术栈）、项目状态（当前进展、待办、已决策事项）、以及明确的结论和约定。抽取的时机一般是会话结束，或者每积累 N 轮触发一次。

存储层负责把抽取出来的记忆落盘并组织。最简单的是一堆文本文件，进阶一点用向量数据库做语义索引，再复杂点会做知识图谱，把实体和关系连起来。存储层要解决的核心问题是：怎么让召回又快又准。纯文本靠关键词匹配，向量库靠语义相似度，图谱靠关系推理，各有取舍。

召回层是每次新会话开始时触发的。它拿当前对话的意图（或者用户的第一句话）去存储层里查，找出最相关的若干条记忆。这里的关键是排序策略：不能只按相似度，还要考虑时间新近度、重要性权重、以及去重。召回太多会污染上下文，召回太少又漏信息，通常控制在几条到十几条之间。

注入层负责把召回的记忆“喂”回给模型。它不是简单粘贴，而是要包装成一段结构化的上下文，比如“以下是关于该用户和项目的已知信息：……”，放在系统提示或对话开头。注入的措辞很讲究，措辞不好模型会把它当成用户说的话，产生混乱。

2.3 方案选型：文件、向量库还是图谱

这三种存储方案我都在不同项目里试过，给你一个直接的对比。

我的建议很明确：从纯文本起步，痛了再上向量库，图谱除非你真有强关系推理需求，否则别碰。很多人一上来就搭向量库、接嵌入模型，结果发现记忆总共就几十条，关键词搜一下就够用，纯属给自己找麻烦。工程上最忌讳的就是过度设计，claude-mem这类工具的价值是解决问题，不是炫技。

3. 核心细节与实操要点

3.1 记忆抽取：让模型自己判断“什么值得记”

抽取层是整个系统的源头，源头脏了后面全白搭。我的做法是给模型一段明确的抽取指令，让它输出结构化的 JSON。指令大概长这样：

请从以下对话中提取值得长期记忆的信息，按类别输出 JSON： - facts: 关于用户或项目的客观事实（技术栈、偏好、约束） - decisions: 已做出的决策及理由 - todos: 待办事项和当前进展 - entities: 涉及的关键实体（人名、项目名、工具名） 只提取有长期价值的信息，忽略寒暄、临时讨论和已被推翻的内容。 如果某类没有内容，返回空数组。

这里有几个实操心得。第一，一定要让它输出结构化格式，自由文本后面没法检索。第二，明确告诉它忽略什么，不然模型会把“你好”“谢谢”也当成记忆存进去。第三，让它标注置信度和时间，后面召回排序用得上。

注意：抽取指令里的类别不要设太多。我见过有人设了十几个类别，结果模型每类都只抽出一两条，还经常分错类。四到六个类别是比较舒服的区间，覆盖事实、决策、待办、实体就够了。

3.2 存储格式：给每条记忆加上“元数据”

存的时候千万别只存一句话。一条合格的记忆记录，至少包含这几个字段：

{ "id": "mem_20240115_001", "content": "项目数据库从 MySQL 迁移到 PostgreSQL，原因是需要更好的 JSON 支持和并发性能", "type": "decision", "timestamp": "2024-01-15T10:30:00Z", "importance": 0.8, "source_session": "sess_abc123", "tags": ["database", "architecture"], "status": "active" }

importance是重要性权重，0 到 1，抽取时让模型打分。status用来标记记忆是否还有效，被推翻的决策标成deprecated，召回时直接过滤掉，这就解决了前面说的“冲突与过期”问题。tags是给关键词检索用的兜底，向量检索失灵时还能靠标签捞回来。

我特别想强调status这个字段。很多人搭记忆系统只想着“怎么存进去”，不想“怎么让它失效”。结果用了一个月，记忆库里全是过期信息，模型召回一堆作废的决策，回答越来越离谱。记忆系统的一半功夫在“遗忘”上，这个认知我是踩了坑才建立起来的。

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

召回的时候，如果只用向量相似度排序，你会遇到一个典型问题：越新的记忆往往越相关，但相似度不一定最高。比如你刚改完数据库，新记忆是“改用 PostgreSQL”，旧记忆是“用 MySQL”，两句话语义高度相似，纯按相似度排，旧的可能还排在前面。

我的排序公式是这样的，你可以参考：

final_score = 0.5 * similarity + 0.3 * recency + 0.2 * importance

similarity是语义相似度，recency是时间新近度（越新越高，可以用指数衰减），importance是存储时打的权重。三个权重可以根据你的场景调，比如做长期知识管理，importance权重可以调高；做实时对话辅助，recency权重调高。

召回数量上，我的经验是控制在 5 到 10 条。少于 5 条容易漏关键信息，多于 10 条上下文开始变脏，模型会抓不住重点。如果召回结果里有明显重复或高度相似的，做个去重，只留分数最高的那条。

3.4 注入措辞：别让模型把记忆当成用户的话

注入层最容易被忽视，但坑最多。我踩过的一个典型坑是：把记忆直接拼在用户消息前面，结果模型以为这些是用户说的，回复时对着记忆内容回应，完全跑偏。

正确的做法是把记忆放在系统提示里，并用明确的分隔和说明。比如：

[系统记忆] 以下是关于当前用户和项目的已知信息，供你参考，不要在回复中直接复述： - 用户是后端工程师，主力语言 Go 和 Python - 项目 X 使用 PostgreSQL，已从 MySQL 迁移 - 上次会话确认：API 采用 RESTful 风格，暂不考虑 GraphQL [记忆结束]

[系统记忆]这种标记很重要，它给模型一个清晰的边界。另外“不要在回复中直接复述”这句也很有用，不然模型会机械地把记忆念一遍，体验很差。

4. 完整实操流程与关键环节

4.1 环境准备与依赖安装

假设我们用 Python 来实现一套最小可用的claude-mem。先明确依赖：调用 Claude 需要官方 SDK，存储用 SQLite 起步（够用且零配置），向量检索如果后面要上，再引入嵌入模型。

pip install anthropic # SQLite 是 Python 内置的，不用装 # 如果后续要向量检索，再装： # pip install sentence-transformers numpy

目录结构我建议这样组织，清晰且好扩展：

claude-mem/ ├── memory/ │ ├── store.py # 存储层：读写记忆 │ ├── extract.py # 抽取层：从对话提炼记忆 │ ├── recall.py # 召回层：检索相关记忆 │ └── inject.py # 注入层：组装上下文 ├── data/ │ └── memory.db # SQLite 数据库 └── main.py # 主流程

为什么用 SQLite 而不是直接上向量库？因为起步阶段记忆量小，SQLite 的全文检索（FTS5）配合标签过滤，已经能覆盖大部分需求。等你记忆上千条、关键词搜不准了，再迁移到向量库也不迟。迁移成本不高，但一开始就上向量库的复杂度成本很高。

4.2 数据库表结构设计

存储层的表结构直接决定了后面召回能玩出什么花样。我的设计是这样的：

CREATE TABLE memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, type TEXT NOT NULL, timestamp TEXT NOT NULL, importance REAL DEFAULT 0.5, source_session TEXT, tags TEXT, status TEXT DEFAULT 'active' ); CREATE VIRTUAL TABLE memories_fts USING fts5( content, tags, content='memories', content_rowid='rowid' );

memories是主表，memories_fts是全文检索的虚拟表，用 FTS5 做关键词匹配。这样即使不上向量库，也能靠关键词搜到记忆。status字段默认active，作废时改成deprecated，召回时加个WHERE status = 'active'就过滤掉了。

提示：tags字段存的是逗号分隔的字符串，简单够用。如果你后面要做复杂的标签查询，可以拆成单独的表，但起步阶段没必要。

4.3 抽取环节的完整实现

抽取是调模型的地方，也是最花 token 的地方。我的实现思路是：把一段对话（通常是最近 N 轮）喂给模型，让它输出结构化 JSON。

import anthropic import json client = anthropic.Anthropic() EXTRACT_PROMPT = """请从以下对话中提取值得长期记忆的信息，按类别输出 JSON。 类别包括： - facts: 关于用户或项目的客观事实 - decisions: 已做出的决策及理由 - todos: 待办事项和当前进展 - entities: 涉及的关键实体 每条记忆包含 content（内容）、importance（0-1 重要性）、tags（标签数组）。 只提取有长期价值的信息，忽略寒暄和临时讨论。 输出格式：{"memories": [{"type": "...", "content": "...", "importance": 0.8, "tags": ["..."]}]} """ def extract_memories(conversation: str) -> list: response = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=2000, messages=[{ "role": "user", "content": f"{EXTRACT_PROMPT}\n\n对话内容：\n{conversation}" }] ) text = response.content[0].text # 容错处理：模型有时会包一层 markdown 代码块 text = text.strip().removeprefix("```json").removesuffix("```").strip() data = json.loads(text) return data.get("memories", [])

这里有个容错细节必须提：模型输出 JSON 时经常手滑包一层```json代码块，直接json.loads会报错。我加了removeprefix和removesuffix来兜底。更稳的做法是用正则提取第一个{到最后一个}之间的内容，但简单场景下前缀后缀处理就够了。

4.4 召回与注入的串联

召回环节，我先把当前对话的意图转成一个查询，然后走“关键词 + 标签 + 时间”的综合排序。

def recall_memories(query: str, top_k: int = 8) -> list: # 1. 关键词检索（FTS5） keyword_results = search_by_keyword(query) # 2. 标签过滤（如果 query 里能提取出标签） # 3. 综合排序 scored = [] for mem in keyword_results: similarity = compute_similarity(query, mem["content"]) recency = compute_recency(mem["timestamp"]) importance = mem["importance"] final = 0.5 * similarity + 0.3 * recency + 0.2 * importance scored.append((final, mem)) scored.sort(reverse=True, key=lambda x: x[0]) return [mem for _, mem in scored[:top_k]]

compute_similarity在纯文本阶段可以用简单的词重叠率，上了向量库就换成余弦相似度。compute_recency用指数衰减，比如exp(-days / 30)，30 天前的记忆权重衰减到约 0.37，这个衰减速度我觉得比较合适，你可以根据项目节奏调。

注入环节就是把召回的记忆拼成前面说的[系统记忆]块，放在系统提示里。整个主流程串起来就是：会话开始 → 召回 → 注入 → 正常对话 → 会话结束 → 抽取 → 存储。一个闭环。

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

5.1 记忆越存越多，召回越来越慢

这是最常见的抱怨。我一开始也遇到，记忆存到几百条后，每次召回要遍历全部，慢得明显。排查下来有两个原因：一是没建索引，二是没做归档。

解决思路：给timestamp和status建索引，召回时先按status = 'active'过滤，再按时间范围缩小。另外，超过一定时间（比如半年）且重要性低的记忆，可以归档到单独的冷表，不参与日常召回。记忆系统不是只进不出的仓库，定期归档和清理是必须的运维动作。

5.2 模型把记忆内容当成用户指令

前面提过这个坑，这里给完整的排查路径。症状是：模型回复时对着记忆内容说话，比如你记忆里存了“用户喜欢简洁回复”，模型回复开头就是“好的，我会保持简洁”——它把记忆当成了刚收到的指令。

根因是注入位置和措辞不对。修复方法：确保记忆放在系统提示（system prompt）里，而不是用户消息里；用[系统记忆]明确标记；加一句“这些是背景信息，不要直接回应”。改完这三处，基本就解决了。

5.3 抽取出来的记忆质量参差不齐

有时候模型抽出来的记忆是“用户问了关于 Python 的问题”这种废话，没有长期价值。根因是抽取指令不够具体，模型不知道什么算“有价值”。

修复方法：在指令里给正反例。比如明确说“不要提取‘用户提问了 X’这类描述，要提取 X 本身的结论”。另外，让模型给每条记忆打importance分，低于 0.3 的直接丢弃，这个阈值过滤能挡掉大部分垃圾记忆。

5.4 常见问题速查表

5.5 几条踩坑换来的经验

第一，别追求“记住一切”。记忆系统的价值在于精准，不在于全。存得越多，召回越难，噪声越大。宁可少存精存。

第二，给记忆加“过期时间”。不是所有记忆都永久有效，待办类记忆完成后就该失效，决策类记忆被推翻后要作废。没有失效机制的记忆库，用一个月就废了。

第三，抽取和召回要用不同的模型或参数。抽取需要模型有判断力，召回需要的是快速匹配。如果都用同一个大模型，成本高且没必要。召回阶段能用轻量方法就用轻量方法。

第四，一定要有日志。每次召回命中了哪些记忆、注入了多少 token、模型回复质量如何，都记下来。出问题时这些日志是唯一的排查依据。我吃过没日志的亏，一个召回 bug 查了一下午。

6. 后续可扩展的方向

这套最小实现跑通之后，有几个方向可以按需扩展。向量检索是最自然的下一步，接一个嵌入模型，把compute_similarity换成余弦相似度，召回精度会有明显提升，代价是多一个模型依赖和一点计算成本。记忆图谱适合实体关系复杂的场景，把entities抽出来连成图，支持“和项目 X 相关的所有决策”这类关系查询，但构建成本高，想清楚再上。

还有一个我觉得很有价值的方向是记忆的自动衰减与强化。被频繁召回的记忆自动提升重要性，长期没被召回的记忆逐渐降权甚至归档。这模拟了人类记忆的“用进废退”，能让记忆库自己保持精简。实现上就是在每次召回后更新importance字段，逻辑不复杂，但效果很实在。

我自己用下来最大的体会是：记忆系统的难点从来不在技术，而在“判断什么值得记”。这个判断标准会随着你的使用不断调整，抽取指令要反复打磨。别指望一次调好，把它当成一个需要持续喂养和修剪的东西，它才会越用越顺手。