claude-mem 记忆层设计：从存储、检索到更新的工程实践

1. 从零认识 claude-mem：它到底解决什么问题

第一次看到claude-mem这个名字，我脑子里蹦出来的第一个念头是：终于有人把「记忆」这件事单独拎出来做了。做过一段时间 AI 应用开发的人都知道，大模型本身是无状态的，每次对话结束，上下文一清空，它就彻底忘了你是谁、之前聊过什么。这个特性在单次问答里没什么问题，但一旦你想让它扮演一个长期助手、一个持续跟进项目的搭档，或者一个能记住用户偏好的客服角色，无状态就成了最大的拦路虎。

claude-mem就是冲着这个痛点来的。从名字拆解，claude指向的是 Anthropic 家的 Claude 系列模型，mem是 memory 的缩写。合起来，它是一套围绕 Claude 构建的记忆层方案——让模型在多次会话之间保留、检索、更新关键信息，从而表现出「记得住」的能力。它要解决的核心问题有三个：第一，跨会话的信息持久化，也就是这次聊的内容下次还能用；第二，记忆的按需检索，不能把所有历史一股脑塞进上下文，那样既贵又慢还容易超长；第三，记忆的更新与淘汰，旧信息过时了要能改、能删，不能让错误记忆一直污染后续对话。

这套东西适合谁？我梳理了一下，大致是三类人。一类是做 AI 应用的产品和开发，想给自己的产品加上「长期记忆」这个卖点；一类是重度使用 Claude 做日常工作的个人用户，比如写作者、研究者、程序员，希望助手能记住自己的项目背景和写作风格；还有一类是研究 Agent 架构的技术人，想搞清楚记忆模块在智能体里到底该怎么设计。不管你是哪一类，理解claude-mem的设计思路，都能帮你少走不少弯路。

需要先说明一点：claude-mem这类项目在开源社区里迭代很快，不同版本、不同 fork 的具体实现细节会有差异。下面我讲的内容，一部分来自对这类记忆层方案的通用拆解，一部分来自我自己搭类似系统时踩过的坑，属于「一个合格从业者在这个场景下最可能采用的合理方案」，你落地时以自己拿到的实际代码为准。

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

2.1 为什么不能只靠「把历史全塞进上下文」

很多人第一反应是：记忆嘛，简单，把之前的对话记录拼起来一起发给模型不就行了。我一开始也这么干过，结果很快就撞墙了。Claude 的上下文窗口虽然不小，但它是有限的，而且成本随 token 线性增长。假设你每天和助手聊 50 轮，每轮平均 500 token，一个月下来就是 75 万 token 的历史。你不可能每次都把这 75 万 token 全发过去，一是超窗口，二是钱包受不了，三是模型在超长上下文里对关键信息的注意力会稀释，反而记不住重点。

所以记忆系统的第一性原理是：存的时候要全，取的时候要精。存储层可以无限大，但每次送进模型上下文的，必须是经过筛选的、和当前问题最相关的那一小部分。这就是claude-mem这类方案和「暴力拼接历史」的本质区别。它把记忆拆成了「写入」和「读取」两个独立环节，写入时做结构化沉淀，读取时做相关性检索。

2.2 三层记忆架构：短期、长期、工作记忆

我在设计自己的记忆层时，参考了认知科学里对人类记忆的分类，落到工程上大致是三层，claude-mem的思路也大同小异。

短期记忆（Short-term Memory）就是当前这次会话的上下文，也就是最近几轮对话。它存在内存里，会话结束就丢，作用是保证当前对话的连贯性。这部分不需要持久化，直接放在 messages 数组里就行。

长期记忆（Long-term Memory）是跨会话持久化的部分，通常落到数据库或向量库里。它存的是从对话中抽取出来的「事实」和「偏好」，比如「用户在做 Python 数据分析项目」「用户偏好简洁的回答风格」「用户的时区是东八区」。这部分是claude-mem的核心价值所在。

工作记忆（Working Memory）是个中间层，我习惯叫它「当前任务上下文」。它是在处理某个具体请求时，临时从长期记忆里检索出来、拼装进 prompt 的那部分内容。它随任务生灭，是长期记忆和短期记忆之间的桥梁。

这三层的关系可以用一个生活类比：短期记忆是你和朋友这次聊天说的话，长期记忆是你对这个朋友的整体印象（他做什么工作、性格如何），工作记忆是你准备这次见面时，脑子里快速调出来的「关于他的几个关键点」。没有长期记忆，你每次见他都像第一次见；没有工作记忆，你会把对他的所有印象一股脑倒出来，显得很啰嗦。

2.3 存储选型：向量库、关系库还是混合

记忆存哪里，是个绕不开的选型问题。我实测下来，纯向量库和纯关系库都不够用，混合方案才是正解。

向量库（比如 Chroma、Qdrant、pgvector）擅长语义检索，你问「我之前说的那个项目」，它能靠语义相似度找到相关记忆，哪怕字面不完全匹配。但向量库的弱点是精确过滤能力差，比如你想「只取最近 7 天的记忆」或者「只取标记为重要的记忆」，纯向量检索做起来很别扭。

关系库（比如 SQLite、PostgreSQL）擅长结构化查询和精确过滤，时间范围、标签、重要性评分这些字段查起来很利索。但它做不了语义匹配。

所以我的做法是：用关系库存记忆的元数据和正文，用向量库存记忆的 embedding，两者用同一个 ID 关联。检索时先用关系库做粗筛（时间、标签、类型），再用向量做精排（语义相关性），最后取 Top-K 送进上下文。claude-mem这类项目大多也是这个路子，只是具体用的库不同。

2.4 记忆的写入策略：什么时候记、记什么

这是最容易被低估的环节。很多人以为记忆就是「把对话存下来」，其实真正难的是决定记什么。全存等于没存，因为噪音太多；存太少又漏掉关键信息。

我的策略是「抽取式写入」：每轮对话结束后，用一个轻量的抽取步骤（可以是一次单独的 Claude 调用，也可以用规则+小模型），从对话里提炼出值得长期保留的信息，分成几类：

• 事实类：用户的身份、项目、技术栈、时间安排等客观信息
• 偏好类：用户的回答风格偏好、常用工具、忌讳的表达
• 决策类：之前做过的关键决定，比如「我们决定用 PostgreSQL 而不是 MySQL」
• 待办类：用户提到但还没做的事

抽取出来的每条记忆，我都会打上时间戳、类型标签、重要性评分（1-5）。重要性评分很关键，它决定了这条记忆在检索时的权重，也决定了它会不会被淘汰。评分可以靠模型判断，也可以靠规则，比如用户明确说「记住这个」就给 5 分。

注意：抽取步骤本身也会消耗 token，所以不要每轮都做全量抽取。我的做法是每 N 轮（比如 5 轮）做一次批量抽取，或者检测到对话里出现「记住」「以后都」「我的偏好是」这类触发词时立即抽取。

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

3.1 记忆的数据结构设计

数据结构设计得好不好，直接决定了后面检索和更新的难易。我踩过的坑是：一开始把记忆存成纯文本，结果想按类型过滤时抓瞎。后来改成结构化 schema，世界就清爽了。下面是我现在用的记忆表结构，你可以直接参考：

CREATE TABLE memories ( id TEXT PRIMARY KEY, -- 唯一ID，和向量库关联 content TEXT NOT NULL, -- 记忆正文 memory_type TEXT NOT NULL, -- fact/preference/decision/todo importance INTEGER DEFAULT 3, -- 1-5，默认3 created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW(), last_accessed TIMESTAMP, -- 最近一次被检索的时间 access_count INTEGER DEFAULT 0, -- 被检索次数 source_session TEXT, -- 来源会话ID tags TEXT, -- 逗号分隔的标签 is_active BOOLEAN DEFAULT TRUE -- 软删除标记 );

几个字段值得单独说。last_accessed和access_count是用来做记忆热度的，经常被检索到的记忆说明它重要，检索时可以加权。is_active做软删除，因为直接物理删除有风险，万一删错了没法恢复，而且向量库那边还要同步删，容易不一致。source_session保留来源，方便追溯这条记忆是从哪次对话来的，出问题时能回查。

3.2 记忆抽取的 prompt 设计

抽取质量直接决定记忆质量。我试过好几种 prompt 写法，最后稳定下来的版本大概是这个结构：先给模型设定角色（你是记忆抽取器），再给明确的输出格式（JSON），再给几个 few-shot 例子，最后才是待抽取的对话。关键是输出格式一定要约束死，否则模型会自由发挥，解析起来很痛苦。

EXTRACT_PROMPT = """你是一个记忆抽取器。从下面的对话中提取值得长期记住的信息。 只提取以下四类： - fact: 客观事实（身份、项目、技术栈、时间等） - preference: 用户偏好（风格、工具、忌讳） - decision: 已做出的决定 - todo: 待办事项 输出严格的 JSON 数组，每个元素包含 type、content、importance(1-5)、tags。 如果没有值得记住的内容，输出空数组 []。 对话内容： {dialogue} 输出："""

这里有个细节：importance让模型自己打分，但我会在代码里做一次校验，如果模型给的分和内容明显不匹配（比如「用户喜欢蓝色」打了 5 分），就按规则修正。完全信任模型打分是不靠谱的。

3.3 检索时的相关性排序算法

检索是记忆系统的性能瓶颈，也是最影响体验的环节。我的排序公式大致是：

final_score = w1 * semantic_similarity + w2 * importance_normalized + w3 * recency_score + w4 * access_frequency_score

其中semantic_similarity是向量余弦相似度，importance_normalized是重要性除以 5，recency_score是按时间衰减算出来的（越新越高），access_frequency_score是访问次数归一化。权重w1到w4需要根据你的场景调，我一般给语义相似度 0.5、重要性 0.2、时效性 0.2、访问频率 0.1。

时效性衰减我用的是指数衰减：

import math def recency_score(created_at, now, half_life_days=30): days = (now - created_at).days return math.pow(0.5, days / half_life_days)

半衰期设 30 天，意思是 30 天前的记忆权重减半。这个值不是拍脑袋来的，我根据自己助手的使用频率调的——如果用户每天都用，半衰期可以短一点；如果一周才用一次，半衰期要拉长，否则记忆很快就「过期」了。

3.4 上下文拼装的 token 预算控制

检索出记忆后，怎么拼进 prompt 也有讲究。我的原则是：给记忆留固定的 token 预算，超了就砍。比如整个 prompt 预算 8000 token，系统提示占 500，当前对话占 2000，那留给记忆的就是 5500。按这个预算，从高分到低分往里塞，塞满为止。

拼装格式我习惯用带标签的结构，让模型清楚哪些是「记忆」：

[相关记忆] - (fact, 重要度5) 用户在做 Python 数据分析项目，用 pandas 和 matplotlib - (preference, 重要度4) 用户偏好简洁回答，不喜欢冗长解释 - (decision, 重要度5) 项目决定用 PostgreSQL 存储，不用 MySQL [记忆结束] [当前对话] ...

标签的作用是让模型知道这些是背景信息，不是当前指令，避免它把记忆内容当成任务去执行。这个细节不注意的话，模型有时会「答非所问」，把记忆里的旧任务当成新任务来做。

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

4.1 环境准备与依赖安装

先把环境搭起来。我用的是 Python 3.10+，主要依赖是 Anthropic 的 SDK、一个向量库、一个关系库。向量库我选 Chroma，因为它轻量、本地跑、零配置，适合快速验证；关系库用 SQLite，同样是为了省事。生产环境你可以换成 Qdrant + PostgreSQL。

pip install anthropic chromadb sqlite-utils python-dotenv

API key 通过环境变量注入，不要硬编码在代码里，这是基本的安全习惯：

export ANTHROPIC_API_KEY="your-key-here"

注意：向量库和关系库的初始化要放在应用启动时做一次，不要每次请求都初始化，那样性能会很差。我见过有人把 Chroma client 写在函数里，每次调用都重新建，结果慢得离谱。

4.2 记忆写入的完整流程实现

写入流程分四步：接收对话、抽取记忆、去重、落库。去重这步很多人会漏，导致同一个事实被反复存，检索时全是重复内容。我的去重策略是：新记忆入库前，先用向量检索找相似度超过 0.9 的已有记忆，如果有，就更新那条而不是新增。

import anthropic import chromadb import json import uuid from datetime import datetime client = anthropic.Anthropic() chroma = chromadb.PersistentClient(path="./memory_db") collection = chroma.get_or_create_collection("memories") def extract_memories(dialogue: str) -> list: resp = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1024, messages=[{"role": "user", "content": EXTRACT_PROMPT.format(dialogue=dialogue)}] ) text = resp.content[0].text.strip() try: return json.loads(text) except json.JSONDecodeError: return [] # 解析失败就当没抽到，不要崩 def save_memory(mem: dict): mem_id = str(uuid.uuid4()) # 先查重 existing = collection.query(query_texts=[mem["content"]], n_results=1) if existing["distances"] and existing["distances"][0]: if existing["distances"][0][0] < 0.1: # 距离越小越相似 # 更新已有记忆 old_id = existing["ids"][0][0] collection.update(ids=[old_id], documents=[mem["content"]]) return old_id # 新增 collection.add( ids=[mem_id], documents=[mem["content"]], metadatas=[{ "type": mem["type"], "importance": mem["importance"], "created_at": datetime.now().isoformat() }] ) return mem_id

这里distances的判断阈值 0.1 是我调出来的经验值，Chroma 默认用 L2 距离，越小越相似。不同向量库的距离度量不一样，你换成余弦相似度的话，阈值要反过来设（越大越相似）。

4.3 记忆检索与注入的代码实现

检索流程是：拿当前用户输入去向量库查，拿到候选后按前面说的公式重排，取 Top-K，拼进 prompt。

def retrieve_memories(query: str, top_k: int = 5) -> list: results = collection.query(query_texts=[query], n_results=top_k * 2) if not results["ids"] or not results["ids"][0]: return [] scored = [] now = datetime.now() for i, mem_id in enumerate(results["ids"][0]): meta = results["metadatas"][0][i] distance = results["distances"][0][i] semantic = 1 - distance # 转成相似度 importance = meta.get("importance", 3) / 5 created = datetime.fromisoformat(meta["created_at"]) recency = recency_score(created, now) score = 0.5 * semantic + 0.2 * importance + 0.2 * recency + 0.1 * 0.5 scored.append((score, results["documents"][0][i], meta)) scored.sort(key=lambda x: x[0], reverse=True) return scored[:top_k] def build_prompt(user_input: str, memories: list) -> str: if not memories: return user_input mem_text = "\n".join( f"- ({m['type']}, 重要度{m['importance']}) {doc}" for _, doc, m in memories ) return f"[相关记忆]\n{mem_text}\n[记忆结束]\n\n[当前对话]\n{user_input}"

access_frequency_score我在示例里简化成了固定值 0.5，实际用的时候要从数据库读access_count算。检索完记得更新last_accessed和access_count，否则热度排序永远是初始值。

4.4 记忆更新与淘汰机制

记忆不是只增不减的。我的淘汰策略是「软删除 + 定期清理」：当一条记忆的importance低于 2 且超过 90 天没被访问过，就标记is_active = FALSE；再超过 180 天，物理删除，同时删向量库里的对应记录。

更新则分两种：一种是内容更新（用户改主意了），一种是重要性调整（某条记忆被频繁访问，说明它重要，可以提分）。我写了个定时任务，每周跑一次，把access_count超过 10 的记忆importance加 1（上限 5），把长期不访问的降级。

实操心得：淘汰机制一定要有，否则记忆库会无限膨胀，检索越来越慢，噪音越来越多。我见过有人跑了半年没清理，检索出来的全是三个月前的无关内容，体验极差。

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

5.1 记忆抽取质量差怎么办

最常见的抱怨是「抽出来的记忆没营养」。原因通常有三个：prompt 太宽松、few-shot 例子不好、模型选得太小。我的排查顺序是：先看 prompt 有没有明确约束类型和格式，再看 few-shot 例子是不是覆盖了正反例，最后考虑换更大的模型做抽取。抽取这步值得用好模型，因为它决定了整个记忆库的质量，省这点钱不划算。

5.2 检索结果不相关怎么调

检索不准，先分清是「召回问题」还是「排序问题」。召回问题表现为相关记忆根本没被查出来，通常是 embedding 模型不适合你的语言或领域，换个更强的 embedding 模型试试。排序问题表现为相关记忆查出来了但排后面，那就是权重没调好，把语义相似度的权重调高，或者检查时效性衰减是不是太激进。

5.3 上下文超长怎么处理

超长通常是因为检索返回太多记忆，或者单条记忆太长。对策是：给记忆总量设硬预算，超了按分数砍；单条记忆超过 200 字就截断或摘要。我还会在拼装时做一次 token 估算，用tiktoken之类的库提前算好，别等 API 报错才发现超了。

5.4 记忆污染与错误传播

这是最隐蔽的坑。如果某次抽取抽错了，错误记忆进了库，之后每次检索都可能把它带进上下文，模型基于错误记忆继续回答，错误就被放大了。我的对策是：给记忆加「置信度」字段，抽取时让模型自评，低置信度的记忆检索时降权；同时提供人工审核入口，重要场景下新记忆先待审再入库。

注意：记忆污染一旦发生，清理起来很麻烦，因为你不确定哪些后续对话被它影响了。所以宁可入库严一点，也不要让低质量记忆混进来。

5.5 多用户场景的记忆隔离

如果你的应用有多个用户，记忆必须按用户隔离，否则 A 的偏好会污染 B 的对话。我的做法是在记忆表加user_id字段，检索时强制带上这个过滤条件，向量库那边用 metadata filter 实现。千万别图省事共用一个记忆库，出了隐私问题就是大事。

6. 我踩过的坑和几条实在建议

搭这套东西的过程中，有几个坑我印象特别深，分享出来帮你省点时间。

第一个坑是过度设计。我一开始想搞一套特别复杂的记忆图谱，实体、关系、时序全上，结果光 schema 就设计了两周，代码写了一堆，实际效果还不如简单的「抽取+向量检索」。后来我砍掉了大半，回归朴素方案，反而跑得更稳。记忆系统的核心是「存得准、取得精」，不是结构多花哨。

第二个坑是忽视成本。抽取和检索都要调模型，如果每轮对话都做全量抽取，token 消耗会翻好几倍。我后来改成触发式抽取，只在检测到关键信息时才抽，成本降了一大截，效果几乎没损失。

第三个坑是不做评估。记忆系统好不好，不能靠感觉，得有指标。我后来加了一套简单的评估：准备一批「应该被记住」的测试对话，跑完后检查这些信息能不能被正确检索出来，算召回率。有了这个指标，调参才有方向，不然就是瞎调。

最后说个实用的小技巧：记忆的content字段尽量写成自包含的完整句子，不要写成依赖上下文的片段。比如不要存「他喜欢用 pandas」，要存「用户在做数据分析时喜欢用 pandas」。因为记忆被检索出来时是脱离原始对话的，自包含的句子模型才能正确理解。这个细节看着小，但对检索后的使用效果影响很大。

这套claude-mem的思路，本质上就是把「让模型记住」这件事工程化、模块化。它不神秘，核心就是存储、检索、更新三件事，但每一件都有讲究。你把这三件事做扎实了，助手的体验就会有质的提升。