feat(memory): Memory V2 重写 - 可插拔 provider + Hindsight 集成

以 Hermes 的可插拔记忆架构为骨架重写 deerflow 记忆模块,兼容原有
结构化数据,并新增 Hindsight 作为外部记忆后端。

P1 - 抽象层 + builtin 本地记忆:
- MemoryProvider 抽象基类 + MemoryManager 编排层(builtin + ≤1 外部)
- BuiltinFileProvider:USER.md/MEMORY.md 二元存储、字符配额、文件锁、
  原子写、frozen snapshot
- memory 工具(LangChain @tool):LLM 主动写入用户画像/工作笔记
- 记忆内容安全扫描(注入/外渗模式 + 不可见 unicode)
- memory_config 改为嵌套结构 + 旧扁平字段兼容 + per-user 三层覆盖
- 迁移脚本 migrate_memory_to_v2.py:旧 memory.json -> USER.md/MEMORY.md
- Gateway 新增 /api/memory/v2 与 v2/config 端点(用户可配置白名单字段)

P2 - Hindsight 外部 provider:
- HindsightProvider:双 bank 隔离(user bank 跨 agent 共享 + work bank
  agent 私有)、并发召回合并、auto-retain、on_memory_write 镜像
- hindsight_recall/reflect/retain 三个 LangChain 工具
- MemoryMiddleware.before_model 注入 Hindsight 动态召回
- context/tools/hybrid 三种 memory_mode
- hindsight-client 作为可选依赖,未装时自动退回纯 builtin

注入走系统提示词(builtin frozen snapshot)+ before_model(Hindsight
动态召回)。后台抽取保留但默认关闭,P3 期重接入。

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 12:15:55 +08:00
1 parent 6947a3ffa7
commit f9d7610679
21 files changed
+3970 -188

No files matched your search

@@ -1,110 +1,270 @@
"""Middleware for memory mechanism."""
import logging
from typing import TYPE_CHECKING, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.config import get_config
from langgraph.runtime import Runtime
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.config.memory_config import get_memory_config
from deerflow.runtime.user_context import get_effective_user_id
if TYPE_CHECKING:
from deerflow.config.memory_config import MemoryConfig
logger = logging.getLogger(__name__)
class MemoryMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
"""Middleware that queues conversation for memory update after agent execution.
This middleware:
1. After each agent execution, queues the conversation for memory update
2. Only includes user inputs and final assistant responses (ignores tool calls)
3. The queue uses debouncing to batch multiple updates together
4. Memory is updated asynchronously via LLM summarization
"""
state_schema = MemoryMiddlewareState
def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | None" = None):
"""Initialize the MemoryMiddleware.
Args:
agent_name: If provided, memory is stored per-agent. If None, uses global memory.
memory_config: Explicit memory config. When omitted, legacy global
config fallback is used.
"""
super().__init__()
self._agent_name = agent_name
self._memory_config = memory_config
@override
def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""Queue conversation for memory update after agent completes.
Args:
state: The current agent state.
runtime: The runtime context.
Returns:
None (no state changes needed from this middleware).
"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
# Get thread ID from runtime context first, then fall back to LangGraph's configurable metadata
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id is None:
config_data = get_config()
thread_id = config_data.get("configurable", {}).get("thread_id")
if not thread_id:
logger.debug("No thread_id in context, skipping memory update")
return None
# Get messages from state
messages = state.get("messages", [])
if not messages:
logger.debug("No messages in state, skipping memory update")
return None
# Filter to only keep user inputs and final assistant responses
filtered_messages = filter_messages_for_memory(messages)
# Only queue if there's meaningful conversation
# At minimum need one user message and one assistant response
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:
return None
# Queue the filtered conversation for memory update
correction_detected = detect_correction(filtered_messages)
reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
# Capture user_id at enqueue time while the request context is still alive.
# threading.Timer fires on a different thread where ContextVar values are not
# propagated, so we must store user_id explicitly in ConversationContext.
user_id = get_effective_user_id()
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
"""记忆机制中间件 (Memory V2)。
本中间件负责两件事:
1. **before_model** —— Hindsight 动态召回注入。
每次 LLM 调用前,用最近一条用户消息作为 query 召回 Hindsight 记忆,
注入成一条带 ``<memory-context>`` 标签的消息。仅在 ``provider="hindsight"``
且配置允许时生效;builtin 的 frozen snapshot 走系统提示词,不在这里。
2. **after_agent** —— Hindsight 自动 retain + 后台抽取排队。
- Hindsight ``auto_retain`` 开启时,把本轮对话写入工作 bank。
- 后台抽取 (``background_extraction.enabled``,默认关) 开启时,把对话
排队给后台 LLM 抽取。
LLM 主动写入走 ``memory`` / ``hindsight_*`` 工具,不经过本中间件。
"""
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 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.config.memory_config import get_effective_memory_config, get_memory_config
from deerflow.runtime.user_context import get_effective_user_id
if TYPE_CHECKING:
from deerflow.config.memory_config import MemoryConfig
logger = logging.getLogger(__name__)
#: 注入的 Hindsight 召回消息的固定 id —— 每轮先删旧的再加新的,保证只有一条且总在末尾。
_RECALL_MESSAGE_ID = "deerflow-memory-recall"
def _coerce_text(content: Any) -> str:
"""把消息 content (可能是 str 或多模态 block 列表) 压成纯文本。"""
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text", "")))
return " ".join(parts)
return str(content or "")
def _latest_human_text(messages: list) -> str:
"""返回最近一条用户消息的纯文本。"""
for msg in reversed(messages):
if isinstance(msg, HumanMessage) and getattr(msg, "id", None) != _RECALL_MESSAGE_ID:
return _coerce_text(msg.content).strip()
return ""
def _last_exchange(filtered_messages: list) -> tuple[str, str]:
"""从过滤后的消息里取最后一轮 (用户输入, 助手回复) 的纯文本。"""
user_text = ""
assistant_text = ""
for msg in reversed(filtered_messages):
if not assistant_text and isinstance(msg, AIMessage):
assistant_text = _coerce_text(msg.content).strip()
elif not user_text and isinstance(msg, HumanMessage):
user_text = _coerce_text(msg.content).strip()
if user_text and assistant_text:
break
return user_text, assistant_text
class MemoryMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
"""记忆中间件:before_model 注入 Hindsight 召回,after_agent 写入与排队。
Memory V2 说明:
- builtin 本地记忆的 frozen snapshot 走系统提示词 (``_get_memory_context``)。
- Hindsight 动态召回走本中间件 ``before_model``。
- 后台抽取默认关闭。
"""
state_schema = MemoryMiddlewareState
def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | None" = None):
"""初始化 MemoryMiddleware。
Args:
agent_name: 提供时记忆按 agent 隔离;None 用默认 agent。
memory_config: 显式记忆配置;省略时用全局配置。
"""
super().__init__()
self._agent_name = agent_name
self._memory_config = memory_config
# ---- 运行时上下文解析 -------------------------------------------------
def _resolve_thread_id(self, runtime: Runtime) -> str | None:
"""从 runtime context 取 thread_id,回退到 LangGraph configurable。"""
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id:
return thread_id
try:
return get_config().get("configurable", {}).get("thread_id")
except RuntimeError:
return None
def _resolve_agent_id(self, runtime: Runtime) -> 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"
# ---- before_model:Hindsight 动态召回注入 ----------------------------
@override
def before_model(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""LLM 调用前,把 Hindsight 召回结果注入成一条记忆上下文消息。"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if not effective_config.enabled or not effective_config.injection.enabled:
return None
# 只有 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
query = _latest_human_text(messages)
if not query:
return None
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
user_id=user_id,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
recall = manager.prefetch_all(query, thread_id=thread_id or "")
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
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))
return {"messages": updates} if updates else None
# ---- after_agent:Hindsight retain + 后台抽取排队 --------------------
@override
def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""agent 完成后写入 Hindsight 并按需排队后台抽取。
Returns:
None (本中间件不改状态)。
"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
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:
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,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
manager.sync_all(user_text, assistant_text, thread_id=thread_id or "")
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,
)