DeerFlow2.0 框架架构07：三级记忆架构

原创于 2026-08-19 16:33:46 发布 · 374 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Architect

Agent

三级记忆架构：分层解耦 + 事件驱动 + Token 预算感知的记忆体系

系列第 7 篇 / 共 7 篇。上一篇拆解了断点续跑的状态管理机制，本文深入 DeerFlow 的记忆体系——如何让 Agent 从"一次对话一次失忆"升级为"可沉淀、可检索、可修正"的结构化状态管理。

一、为什么大多数 Agent 的记忆"没设计好"

大多数 AI Agent 框架的记忆方案极其粗放——直接把对话历史拼接成字符串塞进 Prompt，然后就指望模型自己"记住"用户是谁、偏好什么、关注什么。

这不是记忆，是临时缓存。

问题在于：一次对话结束后，全部遗忘。下次用户来，Agent 又问一遍"你是谁、做什么的、用什么技术栈"——这种体验在企业级场景里是不可接受的。更糟的是，即使在同一会话中，长对话的上下文窗口也会溢出，早期关键信息被后期闲聊挤出窗口。

DeerFlow 没有走传统"短期记忆 + 长期记忆"的老路。它直接搭了一套三级结构化记忆体系，核心数据结构如下：

def _create_empty_memory() -> dict[str, Any]:
    return {
        "version": "1.0",
        "lastUpdated": datetime.utcnow().isoformat() + "Z",
        "user": {
            "workContext": {"summary": "", "updatedAt": ""},
            "personalContext": {"summary": "", "updatedAt": ""},
            "topOfMind": {"summary": "", "updatedAt": ""},
        },
        "history": {
            "recentMonths": {"summary": "", "updatedAt": ""},
            "earlierContext": {"summary": "", "updatedAt": ""},
            "longTermBackground": {"summary": "", "updatedAt": ""},
        },
        "facts": [],
    }

二、三层记忆结构：从"知道是谁"到"记住一切"

2.1 三层总览

层级	类型	更新频率	生命周期	核心作用
user	短期/活跃记忆	每次对话	小时/天	实时反映当下状态，支撑即时响应
history	中期/长期记忆	按月/季度	月/年	沉淀过往行为轨迹，提炼行为规律
facts	结构化长期记忆	低频	永久/半永久	固化离散知识点，供快速检索调用

这三层就像认识一个人：先知道他是谁（user），再了解他做过什么（history），最后记住关键信息（facts）。层层递进，形成完整认知。

2.2 第一层：用户上下文（user）

搞清楚"用户是谁"——Agent 的"实时通知栏"，只显示最新状态。

三个子字段：

workContext（工作背景）：1-2 句话，职业角色、公司、核心项目、技术栈。如"字节跳动高级工程师，主导 DeerFlow 框架开发，技术栈以 Python + LangChain + FastAPI 为核心"
personalContext（个人偏好）：1-2 句话，语言能力、沟通偏好。如"偏好简洁直接的技术沟通风格，不喜欢冗余表述"
topOfMind（当前关注）：3-5 句话，更新频率最高。用户近期在准备项目发布？优化调度策略？这些信息实时更新，Agent 能主动关联

2.3 第二层：历史分层（history）

记录"用户做过什么"——沉淀行为轨迹。

三个时间段，越往前越概括：

recentMonths（近 1-3 月）：4-6 句话，重点突出核心动作和成果
earlierContext（3-12 月前）：3-5 句话，提炼行为规律，非罗列琐事
longTermBackground（长期不变背景）：2-4 句话，从业经验、核心能力

2.4 第三层：事实列表（facts）

存"离散可检索的结构化知识点"——Agent 的"知识库"。

每条 fact 是独立的碎片化知识点，自带 category 字段：

类别	含义	示例
`preference`	用户偏好	“偏好使用 Vim 而非 VS Code”
`knowledge`	专业知识	“精通 Rust 和 WebAssembly”
`context`	背景事实	“在字节跳动担任高级工程师”
`behavior`	行为模式	“习惯先写测试再写实现”
`goal`	目标意图	“计划在 Q2 发布 v2.0”

每条 fact 的结构化定义：

fact_entry = {
    "id": f"fact_{uuid.uuid4().hex[:8]}",
    "content": fact.get("content", ""),
    "category": fact.get("category", "context"),
    "confidence": confidence,
    "createdAt": now,
    "source": thread_id or "unknown",
}

confidence 字段是精华——不是所有 LLM 提取的记忆都可靠。低置信度的 fact 在注入时会被后置或过滤。

三、关键辨析：user 层为什么不是长期记忆

很多人误以为 user 字段属于长期记忆，因为它和 history、facts 一起存在 memory.json 里。但从源码设计和行为模式来看，有本质区别：

长期记忆（history + facts）的核心是"沉淀、固化、不频繁修改"——history 的 longTermBackground 可能几个月才更新一次
用户当前状态（user）的核心是"动态、临时、随时覆盖"——每轮对话都可能更新，旧状态直接被新状态覆盖，不保留历史版本

旧状态去哪了？自动沉淀到 history 的 recentMonths 字段。 这是一个精妙的流转机制：user 层的旧快照不会凭空消失，而是作为"历史行为轨迹"的一部分进入 history 层，形成从短期到长期的平滑过渡。

四、四大核心模块的协同闭环

DeerFlow 记忆模块采用"分层解耦 + 异步协同"的整体架构：

4.1 MemoryMiddleware：事件驱动的入口

MemoryMiddleware 是 DeerFlow 14 层中间件链中的第 9 层。它不是每次对话都触发记忆更新，而是在对话生命周期的"后置处理阶段"提取消息、检测关键信号、入队到 MemoryUpdateQueue。

4.2 消息预处理层：记忆准确性的第一道防线

两个核心功能：

对话清洗：仅保留用户输入（human）和最终助手回复（ai，无工具调用），过滤中间工具调用和临时调试信息。自动剥离 uploaded_files 标签——文件上传是会话临时操作，不适合进入长期记忆。

关键信号检测：自动检测用户纠正和正向反馈信号。检测到纠正时优先更新错误记忆，检测到正向反馈时强化相关记忆置信度——这是"记忆自我优化"的关键。

4.3 防抖队列：异步批量处理的核心

这是工程化落地的关键优化。经过过滤的对话消息不会立即触发 LLM 更新——如果每次对话都触发一次 LLM 调用来更新记忆，10 个用户各聊 10 轮，直接 100 次 LLM 调用，烧穿预算。

MemoryUpdateQueue 将分散的记忆更新请求聚合，防抖窗口到期后批量触发。既减少 LLM 调用次数，又保证了记忆更新的时效性。

4.4 记忆更新引擎：7 步标准化管道

MemoryUpdater.update_memory 方法是一条标准化的生产线：

其中 format_conversation_for_update 做了超长消息截断（>1000 字符截断），避免 Prompt 过长导致 LLM 调用失败：

def format_conversation_for_update(messages: list[Any]) -> str:
    lines = []
    for msg in messages:
        role = getattr(msg, "type", "unknown")
        content = getattr(msg, "content", str(msg))
        if len(str(content)) > 1000:
            content = str(content)[:1000] + "..."
        if role == "human":
            lines.append(f"User: {content}")
        elif role == "ai":
            lines.append(f"Assistant: {content}")
    return "\n\n".join(lines)