Deer-Flow 的长期记忆系统

Deer-Flow 的长期记忆系统

学习目标

• 理解 Deer-Flow 记忆系统的三个层次（用户上下文、历史摘要、离散事实）
• 掌握 LLM 驱动的事实提取和防重队列
• 学会分析每用户隔离的存储布局

前置知识

本章涉及长期记忆的通用原理，建议先阅读：

• 长期记忆系统：跨会话的持久化上下文

下文假设你已理解上述概念，直接聚焦 Deer-Flow 的具体实现。

---

项目实践

记忆层次

Deer-Flow 的记忆分为三个层次：

层次	字段	说明
用户上下文	workContext, personalContext, topOfMind	1-3 句话的用户当前状态
历史摘要	recentMonths, earlierContext, longTermBackground	按时间窗口组织的交互摘要
离散事实	facts[] — id, content, category, confidence	独立的事实条目

记忆更新流程

关键设计

防重队列（Debounce Queue）

• 入队时捕获 user_id（通过 get_effective_user_id()），确保 threading.Timer 边界后仍能使用
• 同一线程的多次更新去重合并
• 默认 30 秒 debounce，避免频繁 LLM 调用

事实去重

• 提取前对事实内容 trim 首尾空白
• 比较已存储事实的 content 字段，相同内容跳过
• 置信度低于阈值（0.7）的事实不存储

每用户隔离

backend/.deer-flow/users/{user_id}/
├── memory.json                    # 通用记忆
├── threads/{thread_id}/           # 线程数据
└── agents/{agent_name}/
    ├── memory.json                # per-agent 记忆
    ├── SOUL.md                    # Agent 人格定义
    └── config.yaml                # Agent 配置

• 通过 get_effective_user_id() 解析用户身份（无认证模式默认 "default"）
• 绝对 storage_path 配置可退出 per-user 隔离
• 支持从旧版共享布局迁移：scripts/migrate_user_isolation.py

记忆注入

下次交互时，系统将 Top 15 相关事实 + 用户上下文注入到系统提示的 <memory> 标签中。最大注入 Token 数限制为 2000。

---

问题与规避

记忆膨胀

事实不断积累，memory.json 变得过大。

Deer-Flow 的规避：

• max_facts: 100 — 最大事实数量
• fact_confidence_threshold: 0.7 — 低置信度事实不存储
• 重复内容在 apply 时跳过，避免无意义积累

过时信息

用户偏好变化后旧记忆仍然注入。

Deer-Flow 的规避：事实附带 confidence 和时间戳，同类别新事实可覆盖旧事实。

---

参考来源

• Deer-Flow CLAUDE.md — Memory System 章节
• packages/harness/deerflow/agents/memory/ — 记忆系统源码