字节跳动开源的DeerFlow我最开始是冲着深度推理四个字去研究的真正让我决定在业务里接入的反而是一直被当成附加功能的长期记忆模块。原因很实在一个聊完就忘的智能体无论推理链路设计得多精巧落到实际体验上都会露馅。上周我把一个旅行规划助手接到DeerFlow上用一条用户不吃海鲜的偏好把两轮对话之间的记忆链路完整跑了一遍。这篇文章就把这套实现方案从环境准备到生产扩展完整拆开讲清楚。1. 长期记忆不是聊天记录DeerFlow给记忆分了三层1.1 一个失忆助手的尴尬场景先还原一个大多数人都遇到过的场景。你上午告诉助手我对花生过敏点餐的时候帮我避开。下午你让它推荐下午茶它兴致勃勃推荐了花生酱吐司。这不是模型能力不行而是整个系统架构里缺了一条从经验到行为的回路——它根本不记得你上午说过什么。普通对话式AI的上下文窗口再大也只覆盖当前会话会话一关所有信息归零。DeerFlow把长期记忆作为一个独立模块做进框架里解决的就是这个问题让智能体在跨会话、跨任务的情况下仍然能调用之前积累的用户事实、偏好和历史决策。1.2 短期上下文、工作记忆与长期记忆的边界DeerFlow里的记忆并不是一个大一统的数据库而是分成三层职责完全不同。第一层是短期记忆本质就是大模型当前的上下文窗口存放本轮会话的原始消息、工具返回结果、当前任务状态它的特点是容量有限、用完即弃。第二层是工作记忆这是推理过程中产生的中间状态比如Planner当前的任务清单、Reasoner正在思考的推理步骤、Executor执行完工具后的临时输出。第三层才是长期记忆指跨会话持久化的稳定知识包括用户偏好、个人画像、历史事件、长期目标。做个厨房类比就很好理解短期记忆是操作台上正在处理的食材工作记忆是旁边备菜区排好的工序长期记忆则是冰箱和调料柜——今天没用上的食材只要放进冰箱明天还能拿出来。很多智能体框架只有操作台DeerFlow多给了你一个冰箱这才有了长期记忆的玩法。1.3 长期记忆模块挂在推理链路的哪个位置我查阅DeerFlow源码时特别关注了记忆模块在整个工作流里的挂载位置。一条完整的处理链路大致是这样用户输入进入系统后先触发记忆检索把和当前任务相关的历史记忆取出来拼进提示词上下文然后Planner基于记忆当前输入制定计划Reasoner深度推理Executor调用工具Reflector反思结果最后输出回复。但这还没完——在回复结束后还有一个异步的记忆固化环节从本轮对话中提取值得长期记住的新信息写入记忆存储。注意这个先检索、后固化的顺序它意味着长期记忆不是事后的日志存档而是参与生成决策的主动组件。这也是DeerFlow和普通RAG问答的本质区别RAG是查文档DeerFlow是查关于这个人的经验。理解了这个位置关系后面看代码就不会晕。2. 跑一个能记住事的DeerFlow环境准备与最小配置2.1 依赖清单与安装步骤我在一台干净的Ubuntu机器上部署Python版本要求3.10以上。DeerFlow本身用git clone拉下来然后通过uv或pip安装依赖。建议直接用uv因为DeerFlow的依赖链比较长uv的并行解析会快很多。安装完成后需要确认自己用的LLM后端支持工具调用和结构化输出DeerFlow默认对接的是兼容OpenAI接口的服务无论是大厂的API还是本地部署的模型只要兼容OpenAI协议就能跑。列一下我这次实际装的东西deerflow核心仓库拉master分支版本号在2.x以上记忆模块才比较完整向量数据库客户端本地方案我选了ChromaDB零配置跑通再换SQLite3Python内置做结构化元数据存储OpenAI兼容的LLM客户端库安装命令非常简单两行就能完成但真正的坑在后头不同版本的DeerFlow记忆模块的模块名和API命名会变。我第一次拉代码时参考的是老文档结果import路径直接报错。所以务必以你拉取版本仓库里的实际代码为准别信网上的过期教程。2.2 配置记忆存储后端向量库元数据库长期记忆要持久化必须同时配两类存储。类存储是结构化元数据库存记忆条目的属性字段比如用户ID、记忆类型、重要度、时间戳我用SQLite完全够用类是向量索引库存记忆内容的语义向量用于语义检索。为什么不能只用其中一个因为向量库不擅长精确过滤查userId123的所有记忆这种操作在向量库里效率很低而SQLite不擅长语义相似度。两者通过memory_id关联。我给DeerFlow写的存储配置大概是这样的memory: enabled: true backend: vector: chroma metadata: sqlite collection: deerflow_memories embedding_model: text-embedding-3-small retrieval: top_k_candidates: 20 top_k_inject: 5 score_threshold: 0.55这里的关键是separate的top_k_candidates和top_k_inject。召回时先取20条候选经过重排后只注入5条到上下文避免把提示词塞爆。score_threshold是相似度阈值低于0.55的记忆宁可不注入否则纯粹是噪声。2.3 最小验证先确认记忆模块真的在工作配完之后不要急着写业务代码先做一次最小验证。我用的是DeerFlow自带的一个example脚本开了两个会话第一个会话里告诉它我的名字叫陈默坐标杭州第二个会话里直接问我叫什么名字。如果第二个会话能答出陈默说明长期记忆链路已经通了存储和检索都工作正常。这一步跑通之后再去读核心示例代码心态完全不一样——你是在看一个已经验证过的系统而不是在一堆抽象概念里猜。3. 示例主线让旅行助手记住用户不吃海鲜3.1 第一轮对话记忆捕捉与写入我的示例场景是一个旅行规划助手。第一轮对话我输入的是帮我规划下周去三亚的行程。对了我不吃海鲜花生过敏节奏慢一点别搞得太赶。这句话里有两类信息。一类是临时任务信息目的地三亚、时间下周、要一份行程规划这些只对本轮任务有效另一类是长期偏好信息不吃海鲜、花生过敏、喜欢慢节奏这些跨会话持续有效。DeerFlow的长期记忆模块要做的第一件事就是区分这两类并只把后者写入持久化存储。这个区分不是简单规则能做到的DeerFlow的做法是让LLM来做初提取再用代码做硬校验。我梳理出的提取逻辑如下# 示意代码DeerFlow记忆提取与过滤 MEMORY_EXTRACTION_PROMPT 你是长期记忆提取器。 从对话中提取值得跨会话记住的信息只提取这些类型 - 用户的稳定偏好喜欢/不喜欢/习惯 - 用户的个人信息职业、所在地、过敏史等 - 用户的长期目标 忽略临时任务、一次性指令和纯闲聊。 对每条候选记忆给出重要度评分0到1并说明理由。 以JSON数组返回[{content: ..., type: ..., importance: 0.9, reason: ...}] async def extract_memories(conversation: list[dict], llm): # 1. 让LLM产出候选记忆 raw await llm.complete(MEMORY_EXTRACTION_PROMPT.format( conversationjson.dumps(conversation, ensure_asciiFalse) )) candidates json.loads(raw) # 2. 代码层硬过滤临时信息一律丢弃 filtered [] for item in candidates: if item[type] not in {preference, profile, goal}: continue if item[importance] 0.6: continue filtered.append(filtered(item)) return filtered注意这里有个很关键的设计LLM判断内容是否重要代码判断类型是否准入。哪怕LLM觉得用户下周去三亚很重要代码也会因为type不是持久类型而把它丢掉。只有规则和模型配合记忆质量才有保证。上面这个函数跑一遍我得到三条记忆用户不吃海鲜typepreferenceimportance0.9用户对花生过敏typeprofileimportance0.95用户倾向于慢节奏旅行typepreferenceimportance0.73.2 记忆存储向量索引与元数据过滤的配合提取出来的记忆不能直接往向量库里一丢了事。DeerFlow的做法是先定义统一的记忆数据结构再分别写进两类存储。我从源码梳理出来的MemoryItem结构大致如下dataclass class MemoryItem: memory_id: str # 全局唯一用于关联向量和元数据 content: str # 记忆内容比如用户不吃海鲜 memory_type: str # preference / profile / goal / event importance: float # 0.0 ~ 1.0 user_id: str # 硬隔离字段防止跨用户串记忆 source_session: str # 记忆来自哪次会话审计用 created_at: datetime updated_at: datetime access_count: int 0 # 召回次数用于热度衰减 metadata: dict field(default_factorydict)写入的时候分三步。第一步对content做embedding得到向量后存入向量库向量库里存的是(memory_id, vector)方便后续相似度检索。第二步把MemoryItem的全部结构化字段写入SQLite。第三步在元数据库里为user_id和memory_type建立索引。为什么明明有了向量库还要建结构化索引因为未来的召回请求通常是给userId123的用户找跟推荐餐厅相关的记忆如果不在元数据层先按userId过滤向量相似度检索会把所有用户的不吃海鲜都召回来后果就是张三的偏好跑进李四的回答里。3.3 第二轮对话记忆召回如何改变生成结果两小时后我重新开了一个会话输入只有一句帮我推荐三亚的餐厅。如果是个没有长期记忆的助手这句话就只是一句普通请求。但在DeerFlow里用户输入会先经过记忆召回模块。召回逻辑我用简化代码还原一下核心思路# 示意代码DeerFlow记忆召回与重排 async def recall_memories(user_id: str, query: str, top_k: int 5): # 1. 先用结构化条件硬过滤再做向量检索 candidates await memory_store.query( user_iduser_id, vectorembedding(query), top_k20 ) # 2. 加权重排语义相似度 重要度 时间衰减 scored [] for item in candidates: recency math.exp(-(now - item.updated_at).days / 30.0) score 0.5 * item.similarity 0.3 * item.importance 0.2 * recency scored.append((score, item)) scored.sort(keylambda x: x[0], reverseTrue) return [item for _, item in scored[:top_k]]这段代码有三个细节值得琢磨。一是硬过滤必须在向量检索之前或者至少在过滤条件里否则召回集里全是别的用户的记忆二是重排时importance占了30%权重这保证了花生过敏这种高重要度的记忆即使相似度不高也能被捞回来三是时间衰减用30天半衰期三个月前的一条低热度记忆会慢慢沉底这是模拟人的遗忘曲线。召回完成后这三条记忆被注入到生成提示词里我抓了一下实际的prompt结构[系统] 你是用户的旅行规划助手。以下是关于用户的长期记忆请优先参考 - 用户不吃海鲜 - 用户对花生过敏 - 用户倾向于慢节奏旅行 如果这些记忆与当前请求相关请自然地在回答中体现。 [用户] 帮我推荐三亚的餐厅。最终DeerFlow生成的推荐结果是椰子鸡火锅、文昌鸡、糟粕醋火锅并且主动标注这家糟粕醋火锅会用到虾酱可能含花生建议提前和店家确认。这个细节就是长期记忆的价值所在——它不仅仅是把历史文本塞回上下文而是真正改变了生成行为。3.4 从代码到链路把完整流程织成一张网上面三节分别讲了提取、存储、召回三个环节但实际运行时它们不是孤立的而是串在DeerFlow主链路里的。完整的运行时序是这样的用户输入到达后DeerFlow先启动记忆召回从当前用户的历史记忆里选出和本次请求相关的条目注入工作上下文接着执行规划-推理-执行-反思的深度推理循环期间工作记忆不断更新生成回复返回给用户后后台异步启动记忆固化对本轮对话做记忆提取把新记忆写入存储并更新旧记忆的访问时间和重要度。有一个很微妙的地方记忆固化的阈值比第一轮提取要严格。原因是第二轮这种推荐餐厅的对话里用户很可能说这家不错太贵了这类情绪化表达如果每个情绪都写成长期记忆系统很快就会被垃圾填满。所以DeerFlow的固化环节加了二次确认先由LLM提出候选记忆再由一个独立的评判模型确认这条信息在三个月后还有用吗确认有用才写入。这个双阶段设计是我觉得整个实现方案最值钱的部分。4. 关键的工程决策为什么记忆要这样设计4.1 记忆不是日志重要性评分和遗忘曲线不是可选项很多第一次接触长期记忆的开发者会把它跟存聊天记录混为一谈。这是最大的误区。聊天记录是原始日志量大、无结构、噪音多真正的长期记忆是提炼过的知识。DeerFlow引入重要性评分和时间衰减本质上是在模拟人脑的记忆机制不是所有经历都值得永远记住重要的事情反复强化不重要的慢慢遗忘。我在业务里观察到一个现象如果你把全部历史都塞给模型模型的注意力会被大量无关内容稀释反而记不住真正关键的信息。这就像把整个硬盘的文件都摆在桌面上你根本找不到想要的那份。重要性评分就是给记忆做桌面临近度管理只有评分足够高的记忆才有资格被摆到手边。DeerFlow里importance的计算是混合策略信号词规则打底出现过敏、永远、从不、工作、孩子这类词直接加分LLM语义打分校准访问频率动态修正三者加权得到最终评分。4.2 双路召回向量相似度和结构化条件缺一不可我在设计召回策略时对比过三种方案。只按向量相似度召回的问题在前面已经说过跨用户串记忆。只按结构化规则召回的问题是你没法用规则穷举用户的表达方式用户说别给我推荐腥味重的东西和我不吃海鲜语义相同但字面完全不同规则匹配不到。DeerFlow的做法是双路召回先用结构化条件把候选集缩小到当前用户 可能相关的记忆类型再用向量把语义相关的捞回来最后用加权公式重排。这个方案在实际运行中还有一个隐藏优点它大幅减少了无用embedding调用。结构化过滤先把候选从几万条筛到几十条向量检索只需要在这几十条里算相似度成本低了一个量级。生产环境里embedding接口的调用量直接决定成本和延迟这个设计帮我把每次请求的记忆召回延迟压到了200ms以内。4.3 记忆冲突与更新策略同一事实被推翻怎么办长期记忆一定会遇到冲突场景。比如旅行助手第一天记住用户不吃海鲜第三天用户说其实我只是不吃贝类鱼和虾还是吃的。如果简单粗暴地覆盖旧记忆不吃海鲜和对花生过敏这类衍生推断可能产生连锁错误。DeerFlow的处理思路是不直接覆盖而是把新记忆作为同一主题的新版本写入旧版本保留在历史表中在召回时如果发现同一主题存在多个版本会触发一次LLM判断由模型结合时间线决定采用哪条。这个设计的好处是保留了一条完整的记忆演化链。当用户质疑你怎么记得我不吃海鲜时系统能翻出最初的来源会话解释这是您7月12日说的。我个人非常推荐保留这条链它既是审计的需要也是排查记忆漂移的依据。代价是多一条LLM判断延迟对于低频的冲突场景完全可以接受。4.4 与深度推理的联动记忆如何参与Planner和ReflectorDeerFlow本身的卖点是深度推理长期记忆和推理不是两个独立模块而是互相协作。Planner在制定计划时召回的记忆作为约束条件直接影响规划路径——用户不吃海鲜会让行程规划自动减少海鲜餐厅、优先筛选标注无花生制品的酒店。Reflector在反思阶段也不会闲着它会把用户对这次推荐的反馈追加为新的记忆输入源。如果用户说这家太吵了Reflector会判断这是用户偏好安静环境的证据从而触发新一轮记忆写入。这个闭环正是DeerFlow和其他Agent框架拉开差距的地方。普通框架的记忆系统是问答时调一下历史记录DeerFlow的记忆系统是推理、执行、反思全部向记忆反馈。这也是标题里深度推理和长期记忆两个关键词能捏合在一起的原因。5. 实测中踩过的坑召回噪声、记忆漂移与性能5.1 记忆粒度太碎导致召回全是噪声我第一次把记忆提取接到业务里跑了三天发现召回质量越来越差。查了记忆库里面塞满了用户今天心情不错用户问了三亚的天气用户喜欢喝椰子水这种碎片化条目。问题出在提取环节没有做粒度控制一句对话里单独出现的短句往往没有持久价值真正有价值的记忆通常是多个信息点的组合。后来我加了一个预处理步骤对话先按语义片段切分每个片段至少包含一个完整意图然后才交给LLM提取。同时把importance阈值从0.6提高到0.7。效果立竿见影记忆库的噪音比例从接近40%降到了10%以内。顺便说一句这个噪音比例指标一定要埋点统计否则记忆库什么时候坏的你都不知道。5.2 多轮交叉后记忆漂移两轮对话的串味踩过的最深的一个坑是多用户记忆漂移。我在本地测试单用户没问题上了测试环境开了两个账号一起跑结果A账号的对话里开始出现B账号的记忆。排查了很久最终定位在召回链路向量检索时我只传了query向量没把user_id作为过滤条件传进去。向量库按相似度召回的20条候选里混入了其他用户的记忆重排之后如果某条跨用户记忆的importance特别高它就会被注入到A账号的prompt里。这个问题的修复也简单把user_id作为硬性过滤条件在查询语句里强制带上。但我想说的是排查过程这类漂移问题很难通过单轮测试发现因为它需要两个用户的数据同时在库里才能触发。我现在的习惯是每次上线前专门设计双用户交叉验证用例确保A的偏好永远不会出现在B的上下文里。5.3 Embedding调用量与延迟的平衡长期记忆模块最容易踩的性能坑是embedding调用失控。我第一版实现里每轮对话结束后的记忆提取会做两次embedding调用一次编码当前对话一次编码候选记忆再加上召回阶段的一次单次对话的embedding调用量是三次。虽然没有量级爆炸但架不住调用频率高延迟从200ms涨到了800ms成本也肉眼可见地增加。优化思路是给记忆固化加信号词触发器。对话中只有检测到强信号词我以后不喜欢过敏职业等时才触发记忆提取没有明确自我指涉信号的轮次直接跳过。这个规则把大约60%的无意义对话挡在了embedding调用之前整体延迟回到了300ms以内。另外一个细节是如果短期连续多轮对话都没有新记忆产生就合并到会话结束时统一做一次固化减少重复调用。5.4 长对话场景下短期记忆与长期记忆的衔接还有一个容易被忽略的坑长时间对话里用户早期说过的关键信息会被上下文窗口挤出。比如用户在第1轮说我对花生过敏第30轮还在继续聊天到第30轮时这句早期信息可能已经在上下文窗口的注意力范围之外了。DeerFlow的做法是定期把短期记忆压缩成摘要再固化到长期记忆。我建议对超过5轮或超过上下文窗口一半的对话就触发一次摘要固化把用户在第1轮提到花生过敏作为一条长期记忆条目而不是依赖原始上下文。这块还有个经验固定化的摘要和用户自己说的原文在召回时的置信度是不一样的。我在MemoryItem里加了一个source_type字段区分user_stated用户原话和inferred系统推断召回重排时给user_stated更高的权重。一句话别让系统的推断覆盖用户自己的表述。6. 从示例到生产多用户隔离、审计与记忆可观测6.1 租户隔离一个记忆库服务多个业务线示例里只有一个人一个助手但真实业务里往往是多个产品线共用一套DeerFlow底座。如果所有用户的记忆都混在一个向量集合里即便有user_id过滤也扛不住业务线之间的矛盾。我的做法是在MemoryItem里额外增加tenant_id字段向量集合按租户拆分每个租户一个collection元数据库里tenant_id和user_id做联合索引。租户拆分还能带来一个运维好处可以针对不同业务线设置不同的importance阈值和召回参数。比如医疗客服业务需要更高的召回严格度而闲聊机器人可以放宽阈值。隔离不是简单的数据分桶而是允许每一条业务线按自己的标准管理记忆质量。6.2 记忆审计与清洗给AI的记忆做体检长期记忆系统运行久了一定会积累一批过期、错误、低质量的记忆。我经历过最典型的case是用户年初说我打算去三亚过年这条goal类型的记忆在2月之后应该失效但系统一直保留着后续每次提到旅行相关话题都会把它召回干扰决策。DeerFlow的解决思路是把清洗做成一等公民定期对记忆做体检按最后访问时间、importance衰减、语义陈旧度三个维度打分低于阈值的记忆转移到冷存储或直接删除。审计也不可或缺。我要求每条记忆都能追溯到来源会话万一用户投诉系统记住的信息是错的运营人员可以顺藤摸瓜找到当时的对话记录。DeerFlow的schema里保留source_session字段配合trace系统能够完整回放这条记忆是怎么来的、什么时候被召回过、哪次生成用了它。没有审计的记忆系统就像一个没有异动记录的数据库出问题只能靠猜。6.3 可观测性从DeerFlow Trace看记忆召回命中情况最后说可观测性。DeerFlow自带trace链路我在接入长期记忆后把记忆召回事件也埋进了trace每个span里记录召回了多少条候选、重排后注入了几条、用户对回答的反馈如何。这样每次对话结束后我都能回答一个灵魂拷问这轮生成到底有没有用上长期记忆具体埋点我是这样做的召回开始时记一条memory_recall_start带上user_id和query召回完成后记memory_recall_end带上retrieved_count和injected_count如果生成的回答里引用了某条记忆再记一条memory_used事件带上memory_id。把这几个事件串起来就能在trace视图里看到一条完整的记忆血缘链路。如果你在基于DeerFlow做二次开发还有一个很实用的技巧把记忆召回事件通过SSE流式推给前端用户在界面上能看到我参考了你之前说的不吃海鲜这类提示。这个交互细节在C端产品里非常打动人。实际生产还有一个指标值得重点盯记忆命中率。我的定义是在用户明确使用你记得我说过……吗这类句式的会话里模型正确引用正确记忆的比例。这个指标比单纯的召回率更贴近真实体验也是我调优整个长期记忆系统的北极星。先把命中率拉到90%以上再去抠向量库参数才有意义。这次把DeerFlow的长期记忆从示例跑到生产我最深的体会是记忆系统的难点从来不在向量库和embedding而在提取什么、如何判级、召回后如何取舍。把这三个环节想清楚DeerFlow的深度推理才能真正在对话里发挥出越聊越懂你的威力。
字节跳动开源的DeerFlow我最开始是冲着深度推理四个字去研究的真正让我决定在业务里接入的反而是一直被当成附加功能的长期记忆模块。原因很实在一个聊完就忘的智能体无论推理链路设计得多精巧落到实际体验上都会露馅。上周我把一个旅行规划助手接到DeerFlow上用一条用户不吃海鲜的偏好把两轮对话之间的记忆链路完整跑了一遍。这篇文章就把这套实现方案从环境准备到生产扩展完整拆开讲清楚。1. 长期记忆不是聊天记录DeerFlow给记忆分了三层1.1 一个失忆助手的尴尬场景先还原一个大多数人都遇到过的场景。你上午告诉助手我对花生过敏点餐的时候帮我避开。下午你让它推荐下午茶它兴致勃勃推荐了花生酱吐司。这不是模型能力不行而是整个系统架构里缺了一条从经验到行为的回路——它根本不记得你上午说过什么。普通对话式AI的上下文窗口再大也只覆盖当前会话会话一关所有信息归零。DeerFlow把长期记忆作为一个独立模块做进框架里解决的就是这个问题让智能体在跨会话、跨任务的情况下仍然能调用之前积累的用户事实、偏好和历史决策。1.2 短期上下文、工作记忆与长期记忆的边界DeerFlow里的记忆并不是一个大一统的数据库而是分成三层职责完全不同。第一层是短期记忆本质就是大模型当前的上下文窗口存放本轮会话的原始消息、工具返回结果、当前任务状态它的特点是容量有限、用完即弃。第二层是工作记忆这是推理过程中产生的中间状态比如Planner当前的任务清单、Reasoner正在思考的推理步骤、Executor执行完工具后的临时输出。第三层才是长期记忆指跨会话持久化的稳定知识包括用户偏好、个人画像、历史事件、长期目标。做个厨房类比就很好理解短期记忆是操作台上正在处理的食材工作记忆是旁边备菜区排好的工序长期记忆则是冰箱和调料柜——今天没用上的食材只要放进冰箱明天还能拿出来。很多智能体框架只有操作台DeerFlow多给了你一个冰箱这才有了长期记忆的玩法。1.3 长期记忆模块挂在推理链路的哪个位置我查阅DeerFlow源码时特别关注了记忆模块在整个工作流里的挂载位置。一条完整的处理链路大致是这样用户输入进入系统后先触发记忆检索把和当前任务相关的历史记忆取出来拼进提示词上下文然后Planner基于记忆当前输入制定计划Reasoner深度推理Executor调用工具Reflector反思结果最后输出回复。但这还没完——在回复结束后还有一个异步的记忆固化环节从本轮对话中提取值得长期记住的新信息写入记忆存储。注意这个先检索、后固化的顺序它意味着长期记忆不是事后的日志存档而是参与生成决策的主动组件。这也是DeerFlow和普通RAG问答的本质区别RAG是查文档DeerFlow是查关于这个人的经验。理解了这个位置关系后面看代码就不会晕。2. 跑一个能记住事的DeerFlow环境准备与最小配置2.1 依赖清单与安装步骤我在一台干净的Ubuntu机器上部署Python版本要求3.10以上。DeerFlow本身用git clone拉下来然后通过uv或pip安装依赖。建议直接用uv因为DeerFlow的依赖链比较长uv的并行解析会快很多。安装完成后需要确认自己用的LLM后端支持工具调用和结构化输出DeerFlow默认对接的是兼容OpenAI接口的服务无论是大厂的API还是本地部署的模型只要兼容OpenAI协议就能跑。列一下我这次实际装的东西deerflow核心仓库拉master分支版本号在2.x以上记忆模块才比较完整向量数据库客户端本地方案我选了ChromaDB零配置跑通再换SQLite3Python内置做结构化元数据存储OpenAI兼容的LLM客户端库安装命令非常简单两行就能完成但真正的坑在后头不同版本的DeerFlow记忆模块的模块名和API命名会变。我第一次拉代码时参考的是老文档结果import路径直接报错。所以务必以你拉取版本仓库里的实际代码为准别信网上的过期教程。2.2 配置记忆存储后端向量库元数据库长期记忆要持久化必须同时配两类存储。类存储是结构化元数据库存记忆条目的属性字段比如用户ID、记忆类型、重要度、时间戳我用SQLite完全够用类是向量索引库存记忆内容的语义向量用于语义检索。为什么不能只用其中一个因为向量库不擅长精确过滤查userId123的所有记忆这种操作在向量库里效率很低而SQLite不擅长语义相似度。两者通过memory_id关联。我给DeerFlow写的存储配置大概是这样的memory: enabled: true backend: vector: chroma metadata: sqlite collection: deerflow_memories embedding_model: text-embedding-3-small retrieval: top_k_candidates: 20 top_k_inject: 5 score_threshold: 0.55这里的关键是separate的top_k_candidates和top_k_inject。召回时先取20条候选经过重排后只注入5条到上下文避免把提示词塞爆。score_threshold是相似度阈值低于0.55的记忆宁可不注入否则纯粹是噪声。2.3 最小验证先确认记忆模块真的在工作配完之后不要急着写业务代码先做一次最小验证。我用的是DeerFlow自带的一个example脚本开了两个会话第一个会话里告诉它我的名字叫陈默坐标杭州第二个会话里直接问我叫什么名字。如果第二个会话能答出陈默说明长期记忆链路已经通了存储和检索都工作正常。这一步跑通之后再去读核心示例代码心态完全不一样——你是在看一个已经验证过的系统而不是在一堆抽象概念里猜。3. 示例主线让旅行助手记住用户不吃海鲜3.1 第一轮对话记忆捕捉与写入我的示例场景是一个旅行规划助手。第一轮对话我输入的是帮我规划下周去三亚的行程。对了我不吃海鲜花生过敏节奏慢一点别搞得太赶。这句话里有两类信息。一类是临时任务信息目的地三亚、时间下周、要一份行程规划这些只对本轮任务有效另一类是长期偏好信息不吃海鲜、花生过敏、喜欢慢节奏这些跨会话持续有效。DeerFlow的长期记忆模块要做的第一件事就是区分这两类并只把后者写入持久化存储。这个区分不是简单规则能做到的DeerFlow的做法是让LLM来做初提取再用代码做硬校验。我梳理出的提取逻辑如下# 示意代码DeerFlow记忆提取与过滤 MEMORY_EXTRACTION_PROMPT 你是长期记忆提取器。 从对话中提取值得跨会话记住的信息只提取这些类型 - 用户的稳定偏好喜欢/不喜欢/习惯 - 用户的个人信息职业、所在地、过敏史等 - 用户的长期目标 忽略临时任务、一次性指令和纯闲聊。 对每条候选记忆给出重要度评分0到1并说明理由。 以JSON数组返回[{content: ..., type: ..., importance: 0.9, reason: ...}] async def extract_memories(conversation: list[dict], llm): # 1. 让LLM产出候选记忆 raw await llm.complete(MEMORY_EXTRACTION_PROMPT.format( conversationjson.dumps(conversation, ensure_asciiFalse) )) candidates json.loads(raw) # 2. 代码层硬过滤临时信息一律丢弃 filtered [] for item in candidates: if item[type] not in {preference, profile, goal}: continue if item[importance] 0.6: continue filtered.append(filtered(item)) return filtered注意这里有个很关键的设计LLM判断内容是否重要代码判断类型是否准入。哪怕LLM觉得用户下周去三亚很重要代码也会因为type不是持久类型而把它丢掉。只有规则和模型配合记忆质量才有保证。上面这个函数跑一遍我得到三条记忆用户不吃海鲜typepreferenceimportance0.9用户对花生过敏typeprofileimportance0.95用户倾向于慢节奏旅行typepreferenceimportance0.73.2 记忆存储向量索引与元数据过滤的配合提取出来的记忆不能直接往向量库里一丢了事。DeerFlow的做法是先定义统一的记忆数据结构再分别写进两类存储。我从源码梳理出来的MemoryItem结构大致如下dataclass class MemoryItem: memory_id: str # 全局唯一用于关联向量和元数据 content: str # 记忆内容比如用户不吃海鲜 memory_type: str # preference / profile / goal / event importance: float # 0.0 ~ 1.0 user_id: str # 硬隔离字段防止跨用户串记忆 source_session: str # 记忆来自哪次会话审计用 created_at: datetime updated_at: datetime access_count: int 0 # 召回次数用于热度衰减 metadata: dict field(default_factorydict)写入的时候分三步。第一步对content做embedding得到向量后存入向量库向量库里存的是(memory_id, vector)方便后续相似度检索。第二步把MemoryItem的全部结构化字段写入SQLite。第三步在元数据库里为user_id和memory_type建立索引。为什么明明有了向量库还要建结构化索引因为未来的召回请求通常是给userId123的用户找跟推荐餐厅相关的记忆如果不在元数据层先按userId过滤向量相似度检索会把所有用户的不吃海鲜都召回来后果就是张三的偏好跑进李四的回答里。3.3 第二轮对话记忆召回如何改变生成结果两小时后我重新开了一个会话输入只有一句帮我推荐三亚的餐厅。如果是个没有长期记忆的助手这句话就只是一句普通请求。但在DeerFlow里用户输入会先经过记忆召回模块。召回逻辑我用简化代码还原一下核心思路# 示意代码DeerFlow记忆召回与重排 async def recall_memories(user_id: str, query: str, top_k: int 5): # 1. 先用结构化条件硬过滤再做向量检索 candidates await memory_store.query( user_iduser_id, vectorembedding(query), top_k20 ) # 2. 加权重排语义相似度 重要度 时间衰减 scored [] for item in candidates: recency math.exp(-(now - item.updated_at).days / 30.0) score 0.5 * item.similarity 0.3 * item.importance 0.2 * recency scored.append((score, item)) scored.sort(keylambda x: x[0], reverseTrue) return [item for _, item in scored[:top_k]]这段代码有三个细节值得琢磨。一是硬过滤必须在向量检索之前或者至少在过滤条件里否则召回集里全是别的用户的记忆二是重排时importance占了30%权重这保证了花生过敏这种高重要度的记忆即使相似度不高也能被捞回来三是时间衰减用30天半衰期三个月前的一条低热度记忆会慢慢沉底这是模拟人的遗忘曲线。召回完成后这三条记忆被注入到生成提示词里我抓了一下实际的prompt结构[系统] 你是用户的旅行规划助手。以下是关于用户的长期记忆请优先参考 - 用户不吃海鲜 - 用户对花生过敏 - 用户倾向于慢节奏旅行 如果这些记忆与当前请求相关请自然地在回答中体现。 [用户] 帮我推荐三亚的餐厅。最终DeerFlow生成的推荐结果是椰子鸡火锅、文昌鸡、糟粕醋火锅并且主动标注这家糟粕醋火锅会用到虾酱可能含花生建议提前和店家确认。这个细节就是长期记忆的价值所在——它不仅仅是把历史文本塞回上下文而是真正改变了生成行为。3.4 从代码到链路把完整流程织成一张网上面三节分别讲了提取、存储、召回三个环节但实际运行时它们不是孤立的而是串在DeerFlow主链路里的。完整的运行时序是这样的用户输入到达后DeerFlow先启动记忆召回从当前用户的历史记忆里选出和本次请求相关的条目注入工作上下文接着执行规划-推理-执行-反思的深度推理循环期间工作记忆不断更新生成回复返回给用户后后台异步启动记忆固化对本轮对话做记忆提取把新记忆写入存储并更新旧记忆的访问时间和重要度。有一个很微妙的地方记忆固化的阈值比第一轮提取要严格。原因是第二轮这种推荐餐厅的对话里用户很可能说这家不错太贵了这类情绪化表达如果每个情绪都写成长期记忆系统很快就会被垃圾填满。所以DeerFlow的固化环节加了二次确认先由LLM提出候选记忆再由一个独立的评判模型确认这条信息在三个月后还有用吗确认有用才写入。这个双阶段设计是我觉得整个实现方案最值钱的部分。4. 关键的工程决策为什么记忆要这样设计4.1 记忆不是日志重要性评分和遗忘曲线不是可选项很多第一次接触长期记忆的开发者会把它跟存聊天记录混为一谈。这是最大的误区。聊天记录是原始日志量大、无结构、噪音多真正的长期记忆是提炼过的知识。DeerFlow引入重要性评分和时间衰减本质上是在模拟人脑的记忆机制不是所有经历都值得永远记住重要的事情反复强化不重要的慢慢遗忘。我在业务里观察到一个现象如果你把全部历史都塞给模型模型的注意力会被大量无关内容稀释反而记不住真正关键的信息。这就像把整个硬盘的文件都摆在桌面上你根本找不到想要的那份。重要性评分就是给记忆做桌面临近度管理只有评分足够高的记忆才有资格被摆到手边。DeerFlow里importance的计算是混合策略信号词规则打底出现过敏、永远、从不、工作、孩子这类词直接加分LLM语义打分校准访问频率动态修正三者加权得到最终评分。4.2 双路召回向量相似度和结构化条件缺一不可我在设计召回策略时对比过三种方案。只按向量相似度召回的问题在前面已经说过跨用户串记忆。只按结构化规则召回的问题是你没法用规则穷举用户的表达方式用户说别给我推荐腥味重的东西和我不吃海鲜语义相同但字面完全不同规则匹配不到。DeerFlow的做法是双路召回先用结构化条件把候选集缩小到当前用户 可能相关的记忆类型再用向量把语义相关的捞回来最后用加权公式重排。这个方案在实际运行中还有一个隐藏优点它大幅减少了无用embedding调用。结构化过滤先把候选从几万条筛到几十条向量检索只需要在这几十条里算相似度成本低了一个量级。生产环境里embedding接口的调用量直接决定成本和延迟这个设计帮我把每次请求的记忆召回延迟压到了200ms以内。4.3 记忆冲突与更新策略同一事实被推翻怎么办长期记忆一定会遇到冲突场景。比如旅行助手第一天记住用户不吃海鲜第三天用户说其实我只是不吃贝类鱼和虾还是吃的。如果简单粗暴地覆盖旧记忆不吃海鲜和对花生过敏这类衍生推断可能产生连锁错误。DeerFlow的处理思路是不直接覆盖而是把新记忆作为同一主题的新版本写入旧版本保留在历史表中在召回时如果发现同一主题存在多个版本会触发一次LLM判断由模型结合时间线决定采用哪条。这个设计的好处是保留了一条完整的记忆演化链。当用户质疑你怎么记得我不吃海鲜时系统能翻出最初的来源会话解释这是您7月12日说的。我个人非常推荐保留这条链它既是审计的需要也是排查记忆漂移的依据。代价是多一条LLM判断延迟对于低频的冲突场景完全可以接受。4.4 与深度推理的联动记忆如何参与Planner和ReflectorDeerFlow本身的卖点是深度推理长期记忆和推理不是两个独立模块而是互相协作。Planner在制定计划时召回的记忆作为约束条件直接影响规划路径——用户不吃海鲜会让行程规划自动减少海鲜餐厅、优先筛选标注无花生制品的酒店。Reflector在反思阶段也不会闲着它会把用户对这次推荐的反馈追加为新的记忆输入源。如果用户说这家太吵了Reflector会判断这是用户偏好安静环境的证据从而触发新一轮记忆写入。这个闭环正是DeerFlow和其他Agent框架拉开差距的地方。普通框架的记忆系统是问答时调一下历史记录DeerFlow的记忆系统是推理、执行、反思全部向记忆反馈。这也是标题里深度推理和长期记忆两个关键词能捏合在一起的原因。5. 实测中踩过的坑召回噪声、记忆漂移与性能5.1 记忆粒度太碎导致召回全是噪声我第一次把记忆提取接到业务里跑了三天发现召回质量越来越差。查了记忆库里面塞满了用户今天心情不错用户问了三亚的天气用户喜欢喝椰子水这种碎片化条目。问题出在提取环节没有做粒度控制一句对话里单独出现的短句往往没有持久价值真正有价值的记忆通常是多个信息点的组合。后来我加了一个预处理步骤对话先按语义片段切分每个片段至少包含一个完整意图然后才交给LLM提取。同时把importance阈值从0.6提高到0.7。效果立竿见影记忆库的噪音比例从接近40%降到了10%以内。顺便说一句这个噪音比例指标一定要埋点统计否则记忆库什么时候坏的你都不知道。5.2 多轮交叉后记忆漂移两轮对话的串味踩过的最深的一个坑是多用户记忆漂移。我在本地测试单用户没问题上了测试环境开了两个账号一起跑结果A账号的对话里开始出现B账号的记忆。排查了很久最终定位在召回链路向量检索时我只传了query向量没把user_id作为过滤条件传进去。向量库按相似度召回的20条候选里混入了其他用户的记忆重排之后如果某条跨用户记忆的importance特别高它就会被注入到A账号的prompt里。这个问题的修复也简单把user_id作为硬性过滤条件在查询语句里强制带上。但我想说的是排查过程这类漂移问题很难通过单轮测试发现因为它需要两个用户的数据同时在库里才能触发。我现在的习惯是每次上线前专门设计双用户交叉验证用例确保A的偏好永远不会出现在B的上下文里。5.3 Embedding调用量与延迟的平衡长期记忆模块最容易踩的性能坑是embedding调用失控。我第一版实现里每轮对话结束后的记忆提取会做两次embedding调用一次编码当前对话一次编码候选记忆再加上召回阶段的一次单次对话的embedding调用量是三次。虽然没有量级爆炸但架不住调用频率高延迟从200ms涨到了800ms成本也肉眼可见地增加。优化思路是给记忆固化加信号词触发器。对话中只有检测到强信号词我以后不喜欢过敏职业等时才触发记忆提取没有明确自我指涉信号的轮次直接跳过。这个规则把大约60%的无意义对话挡在了embedding调用之前整体延迟回到了300ms以内。另外一个细节是如果短期连续多轮对话都没有新记忆产生就合并到会话结束时统一做一次固化减少重复调用。5.4 长对话场景下短期记忆与长期记忆的衔接还有一个容易被忽略的坑长时间对话里用户早期说过的关键信息会被上下文窗口挤出。比如用户在第1轮说我对花生过敏第30轮还在继续聊天到第30轮时这句早期信息可能已经在上下文窗口的注意力范围之外了。DeerFlow的做法是定期把短期记忆压缩成摘要再固化到长期记忆。我建议对超过5轮或超过上下文窗口一半的对话就触发一次摘要固化把用户在第1轮提到花生过敏作为一条长期记忆条目而不是依赖原始上下文。这块还有个经验固定化的摘要和用户自己说的原文在召回时的置信度是不一样的。我在MemoryItem里加了一个source_type字段区分user_stated用户原话和inferred系统推断召回重排时给user_stated更高的权重。一句话别让系统的推断覆盖用户自己的表述。6. 从示例到生产多用户隔离、审计与记忆可观测6.1 租户隔离一个记忆库服务多个业务线示例里只有一个人一个助手但真实业务里往往是多个产品线共用一套DeerFlow底座。如果所有用户的记忆都混在一个向量集合里即便有user_id过滤也扛不住业务线之间的矛盾。我的做法是在MemoryItem里额外增加tenant_id字段向量集合按租户拆分每个租户一个collection元数据库里tenant_id和user_id做联合索引。租户拆分还能带来一个运维好处可以针对不同业务线设置不同的importance阈值和召回参数。比如医疗客服业务需要更高的召回严格度而闲聊机器人可以放宽阈值。隔离不是简单的数据分桶而是允许每一条业务线按自己的标准管理记忆质量。6.2 记忆审计与清洗给AI的记忆做体检长期记忆系统运行久了一定会积累一批过期、错误、低质量的记忆。我经历过最典型的case是用户年初说我打算去三亚过年这条goal类型的记忆在2月之后应该失效但系统一直保留着后续每次提到旅行相关话题都会把它召回干扰决策。DeerFlow的解决思路是把清洗做成一等公民定期对记忆做体检按最后访问时间、importance衰减、语义陈旧度三个维度打分低于阈值的记忆转移到冷存储或直接删除。审计也不可或缺。我要求每条记忆都能追溯到来源会话万一用户投诉系统记住的信息是错的运营人员可以顺藤摸瓜找到当时的对话记录。DeerFlow的schema里保留source_session字段配合trace系统能够完整回放这条记忆是怎么来的、什么时候被召回过、哪次生成用了它。没有审计的记忆系统就像一个没有异动记录的数据库出问题只能靠猜。6.3 可观测性从DeerFlow Trace看记忆召回命中情况最后说可观测性。DeerFlow自带trace链路我在接入长期记忆后把记忆召回事件也埋进了trace每个span里记录召回了多少条候选、重排后注入了几条、用户对回答的反馈如何。这样每次对话结束后我都能回答一个灵魂拷问这轮生成到底有没有用上长期记忆具体埋点我是这样做的召回开始时记一条memory_recall_start带上user_id和query召回完成后记memory_recall_end带上retrieved_count和injected_count如果生成的回答里引用了某条记忆再记一条memory_used事件带上memory_id。把这几个事件串起来就能在trace视图里看到一条完整的记忆血缘链路。如果你在基于DeerFlow做二次开发还有一个很实用的技巧把记忆召回事件通过SSE流式推给前端用户在界面上能看到我参考了你之前说的不吃海鲜这类提示。这个交互细节在C端产品里非常打动人。实际生产还有一个指标值得重点盯记忆命中率。我的定义是在用户明确使用你记得我说过……吗这类句式的会话里模型正确引用正确记忆的比例。这个指标比单纯的召回率更贴近真实体验也是我调优整个长期记忆系统的北极星。先把命中率拉到90%以上再去抠向量库参数才有意义。这次把DeerFlow的长期记忆从示例跑到生产我最深的体会是记忆系统的难点从来不在向量库和embedding而在提取什么、如何判级、召回后如何取舍。把这三个环节想清楚DeerFlow的深度推理才能真正在对话里发挥出越聊越懂你的威力。
