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

@@ -2,31 +2,32 @@
本中间件负责两件事:
1. **before_model** —— Hindsight 动态召回注入。
1. **wrap_model_call** —— Hindsight 动态召回注入。
每次 LLM 调用前,用最近一条用户消息作为 query 召回 Hindsight 记忆,
注入成一条带 ``<memory-context>`` 标签的消息。仅在 ``provider="hindsight"``
且配置允许时生效;builtin 的 frozen snapshot 走系统提示词,不在这里。
作为一条带 ``<memory-context>`` 标签的消息**临时**追加到本次模型请求里。
关键:用 ``wrap_model_call`` 而非 ``before_model`` —— 注入只作用于这一次
模型调用,不写入持久 state,因此不会泄漏给前端、也不会在历史里堆积。
仅在 ``provider="hindsight"`` 且配置允许时生效;builtin 的 frozen
snapshot 走系统提示词,不在这里。
2. **after_agent** —— Hindsight 自动 retain + 后台抽取排队。
- Hindsight ``auto_retain`` 开启时,把本轮对话写入工作 bank。
- 后台抽取 (``background_extraction.enabled``,默认关) 开启时,把对话
排队给后台 LLM 抽取。
2. **after_agent** —— Hindsight 自动 retain。
Hindsight ``auto_retain`` 开启时,把本轮对话写入工作 bank。
LLM 主动写入走 ``memory`` / ``hindsight_*`` 工具,不经过本中间件。
"""
import asyncio
import logging
from typing import TYPE_CHECKING, Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.config import get_config
from langgraph.runtime import Runtime
from deerflow.agents.memory.manager import build_memory_manager
from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
from deerflow.agents.memory.queue import get_memory_queue
from deerflow.agents.memory.message_processing import filter_messages_for_memory
from deerflow.config.memory_config import get_effective_memory_config, get_memory_config
from deerflow.runtime.user_context import get_effective_user_id
@@ -35,9 +36,6 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
#: 注入的 Hindsight 召回消息的固定 id —— 每轮先删旧的再加新的,保证只有一条且总在末尾。
_RECALL_MESSAGE_ID = "deerflow-memory-recall"
def _coerce_text(content: Any) -> str:
"""把消息 content (可能是 str 或多模态 block 列表) 压成纯文本。"""
@@ -57,7 +55,7 @@ def _coerce_text(content: Any) -> str:
def _latest_human_text(messages: list) -> str:
"""返回最近一条用户消息的纯文本。"""
for msg in reversed(messages):
if isinstance(msg, HumanMessage) and getattr(msg, "id", None) != _RECALL_MESSAGE_ID:
if isinstance(msg, HumanMessage):
return _coerce_text(msg.content).strip()
return ""
@@ -83,12 +81,11 @@ class MemoryMiddlewareState(AgentState):
class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
"""记忆中间件:before_model 注入 Hindsight 召回,after_agent 写入与排队。
"""记忆中间件:wrap_model_call 注入 Hindsight 召回,after_agent 自动 retain。
Memory V2 说明:
- builtin 本地记忆的 frozen snapshot 走系统提示词 (``_get_memory_context``)。
- Hindsight 动态召回走本中间件 ``before_model``。
- 后台抽取默认关闭。
- Hindsight 动态召回走本中间件 ``wrap_model_call`` —— 临时注入,不落 state。
"""
state_schema = MemoryMiddlewareState
@@ -106,9 +103,11 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
# ---- 运行时上下文解析 -------------------------------------------------
def _resolve_thread_id(self, runtime: Runtime) -> str | None:
def _resolve_thread_id(self, runtime: Runtime | None) -> str | None:
"""从 runtime context 取 thread_id,回退到 LangGraph configurable。"""
thread_id = runtime.context.get("thread_id") if runtime.context else None
thread_id = None
if runtime is not None and getattr(runtime, "context", None):
thread_id = runtime.context.get("thread_id")
if thread_id:
return thread_id
try:
@@ -116,18 +115,24 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
except RuntimeError:
return None
def _resolve_agent_id(self, runtime: Runtime) -> str:
def _resolve_agent_id(self, runtime: Runtime | None) -> str:
"""解析 agent_id;优先 middleware 构造时的 agent_name,再 runtime context。"""
if self._agent_name:
return self._agent_name
agent_id = runtime.context.get("agent_id") if runtime.context else None
return str(agent_id) if agent_id else "default"
if runtime is not None and getattr(runtime, "context", None):
agent_id = runtime.context.get("agent_id")
if agent_id:
return str(agent_id)
return "default"
# ---- before_model:Hindsight 动态召回注入 ----------------------------
# ---- wrap_model_call:Hindsight 动态召回注入 -------------------------
@override
def before_model(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""LLM 调用前,把 Hindsight 召回结果注入成一条记忆上下文消息。"""
def _build_recall_message(self, request: Any) -> HumanMessage | None:
"""按本次模型请求构建一条 Hindsight 召回消息;无召回内容时返回 None。
召回结果包在 ``<memory-context>`` 标签里并带系统提示,告诉模型这是
背景信息而非用户的新输入。
"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
@@ -136,17 +141,16 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
effective_config = get_effective_memory_config(user_id)
if not effective_config.enabled or not effective_config.injection.enabled:
return None
# 只有 Hindsight 提供动态召回;builtin 走系统提示词,无需在此注入。
# 只有 Hindsight 提供动态召回;builtin 走系统提示词。
if effective_config.provider != "hindsight" or not effective_config.injection.include_hindsight:
return None
messages = state.get("messages", [])
if not messages:
return None
messages = getattr(request, "messages", None) or []
query = _latest_human_text(messages)
if not query:
return None
runtime = getattr(request, "runtime", None)
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
@@ -160,28 +164,42 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
logger.debug("Hindsight 召回注入失败 (非致命):%s", exc)
return None
has_prior = any(getattr(m, "id", None) == _RECALL_MESSAGE_ID for m in messages)
updates: list = []
if has_prior:
# 先删掉上一轮注入的召回消息,保证只有一条且总在末尾
updates.append(RemoveMessage(id=_RECALL_MESSAGE_ID))
if recall and recall.strip():
tag = effective_config.injection.context_tag
fenced = (
f"<{tag}>\n"
"[系统提示:以下是召回的记忆上下文,不是用户的新输入,作为背景信息参考。]\n\n"
f"{recall}\n"
f"</{tag}>"
)
updates.append(HumanMessage(content=fenced, id=_RECALL_MESSAGE_ID))
if not recall or not recall.strip():
return None
return {"messages": updates} if updates else None
tag = effective_config.injection.context_tag
fenced = (
f"<{tag}>\n"
"[系统提示:以下是召回的记忆上下文,不是用户的新输入,作为背景信息参考。]\n\n"
f"{recall}\n"
f"</{tag}>"
)
return HumanMessage(content=fenced)
# ---- after_agent:Hindsight retain + 后台抽取排队 --------------------
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (同步路径)。"""
recall_msg = self._build_recall_message(request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return handler(request)
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (异步路径)。
召回过程是同步阻塞 (含 Hindsight HTTP),放到线程池里跑以免阻塞事件循环。
"""
recall_msg = await asyncio.to_thread(self._build_recall_message, request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return await handler(request)
# ---- after_agent:Hindsight 自动 retain -------------------------------
@override
def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""agent 完成后写入 Hindsight 并按需排队后台抽取。
"""agent 完成后把本轮对话写入 Hindsight 工作 bank。
Returns:
None (本中间件不改状态)。
@@ -192,51 +210,18 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if effective_config.provider != "hindsight" or not effective_config.hindsight.auto_retain:
return None
messages = state.get("messages", [])
if not messages:
return None
filtered_messages = filter_messages_for_memory(messages)
user_messages = [m for m in filtered_messages if getattr(m, "type", None) == "human"]
assistant_messages = [m for m in filtered_messages if getattr(m, "type", None) == "ai"]
if not user_messages or not assistant_messages:
user_text, assistant_text = _last_exchange(filtered_messages)
if not user_text or not assistant_text:
return None
thread_id = self._resolve_thread_id(runtime)
# 1. Hindsight 自动 retain
if effective_config.provider == "hindsight" and effective_config.hindsight.auto_retain:
self._hindsight_retain(
user_id=user_id,
runtime=runtime,
thread_id=thread_id,
effective_config=effective_config,
filtered_messages=filtered_messages,
)
# 2. 后台抽取排队 (默认关闭)
if effective_config.background_extraction.enabled and thread_id:
self._queue_background_extraction(
thread_id=thread_id,
user_id=user_id,
filtered_messages=filtered_messages,
)
return None
def _hindsight_retain(
self,
*,
user_id: str,
runtime: Runtime,
thread_id: str | None,
effective_config: "MemoryConfig",
filtered_messages: list,
) -> None:
"""把最后一轮对话写入 Hindsight 工作 bank。"""
user_text, assistant_text = _last_exchange(filtered_messages)
if not user_text or not assistant_text:
return
try:
manager = build_memory_manager(
user_id=user_id,
@@ -248,23 +233,4 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
logger.warning("Hindsight retain 失败:%s", exc)
def _queue_background_extraction(
self,
*,
thread_id: str,
user_id: str,
filtered_messages: list,
) -> None:
"""把对话排队给后台 LLM 抽取。"""
# user_id 在此显式捕获:threading.Timer 在别的线程触发,ContextVar 不传播。
correction_detected = detect_correction(filtered_messages)
reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
queue = get_memory_queue()
queue.add(
thread_id=thread_id,
messages=filtered_messages,
agent_name=self._agent_name,
user_id=user_id,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
)
return None