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:
1 parent
6947a3ffa7
commit
f9d7610679
21 files changed
+3970
-188
No files matched your search
+270
-110
@@ -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,
|
||||
)
|
||||
Reference in new issue
Block a user