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
@@ -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",
|
||||
|
||||
+155
@@ -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",
|
||||
]
|
||||
+155
@@ -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"]
|
||||
@@ -6,7 +6,7 @@ from deerflow.config import get_app_config
|
||||
from deerflow.config.app_config import AppConfig
|
||||
from deerflow.reflection import resolve_variable
|
||||
from deerflow.sandbox.security import is_host_bash_allowed
|
||||
from deerflow.tools.builtins import ask_clarification_tool, present_file_tool, scheduled_task_tool, task_tool, view_image_tool
|
||||
from deerflow.tools.builtins import ask_clarification_tool, memory_tool, present_file_tool, scheduled_task_tool, task_tool, view_image_tool
|
||||
from deerflow.tools.builtins.tool_search import reset_deferred_registry
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
@@ -84,6 +84,24 @@ def get_available_tools(
|
||||
builtin_tools = BUILTIN_TOOLS.copy()
|
||||
if not is_scheduled_run:
|
||||
builtin_tools.append(scheduled_task_tool)
|
||||
|
||||
# Memory V2:记忆与 builtin provider 都启用时,暴露 memory 工具给 LLM 主动写入
|
||||
memory_config = getattr(config, "memory", None)
|
||||
if memory_config is not None and getattr(memory_config, "enabled", False):
|
||||
builtin_config = getattr(memory_config, "builtin", None)
|
||||
if builtin_config is not None and getattr(builtin_config, "enabled", False):
|
||||
builtin_tools.append(memory_tool)
|
||||
logger.info("Including memory tool (Memory V2 builtin provider enabled)")
|
||||
|
||||
# Hindsight 在 tools / hybrid 模式下,额外暴露 3 个 Hindsight 工具
|
||||
if getattr(memory_config, "provider", "builtin") == "hindsight":
|
||||
hindsight_config = getattr(memory_config, "hindsight", None)
|
||||
memory_mode = getattr(hindsight_config, "memory_mode", "context") if hindsight_config else "context"
|
||||
if memory_mode in ("tools", "hybrid"):
|
||||
from deerflow.tools.builtins.hindsight_tools import HINDSIGHT_TOOLS
|
||||
|
||||
builtin_tools.extend(HINDSIGHT_TOOLS)
|
||||
logger.info("Including Hindsight tools (memory_mode=%s)", memory_mode)
|
||||
skill_evolution_config = getattr(config, "skill_evolution", None)
|
||||
if getattr(skill_evolution_config, "enabled", False):
|
||||
from deerflow.tools.builtins.skill_tools import skill_list_tool, skill_view_tool
|
||||
|
||||
Reference in new issue
Block a user