把Agent从“聪明但健忘”变成“越用越懂你”记忆管理是绕不开的一环。这篇是ai-agent教程系列的第4篇专门拆记忆管理。我先说个真实场景你搭的Agent已经能调工具、能多步推理看起来挺能打可你换个话题再回来问它它完全忘了你十分钟前交代过什么需求。你反复解释它反复忘体验直接跌回“高级搜索引擎”。出现这种情况问题多半不在模型本身而在于你没有给Agent设计一套记忆管理机制。这一篇我会把Agent为什么需要记忆、短期记忆/长期记忆/工作记忆怎么分工、怎么用一套轻量方案实现可落地的记忆模块讲清楚然后拿WorkBuddy这个工作场景Agent当例子从需求拆解到代码实现走一遍最后聊聊我实际踩过的坑。不管你是刚入门还是有几句经验照这篇折腾完至少能给你自己的Agent装上一个“不健忘”的脑子。1. 失忆的Agent没法干正事——记忆管理到底管什么很多人的第一反应是Agent要记忆直接把聊天历史全塞进上下文窗口不就行了这个想法就是早期记忆管理混乱的根源。上下文窗口本质上是一个临时存储区模型每次调用都要重新处理和理解这些内容窗口有长度上限塞满之后最早的信息就会被挤掉。你可以把它类比成服务员的便签纸客人点菜时记几笔没问题但一整天的客流量不可能都靠一张便签纸撑下来更不可能隔了一周还记得老客户的口味偏好。1.1 上下文窗口不是记忆模型本身是“无状态”的它在推理某个请求时只会看到当前输入的这些token。你之所以觉得它“记得”刚才的对话是因为你的调用框架把历史消息一起发给了模型。这套机制在单轮聊天里够用但Agent一旦涉及工具调用、任务编排、多会话并行问题就暴露了会话一长历史消息占满上下文模型开始截断关键信息用户换了个新会话历史全部归零Agent彻底失忆多个任务之间需要共享同一份知识比如公司背景、项目进度、用户偏好这些不可能每轮都重说一遍用户主动纠正过的事情Agent下次依然按错误理解执行所以在Agent架构里记忆管理的本质是把“临时便签”升级成“长期档案系统”。哪些信息值得长期沉淀哪些信息用完就扔哪些信息需要定时过期这都需要一套机制来控制。1.2 四类必须长期记忆的信息我做了这么多Agent项目后发现需要长期记忆的信息基本可以归类成四层记忆类型典型内容生命周期示例用户身份与偏好称呼、职位、语言风格、回复偏好很长“用户偏好简洁回复”“习惯用中文夹杂英文术语”事实知识/项目背景团队成员、代码结构、业务规则较长“支付服务负责人是张三”“项目使用微服务架构”对话状态上次聊到哪、上次的结论中“上轮对话确认了排期未确认开发负责人”任务进度当前任务步骤、完成状态、待办短到中“部署任务已完成第一步等待测试反馈”这四层信息里第一层和第二层最容易被忽视但恰恰是它们决定了Agent能不能从“通用工具”变成“懂你的搭档”。第三层和第四层如果丢了用户就不得不反复交代上下文体验会很差。1.3 失忆的代价没有记忆管理的Agent实际项目中会连续踩中几个坑。最直接的是重复沟通成本用户每开一个新对话都要重新介绍背景Agent每轮都要理解一遍再问一遍其次是决策不一致同一个问题上午一个答案、下午一个答案用户会觉得这系统很不稳最严重的是任务断点无法恢复Agent跑到一半会话崩了或者用户换设备进度全丢相当于白干活。这些问题的共性源头只有一个信息只流动在当次调用的上下文里没有任何沉淀和复用。所以记忆管理不是一个可以后期再补的优化项而是Agent能持续靠谱工作的基础设施。2. 三层记忆架构短期上下文、长期知识库、工作记忆状态我习惯把记忆系统拆成三层分别是短期记忆、长期记忆和工作记忆。这三层对应不同的存储位置、生命周期和读写方式搭在一起才能覆盖Agent的各种使用场景。2.1 短期记忆上下文窗口与滚动摘要短期记忆就是当前会话里正在使用的信息物理载体是上下文窗口。它的特点是读写极快但空间有限。为了在有限空间里装下更多有效信息我一般会做一个“滚动摘要”机制当历史消息接近阈值时比如剩余窗口只有总长度30%调用模型把前面的对话浓缩成一段摘要存进上下文里再把早期原始消息丢弃。滚动摘要的要点是摘要质量。不要只让它机械复述对话要让它提炼出“已经确认的结论”“尚未解决的问题”“用户强调过的事项”。这样即使原始消息被丢掉后续对话依然能围绕关键信息展开。2.2 长期记忆语义向量与档案库长期记忆对应的是跨会话、跨任务复用的知识存储载体通常是外部数据库或者向量库。写入长期记忆的信息需要经过筛选一般是那些“值得以后反复参考”的内容例如用户偏好、项目背景、阶段性结论。检索长期记忆靠的是语义相似度。用户的新问题产生后系统先把它转成向量再到向量索引里找语义相近的记忆。这个过程很像人类在档案柜找资料你不能把整个柜子都搬到桌面上只能根据当前问题找出最相关的几份文件。2.3 工作记忆当前任务的暂存区工作记忆这个概念很多人忽视。它指Agent在执行当前任务时需要持续维护的中间状态比如当前目标、已完成步骤、关键变量、待确认事项。工作记忆不一定需要写入长期存储它更强调“跨推理步骤保持状态”。打个比方你让Agent“帮我写一份活动方案先调研竞品再列出大纲最后写几页PPT”。如果没有工作记忆Agent每一步都可能丢失之前的输出有了工作记忆它就能在步骤之间维护“竞品调研结论是什么”“大纲已经列出到第几部分”把多步任务串成完整流程。实现上工作记忆常常放在会话级的内存结构里任务结束归档或清除。2.4 三层之间怎么配合三层记忆不是互相独立的而是有明确的流动方向。短期记忆是当前正在使用的“桌面”桌面上的重要结论会被定期整理进长期记忆“档案柜”当前任务进行中产生的中间状态放在工作记忆“草稿箱”任务结束后草稿箱里有价值的内容也会归档进长期记忆。我见过很多失败的设计是把所有东西一股脑塞进向量库以为“存得够多就够聪明”。实际上记忆的目的是“在正确的时间给模型引入正确的信息”而不是把全部历史都回放一遍。三层记忆的好处是可以按重要程度和时效性做筛选让模型每次只看到当前最需要的那一小部分。3. 从零搭一个记忆模块数据结构、存储选型与存取链路理论讲完直接动手。我这里的实现思路是轻量优先先用SQLite存结构化数据再配一个向量检索接口不需要一开始就上分布式向量数据库。3.1 记忆的数据结构长什么样先定义一条记忆的最小结构。我认为至少要有这几个字段记忆类型、内容、元数据、重要性、创建时间、过期时间。记忆类型对应上面说的用户偏好、项目背景、对话摘要等元数据用来存标签例如“user_id123”“project_id456”方便按维度过滤重要性用来做后续的排序加权。下面是Python里的数据类定义你可以根据自己的项目调整字段# memory_store.py import sqlite3 import json import time class MemoryItem: def __init__(self, memory_type, content, metadataNone, importance0.5, ttl-1): self.memory_type memory_type # user_profile | project_state | conversation_summary | task_log self.content content # 记忆正文 self.metadata metadata or {} # 附加标签 self.importance importance # 0.0 ~ 1.0 self.created_at int(time.time()) self.expires_at self.created_at ttl if ttl 0 else -1 def to_dict(self): return { memory_type: self.memory_type, content: self.content, metadata: self.metadata, importance: self.importance, created_at: self.created_at, expires_at: self.expires_at, }这段代码看着简单但它决定了一套系统的规范。一旦字段固定后续所有写入、检索、过期清理逻辑都围绕这几个字段展开改起来也方便。3.2 存储选型别一上来就上重型装备很多教程一上来就让你部署Elasticsearch或者专业的向量数据库说实话对大部分项目是杀鸡用牛刀。我的建议是初期用SQLite存记忆的正文、类型、标签和时间向量索引可以用轻量级方案甚至可以先只靠关键词匹配和规则过滤跑通流程。这样选的原因很实际记忆模块的瓶颈往往不在检索性能而在“该存什么、什么时候存、怎么维护”这些设计问题上。用SQLite这样的轻量组件你可以快速迭代逻辑等记忆量真的大了再平滑迁移到专业存储也不迟。反过来如果一开始就上重型组件光运维成本就够你头疼而且并不解决“记错东西”的问题。下面是一个最小版的存储类负责写入和按条件读取class MemoryStore: def __init__(self, db_pathagent_memory.db): self.conn sqlite3.connect(db_path) self._init_table() def _init_table(self): self.conn.execute( CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, memory_type TEXT, content TEXT, metadata TEXT, importance REAL, created_at INTEGER, expires_at INTEGER ) ) self.conn.commit() def add_item(self, item: MemoryItem) - int: cur self.conn.execute( INSERT INTO memories(memory_type, content, metadata, importance, created_at, expires_at) VALUES (?,?,?,?,?,?), ( item.memory_type, item.content, json.dumps(item.metadata, ensure_asciiFalse), item.importance, item.created_at, item.expires_at, ), ) self.conn.commit() return cur.lastrowid def search_by_type(self, memory_type: str, limit: int 20): rows self.conn.execute( SELECT content, metadata, importance, created_at, expires_at FROM memories WHERE memory_type ? AND (expires_at -1 OR expires_at ?) ORDER BY importance DESC, created_at DESC LIMIT ?, (memory_type, int(time.time()), limit), ).fetchall() return [dict(zip([content, metadata, importance, created_at, expires_at], row)) for row in rows]这里我刻意用“按类型查询重要性排序”作为第一版检索手段。因为刚开始你的记忆量不大按类型查比向量检索更可控也好排查问题。3.3 写入链路什么时候该记、记什么格式记忆系统成不成一半看写入策略。写入太频繁库里全是噪音写入太保守该记住的又丢了。我总结出一个经验原则只有在“信息有复用价值”时才写入长期记忆普通闲聊内容一律不落库。有价值的写入时机包括用户明确表达偏好或纠正“以后邮件都简短点”“不要用‘温馨提示’这个词”任务产生了重要的中间结论调研完成、方案确认、某个决策拍板跨会话必需的项目背景成员分工、技术栈、历史遗留问题对话阶段结束时生成的摘要把本阶段的关键信息提炼成一条“conversation_summary”写入格式上我建议用“主谓宾明确”的句子不要用一堆修饰词。例如写“用户偏好简洁回复风格”比“用户说以后回复最好别太长能简短尽量简短方便节约时间”更容易被检索和理解。长期记忆不是给人看的是给模型看的信息密度要高。3.4 读取链路检索、排序、注入Prompt读取链路的目标是拿到用户当前问题从记忆里找出最相关的几条注入到Prompt中。完整流程大致是根据当前query生成检索请求带上必要的过滤条件用户ID、项目ID、记忆类型先做向量语义召回取出top N候选再做一次排序综合考虑重要性、时间衰减和元数据匹配度把最终选出的记忆拼成一段“历史记忆”文本放入系统提示词模型基于“系统提示词历史记忆当前对话”进行推理代码示意如下向量检索部分我抽象了一个接口你接OpenAI的Embedding接口也好、接本地模型也好逻辑都一样class MemoryRetriever: def __init__(self, store: MemoryStore, embed_fn): self.store store self.embed_fn embed_fn def retrieve(self, query, memory_typeNone, top_k6): query_vec self.embed_fn(query) candidates self.vector_search(query_vec, memory_type, top_k30) reranked self.rerank(candidates, query) return reranked[:top_k] def vector_search(self, query_vec, memory_type, top_k): # 这里接入你的向量索引返回候选记忆ID列表 # 初期可以直接用 SQLite 的 LIKE 查询过渡 pass def rerank(self, candidates, query): # 用 importance * decay(时间) 关键词命中加分 做排序 return sorted( candidates, keylambda c: c[importance] * self.time_decay(c[created_at]) self.keyword_bonus(c, query), reverseTrue, )读取链路最怕的是检索出一堆不相关的结果。所以重排列很重要不能只靠向量相似度一个指标。我通常在重排时结合三个维度重要性、时效性、关键词重合度。重要性高的旧记忆保留重要性普通但很新的记忆保留既旧又普通的让路。4. WorkBuddy场景实战给工作Agent装上记忆理论落地最好的方式是用一个具体业务场景走一遍。我这里就拿WorkBuddy举例它是我做的一个工作场景Agent主要帮团队维护项目进度、整理会议记录、回答业务问题。这类Agent对记忆的需求特别明显用户希望它是团队的“活百科全书”而不是每次都要从零开始问的客服机器人。4.1 WorkBuddy需要记住什么我拆了WorkBuddy的核心记忆需求主要有几类团队成员的档案名字、职位、负责领域项目状态当前阶段、关键决策、截止时间用户的工作偏好日报格式、汇报习惯、沟通风格业务领域知识公司产品线、客户信息、常用术语历史会议结论上次会议确认了什么、遗留问题有哪些这些信息如果靠用户每次重新提供效率极低。把工作记忆和长期记忆结合后WorkBuddy一启动就能“想起”该项目的上下文回答问题时能主动引用正确背景。4.2 记忆模块在对话循环里的位置WorkBuddy的主循环大致是接收用户消息 → 检索记忆 → 组装Prompt → 调用模型 → 执行工具调用 → 更新记忆。记忆模块不是挂在旁边的一个装饰品而是每一轮都要参与的环节。一个简化版的对话循环如下class WorkBuddy: def __init__(self, memory_store, retriever): self.memory_store memory_store self.retriever retriever def run(self, user_message, user_id, project_id): query user_message # 1. 检索相关记忆 memories self.retriever.retrieve( query, filter_tags{user_id: user_id, project_id: project_id}, top_k6, ) # 2. 组装带记忆的Prompt memory_block self.format_memory_block(memories) prompt self.build_prompt(memory_block, user_message) # 3. 调用模型 reply self.call_llm(prompt) # 4. 判断是否有值得写入长期记忆的新信息 new_item self.extract_memory_from_interaction(user_message, reply) if new_item: self.memory_store.add_item(new_item) return reply你注意第4步不是每轮对话都写记忆而是经过一个提取判断。我通常用一个额外的小模型调用或者规则判断来识别“这句话值不值得进入长期记忆”。比如用户说“以后报告上午10点发”这就是一条高价值偏好用户说“今天天气不错”就完全没有记录价值。4.3 一个可用的记忆注入模板检索出记忆之后怎么注入Prompt很考验细节。我常用的模板是把记忆放在系统提示词里并且注明信息来源帮助模型区分“事实记忆”和“本次对话内容”。你现在是一个团队成员的工作助手名叫WorkBuddy。 【长期记忆】 - [用户偏好] 用户偏好早上收到日报日报结构按“进展-风险-明日计划”排列 - [项目状态] 支付服务重构处于开发阶段预计两周后进入联调 - [团队档案] 后端负责人是张三前端负责人是李四 - [历史结论] 上周会议确认新官网优先做移动端适配 【本次对话】 用户目前支付服务重构进展怎么样这样模型看到的信息是经过筛选的既不会因为它没有相关背景而瞎编也不会因为塞了太多无关历史而失去重点。5. 遗忘机制与记忆卫生比记住更重要的是忘掉记忆管理做到后面你会发现“忘掉什么”和“记住什么”同样重要。一味把所有信息攒着记忆系统会越来越脏甚至开始误导Agent。5.1 为什么必须主动遗忘首先是成本问题长期记忆存得越多检索时的候选池越大排序耗时越长向量索引的空间也越贵。更关键的是误导问题项目已经迭代好几轮Agent还在引用三个月前的旧方案用户一看就知道这系统不靠谱。还有隐私合规问题用户明确要求删除的数据你这边还留着这是给自己埋雷。5.2 四种实用的遗忘策略我实践中常用的遗忘策略有四种可以组合使用TTL过期给每条记忆设置有效期到期自动标记过期检索时直接过滤容量上限淘汰给每种记忆类型设置最大条数超过后按重要性/新鲜度淘汰最旧的用户主动删除提供“查看记忆/删除记忆”的管理接口用户说“忘掉这件事”时必须真删事件驱动失效项目结束、人员离职、需求变更等事件发生时批量删除或降权相关记忆TTL这块我通常在记忆条目里直接存expires_at字段检索SQL里加一个过滤条件就可以了。事件驱动则需要业务侧给信号比如“项目状态从开发变更为结束”时主动调用一次清理方法。5.3 记忆冲突与用户管理入口记忆系统跑久了还会遇到冲突。比如早上记录了“用户喜欢详细报告”下午用户又说“以后报告精简点就行”这两条记忆同时在库里Agent会不知道该听谁的。我的处理方法是对同一标签下的记忆做“覆盖式更新”当新记忆和旧记忆的元数据高度重合时新记忆直接替代旧记忆而不是追加。实现上可以在写入前做一次查重如果memory_type metadata基本一致就把旧记录标记为过期。用户管理入口也必须有。WorkBuddy里我加了一个“记忆面板”用户可以查看Agent记住了什么也可以手动删除某条记忆。这个功能看起来不显眼但它大大提升用户信任度。很多人不愿意用带记忆的Agent就是怕它乱记隐私有了可见可删的管理入口这种顾虑会小很多。6. 记忆系统调优与踩坑心得最后这部分是我在多个Agent项目里反复踩过的坑每个都真实发生过。6.1 向量检索的假命中向量检索最大的坑是“语义相近但不相关”。举个例子用户问“支付超时怎么处理”向量检索可能召回一条“数据库超时怎么排查”的记忆因为语义距离接近但对当前问题完全没用。解决这个问题的关键是metadata过滤和重排逻辑。我建议先按业务标签硬过滤再用关键词做加分最后才看向量相似度。宁可少召回不要召回一堆带偏模型的噪音。6.2 重复记忆与上下文膨胀如果写入前不做去重同一事实会被反复存成好几条。比如用户说了五次“报告要简洁”库里五条高度相似的记忆检索时全被召回上下文被无意义重复内容占满。我的做法是在写入前做一次相似度检测如果新内容与已有记忆的相似度超过某个阈值就只更新旧记忆的freshness和importance不新增条目。6.3 摘要有损与分层摘要滚动摘要方案虽然好用但摘要本身就是有损压缩。如果你每次都把整段对话塞给模型去总结摘要会越滚越失真。我的改进是分层摘要短期按对话轮次做小段摘要定期再把多个小段摘要合成一个主题摘要长期按主题维护摘要而不是按时间线维护一条巨型摘要。这样既控制上下文长度又能保持关键信息的准确度。6.4 给记忆打标签和做评测最后一个心得是给记忆打标签。每条记忆至少要带用户维度和项目维度标签检索时才能精准过滤。数据结构里那个metadata字段就是干这个的别浪费。评测记忆系统的方法也不复杂。我平时会准备一组典型query标注出每一条query应该召回哪些记忆然后跑一遍检索链路看recallk。这一步看起来很土但它能很快暴露“该记的没记”或“记了一堆没用的”的问题。推荐你在上线前就跑一遍后面迭代才有依据。我个人在实际操作中的体会是记忆系统一开始不用做得很复杂先把“能存、能取、能删、能过期”这四件事跑通再加向量检索、再加重排、再加遗忘策略。很多人一上来就搞一个庞大的知识库系统结果光维护就累得半死Agent反而没有变聪明。WorkBuddy这个项目能稳定跑起来靠的就是这套从简到繁逐步叠加的路子。你按照这个路径走大概率也能少走不少弯路。