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,4 +1,5 @@
from .clarification_tool import ask_clarification_tool
from .memory_tool import memory_tool
from .present_file_tool import present_file_tool
from .scheduled_task_tool import scheduled_task_tool
from .setup_agent_tool import setup_agent
@@ -9,6 +10,7 @@ __all__ = [
"setup_agent",
"present_file_tool",
"ask_clarification_tool",
"memory_tool",
"scheduled_task_tool",
"view_image_tool",
"task_tool",
@@ -0,0 +1,155 @@
"""Memory V2 - Hindsight 的 3 个 LangChain 工具。
仅当 ``config.memory.hindsight.memory_mode`` 为 ``tools`` 或 ``hybrid`` 时,
这些工具才会被 ``get_available_tools`` 加入工具集 (``context`` 模式不暴露)。
- hindsight_recall 多策略检索 (语义 + 实体图谱),查双 bank
- hindsight_reflect 跨记忆综合 (LLM 推理)
- hindsight_retain 主动存储一条记忆到全局 user bank
与 builtin 的 ``memory`` 工具一样,这些工具从 :class:`ToolRuntime` 与请求上下文
解析 user_id / agent_id,按生效配置懒建一个 :class:`HindsightProvider` 后调用。
"""
from __future__ import annotations
import json
import logging
from langchain.tools import ToolRuntime, tool
from langgraph.config import get_config
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config.memory_config import get_effective_memory_config
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
"""从 runtime context / RunnableConfig 解析 agent_id,缺省 ``"default"``。"""
agent_id = runtime.context.get("agent_id") if runtime.context else None
if agent_id:
return str(agent_id)
runtime_config = getattr(runtime, "config", None) or {}
agent_id = runtime_config.get("configurable", {}).get("agent_id")
if agent_id:
return str(agent_id)
try:
agent_id = get_config().get("configurable", {}).get("agent_id")
except RuntimeError:
agent_id = None
return str(agent_id) if agent_id else "default"
def _build_provider(runtime: ToolRuntime[ContextT, ThreadState]):
"""按生效配置懒建并初始化一个 HindsightProvider;不可用时返回 ``None``。"""
from deerflow.agents.memory.providers.hindsight import HindsightProvider
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
if not config.enabled or config.provider != "hindsight":
return None
provider = HindsightProvider(config.hindsight)
if not provider.is_available():
return None
thread_id = runtime.context.get("thread_id") if runtime.context else None
provider.initialize(
user_id=user_id,
agent_id=_resolve_agent_id(runtime),
thread_id=thread_id or "",
base_dir="",
)
return provider
@tool("hindsight_recall", parse_docstring=True)
def hindsight_recall_tool(
runtime: ToolRuntime[ContextT, ThreadState],
query: str,
) -> str:
"""检索 Hindsight 长期记忆,查找与 query 相关的历史信息。
用于回答关于用户、过往会话、之前讨论过的内容的问题。会同时检索全局用户
记忆和当前 agent 的工作记忆。
Args:
query: 检索查询,描述你想找回什么信息。
"""
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
results = provider.recall(query)
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_recall 失败:%s", exc)
return json.dumps({"success": False, "error": f"检索失败:{exc}"}, ensure_ascii=False)
if not results:
return json.dumps({"success": True, "result": "没有找到相关记忆。"}, ensure_ascii=False)
lines = "\n".join(f"{i}. {text}" for i, text in enumerate(results, 1))
return json.dumps({"success": True, "result": lines}, ensure_ascii=False)
@tool("hindsight_reflect", parse_docstring=True)
def hindsight_reflect_tool(
runtime: ToolRuntime[ContextT, ThreadState],
query: str,
) -> str:
"""对 Hindsight 记忆做跨记忆综合推理,得到一段综合性回答。
与 hindsight_recall 返回原始记忆片段不同,reflect 会让 LLM 综合多条记忆
给出推理结论。适合需要归纳、总结、跨记忆关联的问题。
Args:
query: 你希望综合分析的问题。
"""
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
text = provider.reflect(query)
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_reflect 失败:%s", exc)
return json.dumps({"success": False, "error": f"综合失败:{exc}"}, ensure_ascii=False)
return json.dumps(
{"success": True, "result": text or "没有找到相关记忆。"}, ensure_ascii=False
)
@tool("hindsight_retain", parse_docstring=True)
def hindsight_retain_tool(
runtime: ToolRuntime[ContextT, ThreadState],
content: str,
) -> str:
"""主动把一条信息存入 Hindsight 的全局用户记忆库。
用于记录跨会话、跨 agent 仍有价值的用户事实。Hindsight 会自动做实体抽取
和知识图谱关联。
Args:
content: 要存储的记忆内容。
"""
if not content or not content.strip():
return json.dumps({"success": False, "error": "content 不能为空。"}, ensure_ascii=False)
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
provider.retain_to_user_bank(content.strip())
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_retain 失败:%s", exc)
return json.dumps({"success": False, "error": f"存储失败:{exc}"}, ensure_ascii=False)
return json.dumps({"success": True, "result": "记忆已存储。"}, ensure_ascii=False)
#: 三个 Hindsight 工具,供 get_available_tools 在 tools/hybrid 模式下加入。
HINDSIGHT_TOOLS = [hindsight_recall_tool, hindsight_reflect_tool, hindsight_retain_tool]
__all__ = [
"hindsight_recall_tool",
"hindsight_reflect_tool",
"hindsight_retain_tool",
"HINDSIGHT_TOOLS",
]
@@ -0,0 +1,155 @@
"""Memory V2 - LLM 主动调用的 ``memory`` 工具。
让 LLM 在对话过程中主动把跨会话仍有用的信息记到持久化记忆里 ——
对应 Hermes 的 ``memory`` 工具,是双轨写入里的 "主动" 一轨。
工具写入直达 :class:`BuiltinFileProvider`:
- ``target="user"`` -> ``USER.md`` (用户画像,跨 agent 共享)
- ``target="memory"`` -> ``MEMORY.md`` (agent 私有工作笔记)
agent_id / user_id 在工具调用时从 :class:`ToolRuntime` 与请求上下文解析。
P2 期会在写入后追加 Hindsight 镜像 (``on_memory_write`` 钩子)。
"""
from __future__ import annotations
import json
import logging
from typing import Literal
from langchain.tools import ToolRuntime, tool
from langgraph.config import get_config
from langgraph.typing import ContextT
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
from deerflow.agents.thread_state import ThreadState
from deerflow.config.memory_config import get_effective_memory_config
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
"""从 runtime context / RunnableConfig 解析当前 agent_id,缺省为 ``"default"``。"""
agent_id = runtime.context.get("agent_id") if runtime.context else None
if agent_id:
return str(agent_id)
runtime_config = getattr(runtime, "config", None) or {}
agent_id = runtime_config.get("configurable", {}).get("agent_id")
if agent_id:
return str(agent_id)
try:
agent_id = get_config().get("configurable", {}).get("agent_id")
except RuntimeError:
agent_id = None
return str(agent_id) if agent_id else "default"
@tool("memory", parse_docstring=True)
def memory_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: Literal["add", "replace", "remove"],
target: Literal["memory", "user"],
content: str | None = None,
old_text: str | None = None,
) -> str:
"""把跨会话仍有用的信息记到持久化记忆里。
记忆会被注入到后续对话的系统提示词中,所以请保持简洁、只记真正还会用到的事实。
什么时候应该记 (主动判断,不必等用户开口):
- 用户纠正你,或者说 "记住这件事" / "下次别这样"
- 用户透露偏好、习惯、个人信息 (姓名、角色、时区、代码风格)
- 你发现了环境/项目/工具相关、之后还会复用的稳定事实
两类 target:
- user:用户画像 —— 姓名、角色、偏好、沟通风格 (跨 agent 共享)
- memory:当前 agent 的私有工作笔记 —— 环境事实、约定、踩过的坑 (agent 隔离)
不要记:一次性任务进度、可以重新查到的信息、临时 TODO 状态。
Args:
action: 操作类型。add 新增条目;replace 替换 (用 old_text 定位);remove 删除 (用 old_text 定位)。
target: 记忆类别。user 写入用户画像;memory 写入当前 agent 的工作笔记。
content: 条目内容。action 为 add 或 replace 时必填。
old_text: 短唯一子串,用于定位要替换或删除的条目。action 为 replace 或 remove 时必填。
"""
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
if not config.enabled or not config.builtin.enabled:
return json.dumps(
{"success": False, "error": "记忆功能未启用,可能在配置中被关闭。"},
ensure_ascii=False,
)
if target not in ("memory", "user"):
return json.dumps(
{"success": False, "error": f"非法 target '{target}',只能是 'memory' 或 'user'。"},
ensure_ascii=False,
)
agent_id = _resolve_agent_id(runtime)
provider = BuiltinFileProvider(
memory_char_limit=config.builtin.memory_char_limit,
user_char_limit=config.builtin.user_char_limit,
deduplicate_on_load=config.builtin.deduplicate_on_load,
security=config.security,
)
try:
provider.initialize(
user_id=user_id,
agent_id=agent_id,
base_dir=str(get_paths().base_dir),
)
except Exception as exc: # noqa: BLE001 - 初始化失败要返回给 LLM 而非崩溃
logger.warning("memory 工具初始化 BuiltinFileProvider 失败:%s", exc)
return json.dumps(
{"success": False, "error": f"记忆初始化失败:{exc}"}, ensure_ascii=False
)
if action == "add":
if not content:
result = {"success": False, "error": "action=add 需要提供 content。"}
else:
result = provider.add(target, content)
elif action == "replace":
if not old_text:
result = {"success": False, "error": "action=replace 需要提供 old_text。"}
elif not content:
result = {"success": False, "error": "action=replace 需要提供 content。"}
else:
result = provider.replace(target, old_text, content)
elif action == "remove":
if not old_text:
result = {"success": False, "error": "action=remove 需要提供 old_text。"}
else:
result = provider.remove(target, old_text)
else:
result = {"success": False, "error": f"未知 action '{action}',只能是 add / replace / remove。"}
# 写入成功后镜像到外部 provider (Hindsight)。失败不影响 builtin 写入结果。
if result.get("success") and action in ("add", "replace") and content:
_mirror_to_external(config, user_id, agent_id, thread_id="", action=action, target=target, content=content)
return json.dumps(result, ensure_ascii=False)
def _mirror_to_external(config, user_id: str, agent_id: str, *, thread_id: str, action: str, target: str, content: str) -> None:
"""把一次 builtin 记忆写入镜像到外部 provider (P2: Hindsight)。"""
if config.provider != "hindsight":
return
try:
from deerflow.agents.memory.providers.hindsight import HindsightProvider
provider = HindsightProvider(config.hindsight)
if not provider.is_available():
return
provider.initialize(user_id=user_id, agent_id=agent_id, thread_id=thread_id, base_dir="")
provider.on_memory_write(action, target, content, metadata={"user_id": user_id, "agent_id": agent_id})
except Exception as exc: # noqa: BLE001 - 镜像失败不影响 builtin 写入
logger.debug("memory 工具镜像到 Hindsight 失败:%s", exc)
__all__ = ["memory_tool"]