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:
1 parent
f9d7610679
commit
21a76f5e7c
14 files changed
+954
-3085
No files matched your search
+70
-104
@@ -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
|
||||
Reference in new issue
Block a user