想起前阵子做的一个内部工具基于大模型的Agent系统用来处理一堆散落的业务数据查询。最初版本简单到不能再简单用户问一句大模型答一句看起来一切正常。但稍微用久一点就露馅了——用户在一个小时前刚确认过数据源是内网库A隔一会儿再问Agent已经完全不记得又把同一个问题问了一遍。这种金鱼记忆放在真实使用场景里是致命的用户会直接判定这个工具不聪明不靠谱再好的推理能力也救不回来。后来我把项目演进成了 Easy Data × AI 这样的组合形态重点就是在Agent开发里补齐了一套完整的分层记忆系统。这篇笔记就是把我在这个过程中的设计思路、代码骨架、踩过的坑以及最后沉淀下来的调优经验做个梳理给同样在做Agent开发的朋友一些参考。如果你正在做带多轮对话、工具调用或长期任务的Agent这篇内容应该能帮你少走不少弯路。1. 为什么Agent不能只靠大模型对话记忆缺失的真实痛点先说一个反直觉的结论很多人以为大模型有记忆力是因为它在对话里表现得像什么都记得。但实际开发中大模型本身的API设计是无状态的——每次请求送到模型那边它看到的只是本次请求里你塞给它的所有文本。它没有任何上次聊过什么的天然概念所谓的记忆完全要靠开发者在请求里主动拼装。1.1 一个典型的失败场景我最早试过最简单粗暴的方案每次请求都把全部历史消息拼进prompt里。表面看没问题但用了一周就崩了。场景是这样的用户让Agent帮忙分析某块业务报表中间确认了三次数据口径比如最近30天只统计已支付订单排除测试账号。这些确认信息都在对话历史里。当天一切正常第二天用户继续问把昨天的分析结论再跑一遍顺便按渠道拆分Agent需要用到前一天确认过的口径。如果历史全量塞进去它确实能找到但对话轮数多了之后上下文长度很快冲到几万token每次请求的延迟从2秒涨到5秒费用涨了快三倍。更麻烦的是当历史超过模型的上下文窗口上限旧信息会被直接截断。我遇到过一次非常典型的事故用户在第40轮对话时调整了统计口径第50轮时Agent反而采用了更早的旧口径因为早期消息虽然被截断了一部分但恰恰留下了那句按旧口径算的片段。这种错误非常隐蔽用户根本不知道是上下文截断导致的只会觉得这个Agent不可靠。1.2 上下文窗口不是记忆很多人会把大模型的上下文窗口理解成记忆容量这其实是个认知误区。上下文窗口更像是一张白板的大小——你在这张白板上能写多少字模型就能看到多少字但它并不会主动把这张白板保存下来供下次使用。而且窗口越大模型对远端信息的注意力越弱。我实测过超过一定长度之后埋在最前面的约束条件经常被模型忽略不是它不想遵守而是在注意力机制里遥远的文本本身的权重就已经衰减得所剩无几。打个生活化的比方上下文窗口相当于你办公桌上能摊开的纸张面积。记忆系统要解决的不是把桌子换大而是把真正重要的信息整理成便签贴在随时看得见的地方同时把旧文件归档到抽屉里需要的时候再去翻找。1.3 从对话系统到带记忆的Agent的思维转变做Easy Data × AI 的时候我最大的转变是把Agent从单次问答机制调整为带状态的任务执行机制。这里的关键认知是Agent的一轮交互不只是一次大模型调用而是感知—决策—执行—记录的完整循环。感知阶段Agent要决定本次需要哪些记忆用户偏好、历史结论、任务进度。决策阶段大模型根据当前输入和召回的记忆决定调用哪个工具、执行什么动作。执行阶段工具返回结果并被处理。记录阶段系统判断本次交互中有哪些新信息值得写入记忆。这四个环节里记忆系统至少参与了三个感知靠记忆召回决策靠记忆辅助记录靠记忆写入。所以这不是加一个缓存的问题而是要把记忆当成Agent架构的一等公民来设计。想清楚这一点后面的所有设计都会顺理成章。2. Easy Data × AI 的Agent骨架会话、任务与工具调度的耦合方式开始写记忆系统之前我得先把Agent的主干说清楚因为记忆不是游离在外的辅助模块它必须跟会话管理和工具调度紧密耦合。Easy Data × AI 的整体结构其实很常规但有一个地方比较关键所有外部工具调用都走统一的注册表这样记忆系统才能完整观察到Agent做了什么事、结果是什么。2.1 Agent主循环一次完整请求的生命周期一次用户请求的典型处理链路是这样的接收用户消息连同session_id会话标识一起交给Agent核心。Agent核心向记忆系统发起召回拉取与本次问题相关的历史记忆、用户偏好、任务状态。构造系统提示词把召回结果以记忆卡片的形式拼进上下文。大模型产出决策可能是直接回复也可能是请求调用某个工具。如果是工具调用由工具注册表找到对应处理器执行并返回结果。结果再送回大模型继续推理直到产出最终回复。回复返回用户的同时记忆系统异步分析本轮的对话内容、工具结果决定哪些值得写入长期记忆。伪代码大概长这样async def handle_user_message(session_id, user_text): # 1. recall memories memories await memory_manager.recall( session_idsession_id, queryuser_text, top_k5 ) # 2. build prompt with memory context messages build_messages(session_id, user_text, memories) # 3. main loop for step in range(MAX_STEPS): response await llm.chat(messages, toolsTOOL_SCHEMAS) if response.has_tool_calls(): # execute tool outputs await dispatch_tools(response.tool_calls) messages.append_tool_results(outputs) # 4. observe and write episodic memory await memory_manager.observe_tool_use( session_id, response.tool_calls, outputs ) else: final_reply response.text break # 5. async write memory await memory_manager.async_extract_and_store(session_id, user_text, final_reply) return final_reply这里有个容易被低估的点工具调用的中间结果不能只放在当次对话里。如果一个工具调用依赖前一次调用的状态比如先查用户列表、再查某个用户的订单而Agent在一轮中只能完成一步操作那么第二步发起时第一步的结果必须已经从记忆里能找回来。这个稍后我单独讲是个大坑。2.2 工具注册表与任务状态的联动工具注册表是我给Easy Data × AI 加的第三个核心组件。它的作用不只是找函数更重要的是给每个工具定义元信息工具名称、入参schema、执行时间预期、副作用等级只读还是写操作。这些元信息会被记忆系统用来判断该记什么。举个例子一个只读的查询报表工具它的执行结果值得进短期记忆因为用户可能会追问但不必进长期记忆除非结果本身形成了某种结论。而一个修改配置类的写操作执行动作本身必须被记录否则下次用户问我上次改了什么Agent会完全无从答起。我建议把工具注册表的schema也暴露给大模型这样模型在决定调用工具时能同时看到工具的语义。Easy Data × AI 用的就是标准函数调用协议每个schema里除了参数定义我还加了description和memory_hint字段前者描述工具的用途后者告诉记忆系统这个工具的结果倾向于短期还是长期留存。2.3 记忆系统在链路中的插入点很多框架把记忆做成事后补丁插在对话之外这是不对的。我的经验是记忆系统至少要在两个节点上做拦截第一个节点是请求前召回。这里必须同步阻塞因为后续的提示词构造依赖召回结果而一步步工具的继续运行也依赖这些。第二个节点是请求结束后异步写入。写入不能阻塞主流程否则每一次对话都会因为记忆更新而变慢用户能直观感知到卡顿。这里有个性能细节可以分享召回是延迟敏感操作我最初用的是同步方式一次召回耗时接近300ms用户体验明显变差。后来把向量化提前、把召回分成粗召回精重排两段第一段用一个更快的近似最近邻算法第二段才是余弦相似度精排总耗时压到了80ms以内。异步写入则放在消息队列里即使写入失败也不影响主流程的回复只会在日志里留一条告警。3. 记忆系统分层设计工作记忆、短期记忆与长期记忆的边界划分Easy Data × AI 的记忆系统最终采用了三层结构工作记忆、短期记忆、长期记忆。这三层的关系可以类比成你在写一篇长文章时的三种信息状态摆在屏幕最前面的当前段落是工作记忆手边一叠打印出来的参考材料是短期记忆散落在硬盘深处但随时能搜索回来的备份文件是长期记忆。3.1 三层记忆的职责与数据形态工作记忆Working Memory只存在于单次请求生命周期里用来存当前任务的临时状态本轮对话的原始消息、工具返回的原始结果、正在计算的中间变量。它不需要持久化请求完成即清空。但要注意的是如果Agent在单次请求里有多步工具调用工作记忆必须贯穿整个多步循环而不是每一步重新初始化。短期记忆Short-term Memory以会话为单位持久化。它存的是最近几轮对话的摘要、最近一次工具调用的输入输出、用户在当前会话里提到的偏好或临时约束。短期记忆的容量有上限超过上限就做一次压缩把老的内容用大模型总结成要点腾出空间给新的。这条设计非常关键它避免了早期那种全部历史塞进prompt的做法。长期记忆Long-term Memory跨会话、跨用户实例持久化。它存的是用户的稳定画像、业务领域的固定规则、跨会话的重要结论。比如用户说过我只看北美区域的数据这类长期偏好或者某次分析得出的结论性事实Q2营收下降主要是欧洲渠道流失导致。这些内容即使过了一个月也应该在相关场景下能被召回。记忆层数据形态生命周期典型内容存储介质工作记忆内存字典单次请求当前任务参数、工具返回值内存短期记忆摘要文本 最近N轮会话期间对话摘要、临时约束、最近工具调用Redis / SQLite长期记忆向量 结构化字段跨会话用户画像、业务结论、长期偏好向量库 关系型数据库3.2 记忆写入策略什么该记、什么该丢记忆系统的核心难题不是怎么存而是什么值得存。写多了会污染写少了会失忆。这是我反复调了很久才摸到门道的地方。我当时定的写入策略核心是三条过滤规则规则一临时信息不写长期记忆。工具返回的完整JSON、一次性计算结果、用户随口说但马上改口的说法都不进长期层。规则二结论优先于过程。用户说以后报表都按自然月统计这是一条值得长期记忆的结构化偏好但帮我查一下6月的订单量这种一次性请求只进短期记忆就够了。规则三冲突信息必须标记。新信息和旧信息矛盾时不能默默覆盖要有版本标记保证Agent在发现冲突时能向用户确认。为了落地这三条规则我在写入流程里加了一个记忆提取器。它不是简单地把整段对话存档而是用大模型对本次对话做一次结构化提取输出一个JSON{facts: [...], preferences: [...], task_state: {...}, confidence: 0.0~1.0}。只有confidence超过阈值的条目才允许写长期记忆。这样就把拒收垃圾内容的负担交给了模型理解力而不是靠正则和黑名单碰运气。3.3 记忆冲突处理新信息与旧记忆打架时怎么办记忆冲突是我在真实使用中才意识到的问题。举个实际发生的例子用户周一跟Agent说以后数据都看最新口径周三又说昨天那个口径不对还是回归旧口径。如果Agent不处理冲突只把周三的话覆盖进去用户可能遇到一个更隐蔽的问题——Agent在回答你以前说要看最新口径时会把一条已经失效的旧偏好翻出来。我的做法是给每条长期记忆加三个字段created_at创建时间、source来源会话、statusactive / superseded / revoked。写入新记忆时先用语义相似度把相关旧记忆找出来如果相似度超过阈值且内容方向矛盾就把旧记忆标记为superseded而不是直接删除。召回时只返回statusactive的记忆这样模型不会看到互相矛盾的指令。这套方案在内部测试里效果不错。唯一要注意的是语义矛盾的判断不能全靠向量距离因为向量相似度高也可能只是话题接近。我在实验里试过靠相似度判断冲突会有两成左右的误判率所以现在会再加上一层轻量的规则确认比如老记忆里如果包含明确的数值或日期新记忆的相应数值不同就强制标记为冲突交给下一次交互时让用户确认。4. 记忆写入与召回的实现细节向量化、索引与过期策略分层架构定了之后具体实现里的细节才是真正磨人的地方。这一节我把记忆从写入到召回的全链路展开讲包括向量化怎么做、索引怎么建、召回结果怎么组装成prompt的一部分、过期删除怎么才能不出问题。4.1 向量化模型选择与分块策略向量化的目标是让语义相近的内容在向量空间里有相近的距离。我踩过的第一个坑是直接用通用向量模型处理业务文本效果非常差。业务文本里充满专有名词和行业缩写通用模型对这些词的理解很浅。我的建议是如果没有条件训练专用模型至少做到分块和附带元信息两步。分块的意思是不把一大段文本整体向量化而是按语义切块。我用的是按段落切分加最长512字符截断切出的每块在写入时同时存原文文本和向量。附带元信息的意思是向量编码的不仅是文本本身而是文本 标签的拼接比如偏好 | 统计口径 | 用户希望所有报表按自然月统计。这个拼接能让召回时对偏好类信息的定位更准实测top-5准确率能从70%提到85%以上。嵌入模型我最初用的是通用型跑了几天发现对业务查询的召回结果经常答非所问。后来换成了在业务语料上做过微调的版本效果改善很明显——但这个属于有充足工程资源的情况。如果资源有限退一步的选择是不做全量微调而是维护一个业务实体同义词表在向量化之前把原文里的业务实体替换成标准表述比如上个月统一替换成具体月份Q3替换成第三季度。这个小技巧成本极低但对召回效果的提升非常直接。4.2 召回流程与上下文组装召回流程的每一步都有优化空间。我最终稳定的流程是这样的用户问题先做一次轻量改写把指代词它这个那样替换成指代对象把时间相对词昨天上周解析成绝对日期。这一步不经过大模型用规则加词典就能实现耗时可忽略。改写后的文本做向量化进向量库做近似最近邻搜索取top-20候选。对top-20候选做精排按余弦相似度降序再叠加一个时间衰减因子一般取score cosine_sim - 0.1 * age_in_days。这个因子很重要它是参考了信息衰减的常见规律加上的能让近期记忆略微排前防止三个月前的旧结论总是压过昨天的新信息。取精排后的top-5格式化成语义连贯的记忆卡片文本拼接到系统提示词的固定位置。组装格式我调了几版最后确定下来的是这种带来源和时间的结构【记忆卡片 - session: abc123, 3天前】 用户偏好报表统计口径按自然月排除测试账号。 来源会话中用户明确说明。卡片开头标注时间和来源是有实际意义的。我最初直接贴原文模型偶尔会把记忆当成当前对话内容甚至在引用记忆时混淆时间先后。加了时间和来源标记之后模型在引用时会更谨慎幻觉率下降了一个肉眼可见的幅度。4.3 过期、更新与遗忘机制遗忘和记忆同样重要。长期记忆如果只增不减整体召回质量会不断下降因为向量库里的冗余信息会干扰最近邻搜索结果。我设计的过期策略分三层短期记忆按会话周期自动清理会话结束或超过24小时无更新摘要压缩一次原始记录保留7天。长期记忆的软过期每条记忆带last_access_at超过90天未被召回过的记忆会被打上低频标记召回时优先级降低但不删除。长期记忆的硬删除每30天做一次离线清理把statussuperseded且超过180天的记忆从向量库中物理删除。硬删除有一个细节要提醒向量库里的记录和关系型数据库里的结构化记录不是一一对应的删除时要同时删两边的关联记录否则会出现向量能搜到、但详情已经没了的悬浮脏数据。我在第一版就踩了这个坑现象是召回结果里能看到记忆卡片但点开卡片详情是空的前后端都排查了很久才发现是两库不同步。5. 踩坑记录上下文膨胀、记忆污染与工具调用状态丢失不管架构设计得多合理实际运行里总会碰到设计阶段预想不到的问题。这一节是这篇笔记里最有价值的部分因为每个坑我都花了不止一个晚上去排查最后沉淀下来的经验希望能让你少走弯路。5.1 上下文膨胀一次注入上千条记忆导致的效果崩塌做第一版记忆召回时我犯了一个冒进的错误为了让Agent记得更全把召回窗口从top-5加到了top-30。结果效果不但没提升反而明显变差——模型开始在回答里反复引用互不相关的记忆卡片甚至出现把A项目的数据结论安到B项目头上的情况。排查后发现这不是模型能力问题而是记忆卡片的相互干扰。top-30里包含了大量只有表面相似、实际主题不同的记忆模型在上下文里同时看到这么多相关信息注意力被分散了反而抓不住最关键的那一条。打个比方你问一个人昨天下午的会议几点开的他手边同时摆着十张时间表反而更容易看错行。最终我调整成top-5硬召回 按需扩展的方案默认只给模型5张最相关的记忆卡片只有当前任务确实需要更完整的历史背景时才通过一次额外的记忆追问调用把候选扩展到top-15。这个改动让任务完成准确率回升了十几个百分点也让我记住了一条铁律召回数量宁少勿多先保证精准再考虑覆盖。5.2 记忆污染把临时计算过程写进了长期记忆记忆污染的问题出在自动提取器上。我在早期版本里让大模型从每轮对话中提取facts但没有严格区分事实和临时过程。结果很灾难——用户问前三个月的订单量分别是多少提取器把1月订单量100万、2月订单量85万、3月订单量92万当成稳定事实写进了长期记忆。三个月后用户再问类似问题时这些过期数字被当成历史结论召回出现在回答里用户一看数字不对直接质疑系统数据源有问题。修复思路后来我总结成一句话只有跨多轮被确认过、或者由用户明确表述为以后都这样的内容才值得进长期记忆。单轮出现的具体数字默认只进短期记忆。我在提取器里加了提示词约束要求模型区分stable_fact和transient_value两类输出只有当stable_fact出现时才可以写长期记忆transient_value一律走短期层。修改后这类污染基本绝迹。5.3 工具调用状态丢失多步任务在记忆断层后的连锁失败这是我踩过最深的一个坑。场景是Agent需要分三步完成任务先查用户列表再根据返回的用户ID查订单最后汇总成报表。单轮里三步都能走完看起来没问题。但当任务需要跨轮进行时——比如第一步在第一轮完成用户在第二轮说继续——Agent在第二轮就完全不知道第一轮查出来的用户ID是什么了。根因在于工具调用返回的结构化数据默认放在了工作记忆里而工作记忆在请求结束时就被清空了。短期记忆只存了摘要文本没有存结构化数据的关键字段。于是第二轮开始时Agent只知道上次查了用户列表但不知道具体ID。修复方案是在短期记忆里增加一个任务状态槽工具清点的关键输出字段如ID、名称、状态码以结构化JSON的形式写入短期记忆并且这个状态槽专门独立于对话摘要不被压缩策略覆盖。实测修完之后跨轮任务的成功率从不到60%提到90%以上。这个案例也让我意识到记忆系统的设计不能只想着记得住更要想着用什么形式记、要不要结构化留存这两者的差别在关键时刻能决定系统能不能用。6. 实测数据与参数调优建议最后把Easy Data × AI 跑了两个多月的实测数据写出来包括一组我用内部测试样本测出来的对比数据以及最终稳定的参数配置。你可以把这些当成一个参考基线具体数值还需要结合自己的业务场景调整。6.1 一组有代表性的对比数据我用内部测试集做了几轮AB对比测试集包含200个任务样例分四类单轮事实查询、多轮偏好跟踪、跨轮多步任务、长期结论召回。结果如下表数值按比例统计方案单轮查询准确率多轮偏好保持率跨轮任务成功率长期结论召回率无记忆系统仅当前轮92%18%31%12%全量历史塞入prompt85%越长越低74%63%45%单层向量记忆90%81%72%78%三层记忆最终版93%92%88%86%可以看到记忆系统的主要收益集中在多轮和跨长任务上而单轮查询和无记忆的差距并不大这也符合预期。如果你的场景单纯是一问一答不必急着上复杂记忆系统但只要有连续对话、有任务状态延续、有跨会话依赖这套东西的价值立刻体现出来。6.2 推荐的参数区间与配置参考调优过程中参数基本都来回试过最后稳定下来的是这几个区间长期记忆召回top-k5-8超过10会明显引入干扰。短期记忆保留轮数最近6-10轮对话超出就触发摘要压缩。记忆写入置信度阈值0.75-0.8低于这个值建议只进短期记忆。设太低了容易写入垃圾信息。时间衰减因子0.05-0.1/天具体看业务对时效的敏感程度。金融类场景建议加大到0.15以上而知识库类场景可以下调到0.02。向量分块长度256-512 token之间太短则语义碎片化太长则单条记忆被稀释。这些参数不是拍脑袋定的比如top-k我做了从3到30的阶梯测试5-8是准确率和覆盖率交叉点的稳定区段。你可以用相似方式在自己的测试集上逐档扫描一遍选斜率的拐点。6.3 关于记忆系统的一句话经验复盘如果只用一句话总结这段时间做Agent和记忆系统的体会我会说记忆系统不是一个被动的存储空间而是Agent决策能力的一部分。设计时永远先问自己三个问题——这条信息如果不记得会发生什么记住之后会不会误导未来的判断新旧信息冲突的时候模型该怎么选把这三个问题想透了架构上至少能避掉八成典型坑。另外还有一件小事但很实用所有记忆写入、召回、冲突标记的操作尽量留结构化日志。记忆系统的问题天然是慢性的不会当场爆雷而是过几天慢慢浮现。有日志你在排查每个模型为什么突然犯傻的复现问题时能省下大量翻数据的时间。我自己就是靠日志定位了至少五个隐藏bug包括前面提到的两库删除不同步、旧记忆压过新信息之类。
