用claude-mem为Claude打造长期记忆：跨会话上下文管理实践

最开始用 Claude 的时候，我最大的感受是：这家伙在单个对话里很聪明，可一旦新开一个会话，它就彻底忘了我是谁、我们之前聊过什么。项目背景、技术选型、踩过的坑，全得重新讲一遍。后来我接触到 claude-mem 这个专门给 Claude 做长期记忆层的工具，才意识到问题的根源不在模型本身，而在于我们根本没有给对话配上"外置记忆"。这篇文章就围绕 claude-mem 这类记忆方案，聊聊它解决什么问题、内部大致怎么运转、怎么接到自己的项目里，以及我在实测中踩过的那些坑。

如果你也在做基于 Claude API 的工具、Bot 或者 Agent，并且被"多轮对话失忆""上下文塞不下""每次都要重新交代背景"这些问题折磨过，那这篇文章应该能给你一条很具体的解决思路。我尽量少讲虚的，多放能直接用的配置、代码和操作步骤。

1. claude-mem 要解决的根本问题：Claude 的"失忆症"

1.1 会话一关，记忆归零

先说个大伙都有体感的场景。你在网页版或者 API 里跟 Claude 连续聊了半小时，把项目背景、技术栈、目标用户、当前的遗留问题全交代清楚了。它也能准确回答你"上次说的那个模块重构方案"是什么。但只要刷新页面、关掉标签页，或者换一个新会话，它就像被格式化了一样，连你的名字都不知道。

这不是 Claude 笨，而是底层机制决定的。大语言模型的对话本质上是一次无状态的请求-响应循环，模型能看到的只有你当前请求里携带的上下文。也就是说，它的"记忆"完全取决于你每次请求塞给它多少历史内容。网页版有官方帮你维护的历史记录，但 API 面向开发者时，所有上下文都得自己管理。

claude-mem 这类工具就是冲着这个痛点去的。它的核心思路很简单：在 Claude 和你的业务代码之间加一层"记忆服务"，负责把对话里的重要信息沉淀下来，在下一次请求前把相关内容检索出来，混到新的 prompt 里。一句话概括就是——让模型拥有"跨会话的长期记忆"。

1.2 把历史全塞进 Prompt 的代价

可能有人会说，记忆这事没那么复杂，我每次都把完整的历史对话拼进请求不就行了？

我刚开始也是这么做的。结果踩了几个很现实的问题：

• Token 成本膨胀。假设一次对话有 20 轮，每轮平均 400 个 token，完整往返就是 1.6 万 token。如果用户每天发起 100 次请求，光是重复发送历史就要消耗 160 万 token，成本完全不可控。
• 上下文窗口压力。Claude 的上下文窗口虽然大，但历史对话里往往掺着大量寒暄、废话、离题内容，真正有用的也许只有 10%-20%。把这些噪音全部灌进去，既浪费空间，又可能干扰模型对当前问题的判断。
• 效果反而变差。上下文越长，模型对关键信息的注意力会被稀释。我在实测里发现，把一周的对话全堆进 prompt 之后，Claude 反而更容易忽略刚说的重点，回答质量明显下降。

这也是记忆层存在的意义。它要做的不是"完整备份"对话，而是提炼、存储、按时召回。这就像你记笔记不是把整本书抄一遍，而是画重点、做索引、用的时候再翻到对应页。

1.3 记忆层的设计哲学：记住该记住的，忘掉该忘掉的

claude-mem 这类工具跟"把历史全塞给模型"最大的区别，在于它引入了选择性记忆。它不会把你和用户所有的对话内容一字不差地保存，而是通过规则或者模型自身的能力，抽取那些真正有长期价值的信息。

我归纳下来，记忆层至少要处理好三件事：

1. 该记什么：用户偏好、项目术语、已做的决定、待办事项、关键指标、约束条件。这些内容在后续对话中反复被引用，丢掉任何一条都会让体验断档。
2. 该丢什么：寒暄、临时问题、与主题无关的闲聊、一次性问答。这类内容存下来只会变成噪音。
3. 该何时忘：过期信息、被新决定覆盖的旧决策、长期未命中的冷记忆。没有遗忘机制的记忆库，迟早会被垃圾填满。

你可能会问，这些不都是要靠模型提炼吗，为什么还要单独做一个工具？因为封装成工具之后，你就不需要在自己业务代码里反复实现"提取-存储-检索"这套逻辑。无论是接 Claude API，还是换成其他模型，记忆层是可以复用的基础设施。

2. claude-mem 的工作流程：记忆写入、存储与召回

claude-mem 的完整工作流程，可以拆成三个阶段：写入（怎么把对话变成记忆）、存储（记忆以什么形态存在哪）、召回（怎么把相关记忆捞回来）。理解这三个阶段，比看十遍文档都管用。

2.1 写入阶段：从对话里提炼"记忆条目"

在 claude-mem 的设计里，写入并不是简单地调一个save(text)把整段对话存起来。它更常见的是边聊边沉淀或者聊完再沉淀。

边聊边沉淀的做法，是在 Claude 每次返回回复之后，单独把对话内容丢给一个提炼模块，让它产出格式化的记忆条目。一个典型的记忆条目大概长这样：

{ "id": "mem_20240201_user_pref", "type": "user_preference", "content": "用户 prefers TypeScript over JavaScript for new backend services", "source_session": "session_abcd1234", "created_at": "2025-02-01T10:30:00Z", "last_accessed_at": "2025-02-01T10:30:00Z", "access_count": 0 }

如果你在本地跑过 claude-mem，你会发现它默认的存储格式往往是比较透明的，比如 JSONL 或者 SQLite。每条记忆都带有类型、来源会话、时间戳、访问次数这些元信息。这些元信息不是摆设，后面做去重、过期淘汰、检索加权全都要靠它们。

提炼这一步用的是模型还是规则，取决于实际项目。我见过的最小实现是直接上硬规则，比如正则匹配"用户喜欢/不喜欢/偏好/决定/记住"这类关键词，把匹配到的句子存下来。缺点是召回率低。稍微成熟一点的做法，是把一小段对话交给模型做摘要式提炼，产出的记忆质量会高不少，但会额外消耗一些 token 和延迟。

2.2 存储阶段：记忆不是文本文件，而是可检索的库

如果你只存不查，那记忆库就是个摆设。存储的形态直接决定了检索的效率。claude-mem 在存储层通常有两种选择：

• 结构化数据库：比如 SQLite、PostgreSQL。适合存储上面那种带元信息的记忆条目，可以按类型、时间、状态做精确过滤。优点是查询精确、事务可靠；缺点是没法做语义相似度检索。
• 向量数据库：比如本地文件加 embedding，或者 Chroma、Qdrant、Milvus 这类服务。先把记忆内容向量化，检索时用语义相似度找最相关的几条。优点是能处理"意思相近但关键词不同"的检索需求；缺点是需要额外维护 embedding 流程和向量库本身。

实际项目里，两者常常是搭配用的：结构化的元信息负责筛选条件（比如只看用户偏好、只看最近一周），向量检索负责语义召回，最后把两个结果合并去重。

我最初图省事，把记忆全部存成普通文本文件，检索用关键词匹配。结果用户说"上次聊的支付流程"时，记忆里存的是"结算环节"，关键词对不上，检索直接落空。后来换成 embedding 方案，同样的意思不同的词也能捞出来。这个教训后面细说。

2.3 召回阶段：只把相关记忆塞回上下文

召回是整个记忆层里最影响体验的一环。它决定了每轮请求前，你要从记忆库里捞多少条、按什么顺序、以什么格式拼到 prompt 里。

claude-mem 的召回逻辑大概是这样：

1. 拿到用户最新的消息，生成 embedding；
2. 在向量库里做相似度检索，取 top-k（我常用的 k 是 5-10）；
3. 结合元信息过滤，去掉过期、失效的记忆；
4. 把召回的记忆条目拼成一段前缀，插入到 history 的最前面或者 system prompt 里。

拼装出来的效果类似：

你是一位拥有长期记忆的助手。以下是关于用户的已知信息： - 用户后端的核心语言是 Go，偏好避免引入 Python 服务。 - 之前讨论过订单模块改用消息队列削峰，方向是 RabbitMQ。 - 用户公司内部术语：把"生产环境"称为"正式环境"。 请结合这些信息回答用户的问题。

这里有几个小细节会影响体验。一个是时间线：太旧的记忆默认权重低，但如果有last_accessed_at字段，可以做一个简单的热度排序，让常被用到的记忆排在前面。另一个是数量控制：每次塞回给模型的记忆不能太多，10 条以内通常比较稳，超过之后模型的注意力会被分散。

3. 从零把 claude-mem 接进项目：一个可跑的最小示例

纸上谈兵没什么意思。这一节我带你把 claude-mem 接到一个最简单的 Claude API 项目里，把完整链路跑通。

3.1 准备环境和依赖

我做了一个 Python 版本的最小示例。你需要准备：

• Python 3.10+；
• anthropicSDK 和openaiSDK（embedding 我用 OpenAI 的接口做演示，你也可以换任何兼容 embedding 的服务）；
• 一个本地目录用来存记忆库文件。

mkdir claude-mem-demo && cd claude-mem-demo python -m venv venv source venv/bin/activate pip install anthropic openai python-json-logger

3.2 初始化记忆库和工具函数

这里我用最简单的 JSONL 文件做持久化，每行一条记忆记录。虽然前面说了文件型存储有检索短板，但对于最小 demo 足够直观，也能让你看清楚整个流程。

import json import time import hashlib from pathlib import Path MEMORY_FILE = Path("memories.jsonl") def add_memory(content, mem_type="general", session_id="default"): record = { "id": hashlib.sha256(f"{time.time()}-{content}".encode()).hexdigest()[:12], "type": mem_type, "content": content, "source_session": session_id, "created_at": int(time.time()), "last_accessed_at": int(time.time()), "access_count": 0, } with open(MEMORY_FILE, "a", encoding="utf-8") as f: f.write(json.dumps(record, ensure_ascii=False) + "\n") return record

3.3 写入记忆：提炼关键信息的两个办法

写入部分的核心问题是"提炼"。我试验过两种方案，可以按你的精度要求和成本预算选。

方案 A：规则抽取（免费但粗糙）

用正则或关键词匹配，把对话里带强指示词的内容直接存进去。

import re INDICATORS = ["偏好", "喜欢", "不喜欢", "采用", "决定", "记住", "注意", "要求"] def extract_by_rules(text, session_id): got = [] for line in text.split("\n"): for word in INDICATORS: if word in line and len(line.strip()) > 5: got.append(add_memory(line.strip(), "rule_extracted", session_id)) return got

方案 B：模型提炼（多花一点 token 但质量高很多）

让 Claude 自己判断哪些信息值得长期记住，并输出结构化 JSON。我用下来，这个方案产出的记忆质量明显高于正则，特别是在上下文比较复杂的时候。

from anthropic import Anthropic ANTHROPIC_KEY = "your-anthropic-key" client = Anthropic(api_key=ANTHROPIC_KEY) def extract_by_model(session_text, session_id): response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=500, system="从对话中提取值得长期记住的事实，只输出 JSON，不要解释。格式: [{\"type\":\"fact|preference|decision|task\", \"content\":\"...\"}]", messages=[{"role": "user", "content": session_text}] ) try: items = json.loads(response.content[0].text.strip()) except Exception: return [] for item in items: add_memory(item["content"], item["type"], session_id) return items

3.4 召回记忆：用 embedding 找到最相关的内容

召回部分我直接用了 embedding 相似度。先给每条记忆生成向量，再对用户当前输入做向量检索，取 top-k。

from openai import OpenAI EMBED_KEY = "your-embedding-key" openai_client = OpenAI(api_key=EMBED_KEY) def embed(text): resp = openai_client.embeddings.create(input=text, model="text-embedding-3-small") return resp.data[0].embedding def load_memories(): if not MEMORY_FILE.exists(): return [] with open(MEMORY_FILE, encoding="utf-8") as f: return [json.loads(line) for line in f if line.strip()] def recall(query, top_k=5): memories = load_memories() if not memories: return [] q_vec = embed(query) scored = [] for m in memories: m_vec = embed(m["content"]) # 简化版余弦相似度，实际项目建议缓存向量 dot = sum(a * b for a, b in zip(q_vec, m_vec)) norm_q = sum(a * a for a in q_vec) ** 0.5 norm_m = sum(b * b for b in m_vec) ** 0.5 score = dot / (norm_q * norm_m) scored.append((score, m)) scored.sort(key=lambda x: x[0], reverse=True) return [m for _, m in scored[:top_k]]

3.5 把记忆拼进 Claude 请求

最后一步是把召回结果拼成前缀，做成 system prompt 的一部分，再正常调用 Claude。

def build_system_prompt(recalled): if not recalled: return "你是一位 AI 助手，请直接回答用户问题。" lines = ["你是一位具备长期记忆的 AI 助手。以下是与用户相关历史记忆："] for m in recalled: lines.append(f"- [{m['type']}] {m['content']}") lines.append("如果记忆与当前问题无关，请忽略；如果与问题相关，请自然引用这些信息作答。") return "\n".join(lines) def ask_with_memory(question, session_id): memories = recall(question, top_k=5) sys_prompt = build_system_prompt(memories) resp = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1000, system=sys_prompt, messages=[{"role": "user", "content": question}] ) return resp.content[0].text

把这个最小链路跑通之后，你就拥有了一个最简版 claude-mem：对话关键信息被提炼入库，每次提问前自动召回相关历史，并通过 system prompt 注入。实际项目里 claude-mem 大概率做得比这个复杂，比如自动切分长对话、增量更新向量索引、支持记忆编辑等，但核心骨架就是我上面写的这套。

4. 实测中容易踩的坑：记忆污染、重复与过期

接进项目只是第一步，真正让记忆层"能用"的是后来的调优。这里我汇总了几个我踩过、也帮别人排查过的典型问题，基本都在生产环境遇到过。

4.1 记忆污染是最大的隐形杀手

所谓记忆污染，就是记忆库里存了大量错误、过期、甚至完全无关的信息，结果召回时把它们当成背景知识塞给了模型，导致回答被带偏。

我给你一个真实案例。我之前给一个客服机器人接记忆层时，把会话里的所有文本都交给模型做提炼，没有做类型过滤。结果有一次用户开着玩笑说"再这样我就换别家了"，这条内容被提炼成"用户有流失意向"，后续很多次对话都被这条错误记忆干扰，回答变的过度防御，用户体验反而更差。

解决办法有几个：

• 提炼阶段加置信度门槛：让提炼模型同时返回一个confidence字段，低于阈值的记忆不写入。
• 按记忆类型做差异化处理：只有decision、preference、task这类高价值信息才允许长期保存，普通fact只保留几天。
• 增加人工确认入口：如果你的产品有运营后台，把新增记忆变成一条可审核的任务，确认后才生效。这听起来重，但对 To B 场景很值。

4.2 去重与合并机制：防止同一件事被记十遍

另一个高频问题是重复。同一句"我偏好 Go 语言"，用户可能在多次对话里用不同方式表达过，每次都被提炼模块存了一遍。召回时 top-5 里可能挤进来四条意思几乎一样的记忆，白白占用上下文窗口。

我建议做两层处理：

1. 写入前查重：新记忆入库前先做一次语义相似度检测，跟已有记忆的相似度超过比如 0.92，就不再新增，而是更新原记忆的last_accessed_at和access_count。
2. 定期合并：每天或者每周跑一次合并任务，把相似记忆聚簇，合并成一条更完整的表述。比如：

["用户后端用 Go", "用户偏好在后端服务使用 Go 而不是 Python", "新服务开发首选 Go"] => "用户后端开发首选 Go，尽量避免 Python 服务，新服务开发默认选 Go。"

这样既能压缩记忆体积，也能避免模型被重复信息洗脑。合并任务同样可以让模型来做，把一组相似记忆丢给它，让它输出合并后的文本，实测效果不错。

4.3 过期与遗忘策略：没有遗忘机制的记忆库终将腐烂

我做记忆层初期有个错觉：记忆越多越聪明。后来发现完全不是这么回事。记忆库膨胀到一定规模后，每次召回都要扫描大量候选，检索延迟上升，而且能捞回来的记忆质量会下降——因为新的重要信息往往淹没在历史噪声里。

我现在的做法是给记忆设"生命周期"：

具体实现时，我加了一个后台清理任务，每天扫一遍last_accessed_at超过过期时间的记忆，先归档到.archive文件，再物理删除。检索时只查活跃记忆，这样召回速度和准确率都能保住。

还有一个值得注意的点：新记忆要有抢占能力。用户明确说"之前那个方案废了，改用新方案"时，旧决策必须立刻失效。我在写入时加了一个规则，如果新记忆的类型是decision且内容与旧记忆存在明显语义冲突，就自动把旧记忆标记为superseded。

5. claude-mem 之外的延伸：给 Agent 做记忆层的通用经验

claude-mem 本质上是把"记忆管理"这件事从一个业务需求变成了可复用能力。做完这一类项目之后，我最大的收获是：记忆层不该只服务于某个具体模型，它应该是一套独立的、跟模型解耦的基础设施。顺着这个思路，有几点延伸经验分享给你。

5.1 向量库选型与检索调优

如果你要接的不只是 Claude，还有其他的 Agent 或者多个应用，建议从一开始就选独立的向量库，而不是用文件把记忆锁在单个进程里。

我对比过几类方案：

对于大多数中小型项目，我的建议是：先用 SQLite 或者 Chroma 跑通，等并发和记忆量上来了再迁 Qdrant。别一上来就上重武器，记忆层的瓶颈往往不在检索速度，而在提炼质量和去重策略。

检索调优方面有几个参数值得反复试：

• top_k：我开始用 20，发现输出里无关记忆太多，降到 5 之后准确率明显提升。
• 相似度阈值：低于 0.75 的召回结果直接丢弃，避免模型被弱相关记忆干扰。
• 混合过滤：用类型和时间字段先缩小候选集，再算相似度。先粗筛再精排，性能和质量都会改善。

5.2 记忆分区：会话级、用户级、项目级

不是所有记忆都该放在同一个池子里。我在 claude-mem 的二次开发里引入了分区概念，效果非常好。

• 会话级记忆：只属于当前 session，比如这一轮对话里聊到的临时细节，会话结束时清理。
• 用户级记忆：跟随用户 ID 跨会话持久化，比如用户的偏好、语言习惯、历史决策。
• 项目级记忆：跟具体项目或知识库绑定，比如代码仓库的命名约定、团队术语、架构约束。

分区的好处是：召回时可以按需指定作用域，避免把一个用户的偏好错误地带给另一个用户。这既是体验问题，也是隐私问题。

分区实现上其实不复杂，就是在记忆记录里加一个scope字段，召回时加一层过滤：

def recall_scoped(query, scope, top_k=5): memories = [m for m in load_memories() if m.get("scope") == scope] # 后续相似度计算与召回逻辑同上

5.3 和 Agent 编排框架配合

如果你在用 LangChain、LlamaIndex 或者自研的 Agent 框架，记忆层不应该跟具体的 Agent 步骤耦合，而应该暴露三个接口：write、search、delete。Agent 在每轮执行前后调用写入和召回，就像人做项目前先翻一下自己的笔记。

我在实际项目里的接法是：Agent 每完成一个重要节点（比如完成一个子任务、作出一个决策），就调一次write把结果沉淀下来；每轮开始前调一次search，把跟当前目标相关的历史拉回来。这样即使 Agent 实例崩溃重启，也能接着上一次的节奏往下干。

还有一个小技巧：把记忆能力封装成函数工具给 Agent 调用，而不是只在外部拼 prompt。也就是说，Agent 可以自己决定"这个问题我需要翻一下旧档案"，而不是每次都被动地被喂一堆背景。这样记忆的使用更精准，Token 消耗也更小。

最后分享一点个人心得

如果你准备在项目里引入 claude-mem 或者任何一套记忆层方案，我的建议是从小处开始：先跑通一条最简单的写入-存储-召回链路，再逐步加去重、过期、分区这些进阶能力。不要一开始就想着把所有的对话历史都永久的记下来，事实证明"少而精"的记忆远比"多而杂"的档案有用。

另一个容易被忽视的点是：记忆质量需要持续监控。我每隔一段时间会抽样看看记忆库里最近新增的条目，如果发现提炼质量下降，通常是提炼模型需要换更强的版本，或者规则需要调整。记忆层不是一个写完就能撒手的组件，它跟业务一样需要运营和迭代。