refactor(memory): Memory V2 P3 - 舍弃后台抽取 + Gateway 端点收口

P3 在 P1/P2 基础上完成 Memory V2 收尾:

舍弃后台抽取:
- 删除 updater/queue/storage/prompt/summarization_hook 五个模块
- 移除 background_extraction 配置段、扁平字段兼容、storage 字段
- 理由:Hindsight auto_retain 已自动留存每轮对话,后台抽取冗余

Hindsight 召回注入改用 wrap_model_call:
- 由 before_model 改为 wrap_model_call —— 召回只注入单次模型请求、
  不落持久 state,从根上消除 <memory-context> 泄漏给前端的风险
- builtin frozen snapshot 仍走系统提示词

Gateway 端点收口为 /api/memory/v2*:
- 删除旧 facts/history 端点 (/api/memory、/memory/facts 等)
- 新增 entries 增删改 (POST/PUT/DELETE /memory/v2/entries)
- 新增 POST /memory/v2/search —— Hindsight recall/reflect 检索代理
- client.py memory 方法重写为 V2 等价方法

文档同步更新 CLAUDE.md 与 MEMORY_V2_DESIGN_ZH.md。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
xuhdandClaude Opus 4.7 committed 2026-05-15 13:08:18 +08:00
1 parent f9d7610679
commit 21a76f5e7c
14 files changed
+954 -3085

No files matched your search

@@ -1,18 +1,44 @@
# Memory V2 设计文档(Hermes 兼容 + Hindsight 集成)
> **状态**: Draft v1 · 待 review
> **状态**: 已实施 (P1/P2/P3 完成)
> **作者**: xuhd
> **日期**: 2026-05-15
> **目标版本**: DeerFlow 内部 1.x
本设计文档描述以 Hermes Agent 的记忆架构为骨架,重写 DeerFlow 的 memory 子系统的方案。重写后:
- **保留** DeerFlow 当前的"后台 LLM 抽取 facts"能力(可选,默认关闭)。
- **引入** Hermes 的 `MemoryProvider` 可插拔抽象 + `MemoryManager` 编排层 + LLM 主动调 `memory` 工具的能力。
- **新增** Hindsight Docker 实例作为唯一支持的外部 provider(语义检索 + 知识图谱)。
- **统一** USER / MEMORY 二元分类,并按 user / agent 维度做双 bank 隔离。
---
## 0. 实施变更记录(与下文原计划的偏差)
下文 §1~§18 是规划阶段的原始设计。实施过程中有以下偏差,**以本节为准**:
1. **后台抽取已舍弃**(原计划保留为可选)。`updater.py` / `queue.py` /
`storage.py` / `prompt.py` / `summarization_hook.py` 全部删除,`background_extraction`
配置段移除。理由:Hindsight 的 `auto_retain` 已把每轮对话自动存入 work bank,
"不漏记"场景完全覆盖,后台抽取冗余且白费 token。下文 §6 的"后台抽取"路径、
§9 的 `background_extraction` 配置、§16 P3 的后台抽取重接入均作废。
2. **Hindsight 动态召回走 `wrap_model_call` 而非 `before_model`**(原计划见 Appendix B.1)。
`wrap_model_call` 把召回内容只注入到单次模型请求、不落持久 state —— 因此不会泄漏
给前端、也不会在历史里堆积。builtin 的 frozen snapshot 仍走系统提示词
(`_get_memory_context`)。
3. **streaming scrubber 未实现**(原计划见 §12.3)。`wrap_model_call` 的瞬态注入已从
结构上消除 `<memory-context>` 泄漏,scrubber 无必要。
4. **Gateway 端点最终形态**:全部用 `/api/memory/v2*` 前缀,旧 facts/history 端点
(`/api/memory`、`/memory/facts` 等) 已删除。端点见 §11 修订 + 新增
`POST /api/memory/v2/search`(Hindsight recall/reflect 代理)。
5. **`client.py` memory 方法**重写为 V2 等价方法(`get_memory` / `add_memory_entry` /
`replace_memory_entry` / `remove_memory_entry` / `get_memory_config` / `search_memory`)。
---
## 1. 设计目标
### 1.1 业务目标