干了这么多年大模型应用，被"Agent 的记忆"坑过太多次了。换了框架，记忆清零，用户像个失忆症患者重新教你；换个部署环境，历史对话没了，Agent 又变回了第一天上班的实习生。最近我终于把一套成熟的方案跑通了，让 Agent 的记忆从框架和工具链里彻底解耦出来，真正做到"记忆跟着 Agent 走，不跟着工具搬家"。这套方案我用了双网络记忆模型，引入了记忆打分机制加时间半衰期衰减，还封装成了 WorkBuddy 的跨对话记忆 skill，实测下来非常稳。这篇文章就完整拆解一下我的设计思路和落地方案，给同样被记忆问题折磨的 Agent 开发者一条可抄的作业。
1. 为什么 Agent 的记忆总在"跟着工具搬家"
1.1 框架绑定式记忆：行业里的通病
先说说这个痛点是怎么来的。绝大多数 Agent 框架，从早期 LangChain 的ConversationBufferMemory，到后来各种 Agent 框架内置的chat_history、message_store，默认都是把记忆挂在框架自己的上下文里。你在这个框架里跑的对话记录、用户偏好、任务状态，全存在框架定义的数据结构里。一旦你决定换框架——比如从 LangChain 迁到 CrewAI，或者从某个垂直 Agent 平台迁到自研架构——这些数据就变成了"死数据"。
我之前接手的几个项目全是这个状态：Agent 在 Dialogflow 里沉淀了半年的用户偏好，迁移到自研平台时全部作废，运营团队直接崩溃，因为用户打电话进来 Agent 完全不记得人家是 VIP。后来我总结出一个判断标准：一份记忆数据如果不能脱离当前框架独立导出、独立重建，它就是框架的附属品，不是 Agent 的记忆。这也是"记忆跟着工具搬家"的最本质原因。
1.2 记忆迁移失败的四个典型场景
从实际项目里，我把记忆迁移失败的情况归纳成四类，每一类我都踩过。
- 换框架丢记忆：最常见。原因就是记忆数据结构跟框架绑定。比如 LangChain 的
ConversationBufferWindowMemory只保留固定窗口的对话，存的是半结构化的HumanMessage/AIMessage列表，换个框架根本没有对应的数据结构，读不出来。 - 换模型丢记忆：你以为记忆存在模型那边的 context 里，其实没存。GPT 的对话上下文只在一次会话内有效，会话结束后就没了。有的开发者直接把整个 history 塞进 prompt 里，换了模型 API 就全部重来。
- 换存储丢记忆：Redis 里的记忆迁移到 PostgreSQL，如果当初存的是 Redis 特有的数据结构（比如 List、Hash），迁移时序列化格式不兼容，照样读不出来。
- 换环境丢记忆：从开发环境到生产环境，docker 重建、沙盒更新之后记忆数据丢失。很多 Agent 框架的默认实现是把记忆文件和运行进程绑在一起，容器一删就全没了。
这四类问题本质上是同一件事：记忆没有独立的生命周期，而是寄生在某个工具或框架的生命周期里。只要在架构设计上把记忆层从工具层抽离出来，这些问题可以一次性解决。
1.3 核心先搞清楚：记忆到底是"数据"还是"上下文"
要认真解决这个问题，先得统一认知。我对 Agent 记忆的定义很简单：记忆是可以在不同会话、不同工具、不同时间点之间持久化复用的数据。它不等于对话上下文，也不等于 prompt 的一部分。上下文是记忆的载体之一，但不是记忆本身。
用一个生活化的类比：你去银行办事，柜员查得到你过去五年的流水记录，这是"记忆"。但如果柜员每次办完业务就把工作日志撕掉，换个人来上班什么都不记得，那就是"记忆跟着柜员搬家了"。我们设计 Agent 记忆的目标，就是打破这个"柜员个人绑定"，让记忆归银行（也就是归 Agent 自己），不归某个具体的柜员（框架/工具链）。
认清楚这个区别之后，整个架构怎么设计就很清晰了：Agent 本体负责"思考"和"行动"，记忆层负责"记住"和"回忆"，框架只是运行时载体。
2. 架构方案：双网络记忆模型
2.1 为什么选双网络而不是单一大池子
我采用的方案是双网络记忆模型，这也是目前业内比较认可的一种思路。简单说就是把记忆拆成两个网络：工作记忆（短期）和长期记忆（长期），两者独立存储、独立检索、按需合并。
一开始我也试过一个大池子全量存储的方案，把用户所有的历史交互塞到一个向量数据库里，需要用的时候全量召回。结果性能惨不忍睹，检索噪声也大——你问用户最近想吃什么，结果召回出来三年前他想吃火锅的记录，因为向量相似度碰巧高。后来我调整思路：短期的工作记忆管"当前正在进行的任务上下文"，长期记忆管"跨会话沉淀的用户画像、偏好、关键结论"，两者各司其职，检索效率和准确率都上去了。
双网络的另一个优点是迁移成本天然更低。工作记忆很容易序列化成 JSON 快照，长期记忆就是一条一条带元数据的记录。无论你前端跑的是什么框架，只要这两个数据接口是一致的，记忆就能无损平移。
2.2 工作记忆：session 级的瞬时可迁移存储
工作记忆的设计目标：快。它存储的是当前会话内 Agent 需要用到的短期信息，比如用户本轮对话里提到的临时需求、正在执行的任务流水、最近几句对话的语义摘要。它的生命周期通常短于会话本身，会话结束或者超时就逐步释放。
具体实现上，我把它做成一个可序列化的上下文快照对象，核心字段如下：
@dataclass class WorkingMemorySnapshot: session_id: str agent_id: str created_at: float updated_at: float context_slots: dict # 关键信息槽位，比如 {target_date: "2026-03-20"} recent_events: list # 最近的交互事件流水 task_stack: list # 当前任务栈 compressed_summary: str # 会话内摘要这个快照对象有两个关键约束：第一，所有字段类型必须是 JSON 可序列化的，不允许出现框架专属的 Message 对象、Tensor 对象、类实例；第二，快照的存储介质必须是独立于框架的外部存储，比如 Redis 或 PostgreSQL。这两条约束是后面"不跟工具搬家"的基础。
每次会话结束时，我会把最新的工作记忆快照写入存储；下次会话恢复时，只要拿到 session_id，就能完整还原上下文。迁移框架时，把这个 JSON 卸载下来，再灌到新框架的工作记忆接口里，整个状态就回来了。
2.3 长期记忆：score + 时间半衰期
长期记忆是这套方案的灵魂。它要解决的问题是：面对大量历史交互数据，如何高效地保留重要信息、淘汰过期信息。
我用的是当下效果比较好的记忆评分 + 时间半衰期机制。核心公式非常简洁：
memory_score = base_score * decay^(age / half_life)其中base_score是记忆在写入时的初始评分，decay是衰减因子（通常是 0.5），age是记忆写入后的时长，half_life是半衰期参数。简单解释：一条记忆每隔一个半衰期，它的有效得分就衰减一半。比如一条记忆的 half_life 是 7 天，7 天后的分数是初始的 50%，14 天后是 25%，以此类推。
这个公式用生活经验理解特别直观：你昨天吃过的餐厅，Agent 应该记得牢牢的；三个月前一次普通的点餐记录，Agent 就没必要记住了。但如果你三个月前在对话里说过"我对花生过敏"，这条记忆的重要度评分极高，即使衰减了还是应该留下——所以 base_score 不能拍脑袋定，要跟业务重要度挂钩。
2.4 打分初始值怎么定：1 到 100 的编码规则
分词"1 到 100 记忆编码大全"触动了我。实际操作中，initial score 的赋值规则不能随便写死，需要一个能落地的编码体系。我给每条记忆的 base_score 分成了五个档位：
| 记忆类型 | 典型内容举例 | base_score初始值 | 说明 |
|---|---|---|---|
| 永久性安全信息 | 过敏原、身份证号、家庭住址 | 95 ~ 100 | 几乎不衰减，半衰期设得很长，如365天 |
| 核心偏好 | 喜欢的口味、忌讳的话题、习惯的工作状态 | 80 ~ 90 | 半衰期约30天，长期生效 |
| 事实性知识 | 用户所在行业、职业、常用工具 | 60 ~ 80 | 半衰期约60天 |
| 过程性信息 | 某个任务的中间状态、临时约定 | 40 ~ 60 | 半衰期约7天 |
| 即时性信息 | 本周的日程、昨天买的东西 | 10 ~ 40 | 半衰期约1~3天，快速衰减 |
这个档位表不是凭空定的，是根据我几个实际业务场景的效果调出来的。一个关键经验：用户主动用确定性语气提供的信息（"我对花生过敏""我平时工作到晚上八点"），base_score 给高；从对话里被动推断出来的信息（"他今天提了三次某个关键词"），base_score 给中低。主动提供的信息置信度高，被动推断的信息需要时间验证。
代码实现如下：
import time def memory_key(score, created_at, half_life=86400 * 7, decay=0.5): age = time.time() - created_at return score * (decay ** (age / half_life))half_life和decay都可以按记忆类型覆盖，用元组(memory_content, score, created_at, half_life)的方式存到存储层，查询时实时计算有效得分，然后取 Top-N。
2.5 记忆淘汰与召回：别让长期记忆变成垃圾场
长期记忆如果没有淘汰机制，两三个月后就会变成垃圾场，检索效率断崖式下降。我的策略是双层淘汰。
第一层是分数淘汰：当一条记忆的memory_score低于某个阈值（比如 1.0，或者初始分数的 2%），这条记忆就进入"待归档"状态，不再参与正常的 Top-K 召回。为了安全起见，我不直接物理删除，而是把状态标记为archived，保留在存储里，防止以后误删重要信息需要溯源。
第二层是存储空间控制：每个用户的长期记忆总量设一个上限（比如 2000 条），超过上限时优先淘汰"分数最低且最后访问时间最久"的记忆。这样长期记忆池能保持在一个可控的体积，向量检索和关系查询都不会太慢。
召回的时候，我会同时考虑相关性和记忆分：先用 embedding 相似度找出候选集（Top-K=50），再用记忆分进行倒序取前 10 条注入 prompt。这样双路召回的好处是：相关性保证"找得对"，记忆分保证"留得该留的"。
3. 实操落地：如何让记忆真正"不跟着工具搬家"
3.1 存储层选型：我为什么放弃了向量数据库
很多 Agent 开发者一拍脑袋就用向量数据库存记忆，理由是"语义检索方便"。我在几个项目里走过这个弯路之后，现在的建议是：主存储用关系型数据库或键值数据库，向量索引只做辅助检索，不要当唯一的事实源。
原因有三个。第一，向量数据库的"语义相似"不等于"事实正确"，如果你用向量召回用户过敏信息，查出来的可能是语义相似但内容完全不同的记录；第二，向量数据库的迁移成本高，各家向量字段定义、索引参数、量化方式都不一样，想导出再导入别家平台，映射工作量大得想哭；第三，记忆分和时间衰减的计算，在关系型数据库里用 SQL 一句话就能完成，在向量库里反而要写一堆脚本。
我现在的主力方案是PostgreSQL + pgvector 插件。一张核心表搞定：
CREATE TABLE agent_memory ( id BIGSERIAL PRIMARY KEY, agent_id VARCHAR(64) NOT NULL, user_id VARCHAR(64) NOT NULL, content TEXT NOT NULL, score FLOAT NOT NULL, created_at DOUBLE PRECISION NOT NULL, last_access_at DOUBLE PRECISION NOT NULL, half_life DOUBLE PRECISION NOT NULL DEFAULT 604800, memory_type VARCHAR(16) NOT NULL DEFAULT 'general', status VARCHAR(16) NOT NULL DEFAULT 'active', embedding vector(1536) );这张表的设计要点：
- agent_id 和 user_id 双主维度：同一个用户在 A Agent 下的记忆，迁移到 B Agent 时，只要把 agent_id 改掉（或者走映射表），数据就能无缝复用。这正是"记忆不跟着工具搬家"的物理基础。
- created_at 和 half_life 都是数值类型：算记忆分一个
SELECT就完成，不需要任何框架适配。 - embedding 字段只做召回辅助：真实事实以 content 字段为准，避免向量误召回导致幻觉信息进 prompt。
迁移的时候，逻辑极其简单：把这张表按user_id维度导出，然后INSERT到新环境的同一张表结构里，一个框架时代的记忆就完整带过去了。我在实际项目中把 100 万级记忆记录从一套系统迁到另一套系统，耗时不超过五分钟。
3.2 框架无关的记忆读写接口
解决了"存哪里"，下一步就是解决"怎么读写"。我给记忆层定义了一套框架无关的接口，这套接口可以适配到任何 Agent 框架上。核心接口就四个：
class MemoryPort: def save(self, user_id: str, content: str, score: float, memory_type: str) -> int: ... def recall(self, user_id: str, query: str, top_k: int = 10) -> list[dict]: ... def forget(self, user_id: str, threshold: float = 1.0) -> int: ... def snapshot(self, user_id: str) -> dict: ...save()：写一条带分数的新记忆。recall()：按用户 ID 召回与当前 query 有关的高分记忆。forget()：把低于阈值分数的那批记忆标记为归档。snapshot()：把用户在某时间点的完整记忆状态导出为 JSON。
这套接口的精妙之处在于接口里没有任何框架概念：它不认识 LangChain 的 Message，不认识 OpenAI 的 ChatCompletion，也不认识你自己的 Executor。任何框架只要能调四个函数，就能获得完整的跨会话记忆能力。
3.3 LangChain / CrewAI / 自研框架的适配写法
有了接口，适配框架就是写一层薄薄的胶水代码。举个例子，在 LangChain 里给 Agent 接上这套记忆：
# 适配 LangChain 的记忆接口 class PortableMemory(BaseChatMemory): def __init__(self, memory_port: MemoryPort, user_id: str): self.port = memory_port self.uid = user_id def load_memory_variables(self, inputs): query = inputs.get("input", "") memories = self.port.recall(self.uid, query, top_k=10) return {"memory_context": format_memories(memories)} def save_context(self, inputs, outputs): # 从对话中提取值得记忆的信息 extracted = extract_key_facts(inputs["input"], outputs["output"]) for fact in extracted: score = score_fact(fact) self.port.save(self.uid, fact["content"], score, fact["type"])核心就两步：load_memory_variables从记忆层取回相关信息拼进 prompt；save_context把当前对话里有价值的信息提取出来写进记忆层。换成 CrewAI 或者自研框架，本质也是一样：在框架的"对话前钩子"里读记忆，在"对话后钩子"里写记忆。
用这个方案，我做到过把同一个带记忆的 Agent 从 LangChain 迁到自研框架，整个迁移过程没改记忆层的一行代码，只重写了那层胶水逻辑。原来要几千行记忆管理代码的项目，最后核心记忆逻辑只有 300 行左右。
3.4 封装成 WorkBuddy skill 的实战过程
热搜词里提到的 WorkBuddy 跨对话记忆 skill，正好是我实际工程里的一个产物。我把它拆成一个独立 skill，放在了业务侧的 Agent 工作流里。
skill 的核心目标是：让 WorkBuddy 平台上的 Agent 无论怎么切换业务场景，都能共享一份用户画像级的长期记忆。实现方式就是上面这套记忆端口，我封装成了三个回调注入点：
on_session_start(user_id)：加载该用户的工作记忆快照和 Top-K 长期记忆，注入 Agent 的系统提示词。on_turn_end(user_id, dialog)：每轮对话结束后，提取本轮的关键事实，打分并写入长期记忆，同时更新工作记忆快照。on_session_end(user_id)：把最终的会话摘要和重要结论沉淀到长期记忆，避免对话窗口关闭后全部丢失。
用 skill 的优势在于可复用、可分享。不管在哪个业务 Agent 里，只要挂上这个 skill，记忆能力立刻齐活。我在内部至少挂了五六个不同的 Agent 上，跑了两周多，效果稳定。现在团队里新来的同事开发带记忆的 Agent，不用再研究记忆模块，直接pip install我们封装的记忆包，挂上 skill 就行了。
3.5 落地一个最小可用版本只要三步
如果你现在就想上手，我建议别急着搞全功能，先跑通最小可用版本（MVP），流程如下：
- 建表：用上面那段 SQL 在 PostgreSQL 里建好
agent_memory表，装好 pgvector 扩展。 - 实现 MemoryPort：写四个接口函数，用 psycopg 连接库 + 15 行左右的 SQL 完成 save/recall/forget/snapshot。
- 接入 Agent 生命周期：在你的 Agent 框架里找到会话开始/结束的钩子，把 session 级上下文接入
MemoryPort。
这个 MVP 大约半天时间就能完成。跑通之后你会立刻看到效果：一个 Agent 在对话里记住的东西，重启进程之后还在；切换模型 API 之后还在；换个框架之后依然在。
4. Agent 抗并发与生产环境部署要点
4.1 并发读写同一个用户的记忆：别让孩子打架
单独一个用户还好处理，到了多用户并发访问，记忆系统就会变成瓶颈。我踩过最大的坑就是同一个用户的记忆在多个会话里同时读写。比如用户在 Web 端开了一个会话，又在手机 App 端开了另一个会话，两边同时往长期记忆里写信息，如果没有任何并发控制，最后就会出现"最后一次写入覆盖前一次"的脏数据问题。
这个问题的解法不复杂，本质就是数据库层面的行级锁 + 乐观锁。
- 写操作串行化：同一个
(agent_id, user_id)对，写操作通过 PostgreSQL 的行级锁来保证同一时刻只有一个会话在更新。也就是说，save()时先SELECT ... FOR UPDATE锁定用户对应的记忆行，再执行更新。 - 版本号防冲突：工作记忆快照里增加
version字段，恢复快照时如果检测到 version 落后，说明有其他会话已经修改过记忆，此时触发冲突合并策略，而不是简单覆盖。
这两条配合，并发场景下基本不会出现记忆互相覆盖的问题。
4.2 SQL 批处理：性能提升 20 倍的写法
刚开始做的时候，我老老实实了一条条 SQL 插入记忆，结果压测一上来就顶不住：平均每秒只能写 20~30 条记忆，还动不动锁超时。后来优化成批量写入，性能直接拉满。
def save_many(user_id, records): values = [ (user_id, r["content"], r["score"], time.time(), r["half_life"], r["type"]) for r in records ] with conn.cursor() as cur: cur.executemany( """ INSERT INTO agent_memory (user_id, content, score, created_at, half_life, memory_type) VALUES (%s, %s, %s, %s, %s, %s) """, values, )批量写入能把每秒写入量提升到 400~600 条，翻了 20 倍。另外一个优化点是召回缓存：同一个用户的 Top-K 长期记忆，如果 query 和最后访问时间变化不大，其实可以缓存 5~10 秒不用重新算向量相似度。并发高峰期这个缓存能挡住 80% 的重复查询压力。
4.3 沙盒环境下记忆的安全隔离
热搜词里提到"沙盒"这个词，在 Agent 部署里很常见。沙盒环境是用来隔离不可信代码和不稳定 Agent 行为的，记忆系统如果是全局共享的，很容易出现A Agent 的记忆串到 B Agent 的上下文里的安全事故。
我用三个策略做隔离：
- 存储层命名空间隔离：每个 Agent 用自己的 schema 或用自己的前缀
agent_memory_{agent_id}，从物理存储上隔开。 - 访问需要白名单：对外暴露的记忆 API，只接收已经在白名单里的
agent_id请求。新 Agent 上线必须申请开通，避免野生 Agent 读取数据。 - 敏感记忆字段脱敏：用户身份证、手机号、地址等信息，保存前进行 AES 加密或者脱敏处理，存储在独立字段。召回时不直接返回明文，只有 Agent 有明确业务需求时（比如下单要填地址）才解密。
这三条做完，沙盒隔离下的记忆安全才算有底。不然哪天审计出"用户 A 的过敏信息在用户 B 的对话里出现了"，那就不是技术问题了，是事故。
5. 常见问题与排查要点
5.1 高频问题速查表
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
| 换框架后 Agent 完全不记得任何历史信息 | 记忆数据绑定在旧框架的上下文对象里，没有独立持久化 | 迁移前用 snapshot() 导出记忆 JSON，再到新框架灌入 |
| 长期记忆召回到的都是噪声，答非所问 | 只用了向量相似度召回，没有按记忆分过滤和重新排序 | 召回流程改为"向量筛候选 + 记忆分排序" |
| 记忆越积越多，查询越来越慢 | 没有定期淘汰小便签，也没有分页控制 | 实现 forget() 流程，定期归档低分记忆 |
| 同用户多个会话互相覆盖记忆 | 缺少行级锁或版本控制 | 写操作加 SELECT FOR UPDATE 锁，快照携带 version 字段 |
| 重启或者发版之后记忆丢失 | 内存态保存，没有落盘到外部存储 | 强制所有记忆读写走 MemoryPort，不下沉到进程内对象 |
| Agent 回复时幻觉出用户从未提供过的信息 | 低分噪声记忆被当成高置信度事实用 | 设置召回最低记忆分阈值，同时只采信主动高分的记忆 |
5.2 一个隐蔽的坑：记忆注入 prompt 的顺序
你可能会忽略一个问题——记忆内容注入 prompt 的位置和顺序，会显著影响 Agent 的行为。我把同样一批记忆放在 system prompt 末尾（靠近用户的当前提问）时，Agent 对记忆的遵循程度明显更高，几乎是"看一次用一次"；放在 prompt 开头时，Agent 经常忽略它，因为注意力被后面的长文本稀释了。
这个观察符合 Transformer 的注意力机制特点：离当前 token 近的内容权重更高。所以我的最佳实践是：把召回的关键记忆，放在 system prompt 的最后段，紧接着用户当前对话。格式类似：
【长期记忆参考（按重要度排序）】 1. [用户自述] 对花生严重过敏，任何餐食推荐都必须避开花生制品。 2. [用户偏好] 偏好川菜，微辣，不喜欢香菜。 3. [事实信息] 工作地点在杭州滨江，常加班。 当前用户问题：帮我推荐明天中午的餐厅。这样格式清晰，Agent 一眼就能看到"有哪些硬约束"，然后给出的推荐才不会踩用户的雷。
5.3 评估记忆系统好不好用的可用性指标
很多开发者做完记忆系统之后不知道该怎么验收。我整理了一套自己的评估清单，不一定全面，但能帮忙判断系统是否真的达标：
- 跨会话保持率：两天前的会话里用户提到的核心信息，今天在新会话里主动问 Agent，Agent 能不能准确回忆起来。目标是 80% 以上。
- 跨框架迁移成功率：从框架 A 导出的记忆快照，灌到框架 B 后，Agent 在新框架里能不能复现同样的对话状态。目标是 100% 无损迁移。
- 记忆召回精确率：随机抽 100 次召回，看看 Top-10 命中与当前问题真正相关的比例。经验值在 60% 以上算及格，70% 以上算良好。
- 误记率：Agent 主动以"我记得你..."开头说的话里，有多少是用户从未提供过的信息。这个越低越好，理想状态是 0，实际做到 5% 以下就不错了，超过 10% 说明你的记忆数据里噪声太多。
每次迭代完记忆逻辑，跑一遍这四类指标，你会发现改进方向非常明确。
最后分享一点经验
单独说一点这套方案给我最大的收获：把记忆当成产品的一等公民来设计，而不是当成框架的附属品。以前我做 Agent 项目，总会先选框架再想记忆怎么存，导致记忆的形态被框架牵着走。现在反过来了，我先定义好记忆的数据模型和接口，再考虑框架怎么挂上去，反而轻松很多。记忆层变成了一块独立的基础设施，任何 Agent 想用就接，想迁就能迁，想扩容就扩容，不用再跟着工具链折腾。
另外一个我个人坚持的小技巧是：给每条记忆都留一条溯源信息。记录这条记忆来自哪次会话、哪条原始消息。这个设计平时看着没用，等出了"Agent 把我没说过的话当成事实"的事故时，你会感谢当初留的溯源字段——它让你能在五分钟之内定位到是哪条记忆出错了，而不是翻几十万条数据大海捞针。
这套方案目前已经在我手上的多个 Agent 项目里稳定跑了快两个月，迁移过四次框架，重启过多轮环境，记忆一次都没丢过。如果你也在被 Agent 记忆问题困扰，完全可以按这篇文章的思路，先搭个 MVP 验证一下，再逐步完善自己业务里的记忆细节。等你的 Agent 也能"换个地方住，记忆还在"，你就会明白那种爽快了。
