Merge branch 'master' of http://192.168.0.200/knowledge-base-bj/deerflow-server into dhk-1
This commit is contained in:
commit
226439ef36
100 files changed
+12966
-7151
No files matched your search
+32
-34
@@ -5,7 +5,6 @@ from langchain.agents.middleware import AgentMiddleware
|
||||
from langchain_core.runnables import RunnableConfig
|
||||
|
||||
from deerflow.agents.lead_agent.prompt import apply_prompt_template
|
||||
from deerflow.agents.memory.summarization_hook import memory_flush_hook
|
||||
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
|
||||
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
|
||||
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
|
||||
@@ -92,9 +91,8 @@ def _create_summarization_middleware(*, app_config: AppConfig | None = None) ->
|
||||
if config.summary_prompt is not None:
|
||||
kwargs["summary_prompt"] = config.summary_prompt
|
||||
|
||||
# Memory V2:不再有后台抽取队列,无需 summarization 前的 flush hook。
|
||||
hooks: list[BeforeSummarizationHook] = []
|
||||
if resolved_app_config.memory.enabled:
|
||||
hooks.append(memory_flush_hook)
|
||||
|
||||
# The logic below relies on two assumptions holding true: this factory is
|
||||
# the sole entry point for DeerFlowSummarizationMiddleware, and the runtime
|
||||
@@ -336,13 +334,13 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
|
||||
requested_model_name: str | None = cfg.get("model_name") or cfg.get("model")
|
||||
is_plan_mode = cfg.get("is_plan_mode", False)
|
||||
subagent_enabled = cfg.get("subagent_enabled", False)
|
||||
max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
|
||||
is_bootstrap = cfg.get("is_bootstrap", False)
|
||||
writing_mode = bool(cfg.get("writing_mode", False))
|
||||
writing_artifact_path = cfg.get("writing_artifact_path") if writing_mode else None
|
||||
if not isinstance(writing_artifact_path, str) or not writing_artifact_path.strip():
|
||||
writing_artifact_path = None
|
||||
agent_id = validate_agent_id(cfg.get("agent_id") or cfg.get("agent_name"))
|
||||
max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
|
||||
is_bootstrap = cfg.get("is_bootstrap", False)
|
||||
writing_mode = bool(cfg.get("writing_mode", False))
|
||||
writing_artifact_path = cfg.get("writing_artifact_path") if writing_mode else None
|
||||
if not isinstance(writing_artifact_path, str) or not writing_artifact_path.strip():
|
||||
writing_artifact_path = None
|
||||
agent_id = validate_agent_id(cfg.get("agent_id") or cfg.get("agent_name"))
|
||||
|
||||
agent_config = load_agent_config(agent_id) if not is_bootstrap else None
|
||||
agent_display_name = agent_config.name if agent_config else agent_id
|
||||
@@ -361,15 +359,15 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
|
||||
thinking_enabled = False
|
||||
|
||||
logger.info(
|
||||
"Create Agent(%s) -> thinking_enabled: %s, reasoning_effort: %s, model_name: %s, is_plan_mode: %s, subagent_enabled: %s, max_concurrent_subagents: %s, writing_mode: %s",
|
||||
agent_id or "default",
|
||||
thinking_enabled,
|
||||
reasoning_effort,
|
||||
model_name,
|
||||
is_plan_mode,
|
||||
subagent_enabled,
|
||||
max_concurrent_subagents,
|
||||
writing_mode,
|
||||
"Create Agent(%s) -> thinking_enabled: %s, reasoning_effort: %s, model_name: %s, is_plan_mode: %s, subagent_enabled: %s, max_concurrent_subagents: %s, writing_mode: %s",
|
||||
agent_id or "default",
|
||||
thinking_enabled,
|
||||
reasoning_effort,
|
||||
model_name,
|
||||
is_plan_mode,
|
||||
subagent_enabled,
|
||||
max_concurrent_subagents,
|
||||
writing_mode,
|
||||
)
|
||||
|
||||
# Inject run metadata for LangSmith trace tagging
|
||||
@@ -393,10 +391,10 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
|
||||
"thinking_enabled": thinking_enabled,
|
||||
"reasoning_effort": reasoning_effort,
|
||||
"is_plan_mode": is_plan_mode,
|
||||
"subagent_enabled": subagent_enabled,
|
||||
"writing_mode": writing_mode,
|
||||
"writing_artifact_path": writing_artifact_path,
|
||||
"tool_groups": agent_config.tool_groups if agent_config else None,
|
||||
"subagent_enabled": subagent_enabled,
|
||||
"writing_mode": writing_mode,
|
||||
"writing_artifact_path": writing_artifact_path,
|
||||
"tool_groups": agent_config.tool_groups if agent_config else None,
|
||||
"available_skills": runtime_available_skills,
|
||||
}
|
||||
)
|
||||
@@ -415,11 +413,11 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
|
||||
middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
|
||||
system_prompt=apply_prompt_template(
|
||||
subagent_enabled=subagent_enabled,
|
||||
max_concurrent_subagents=max_concurrent_subagents,
|
||||
writing_mode=writing_mode,
|
||||
writing_artifact_path=writing_artifact_path,
|
||||
available_skills=set(["bootstrap"]),
|
||||
app_config=resolved_app_config,
|
||||
max_concurrent_subagents=max_concurrent_subagents,
|
||||
writing_mode=writing_mode,
|
||||
writing_artifact_path=writing_artifact_path,
|
||||
available_skills=set(["bootstrap"]),
|
||||
app_config=resolved_app_config,
|
||||
),
|
||||
state_schema=ThreadState,
|
||||
)
|
||||
@@ -438,12 +436,12 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
|
||||
system_prompt=apply_prompt_template(
|
||||
subagent_enabled=subagent_enabled,
|
||||
max_concurrent_subagents=max_concurrent_subagents,
|
||||
agent_id=agent_id,
|
||||
agent_name=agent_display_name,
|
||||
writing_mode=writing_mode,
|
||||
writing_artifact_path=writing_artifact_path,
|
||||
available_skills=(set(agent_config.skills or []) if agent_config else None),
|
||||
app_config=resolved_app_config,
|
||||
agent_id=agent_id,
|
||||
agent_name=agent_display_name,
|
||||
writing_mode=writing_mode,
|
||||
writing_artifact_path=writing_artifact_path,
|
||||
available_skills=(set(agent_config.skills or []) if agent_config else None),
|
||||
app_config=resolved_app_config,
|
||||
),
|
||||
state_schema=ThreadState,
|
||||
)
|
||||
+21
-15
@@ -603,32 +603,38 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
|
||||
|
||||
|
||||
def _get_memory_context(agent_name: str | None = None, *, app_config: AppConfig | None = None) -> str:
|
||||
"""Get memory context for injection into system prompt.
|
||||
"""组装注入系统提示词的记忆上下文 (Memory V2)。
|
||||
|
||||
通过 :class:`MemoryManager` 收集各 provider 的记忆块。P1 期只有 builtin
|
||||
本地 provider —— 返回 USER.md / MEMORY.md 的 frozen snapshot。系统提示词
|
||||
在 agent 构建时定型,因此天然就是 frozen snapshot 语义。
|
||||
|
||||
Args:
|
||||
agent_name: If provided, loads per-agent memory. If None, loads global memory.
|
||||
app_config: Explicit application config. When provided, memory options
|
||||
are read from this value instead of the global config singleton.
|
||||
agent_name: agent 标识;``None`` 时按 "default" 处理。
|
||||
app_config: 显式应用配置 (本函数实际按 per-user 覆盖解析生效配置)。
|
||||
|
||||
Returns:
|
||||
Formatted memory context string wrapped in XML tags, or empty string if disabled.
|
||||
包在 ``<memory>`` 标签里的记忆上下文;未启用或为空时返回空串。
|
||||
"""
|
||||
try:
|
||||
from deerflow.agents.memory import format_memory_for_injection, get_memory_data
|
||||
from deerflow.agents.memory.manager import build_memory_manager
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
if app_config is None:
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
user_id = get_effective_user_id()
|
||||
config = get_effective_memory_config(user_id)
|
||||
|
||||
config = get_memory_config()
|
||||
else:
|
||||
config = app_config.memory
|
||||
|
||||
if not config.enabled or not config.injection_enabled:
|
||||
if not config.enabled or not config.injection.enabled:
|
||||
return ""
|
||||
|
||||
memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
|
||||
memory_content = format_memory_for_injection(memory_data, max_tokens=config.max_injection_tokens)
|
||||
manager = build_memory_manager(
|
||||
user_id=user_id,
|
||||
agent_id=agent_name or "default",
|
||||
config=config,
|
||||
)
|
||||
# 只取静态块 (builtin 的 frozen snapshot + Hindsight 的模式说明)。
|
||||
# Hindsight 的动态召回需要当前 query,走 MemoryMiddleware.before_model。
|
||||
memory_content = manager.build_system_prompt()
|
||||
|
||||
if not memory_content.strip():
|
||||
return ""
|
||||
|
||||
+37
-57
@@ -1,57 +1,37 @@
|
||||
"""Memory module for DeerFlow.
|
||||
|
||||
This module provides a global memory mechanism that:
|
||||
- Stores user context and conversation history in memory.json
|
||||
- Uses LLM to summarize and extract facts from conversations
|
||||
- Injects relevant memory into system prompts for personalized responses
|
||||
"""
|
||||
|
||||
from deerflow.agents.memory.prompt import (
|
||||
FACT_EXTRACTION_PROMPT,
|
||||
MEMORY_UPDATE_PROMPT,
|
||||
format_conversation_for_update,
|
||||
format_memory_for_injection,
|
||||
)
|
||||
from deerflow.agents.memory.queue import (
|
||||
ConversationContext,
|
||||
MemoryUpdateQueue,
|
||||
get_memory_queue,
|
||||
reset_memory_queue,
|
||||
)
|
||||
from deerflow.agents.memory.storage import (
|
||||
FileMemoryStorage,
|
||||
MemoryStorage,
|
||||
get_memory_storage,
|
||||
)
|
||||
from deerflow.agents.memory.updater import (
|
||||
MemoryUpdater,
|
||||
clear_memory_data,
|
||||
delete_memory_fact,
|
||||
get_memory_data,
|
||||
reload_memory_data,
|
||||
update_memory_from_conversation,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
# Prompt utilities
|
||||
"MEMORY_UPDATE_PROMPT",
|
||||
"FACT_EXTRACTION_PROMPT",
|
||||
"format_memory_for_injection",
|
||||
"format_conversation_for_update",
|
||||
# Queue
|
||||
"ConversationContext",
|
||||
"MemoryUpdateQueue",
|
||||
"get_memory_queue",
|
||||
"reset_memory_queue",
|
||||
# Storage
|
||||
"MemoryStorage",
|
||||
"FileMemoryStorage",
|
||||
"get_memory_storage",
|
||||
# Updater
|
||||
"MemoryUpdater",
|
||||
"clear_memory_data",
|
||||
"delete_memory_fact",
|
||||
"get_memory_data",
|
||||
"reload_memory_data",
|
||||
"update_memory_from_conversation",
|
||||
]
|
||||
"""DeerFlow 记忆模块 (Memory V2)。
|
||||
|
||||
架构 (详见 docs/MEMORY_V2_DESIGN_ZH.md):
|
||||
- :class:`MemoryProvider` 可插拔记忆 provider 抽象基类
|
||||
- :class:`MemoryManager` 编排内建 + 至多 1 个外部 provider
|
||||
- :func:`build_memory_manager` 按生效配置组装 manager 的统一入口
|
||||
- :class:`BuiltinFileProvider` 本地 USER.md / MEMORY.md provider
|
||||
- :class:`HindsightProvider` Hindsight HTTP 外部 provider
|
||||
- :mod:`deerflow.agents.memory.security` 记忆内容安全扫描
|
||||
|
||||
记忆有两条自动写入路径:LLM 主动调 ``memory`` / ``hindsight_*`` 工具,
|
||||
以及 Hindsight 的 auto-retain。注入走系统提示词 (builtin frozen snapshot)
|
||||
与 ``MemoryMiddleware.wrap_model_call`` (Hindsight 动态召回)。
|
||||
"""
|
||||
|
||||
from deerflow.agents.memory.manager import MemoryManager, build_memory_manager
|
||||
from deerflow.agents.memory.message_processing import filter_messages_for_memory
|
||||
from deerflow.agents.memory.provider import MemoryProvider
|
||||
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
|
||||
from deerflow.agents.memory.providers.hindsight import HindsightProvider
|
||||
from deerflow.agents.memory.security import (
|
||||
MemoryContentBlocked,
|
||||
assert_memory_content_safe,
|
||||
scan_memory_content,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"MemoryProvider",
|
||||
"MemoryManager",
|
||||
"build_memory_manager",
|
||||
"BuiltinFileProvider",
|
||||
"HindsightProvider",
|
||||
"MemoryContentBlocked",
|
||||
"scan_memory_content",
|
||||
"assert_memory_content_safe",
|
||||
"filter_messages_for_memory",
|
||||
]
|
||||
@@ -0,0 +1,277 @@
|
||||
"""Memory V2 - MemoryManager 编排层。
|
||||
|
||||
职责
|
||||
====
|
||||
编排 1 个内建 provider (``builtin``,始终存在) + 至多 1 个外部 provider
|
||||
(P2 期的 ``hindsight``)。把系统提示词组装、召回、生命周期 hook 分发到各 provider。
|
||||
任一 provider 出错都不会阻断其他 provider,也不会阻断对话。
|
||||
|
||||
典型用法 (由 MemoryMiddleware 每轮构建)
|
||||
=======================================
|
||||
::
|
||||
|
||||
manager = MemoryManager()
|
||||
manager.add_provider(BuiltinFileProvider(...))
|
||||
manager.add_provider(hindsight_provider) # 可选,至多 1 个
|
||||
manager.initialize_all(user_id=..., agent_id=..., thread_id=..., base_dir=...)
|
||||
|
||||
block = manager.build_injection_block(query=user_msg, thread_id=tid)
|
||||
# ... 把 block 注入系统提示词 ...
|
||||
|
||||
manager.sync_all(user_msg, assistant_msg, thread_id=tid)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from deerflow.agents.memory.provider import MemoryProvider
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
#: 内建 provider 的固定名字。
|
||||
BUILTIN_PROVIDER_NAME = "builtin"
|
||||
|
||||
|
||||
class MemoryManager:
|
||||
"""编排内建 provider + 至多 1 个外部 provider。"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._providers: list[MemoryProvider] = []
|
||||
self._has_external: bool = False
|
||||
|
||||
# ---- 注册 ------------------------------------------------------------
|
||||
|
||||
def add_provider(self, provider: MemoryProvider) -> bool:
|
||||
"""注册一个 provider。
|
||||
|
||||
内建 provider (``name == "builtin"``) 始终接受。外部 provider 至多 1 个,
|
||||
第二个会被拒绝并 log 警告。返回是否注册成功。
|
||||
"""
|
||||
is_builtin = provider.name == BUILTIN_PROVIDER_NAME
|
||||
if not is_builtin:
|
||||
if self._has_external:
|
||||
existing = next(
|
||||
(p.name for p in self._providers if p.name != BUILTIN_PROVIDER_NAME),
|
||||
"unknown",
|
||||
)
|
||||
logger.warning(
|
||||
"拒绝注册记忆 provider '%s' —— 已存在外部 provider '%s'。"
|
||||
"同一时间只允许 1 个外部 provider,请用 config.memory.provider 选择。",
|
||||
provider.name,
|
||||
existing,
|
||||
)
|
||||
return False
|
||||
self._has_external = True
|
||||
self._providers.append(provider)
|
||||
logger.info("记忆 provider '%s' 已注册", provider.name)
|
||||
return True
|
||||
|
||||
@property
|
||||
def providers(self) -> list[MemoryProvider]:
|
||||
"""按注册顺序返回所有 provider。"""
|
||||
return list(self._providers)
|
||||
|
||||
def get_provider(self, name: str) -> MemoryProvider | None:
|
||||
"""按名字取 provider,不存在返回 ``None``。"""
|
||||
for p in self._providers:
|
||||
if p.name == name:
|
||||
return p
|
||||
return None
|
||||
|
||||
# ---- 生命周期 ---------------------------------------------------------
|
||||
|
||||
def initialize_all(self, **kwargs: Any) -> None:
|
||||
"""初始化所有 provider。单个 provider 失败不影响其他。"""
|
||||
for provider in self._providers:
|
||||
try:
|
||||
provider.initialize(**kwargs)
|
||||
except Exception as exc: # noqa: BLE001 - provider 失败必须隔离
|
||||
logger.warning("记忆 provider '%s' initialize 失败:%s", provider.name, exc)
|
||||
|
||||
def shutdown_all(self) -> None:
|
||||
"""关闭所有 provider (逆序,保证干净拆除)。"""
|
||||
for provider in reversed(self._providers):
|
||||
try:
|
||||
provider.shutdown()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("记忆 provider '%s' shutdown 失败:%s", provider.name, exc)
|
||||
|
||||
# ---- 系统提示词组装 / 召回 -------------------------------------------
|
||||
|
||||
def build_system_prompt(self) -> str:
|
||||
"""收集所有 provider 的静态系统提示词块。"""
|
||||
blocks: list[str] = []
|
||||
for provider in self._providers:
|
||||
try:
|
||||
block = provider.system_prompt_block()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("记忆 provider '%s' system_prompt_block 失败:%s", provider.name, exc)
|
||||
continue
|
||||
if block and block.strip():
|
||||
blocks.append(block)
|
||||
return "\n\n".join(blocks)
|
||||
|
||||
def prefetch_all(self, query: str, *, thread_id: str = "") -> str:
|
||||
"""收集所有 provider 的召回上下文。单个失败不阻断其他。"""
|
||||
parts: list[str] = []
|
||||
for provider in self._providers:
|
||||
try:
|
||||
result = provider.prefetch(query, thread_id=thread_id)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.debug("记忆 provider '%s' prefetch 失败 (非致命):%s", provider.name, exc)
|
||||
continue
|
||||
if result and result.strip():
|
||||
parts.append(result)
|
||||
return "\n\n".join(parts)
|
||||
|
||||
def build_injection_block(self, query: str, *, thread_id: str = "") -> str:
|
||||
"""组装注入系统提示词的完整记忆块。
|
||||
|
||||
= 所有 provider 的静态块 (frozen snapshot 等) + 动态召回块。
|
||||
返回空串表示无内容可注入。
|
||||
"""
|
||||
static_part = self.build_system_prompt()
|
||||
dynamic_part = self.prefetch_all(query, thread_id=thread_id)
|
||||
parts = [p for p in (static_part, dynamic_part) if p and p.strip()]
|
||||
return "\n\n".join(parts)
|
||||
|
||||
def queue_prefetch_all(self, query: str, *, thread_id: str = "") -> None:
|
||||
"""通知所有 provider 后台预热下一轮召回。"""
|
||||
for provider in self._providers:
|
||||
try:
|
||||
provider.queue_prefetch(query, thread_id=thread_id)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.debug("记忆 provider '%s' queue_prefetch 失败:%s", provider.name, exc)
|
||||
|
||||
# ---- 写入 ------------------------------------------------------------
|
||||
|
||||
def sync_all(
|
||||
self,
|
||||
user_content: str,
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""把一轮完成的对话同步到所有 provider。
|
||||
|
||||
``turn_index`` 是当前对话的轮次序号,透传给各 provider 用于轮次节流。
|
||||
"""
|
||||
for provider in self._providers:
|
||||
try:
|
||||
provider.sync_turn(
|
||||
user_content,
|
||||
assistant_content,
|
||||
thread_id=thread_id,
|
||||
turn_index=turn_index,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("记忆 provider '%s' sync_turn 失败:%s", provider.name, exc)
|
||||
|
||||
def on_memory_write(
|
||||
self,
|
||||
action: str,
|
||||
target: str,
|
||||
content: str,
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
"""builtin 写入后,通知外部 provider 镜像。
|
||||
|
||||
跳过 builtin 自身 (它就是写入源,镜像回去没有意义)。
|
||||
"""
|
||||
for provider in self._providers:
|
||||
if provider.name == BUILTIN_PROVIDER_NAME:
|
||||
continue
|
||||
try:
|
||||
provider.on_memory_write(action, target, content, metadata)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.debug("记忆 provider '%s' on_memory_write 失败:%s", provider.name, exc)
|
||||
|
||||
# ---- 可选 hooks ------------------------------------------------------
|
||||
|
||||
def on_session_switch_all(
|
||||
self,
|
||||
new_thread_id: str,
|
||||
*,
|
||||
parent_thread_id: str = "",
|
||||
reset: bool = False,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""通知所有 provider thread_id 已切换。"""
|
||||
if not new_thread_id:
|
||||
return
|
||||
for provider in self._providers:
|
||||
try:
|
||||
provider.on_session_switch(
|
||||
new_thread_id,
|
||||
parent_thread_id=parent_thread_id,
|
||||
reset=reset,
|
||||
**kwargs,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.debug("记忆 provider '%s' on_session_switch 失败:%s", provider.name, exc)
|
||||
|
||||
|
||||
def build_memory_manager(
|
||||
*,
|
||||
user_id: str,
|
||||
agent_id: str | None = None,
|
||||
thread_id: str | None = None,
|
||||
config: Any = None,
|
||||
) -> MemoryManager:
|
||||
"""按生效配置组装并初始化一个 MemoryManager。
|
||||
|
||||
这是构建 manager 的统一入口 —— 注册 builtin provider,以及在
|
||||
``config.provider == "hindsight"`` 且 Hindsight 可用时注册 HindsightProvider。
|
||||
所有 provider 已 ``initialize`` 完毕,可直接使用。
|
||||
|
||||
Parameters
|
||||
----------
|
||||
user_id / agent_id / thread_id:
|
||||
请求上下文标识。
|
||||
config:
|
||||
生效的 :class:`MemoryConfig`;为 ``None`` 时按 ``user_id`` 解析 per-user 配置。
|
||||
"""
|
||||
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
if config is None:
|
||||
config = get_effective_memory_config(user_id)
|
||||
|
||||
manager = MemoryManager()
|
||||
|
||||
if config.builtin.enabled:
|
||||
manager.add_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,
|
||||
)
|
||||
)
|
||||
|
||||
if config.provider == "hindsight":
|
||||
try:
|
||||
from deerflow.agents.memory.providers.hindsight import HindsightProvider
|
||||
|
||||
hindsight = HindsightProvider(config.hindsight)
|
||||
if hindsight.is_available():
|
||||
manager.add_provider(hindsight)
|
||||
else:
|
||||
logger.info("Hindsight provider 已配置但不可用 (包未装或缺 api_url),退回纯 builtin")
|
||||
except Exception as exc: # noqa: BLE001 - Hindsight 接入失败不能阻断记忆系统
|
||||
logger.warning("加载 Hindsight provider 失败,退回纯 builtin:%s", exc)
|
||||
|
||||
manager.initialize_all(
|
||||
user_id=user_id,
|
||||
agent_id=agent_id or "default",
|
||||
thread_id=thread_id,
|
||||
base_dir=str(get_paths().base_dir),
|
||||
)
|
||||
return manager
|
||||
|
||||
|
||||
__all__ = ["MemoryManager", "BUILTIN_PROVIDER_NAME", "build_memory_manager"]
|
||||
+15
-53
@@ -1,4 +1,8 @@
|
||||
"""Shared helpers for turning conversations into memory update inputs."""
|
||||
"""把对话整理成记忆写入所需输入的共享辅助函数。
|
||||
|
||||
Memory V2 说明:后台抽取已舍弃,这里只保留 ``filter_messages_for_memory``
|
||||
(供 MemoryMiddleware 取出最后一轮对话用于 Hindsight retain)。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -7,34 +11,6 @@ from copy import copy
|
||||
from typing import Any
|
||||
|
||||
_UPLOAD_BLOCK_RE = re.compile(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", re.IGNORECASE)
|
||||
_CORRECTION_PATTERNS = (
|
||||
re.compile(r"\bthat(?:'s| is) (?:wrong|incorrect)\b", re.IGNORECASE),
|
||||
re.compile(r"\byou misunderstood\b", re.IGNORECASE),
|
||||
re.compile(r"\btry again\b", re.IGNORECASE),
|
||||
re.compile(r"\bredo\b", re.IGNORECASE),
|
||||
re.compile(r"不对"),
|
||||
re.compile(r"你理解错了"),
|
||||
re.compile(r"你理解有误"),
|
||||
re.compile(r"重试"),
|
||||
re.compile(r"重新来"),
|
||||
re.compile(r"换一种"),
|
||||
re.compile(r"改用"),
|
||||
)
|
||||
_REINFORCEMENT_PATTERNS = (
|
||||
re.compile(r"\byes[,.]?\s+(?:exactly|perfect|that(?:'s| is) (?:right|correct|it))\b", re.IGNORECASE),
|
||||
re.compile(r"\bperfect(?:[.!?]|$)", re.IGNORECASE),
|
||||
re.compile(r"\bexactly\s+(?:right|correct)\b", re.IGNORECASE),
|
||||
re.compile(r"\bthat(?:'s| is)\s+(?:exactly\s+)?(?:right|correct|what i (?:wanted|needed|meant))\b", re.IGNORECASE),
|
||||
re.compile(r"\bkeep\s+(?:doing\s+)?that\b", re.IGNORECASE),
|
||||
re.compile(r"\bjust\s+(?:like\s+)?(?:that|this)\b", re.IGNORECASE),
|
||||
re.compile(r"\bthis is (?:great|helpful)\b(?:[.!?]|$)", re.IGNORECASE),
|
||||
re.compile(r"\bthis is what i wanted\b(?:[.!?]|$)", re.IGNORECASE),
|
||||
re.compile(r"对[,,]?\s*就是这样(?:[。!?!?.]|$)"),
|
||||
re.compile(r"完全正确(?:[。!?!?.]|$)"),
|
||||
re.compile(r"(?:对[,,]?\s*)?就是这个意思(?:[。!?!?.]|$)"),
|
||||
re.compile(r"正是我想要的(?:[。!?!?.]|$)"),
|
||||
re.compile(r"继续保持(?:[。!?!?.]|$)"),
|
||||
)
|
||||
|
||||
|
||||
def extract_message_text(message: Any) -> str:
|
||||
@@ -53,6 +29,16 @@ def extract_message_text(message: Any) -> str:
|
||||
return str(content)
|
||||
|
||||
|
||||
def count_user_turns(filtered_messages: list[Any]) -> int:
|
||||
"""统计已过滤消息里的用户轮次数 (= human 消息条数)。
|
||||
|
||||
供 MemoryMiddleware 算出当前轮次序号传给 provider 做轮次节流 ——
|
||||
provider 每轮被重建、无法靠自身计数,必须由这里按对话历史推算。
|
||||
入参应是 :func:`filter_messages_for_memory` 的输出。
|
||||
"""
|
||||
return sum(1 for msg in filtered_messages if getattr(msg, "type", None) == "human")
|
||||
|
||||
|
||||
def filter_messages_for_memory(messages: list[Any]) -> list[Any]:
|
||||
"""Keep only user inputs and final assistant responses for memory updates."""
|
||||
filtered = []
|
||||
@@ -83,27 +69,3 @@ def filter_messages_for_memory(messages: list[Any]) -> list[Any]:
|
||||
filtered.append(msg)
|
||||
|
||||
return filtered
|
||||
|
||||
|
||||
def detect_correction(messages: list[Any]) -> bool:
|
||||
"""Detect explicit user corrections in recent conversation turns."""
|
||||
recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
|
||||
|
||||
for msg in recent_user_msgs:
|
||||
content = extract_message_text(msg).strip()
|
||||
if content and any(pattern.search(content) for pattern in _CORRECTION_PATTERNS):
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def detect_reinforcement(messages: list[Any]) -> bool:
|
||||
"""Detect explicit positive reinforcement signals in recent conversation turns."""
|
||||
recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
|
||||
|
||||
for msg in recent_user_msgs:
|
||||
content = extract_message_text(msg).strip()
|
||||
if content and any(pattern.search(content) for pattern in _REINFORCEMENT_PATTERNS):
|
||||
return True
|
||||
|
||||
return False
|
||||
@@ -1,363 +0,0 @@
|
||||
"""Prompt templates for memory update and injection."""
|
||||
|
||||
import math
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
try:
|
||||
import tiktoken
|
||||
|
||||
TIKTOKEN_AVAILABLE = True
|
||||
except ImportError:
|
||||
TIKTOKEN_AVAILABLE = False
|
||||
|
||||
# Prompt template for updating memory based on conversation
|
||||
MEMORY_UPDATE_PROMPT = """You are a memory management system. Your task is to analyze a conversation and update the user's memory profile.
|
||||
|
||||
Current Memory State:
|
||||
<current_memory>
|
||||
{current_memory}
|
||||
</current_memory>
|
||||
|
||||
New Conversation to Process:
|
||||
<conversation>
|
||||
{conversation}
|
||||
</conversation>
|
||||
|
||||
Instructions:
|
||||
1. Analyze the conversation for important information about the user
|
||||
2. Extract relevant facts, preferences, and context with specific details (numbers, names, technologies)
|
||||
3. Update the memory sections as needed following the detailed length guidelines below
|
||||
|
||||
Before extracting facts, perform a structured reflection on the conversation:
|
||||
1. Error/Retry Detection: Did the agent encounter errors, require retries, or produce incorrect results?
|
||||
If yes, record the root cause and correct approach as a high-confidence fact with category "correction".
|
||||
2. User Correction Detection: Did the user correct the agent's direction, understanding, or output?
|
||||
If yes, record the correct interpretation or approach as a high-confidence fact with category "correction".
|
||||
Include what went wrong in "sourceError" only when category is "correction" and the mistake is explicit in the conversation.
|
||||
3. Project Constraint Discovery: Were any project-specific constraints discovered during the conversation?
|
||||
If yes, record them as facts with the most appropriate category and confidence.
|
||||
|
||||
{correction_hint}
|
||||
|
||||
Memory Section Guidelines:
|
||||
|
||||
**User Context** (Current state - concise summaries):
|
||||
- workContext: Professional role, company, key projects, main technologies (2-3 sentences)
|
||||
Example: Core contributor, project names with metrics (16k+ stars), technical stack
|
||||
- personalContext: Languages, communication preferences, key interests (1-2 sentences)
|
||||
Example: Bilingual capabilities, specific interest areas, expertise domains
|
||||
- topOfMind: Multiple ongoing focus areas and priorities (3-5 sentences, detailed paragraph)
|
||||
Example: Primary project work, parallel technical investigations, ongoing learning/tracking
|
||||
Include: Active implementation work, troubleshooting issues, market/research interests
|
||||
Note: This captures SEVERAL concurrent focus areas, not just one task
|
||||
|
||||
**History** (Temporal context - rich paragraphs):
|
||||
- recentMonths: Detailed summary of recent activities (4-6 sentences or 1-2 paragraphs)
|
||||
Timeline: Last 1-3 months of interactions
|
||||
Include: Technologies explored, projects worked on, problems solved, interests demonstrated
|
||||
- earlierContext: Important historical patterns (3-5 sentences or 1 paragraph)
|
||||
Timeline: 3-12 months ago
|
||||
Include: Past projects, learning journeys, established patterns
|
||||
- longTermBackground: Persistent background and foundational context (2-4 sentences)
|
||||
Timeline: Overall/foundational information
|
||||
Include: Core expertise, longstanding interests, fundamental working style
|
||||
|
||||
**Facts Extraction**:
|
||||
- Extract specific, quantifiable details (e.g., "16k+ GitHub stars", "200+ datasets")
|
||||
- Include proper nouns (company names, project names, technology names)
|
||||
- Preserve technical terminology and version numbers
|
||||
- Categories:
|
||||
* preference: Tools, styles, approaches user prefers/dislikes
|
||||
* knowledge: Specific expertise, technologies mastered, domain knowledge
|
||||
* context: Background facts (job title, projects, locations, languages)
|
||||
* behavior: Working patterns, communication habits, problem-solving approaches
|
||||
* goal: Stated objectives, learning targets, project ambitions
|
||||
* correction: Explicit agent mistakes or user corrections, including the correct approach
|
||||
- Confidence levels:
|
||||
* 0.9-1.0: Explicitly stated facts ("I work on X", "My role is Y")
|
||||
* 0.7-0.8: Strongly implied from actions/discussions
|
||||
* 0.5-0.6: Inferred patterns (use sparingly, only for clear patterns)
|
||||
|
||||
**What Goes Where**:
|
||||
- workContext: Current job, active projects, primary tech stack
|
||||
- personalContext: Languages, personality, interests outside direct work tasks
|
||||
- topOfMind: Multiple ongoing priorities and focus areas user cares about recently (gets updated most frequently)
|
||||
Should capture 3-5 concurrent themes: main work, side explorations, learning/tracking interests
|
||||
- recentMonths: Detailed account of recent technical explorations and work
|
||||
- earlierContext: Patterns from slightly older interactions still relevant
|
||||
- longTermBackground: Unchanging foundational facts about the user
|
||||
|
||||
**Multilingual Content**:
|
||||
- Preserve original language for proper nouns and company names
|
||||
- Keep technical terms in their original form (DeepSeek, LangGraph, etc.)
|
||||
- Note language capabilities in personalContext
|
||||
|
||||
Output Format (JSON):
|
||||
{{
|
||||
"user": {{
|
||||
"workContext": {{ "summary": "...", "shouldUpdate": true/false }},
|
||||
"personalContext": {{ "summary": "...", "shouldUpdate": true/false }},
|
||||
"topOfMind": {{ "summary": "...", "shouldUpdate": true/false }}
|
||||
}},
|
||||
"history": {{
|
||||
"recentMonths": {{ "summary": "...", "shouldUpdate": true/false }},
|
||||
"earlierContext": {{ "summary": "...", "shouldUpdate": true/false }},
|
||||
"longTermBackground": {{ "summary": "...", "shouldUpdate": true/false }}
|
||||
}},
|
||||
"newFacts": [
|
||||
{{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
|
||||
],
|
||||
"factsToRemove": ["fact_id_1", "fact_id_2"]
|
||||
}}
|
||||
|
||||
Important Rules:
|
||||
- Only set shouldUpdate=true if there's meaningful new information
|
||||
- Follow length guidelines: workContext/personalContext are concise (1-3 sentences), topOfMind and history sections are detailed (paragraphs)
|
||||
- Include specific metrics, version numbers, and proper nouns in facts
|
||||
- Only add facts that are clearly stated (0.9+) or strongly implied (0.7+)
|
||||
- Use category "correction" for explicit agent mistakes or user corrections; assign confidence >= 0.95 when the correction is explicit
|
||||
- Include "sourceError" only for explicit correction facts when the prior mistake or wrong approach is clearly stated; omit it otherwise
|
||||
- Remove facts that are contradicted by new information
|
||||
- When updating topOfMind, integrate new focus areas while removing completed/abandoned ones
|
||||
Keep 3-5 concurrent focus themes that are still active and relevant
|
||||
- For history sections, integrate new information chronologically into appropriate time period
|
||||
- Preserve technical accuracy - keep exact names of technologies, companies, projects
|
||||
- Focus on information useful for future interactions and personalization
|
||||
- IMPORTANT: Do NOT record file upload events in memory. Uploaded files are
|
||||
session-specific and ephemeral — they will not be accessible in future sessions.
|
||||
Recording upload events causes confusion in subsequent conversations.
|
||||
|
||||
Return ONLY valid JSON, no explanation or markdown."""
|
||||
|
||||
|
||||
# Prompt template for extracting facts from a single message
|
||||
FACT_EXTRACTION_PROMPT = """Extract factual information about the user from this message.
|
||||
|
||||
Message:
|
||||
{message}
|
||||
|
||||
Extract facts in this JSON format:
|
||||
{{
|
||||
"facts": [
|
||||
{{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
|
||||
]
|
||||
}}
|
||||
|
||||
Categories:
|
||||
- preference: User preferences (likes/dislikes, styles, tools)
|
||||
- knowledge: User's expertise or knowledge areas
|
||||
- context: Background context (location, job, projects)
|
||||
- behavior: Behavioral patterns
|
||||
- goal: User's goals or objectives
|
||||
- correction: Explicit corrections or mistakes to avoid repeating
|
||||
|
||||
Rules:
|
||||
- Only extract clear, specific facts
|
||||
- Confidence should reflect certainty (explicit statement = 0.9+, implied = 0.6-0.8)
|
||||
- Skip vague or temporary information
|
||||
|
||||
Return ONLY valid JSON."""
|
||||
|
||||
|
||||
def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
|
||||
"""Count tokens in text using tiktoken.
|
||||
|
||||
Args:
|
||||
text: The text to count tokens for.
|
||||
encoding_name: The encoding to use (default: cl100k_base for GPT-4/3.5).
|
||||
|
||||
Returns:
|
||||
The number of tokens in the text.
|
||||
"""
|
||||
if not TIKTOKEN_AVAILABLE:
|
||||
# Fallback to character-based estimation if tiktoken is not available
|
||||
return len(text) // 4
|
||||
|
||||
try:
|
||||
encoding = tiktoken.get_encoding(encoding_name)
|
||||
return len(encoding.encode(text))
|
||||
except Exception:
|
||||
# Fallback to character-based estimation on error
|
||||
return len(text) // 4
|
||||
|
||||
|
||||
def _coerce_confidence(value: Any, default: float = 0.0) -> float:
|
||||
"""Coerce a confidence-like value to a bounded float in [0, 1].
|
||||
|
||||
Non-finite values (NaN, inf, -inf) are treated as invalid and fall back
|
||||
to the default before clamping, preventing them from dominating ranking.
|
||||
The ``default`` parameter is assumed to be a finite value.
|
||||
"""
|
||||
try:
|
||||
confidence = float(value)
|
||||
except (TypeError, ValueError):
|
||||
return max(0.0, min(1.0, default))
|
||||
if not math.isfinite(confidence):
|
||||
return max(0.0, min(1.0, default))
|
||||
return max(0.0, min(1.0, confidence))
|
||||
|
||||
|
||||
def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
|
||||
"""Format memory data for injection into system prompt.
|
||||
|
||||
Args:
|
||||
memory_data: The memory data dictionary.
|
||||
max_tokens: Maximum tokens to use (counted via tiktoken for accuracy).
|
||||
|
||||
Returns:
|
||||
Formatted memory string for system prompt injection.
|
||||
"""
|
||||
if not memory_data:
|
||||
return ""
|
||||
|
||||
sections = []
|
||||
|
||||
# Format user context
|
||||
user_data = memory_data.get("user", {})
|
||||
if user_data:
|
||||
user_sections = []
|
||||
|
||||
work_ctx = user_data.get("workContext", {})
|
||||
if work_ctx.get("summary"):
|
||||
user_sections.append(f"Work: {work_ctx['summary']}")
|
||||
|
||||
personal_ctx = user_data.get("personalContext", {})
|
||||
if personal_ctx.get("summary"):
|
||||
user_sections.append(f"Personal: {personal_ctx['summary']}")
|
||||
|
||||
top_of_mind = user_data.get("topOfMind", {})
|
||||
if top_of_mind.get("summary"):
|
||||
user_sections.append(f"Current Focus: {top_of_mind['summary']}")
|
||||
|
||||
if user_sections:
|
||||
sections.append("User Context:\n" + "\n".join(f"- {s}" for s in user_sections))
|
||||
|
||||
# Format history
|
||||
history_data = memory_data.get("history", {})
|
||||
if history_data:
|
||||
history_sections = []
|
||||
|
||||
recent = history_data.get("recentMonths", {})
|
||||
if recent.get("summary"):
|
||||
history_sections.append(f"Recent: {recent['summary']}")
|
||||
|
||||
earlier = history_data.get("earlierContext", {})
|
||||
if earlier.get("summary"):
|
||||
history_sections.append(f"Earlier: {earlier['summary']}")
|
||||
|
||||
background = history_data.get("longTermBackground", {})
|
||||
if background.get("summary"):
|
||||
history_sections.append(f"Background: {background['summary']}")
|
||||
|
||||
if history_sections:
|
||||
sections.append("History:\n" + "\n".join(f"- {s}" for s in history_sections))
|
||||
|
||||
# Format facts (sorted by confidence; include as many as token budget allows)
|
||||
facts_data = memory_data.get("facts", [])
|
||||
if isinstance(facts_data, list) and facts_data:
|
||||
ranked_facts = sorted(
|
||||
(f for f in facts_data if isinstance(f, dict) and isinstance(f.get("content"), str) and f.get("content").strip()),
|
||||
key=lambda fact: _coerce_confidence(fact.get("confidence"), default=0.0),
|
||||
reverse=True,
|
||||
)
|
||||
|
||||
# Compute token count for existing sections once, then account
|
||||
# incrementally for each fact line to avoid full-string re-tokenization.
|
||||
base_text = "\n\n".join(sections)
|
||||
base_tokens = _count_tokens(base_text) if base_text else 0
|
||||
# Account for the separator between existing sections and the facts section.
|
||||
facts_header = "Facts:\n"
|
||||
separator_tokens = _count_tokens("\n\n" + facts_header) if base_text else _count_tokens(facts_header)
|
||||
running_tokens = base_tokens + separator_tokens
|
||||
|
||||
fact_lines: list[str] = []
|
||||
for fact in ranked_facts:
|
||||
content_value = fact.get("content")
|
||||
if not isinstance(content_value, str):
|
||||
continue
|
||||
content = content_value.strip()
|
||||
if not content:
|
||||
continue
|
||||
category = str(fact.get("category", "context")).strip() or "context"
|
||||
confidence = _coerce_confidence(fact.get("confidence"), default=0.0)
|
||||
source_error = fact.get("sourceError")
|
||||
if category == "correction" and isinstance(source_error, str) and source_error.strip():
|
||||
line = f"- [{category} | {confidence:.2f}] {content} (avoid: {source_error.strip()})"
|
||||
else:
|
||||
line = f"- [{category} | {confidence:.2f}] {content}"
|
||||
|
||||
# Each additional line is preceded by a newline (except the first).
|
||||
line_text = ("\n" + line) if fact_lines else line
|
||||
line_tokens = _count_tokens(line_text)
|
||||
|
||||
if running_tokens + line_tokens <= max_tokens:
|
||||
fact_lines.append(line)
|
||||
running_tokens += line_tokens
|
||||
else:
|
||||
break
|
||||
|
||||
if fact_lines:
|
||||
sections.append("Facts:\n" + "\n".join(fact_lines))
|
||||
|
||||
if not sections:
|
||||
return ""
|
||||
|
||||
result = "\n\n".join(sections)
|
||||
|
||||
# Use accurate token counting with tiktoken
|
||||
token_count = _count_tokens(result)
|
||||
if token_count > max_tokens:
|
||||
# Truncate to fit within token limit
|
||||
# Estimate characters to remove based on token ratio
|
||||
char_per_token = len(result) / token_count
|
||||
target_chars = int(max_tokens * char_per_token * 0.95) # 95% to leave margin
|
||||
result = result[:target_chars] + "\n..."
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def format_conversation_for_update(messages: list[Any]) -> str:
|
||||
"""Format conversation messages for memory update prompt.
|
||||
|
||||
Args:
|
||||
messages: List of conversation messages.
|
||||
|
||||
Returns:
|
||||
Formatted conversation string.
|
||||
"""
|
||||
lines = []
|
||||
for msg in messages:
|
||||
role = getattr(msg, "type", "unknown")
|
||||
content = getattr(msg, "content", str(msg))
|
||||
|
||||
# Handle content that might be a list (multimodal)
|
||||
if isinstance(content, list):
|
||||
text_parts = []
|
||||
for p in content:
|
||||
if isinstance(p, str):
|
||||
text_parts.append(p)
|
||||
elif isinstance(p, dict):
|
||||
text_val = p.get("text")
|
||||
if isinstance(text_val, str):
|
||||
text_parts.append(text_val)
|
||||
content = " ".join(text_parts) if text_parts else str(content)
|
||||
|
||||
# Strip uploaded_files tags from human messages to avoid persisting
|
||||
# ephemeral file path info into long-term memory. Skip the turn entirely
|
||||
# when nothing remains after stripping (upload-only message).
|
||||
if role == "human":
|
||||
content = re.sub(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", "", str(content)).strip()
|
||||
if not content:
|
||||
continue
|
||||
|
||||
# Truncate very long messages
|
||||
if len(str(content)) > 1000:
|
||||
content = str(content)[:1000] + "..."
|
||||
|
||||
if role == "human":
|
||||
lines.append(f"User: {content}")
|
||||
elif role == "ai":
|
||||
lines.append(f"Assistant: {content}")
|
||||
|
||||
return "\n\n".join(lines)
|
||||
@@ -0,0 +1,205 @@
|
||||
"""Memory V2 - 记忆 Provider 抽象基类。
|
||||
|
||||
设计动机
|
||||
========
|
||||
Hermes Agent 的可插拔记忆系统的 deerflow 版本。所有具体的记忆后端
|
||||
(builtin 本地文件、Hindsight HTTP 等)都实现这个接口,由 ``MemoryManager``
|
||||
统一编排。Provider 之间互不感知,可自由组合 (内建 + 至多 1 个外部 plugin)。
|
||||
|
||||
生命周期
|
||||
========
|
||||
:func:`MemoryProvider.initialize` 初始化 (创建 bank、加载本地文件、建立连接)
|
||||
:func:`MemoryProvider.system_prompt_block` 注入系统提示词的静态说明文本
|
||||
:func:`MemoryProvider.prefetch` 每轮对话前召回上下文
|
||||
:func:`MemoryProvider.queue_prefetch` 下一轮的后台预热
|
||||
:func:`MemoryProvider.sync_turn` 每轮对话后异步写入后端
|
||||
:func:`MemoryProvider.get_tool_schemas` 暴露给 LLM 的工具 schema
|
||||
:func:`MemoryProvider.handle_tool_call` 路由工具调用
|
||||
:func:`MemoryProvider.shutdown` 清理 (flush 队列、关连接)
|
||||
|
||||
可选 hooks
|
||||
==========
|
||||
仅按 ``生产推荐档`` 移植两个 ——
|
||||
- :func:`MemoryProvider.on_session_switch` thread_id 切换时 (branch/resume/reset/压缩后)
|
||||
- :func:`MemoryProvider.on_memory_write` builtin 写入时,通知外部 provider 镜像
|
||||
|
||||
参见 ``docs/MEMORY_V2_DESIGN_ZH.md`` §4 的完整接口定义和 §16 的实施分期。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class MemoryProvider(ABC):
|
||||
"""所有记忆 provider 必须实现的接口。"""
|
||||
|
||||
# ---- 身份 ------------------------------------------------------------
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def name(self) -> str:
|
||||
"""短标识,如 ``'builtin'`` / ``'hindsight'``。"""
|
||||
|
||||
# ---- 生命周期 ---------------------------------------------------------
|
||||
|
||||
@abstractmethod
|
||||
def is_available(self) -> bool:
|
||||
"""是否已配置并可用。
|
||||
|
||||
在 agent 启动时被调用,用于判断要不要激活该 provider。
|
||||
实现里只检查配置和依赖,不发网络请求。
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
def initialize(
|
||||
self,
|
||||
*,
|
||||
user_id: str,
|
||||
agent_id: str | None = None,
|
||||
thread_id: str | None = None,
|
||||
base_dir: str,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""初始化:打开连接、创建 bank、加载本地文件等。
|
||||
|
||||
kwargs 至少包含 ``user_id`` / ``base_dir``,其余字段视 provider 而定。
|
||||
Provider 可以根据 ``agent_id is None`` 决定走全局还是 per-agent 路径。
|
||||
|
||||
Parameters
|
||||
----------
|
||||
user_id:
|
||||
当前用户的隔离标识(无认证场景下为 ``"default"``)。
|
||||
agent_id:
|
||||
当前 agent 的稳定标识;``None`` 表示走全局/默认 agent。
|
||||
thread_id:
|
||||
当前对话的 thread id;某些 provider 用它做并发隔离或 bank 后缀。
|
||||
base_dir:
|
||||
``Paths.base_dir`` 字符串形式,避免每个 provider 重复解析路径。
|
||||
"""
|
||||
|
||||
def shutdown(self) -> None:
|
||||
"""清理:刷队列、关连接。默认 no-op。"""
|
||||
|
||||
# ---- 系统提示词块 -----------------------------------------------------
|
||||
|
||||
def system_prompt_block(self) -> str:
|
||||
"""注入系统提示词的静态文本。
|
||||
|
||||
典型用途:USER.md / MEMORY.md 的 frozen snapshot,provider 状态说明等。
|
||||
返回空串表示不贡献内容。
|
||||
"""
|
||||
return ""
|
||||
|
||||
# ---- 召回 / 写入 -----------------------------------------------------
|
||||
|
||||
def prefetch(self, query: str, *, thread_id: str = "") -> str:
|
||||
"""对话前召回上下文。
|
||||
|
||||
在每次 LLM 调用前由 :class:`MemoryMiddleware` 触发。``query`` 通常
|
||||
是用户最近一条消息。实现要快;真正的网络召回应该走后台线程,
|
||||
这里直接返回缓存结果。
|
||||
|
||||
返回值:带格式的文本块,会被拼接到系统提示词末尾。空串表示无内容。
|
||||
"""
|
||||
return ""
|
||||
|
||||
def queue_prefetch(self, query: str, *, thread_id: str = "") -> None:
|
||||
"""后台预热下一轮的召回。默认 no-op。"""
|
||||
|
||||
def sync_turn(
|
||||
self,
|
||||
user_content: str,
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""每轮对话结束后把对话持久化到后端。
|
||||
|
||||
实现应当非阻塞 —— 如果后端有延迟,排队到后台处理而不是直接调用。
|
||||
默认 no-op。
|
||||
|
||||
``turn_index`` 是当前对话的轮次序号 (从 1 开始,由编排层按对话历史算出)。
|
||||
provider 通常被每轮重新构造、无法靠自身计数,需要按轮次节流写入
|
||||
(例如 "每 N 轮 retain 一次") 的实现应当用它而非进程内计数器。
|
||||
缺省 ``None`` 表示调用方未提供。
|
||||
"""
|
||||
|
||||
# ---- LLM 工具 --------------------------------------------------------
|
||||
|
||||
@abstractmethod
|
||||
def get_tool_schemas(self) -> list[dict[str, Any]]:
|
||||
"""暴露给 LLM 的工具 schema 列表。
|
||||
|
||||
每个 schema 遵循 OpenAI function calling 格式::
|
||||
|
||||
{"name": "...", "description": "...", "parameters": {...}}
|
||||
|
||||
空数组表示 context-only(只做自动 recall/retain,不让 LLM 看见工具)。
|
||||
"""
|
||||
|
||||
def handle_tool_call(
|
||||
self, tool_name: str, args: dict[str, Any], **kwargs: Any
|
||||
) -> str:
|
||||
"""处理一个工具调用,必须返回 JSON 字符串。
|
||||
|
||||
``MemoryManager`` 会确保只把本 provider ``get_tool_schemas`` 里
|
||||
声明的工具名路由到这里。
|
||||
"""
|
||||
raise NotImplementedError(
|
||||
f"Provider {self.name} does not handle tool {tool_name}"
|
||||
)
|
||||
|
||||
# ---- 可选 hooks (生产推荐档移植) -------------------------------------
|
||||
|
||||
def on_session_switch(
|
||||
self,
|
||||
new_thread_id: str,
|
||||
*,
|
||||
parent_thread_id: str = "",
|
||||
reset: bool = False,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""thread_id 切换时触发。
|
||||
|
||||
deerflow 的 thread_id 在以下场景会变化:
|
||||
- 用户新建/切换 thread (``reset=True``)
|
||||
- LangGraph thread branch (``reset=False``,``parent_thread_id`` 为原 thread)
|
||||
- SummarizationMiddleware 压缩后继续 (``reset=False``)
|
||||
|
||||
Provider 在 ``initialize`` 时如果缓存了 per-session 的状态
|
||||
(``_session_turns`` 累积缓冲、bank 关联、查询缓存等),应当在
|
||||
这里刷新。默认 no-op。
|
||||
"""
|
||||
|
||||
def on_memory_write(
|
||||
self,
|
||||
action: str,
|
||||
target: str,
|
||||
content: str,
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
"""builtin 写入时触发,通知外部 provider 镜像同一条记忆。
|
||||
|
||||
Parameters
|
||||
----------
|
||||
action:
|
||||
``'add'`` / ``'replace'`` / ``'remove'``。
|
||||
target:
|
||||
``'user'`` / ``'memory'``,决定走全局 user bank 还是 agent 工作 bank。
|
||||
content:
|
||||
条目内容。``remove`` 时为待删除条目的内容(供 external 做幂等)。
|
||||
metadata:
|
||||
写入来源元数据 (``user_id`` / ``agent_id`` / ``thread_id`` / ``tool_name``)。
|
||||
|
||||
默认 no-op —— 只有需要镜像 builtin 写入的外部 provider (例如 Hindsight)
|
||||
才需要重写。``MemoryManager`` 调度时会跳过 builtin 自身,避免无意义的回环。
|
||||
"""
|
||||
|
||||
|
||||
__all__ = ["MemoryProvider"]
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
"""Memory V2 - 具体 provider 实现。
|
||||
|
||||
- :class:`~deerflow.agents.memory.providers.builtin.BuiltinFileProvider`
|
||||
本地文件 provider (USER.md / MEMORY.md),始终启用。
|
||||
- ``HindsightProvider`` — Hindsight HTTP 客户端,P2 期接入。
|
||||
"""
|
||||
|
||||
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
|
||||
|
||||
__all__ = ["BuiltinFileProvider"]
|
||||
+417
@@ -0,0 +1,417 @@
|
||||
"""Memory V2 - 本地文件 provider (USER.md / MEMORY.md)。
|
||||
|
||||
从 Hermes ``tools/memory_tool.py`` 的 ``MemoryStore`` 移植,适配 deerflow 的
|
||||
per-user / per-agent 目录结构与 :class:`MemoryProvider` 接口。
|
||||
|
||||
两类存储
|
||||
========
|
||||
- ``USER.md`` 用户画像 —— LLM 主动写入的 ``target="user"`` 记忆,跨 agent 共享。
|
||||
路径:``{base_dir}/users/{user_id}/USER.md``
|
||||
- ``MEMORY.md`` agent 工作笔记 —— LLM 主动写入的 ``target="memory"`` 记忆,agent 隔离。
|
||||
路径:``{base_dir}/users/{user_id}/agents/{agent_id}/MEMORY.md``
|
||||
|
||||
设计要点
|
||||
========
|
||||
- 条目以 ``\\n§\\n`` 分隔,支持多行;采用字符级配额 (与模型无关)。
|
||||
- frozen snapshot:``initialize`` 时读盘一次并冻结为系统提示词块,会话内写入
|
||||
直接落盘 (durable) 但不刷新快照 —— 保持系统提示词稳定,利于 prefix cache。
|
||||
- 读-改-写经文件锁串行化;写入用临时文件 + 原子 rename,避免并发读到半截文件。
|
||||
- 写入前经 :mod:`deerflow.agents.memory.security` 扫描注入/外渗。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import os
|
||||
import tempfile
|
||||
import threading
|
||||
from contextlib import contextmanager
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from deerflow.agents.memory.provider import MemoryProvider
|
||||
from deerflow.agents.memory.security import scan_memory_content
|
||||
from deerflow.config.memory_config import SecurityConfig
|
||||
from deerflow.config.paths import get_paths
|
||||
from deerflow.runtime.user_context import DEFAULT_USER_ID
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# 跨平台文件锁:Unix 用 fcntl,Windows 用 msvcrt。
|
||||
_fcntl: Any = None
|
||||
_msvcrt: Any = None
|
||||
try: # pragma: no cover - 平台相关
|
||||
import fcntl as _fcntl_mod
|
||||
|
||||
_fcntl = _fcntl_mod
|
||||
except ImportError: # pragma: no cover - Windows
|
||||
try:
|
||||
import msvcrt as _msvcrt_mod
|
||||
|
||||
_msvcrt = _msvcrt_mod
|
||||
except ImportError:
|
||||
pass
|
||||
|
||||
#: 条目分隔符。``§`` = section sign (U+00A7)。
|
||||
ENTRY_DELIMITER = "\n§\n"
|
||||
|
||||
#: target 取值。
|
||||
_VALID_TARGETS = ("memory", "user")
|
||||
|
||||
# 同一进程内对同一文件路径的写入串行化锁 (文件锁之上再加一层,降低自争用)。
|
||||
_PATH_LOCKS: dict[str, threading.Lock] = {}
|
||||
_PATH_LOCKS_GUARD = threading.Lock()
|
||||
|
||||
|
||||
def _get_path_lock(path: Path) -> threading.Lock:
|
||||
"""返回某文件路径对应的进程内锁 (按路径字符串缓存)。"""
|
||||
key = str(path)
|
||||
with _PATH_LOCKS_GUARD:
|
||||
lock = _PATH_LOCKS.get(key)
|
||||
if lock is None:
|
||||
lock = threading.Lock()
|
||||
_PATH_LOCKS[key] = lock
|
||||
return lock
|
||||
|
||||
|
||||
@contextmanager
|
||||
def _file_lock(path: Path):
|
||||
"""获取某文件的排他锁,保证读-改-写安全。
|
||||
|
||||
用单独的 ``.lock`` 文件加锁,这样记忆文件本身仍可被 ``os.replace`` 原子替换。
|
||||
进程内先抢 :func:`_get_path_lock`,再抢跨进程文件锁。
|
||||
"""
|
||||
process_lock = _get_path_lock(path)
|
||||
process_lock.acquire()
|
||||
lock_path = path.with_suffix(path.suffix + ".lock")
|
||||
try:
|
||||
lock_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
if _fcntl is None and _msvcrt is None: # pragma: no cover - 无锁平台
|
||||
yield
|
||||
return
|
||||
if _msvcrt is not None and (not lock_path.exists() or lock_path.stat().st_size == 0):
|
||||
lock_path.write_text(" ", encoding="utf-8")
|
||||
fd = open(lock_path, "r+" if _msvcrt is not None else "a+")
|
||||
try:
|
||||
if _fcntl is not None:
|
||||
_fcntl.flock(fd, _fcntl.LOCK_EX)
|
||||
else: # pragma: no cover - Windows
|
||||
fd.seek(0)
|
||||
_msvcrt.locking(fd.fileno(), _msvcrt.LK_LOCK, 1)
|
||||
yield
|
||||
finally:
|
||||
try:
|
||||
if _fcntl is not None:
|
||||
_fcntl.flock(fd, _fcntl.LOCK_UN)
|
||||
elif _msvcrt is not None: # pragma: no cover - Windows
|
||||
fd.seek(0)
|
||||
_msvcrt.locking(fd.fileno(), _msvcrt.LK_UNLCK, 1)
|
||||
except OSError:
|
||||
pass
|
||||
fd.close()
|
||||
finally:
|
||||
process_lock.release()
|
||||
|
||||
|
||||
def _read_entries(path: Path) -> list[str]:
|
||||
"""读取一个记忆文件并按分隔符切成条目列表。
|
||||
|
||||
无需加锁:写入用原子 rename,读者总能看到旧文件或新文件的完整内容。
|
||||
"""
|
||||
if not path.exists():
|
||||
return []
|
||||
try:
|
||||
raw = path.read_text(encoding="utf-8")
|
||||
except OSError:
|
||||
return []
|
||||
if not raw.strip():
|
||||
return []
|
||||
entries = [e.strip() for e in raw.split(ENTRY_DELIMITER)]
|
||||
return [e for e in entries if e]
|
||||
|
||||
|
||||
def _write_entries(path: Path, entries: list[str]) -> None:
|
||||
"""用临时文件 + 原子 rename 写入记忆文件。"""
|
||||
content = ENTRY_DELIMITER.join(entries) if entries else ""
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp", prefix=".mem_")
|
||||
try:
|
||||
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
||||
f.write(content)
|
||||
f.flush()
|
||||
os.fsync(f.fileno())
|
||||
os.replace(tmp_path, path)
|
||||
except BaseException:
|
||||
try:
|
||||
os.unlink(tmp_path)
|
||||
except OSError:
|
||||
pass
|
||||
raise
|
||||
|
||||
|
||||
class BuiltinFileProvider(MemoryProvider):
|
||||
"""本地文件记忆 provider,始终可用,不可移除。"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
memory_char_limit: int = 2200,
|
||||
user_char_limit: int = 1375,
|
||||
deduplicate_on_load: bool = True,
|
||||
security: SecurityConfig | None = None,
|
||||
) -> None:
|
||||
self._memory_char_limit = memory_char_limit
|
||||
self._user_char_limit = user_char_limit
|
||||
self._deduplicate_on_load = deduplicate_on_load
|
||||
self._security = security or SecurityConfig()
|
||||
|
||||
self._user_id: str = DEFAULT_USER_ID
|
||||
self._agent_id: str = "default"
|
||||
self._user_path: Path | None = None
|
||||
self._memory_path: Path | None = None
|
||||
|
||||
# 实时状态 (工具写入后立即更新并落盘)
|
||||
self._user_entries: list[str] = []
|
||||
self._memory_entries: list[str] = []
|
||||
# frozen snapshot (initialize 时冻结,系统提示词注入用)
|
||||
self._snapshot: dict[str, str] = {"user": "", "memory": ""}
|
||||
|
||||
# ---- 身份 ------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "builtin"
|
||||
|
||||
def is_available(self) -> bool:
|
||||
"""本地文件 provider 无外部依赖,始终可用。"""
|
||||
return True
|
||||
|
||||
# ---- 生命周期 ---------------------------------------------------------
|
||||
|
||||
def initialize(
|
||||
self,
|
||||
*,
|
||||
user_id: str,
|
||||
agent_id: str | None = None,
|
||||
thread_id: str | None = None,
|
||||
base_dir: str = "",
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""解析 per-user / per-agent 路径,加载文件并冻结系统提示词快照。"""
|
||||
self._user_id = user_id or DEFAULT_USER_ID
|
||||
self._agent_id = (agent_id or "default").lower()
|
||||
paths = get_paths()
|
||||
self._user_path = paths.user_profile_md_file(self._user_id)
|
||||
self._memory_path = paths.user_agent_memory_md_file(self._user_id, self._agent_id)
|
||||
self._load_from_disk()
|
||||
|
||||
def _load_from_disk(self) -> None:
|
||||
"""从磁盘加载两个文件,去重,并冻结系统提示词快照。"""
|
||||
assert self._user_path is not None and self._memory_path is not None
|
||||
self._user_entries = _read_entries(self._user_path)
|
||||
self._memory_entries = _read_entries(self._memory_path)
|
||||
if self._deduplicate_on_load:
|
||||
self._user_entries = list(dict.fromkeys(self._user_entries))
|
||||
self._memory_entries = list(dict.fromkeys(self._memory_entries))
|
||||
self._snapshot = {
|
||||
"user": self._render_block("user", self._user_entries),
|
||||
"memory": self._render_block("memory", self._memory_entries),
|
||||
}
|
||||
|
||||
# ---- 系统提示词块 -----------------------------------------------------
|
||||
|
||||
def system_prompt_block(self) -> str:
|
||||
"""返回 frozen snapshot:USER PROFILE 块 + MEMORY 块。
|
||||
|
||||
返回 ``initialize`` 时冻结的内容,会话内的工具写入不影响它 ——
|
||||
保持系统提示词稳定,利于 prefix cache。
|
||||
"""
|
||||
blocks = [b for b in (self._snapshot.get("user"), self._snapshot.get("memory")) if b]
|
||||
return "\n\n".join(blocks)
|
||||
|
||||
def get_tool_schemas(self) -> list[dict[str, Any]]:
|
||||
"""builtin 的 ``memory`` 工具以 LangChain BaseTool 形式独立注册,
|
||||
|
||||
不经 MemoryManager 路由,因此这里返回空列表。
|
||||
"""
|
||||
return []
|
||||
|
||||
# ---- 工具写入操作 (供 memory 工具直接调用) ---------------------------
|
||||
|
||||
def add(self, target: str, content: str) -> dict[str, Any]:
|
||||
"""追加一条记忆条目。超出字符配额时返回错误。"""
|
||||
content = (content or "").strip()
|
||||
if not content:
|
||||
return {"success": False, "error": "条目内容不能为空。"}
|
||||
if (err := self._scan(content)) is not None:
|
||||
return {"success": False, "error": err}
|
||||
|
||||
path = self._path_for(target)
|
||||
with _file_lock(path):
|
||||
entries = self._reload_target(target)
|
||||
if content in entries:
|
||||
return self._success(target, "条目已存在,未重复添加。")
|
||||
limit = self._char_limit(target)
|
||||
new_total = len(ENTRY_DELIMITER.join([*entries, content]))
|
||||
if new_total > limit:
|
||||
current = self._char_count(entries)
|
||||
return {
|
||||
"success": False,
|
||||
"error": (
|
||||
f"记忆已用 {current:,}/{limit:,} 字符,"
|
||||
f"再加这条 ({len(content)} 字符) 会超出配额。"
|
||||
"请先 replace 或 remove 现有条目。"
|
||||
),
|
||||
"entries": entries,
|
||||
}
|
||||
entries.append(content)
|
||||
_write_entries(path, entries)
|
||||
self._set_entries(target, entries)
|
||||
return self._success(target, "条目已添加。")
|
||||
|
||||
def replace(self, target: str, old_text: str, new_content: str) -> dict[str, Any]:
|
||||
"""用 ``old_text`` 短串定位条目,替换为 ``new_content``。"""
|
||||
old_text = (old_text or "").strip()
|
||||
new_content = (new_content or "").strip()
|
||||
if not old_text:
|
||||
return {"success": False, "error": "old_text 不能为空。"}
|
||||
if not new_content:
|
||||
return {"success": False, "error": "new_content 不能为空;删除条目请用 remove。"}
|
||||
if (err := self._scan(new_content)) is not None:
|
||||
return {"success": False, "error": err}
|
||||
|
||||
path = self._path_for(target)
|
||||
with _file_lock(path):
|
||||
entries = self._reload_target(target)
|
||||
matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
|
||||
if not matches:
|
||||
return {"success": False, "error": f"没有条目匹配 '{old_text}'。"}
|
||||
if len({e for _, e in matches}) > 1:
|
||||
previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
|
||||
return {
|
||||
"success": False,
|
||||
"error": f"多个条目匹配 '{old_text}',请用更精确的 old_text。",
|
||||
"matches": previews,
|
||||
}
|
||||
idx = matches[0][0]
|
||||
limit = self._char_limit(target)
|
||||
test_entries = list(entries)
|
||||
test_entries[idx] = new_content
|
||||
new_total = len(ENTRY_DELIMITER.join(test_entries))
|
||||
if new_total > limit:
|
||||
return {
|
||||
"success": False,
|
||||
"error": (
|
||||
f"替换后会达到 {new_total:,}/{limit:,} 字符,超出配额。"
|
||||
"请缩短新内容或先删除其他条目。"
|
||||
),
|
||||
}
|
||||
entries[idx] = new_content
|
||||
_write_entries(path, entries)
|
||||
self._set_entries(target, entries)
|
||||
return self._success(target, "条目已替换。")
|
||||
|
||||
def remove(self, target: str, old_text: str) -> dict[str, Any]:
|
||||
"""用 ``old_text`` 短串定位并删除条目。"""
|
||||
old_text = (old_text or "").strip()
|
||||
if not old_text:
|
||||
return {"success": False, "error": "old_text 不能为空。"}
|
||||
|
||||
path = self._path_for(target)
|
||||
with _file_lock(path):
|
||||
entries = self._reload_target(target)
|
||||
matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
|
||||
if not matches:
|
||||
return {"success": False, "error": f"没有条目匹配 '{old_text}'。"}
|
||||
if len({e for _, e in matches}) > 1:
|
||||
previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
|
||||
return {
|
||||
"success": False,
|
||||
"error": f"多个条目匹配 '{old_text}',请用更精确的 old_text。",
|
||||
"matches": previews,
|
||||
}
|
||||
entries.pop(matches[0][0])
|
||||
_write_entries(path, entries)
|
||||
self._set_entries(target, entries)
|
||||
return self._success(target, "条目已删除。")
|
||||
|
||||
def read(self, target: str) -> list[str]:
|
||||
"""返回某 target 的实时条目列表 (从磁盘重读)。"""
|
||||
return self._reload_target(target)
|
||||
|
||||
def usage(self, target: str) -> str:
|
||||
"""返回某 target 的字符用量描述,如 ``'12% — 165/1375 字符'``。"""
|
||||
entries = self._reload_target(target)
|
||||
current = self._char_count(entries)
|
||||
limit = self._char_limit(target)
|
||||
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
|
||||
return f"{pct}% — {current:,}/{limit:,} 字符"
|
||||
|
||||
# ---- 内部辅助 --------------------------------------------------------
|
||||
|
||||
def _scan(self, content: str) -> str | None:
|
||||
return scan_memory_content(
|
||||
content,
|
||||
scan_threats=self._security.scan_content,
|
||||
block_invisible_unicode=self._security.block_invisible_unicode,
|
||||
)
|
||||
|
||||
def _path_for(self, target: str) -> Path:
|
||||
if target not in _VALID_TARGETS:
|
||||
raise ValueError(f"非法 target '{target}',只能是 'memory' 或 'user'。")
|
||||
if self._user_path is None or self._memory_path is None:
|
||||
raise RuntimeError("BuiltinFileProvider 未初始化,请先调用 initialize()。")
|
||||
return self._user_path if target == "user" else self._memory_path
|
||||
|
||||
def _char_limit(self, target: str) -> int:
|
||||
return self._user_char_limit if target == "user" else self._memory_char_limit
|
||||
|
||||
@staticmethod
|
||||
def _char_count(entries: list[str]) -> int:
|
||||
return len(ENTRY_DELIMITER.join(entries)) if entries else 0
|
||||
|
||||
def _reload_target(self, target: str) -> list[str]:
|
||||
"""加锁状态下从磁盘重读条目 (拿到其他会话写入的最新状态)。"""
|
||||
entries = _read_entries(self._path_for(target))
|
||||
if self._deduplicate_on_load:
|
||||
entries = list(dict.fromkeys(entries))
|
||||
self._set_entries(target, entries)
|
||||
return entries
|
||||
|
||||
def _set_entries(self, target: str, entries: list[str]) -> None:
|
||||
if target == "user":
|
||||
self._user_entries = entries
|
||||
else:
|
||||
self._memory_entries = entries
|
||||
|
||||
def _success(self, target: str, message: str) -> dict[str, Any]:
|
||||
entries = self._user_entries if target == "user" else self._memory_entries
|
||||
current = self._char_count(entries)
|
||||
limit = self._char_limit(target)
|
||||
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
|
||||
return {
|
||||
"success": True,
|
||||
"target": target,
|
||||
"entries": entries,
|
||||
"entry_count": len(entries),
|
||||
"usage": f"{pct}% — {current:,}/{limit:,} 字符",
|
||||
"message": message,
|
||||
}
|
||||
|
||||
def _render_block(self, target: str, entries: list[str]) -> str:
|
||||
"""渲染一个系统提示词块 (带表头和用量指示)。"""
|
||||
if not entries:
|
||||
return ""
|
||||
limit = self._char_limit(target)
|
||||
content = ENTRY_DELIMITER.join(entries)
|
||||
current = len(content)
|
||||
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
|
||||
if target == "user":
|
||||
header = f"用户画像 USER PROFILE [{pct}% — {current:,}/{limit:,} 字符]"
|
||||
else:
|
||||
header = f"记忆笔记 MEMORY [{pct}% — {current:,}/{limit:,} 字符]"
|
||||
separator = "═" * 46
|
||||
return f"{separator}\n{header}\n{separator}\n{content}"
|
||||
|
||||
|
||||
__all__ = ["BuiltinFileProvider", "ENTRY_DELIMITER"]
|
||||
+462
@@ -0,0 +1,462 @@
|
||||
"""Memory V2 - Hindsight 外部 provider。
|
||||
|
||||
Hindsight 是带知识图谱、实体消解、多策略检索的长期记忆服务。本 provider 以
|
||||
HTTP 客户端方式接入一个用户自起的 Hindsight Docker 实例 (``local_external`` 模式)。
|
||||
|
||||
双 bank 隔离 (B 方案,详见 docs/MEMORY_V2_DESIGN_ZH.md §3)
|
||||
==========================================================
|
||||
- 全局 user bank ``bank_id_template`` 例:``deerflow-user-{user_id}``
|
||||
存用户身份、偏好,跨 agent 共享。
|
||||
- agent 工作 bank ``work_bank_id_template`` 例:``deerflow-work-{user_id}-{agent_id}``
|
||||
存 agent 私有工作笔记。
|
||||
|
||||
写入路由:
|
||||
- LLM 主动 ``memory(target="user")`` -> 镜像到 user bank
|
||||
- LLM 主动 ``memory(target="memory")`` -> 镜像到 work bank
|
||||
- 自动 retain 的对话 (``sync_turn``) -> work bank
|
||||
|
||||
召回:``prefetch`` 并发查两个 bank,合并结果。
|
||||
|
||||
document_id 与轮次计数
|
||||
======================
|
||||
本 provider 被 ``build_memory_manager`` 每轮重新构造 —— 是无状态的。因此:
|
||||
- ``document_id`` 每次 ``initialize`` 用带时间戳的新值,每轮对话的 retain 落到
|
||||
各自独立的 Hindsight 文档。
|
||||
- ``retain_every_n_turns`` 的轮次判定依赖外部传入的 ``turn_index``
|
||||
(由 ``MemoryMiddleware`` 按对话历史算出);未传时退回进程内 ``_turn_counter``。
|
||||
|
||||
客户端生命周期
|
||||
==============
|
||||
``_run_coro`` 每次操作新建一个事件循环。aiohttp ``ClientSession`` 是
|
||||
loop-bound 的,跨 loop 复用会泄漏并失效。因此本 provider **不缓存客户端** ——
|
||||
每次记忆操作在 :meth:`_run_with_client` 里即开即关,保证 session 在其所属的
|
||||
loop 内被正常关闭。
|
||||
|
||||
降级
|
||||
====
|
||||
``hindsight-client`` 是可选依赖。未安装或未配置 ``api_url`` 时 :meth:`is_available`
|
||||
返回 ``False``,provider 不会被注册,记忆系统退回纯 builtin —— 不影响任何功能。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import threading
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from deerflow.agents.memory.provider import MemoryProvider
|
||||
from deerflow.config.memory_config import HindsightMemoryConfig
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
#: hindsight-client 最低版本。
|
||||
MIN_CLIENT_VERSION = "0.4.22"
|
||||
|
||||
|
||||
def hindsight_client_available() -> bool:
|
||||
"""返回 ``hindsight-client`` 包是否已安装 (不导入实际客户端)。"""
|
||||
import importlib.util
|
||||
|
||||
return importlib.util.find_spec("hindsight_client") is not None
|
||||
|
||||
|
||||
def _run_coro(coro: Any, timeout: float) -> Any:
|
||||
"""把一个 async coro 跑到完成并返回结果 (带超时)。
|
||||
|
||||
deerflow 的中间件钩子有同步也有异步路径;本 helper 两种场景都能用:
|
||||
- 当前线程没有运行中的事件循环 -> 直接 ``asyncio.run``
|
||||
- 当前线程已在事件循环里 -> 另起线程跑,避免嵌套循环报错
|
||||
"""
|
||||
try:
|
||||
asyncio.get_running_loop()
|
||||
in_loop = True
|
||||
except RuntimeError:
|
||||
in_loop = False
|
||||
|
||||
if not in_loop:
|
||||
return asyncio.run(asyncio.wait_for(coro, timeout))
|
||||
|
||||
box: dict[str, Any] = {}
|
||||
|
||||
def _runner() -> None:
|
||||
try:
|
||||
box["value"] = asyncio.run(asyncio.wait_for(coro, timeout))
|
||||
except BaseException as exc: # noqa: BLE001 - 跨线程传递异常
|
||||
box["error"] = exc
|
||||
|
||||
thread = threading.Thread(target=_runner, name="hindsight-coro", daemon=True)
|
||||
thread.start()
|
||||
thread.join(timeout + 5)
|
||||
if "error" in box:
|
||||
raise box["error"]
|
||||
if "value" not in box:
|
||||
raise TimeoutError("Hindsight 操作超时")
|
||||
return box["value"]
|
||||
|
||||
|
||||
def _utc_now_iso() -> str:
|
||||
return datetime.now(UTC).isoformat()
|
||||
|
||||
|
||||
class HindsightProvider(MemoryProvider):
|
||||
"""Hindsight 外部记忆 provider。"""
|
||||
|
||||
def __init__(self, config: HindsightMemoryConfig | None = None) -> None:
|
||||
self._config = config or HindsightMemoryConfig()
|
||||
|
||||
self._user_id: str = ""
|
||||
self._agent_id: str = "default"
|
||||
self._thread_id: str = ""
|
||||
self._user_bank: str = ""
|
||||
self._work_bank: str = ""
|
||||
|
||||
# retain 批次的 document id 与轮次计数 (on_session_switch 会重置)
|
||||
self._document_id: str = ""
|
||||
self._turn_counter: int = 0
|
||||
|
||||
# ---- 身份 ------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "hindsight"
|
||||
|
||||
def is_available(self) -> bool:
|
||||
"""配置完整且 hindsight-client 已安装时才可用。"""
|
||||
if not hindsight_client_available():
|
||||
logger.debug("Hindsight 不可用:hindsight-client 未安装")
|
||||
return False
|
||||
if not self._config.api_url:
|
||||
logger.debug("Hindsight 不可用:未配置 api_url")
|
||||
return False
|
||||
return True
|
||||
|
||||
# ---- 生命周期 ---------------------------------------------------------
|
||||
|
||||
def initialize(
|
||||
self,
|
||||
*,
|
||||
user_id: str,
|
||||
agent_id: str | None = None,
|
||||
thread_id: str | None = None,
|
||||
base_dir: str = "",
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""解析双 bank 名称,准备 retain 批次状态。客户端每次操作即开即关。"""
|
||||
self._user_id = user_id or "default"
|
||||
self._agent_id = (agent_id or "default").lower()
|
||||
self._thread_id = thread_id or ""
|
||||
self._user_bank = self._resolve_bank(self._config.bank_id_template)
|
||||
self._work_bank = self._resolve_bank(self._config.work_bank_id_template)
|
||||
self._reset_retain_batch()
|
||||
|
||||
def _resolve_bank(self, template: str) -> str:
|
||||
"""用 user_id / agent_id / thread_id 填充 bank 名称模板。
|
||||
|
||||
空占位符会塌缩 (例如 ``deerflow-{thread_id}`` 在无 thread 时变成 ``deerflow-``,
|
||||
再清理多余连字符)。
|
||||
"""
|
||||
name = template.format(
|
||||
user_id=self._user_id,
|
||||
agent_id=self._agent_id,
|
||||
thread_id=self._thread_id,
|
||||
)
|
||||
# 清理空占位符塌缩留下的多余连字符
|
||||
while "--" in name:
|
||||
name = name.replace("--", "-")
|
||||
return name.strip("-") or "deerflow"
|
||||
|
||||
def _reset_retain_batch(self) -> None:
|
||||
"""重置 retain 批次状态 (新的 document_id + 轮次清零)。
|
||||
|
||||
每次 ``initialize`` 用带时间戳的新 ``document_id`` —— 每轮对话的 retain
|
||||
落到各自独立的 Hindsight 文档。轮次计数清零,仅作为 ``turn_index`` 缺失
|
||||
时的退路。
|
||||
"""
|
||||
ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
|
||||
self._document_id = f"{self._thread_id or 'thread'}-{ts}"
|
||||
self._turn_counter = 0
|
||||
|
||||
def shutdown(self) -> None:
|
||||
"""无需清理 —— 客户端在每次操作内即开即关,不缓存。"""
|
||||
|
||||
# ---- 客户端生命周期 --------------------------------------------------
|
||||
|
||||
def _client_factory(self) -> Any:
|
||||
"""创建一个新的 Hindsight HTTP 客户端。
|
||||
|
||||
每次记忆操作都新建一个、用完即关,**不缓存** —— aiohttp ClientSession
|
||||
是 loop-bound 的,而 ``_run_coro`` 每次新建事件循环。测试可覆盖本方法
|
||||
注入 fake 客户端。
|
||||
"""
|
||||
from hindsight_client import Hindsight
|
||||
|
||||
kwargs: dict[str, Any] = {
|
||||
"base_url": self._config.api_url,
|
||||
"timeout": 30.0,
|
||||
}
|
||||
if self._config.api_key:
|
||||
kwargs["api_key"] = self._config.api_key
|
||||
return Hindsight(**kwargs)
|
||||
|
||||
@staticmethod
|
||||
async def _aclose_client(client: Any) -> None:
|
||||
"""关闭客户端 (兼容暴露 ``aclose`` 或 ``close`` 的实现)。"""
|
||||
close = getattr(client, "aclose", None) or getattr(client, "close", None)
|
||||
if close is None:
|
||||
return
|
||||
try:
|
||||
result = close()
|
||||
if asyncio.iscoroutine(result):
|
||||
await result
|
||||
except Exception as exc: # noqa: BLE001 - 关闭失败不影响结果
|
||||
logger.debug("Hindsight 客户端关闭失败:%s", exc)
|
||||
|
||||
async def _run_with_client(self, op: Any) -> Any:
|
||||
"""在当前事件循环内创建客户端、执行 ``op(client)``、保证关闭客户端。
|
||||
|
||||
``op`` 是一个接收 client、返回 awaitable 的协程函数。无论成功、异常还是
|
||||
被取消 (超时),``finally`` 都会关闭客户端 —— 杜绝 ``Unclosed client session``。
|
||||
"""
|
||||
client = self._client_factory()
|
||||
try:
|
||||
return await op(client)
|
||||
finally:
|
||||
await self._aclose_client(client)
|
||||
|
||||
# ---- 系统提示词块 -----------------------------------------------------
|
||||
|
||||
def system_prompt_block(self) -> str:
|
||||
"""返回一小段静态说明 (告诉 LLM Hindsight 处于哪种模式)。"""
|
||||
mode = self._config.memory_mode
|
||||
if mode == "context":
|
||||
return "" # context 模式纯后台,无需告知 LLM
|
||||
if mode == "tools":
|
||||
return (
|
||||
"# Hindsight 长期记忆\n"
|
||||
"可用 hindsight_recall 检索、hindsight_reflect 综合、hindsight_retain 存储。"
|
||||
)
|
||||
return (
|
||||
"# Hindsight 长期记忆\n"
|
||||
"相关记忆会自动注入上下文;也可用 hindsight_recall / hindsight_reflect / "
|
||||
"hindsight_retain 主动检索与存储。"
|
||||
)
|
||||
|
||||
# ---- 召回 ------------------------------------------------------------
|
||||
|
||||
def prefetch(self, query: str, *, thread_id: str = "") -> str:
|
||||
"""并发召回两个 bank 并合并结果。
|
||||
|
||||
``memory_mode='tools'`` 或 ``auto_recall=False`` 时不做自动召回。
|
||||
召回失败 (Hindsight 不可达等) 返回空串,不抛异常。
|
||||
"""
|
||||
if self._config.memory_mode == "tools":
|
||||
return ""
|
||||
if not self._config.auto_recall:
|
||||
return ""
|
||||
query = (query or "").strip()
|
||||
if not query:
|
||||
return ""
|
||||
if self._config.recall_max_input_chars and len(query) > self._config.recall_max_input_chars:
|
||||
query = query[: self._config.recall_max_input_chars]
|
||||
|
||||
try:
|
||||
merged = self._recall_both(query)
|
||||
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
|
||||
logger.debug("Hindsight 召回失败 (非致命):%s", exc)
|
||||
return ""
|
||||
|
||||
if not merged:
|
||||
return ""
|
||||
lines = "\n".join(f"- {text}" for text in merged)
|
||||
return (
|
||||
"# Hindsight 记忆召回 (跨会话持久上下文)\n"
|
||||
"下面是与当前对话相关的历史记忆,可据此回答关于用户和过往会话的问题。\n\n"
|
||||
f"{lines}"
|
||||
)
|
||||
|
||||
def _recall_both(self, query: str) -> list[str]:
|
||||
"""并发召回 user + work 两个 bank,合并去重。一次操作共用一个客户端。"""
|
||||
|
||||
async def _op(client: Any) -> tuple[Any, Any]:
|
||||
return await asyncio.gather(
|
||||
client.arecall(
|
||||
bank_id=self._user_bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
max_tokens=self._config.recall_max_tokens,
|
||||
),
|
||||
client.arecall(
|
||||
bank_id=self._work_bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
max_tokens=self._config.recall_max_tokens,
|
||||
),
|
||||
)
|
||||
|
||||
user_resp, work_resp = _run_coro(self._run_with_client(_op), timeout=15)
|
||||
return self._merge_results(
|
||||
self._extract_results(user_resp),
|
||||
self._extract_results(work_resp),
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _extract_results(resp: Any) -> list[tuple[float, str]]:
|
||||
"""从一个 recall 响应里抽出 ``[(score, text), ...]``。"""
|
||||
results = getattr(resp, "results", None) or []
|
||||
out: list[tuple[float, str]] = []
|
||||
for r in results:
|
||||
text = (getattr(r, "text", "") or "").strip()
|
||||
if text:
|
||||
out.append((float(getattr(r, "score", 0.0) or 0.0), text))
|
||||
return out
|
||||
|
||||
@staticmethod
|
||||
def _merge_results(
|
||||
user_results: list[tuple[float, str]],
|
||||
work_results: list[tuple[float, str]],
|
||||
) -> list[str]:
|
||||
"""合并双 bank 召回结果:按 score 倒序,去重保序。"""
|
||||
combined = sorted(user_results + work_results, key=lambda x: -x[0])
|
||||
seen: set[str] = set()
|
||||
merged: list[str] = []
|
||||
for _, text in combined:
|
||||
if text not in seen:
|
||||
seen.add(text)
|
||||
merged.append(text)
|
||||
return merged
|
||||
|
||||
# ---- 写入 ------------------------------------------------------------
|
||||
|
||||
def sync_turn(
|
||||
self,
|
||||
user_content: str,
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""自动 retain 一轮对话到 work bank。
|
||||
|
||||
``auto_retain=False`` 时不写。按 ``retain_every_n_turns`` 控制频率。
|
||||
|
||||
轮次判定优先用调用方传入的 ``turn_index`` (由 MemoryMiddleware 按对话历史
|
||||
算出) —— 因为本 provider 每轮被重建、进程内 ``_turn_counter`` 会被重置,
|
||||
单靠它在 ``retain_every_n_turns > 1`` 时会永远不触发。``turn_index`` 缺失
|
||||
时才退回 ``_turn_counter``。
|
||||
"""
|
||||
if not self._config.auto_retain:
|
||||
return
|
||||
|
||||
if turn_index is not None:
|
||||
counter = turn_index
|
||||
else:
|
||||
self._turn_counter += 1
|
||||
counter = self._turn_counter
|
||||
|
||||
every = max(1, self._config.retain_every_n_turns)
|
||||
if counter % every != 0:
|
||||
return
|
||||
|
||||
turn_text = (
|
||||
f"{self._config.retain_user_prefix}: {user_content}\n"
|
||||
f"{self._config.retain_assistant_prefix}: {assistant_content}"
|
||||
)
|
||||
try:
|
||||
self._retain(self._work_bank, turn_text, kind="conversation")
|
||||
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
|
||||
logger.warning("Hindsight sync_turn 写入失败:%s", exc)
|
||||
|
||||
def on_memory_write(
|
||||
self,
|
||||
action: str,
|
||||
target: str,
|
||||
content: str,
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
"""builtin 写入时镜像到 Hindsight。
|
||||
|
||||
``target="user"`` -> user bank;``target="memory"`` -> work bank。
|
||||
目前只镜像 ``add`` / ``replace`` 的新内容 (Hindsight 是 append-only 语义,
|
||||
``remove`` 不反向删除)。
|
||||
"""
|
||||
if action not in ("add", "replace"):
|
||||
return
|
||||
content = (content or "").strip()
|
||||
if not content:
|
||||
return
|
||||
bank = self._user_bank if target == "user" else self._work_bank
|
||||
try:
|
||||
self._retain(bank, content, kind=f"builtin_{target}")
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.debug("Hindsight on_memory_write 镜像失败:%s", exc)
|
||||
|
||||
def _retain(self, bank_id: str, content: str, *, kind: str) -> None:
|
||||
"""向某 bank 写入一条记忆。客户端即开即关。"""
|
||||
metadata = {
|
||||
"retained_at": _utc_now_iso(),
|
||||
"kind": kind,
|
||||
"user_id": self._user_id,
|
||||
"agent_id": self._agent_id,
|
||||
}
|
||||
if self._thread_id:
|
||||
metadata["thread_id"] = self._thread_id
|
||||
|
||||
async def _op(client: Any) -> Any:
|
||||
return await client.aretain(
|
||||
bank_id=bank_id,
|
||||
content=content,
|
||||
context=self._config.bank_retain_mission or None,
|
||||
metadata=metadata,
|
||||
document_id=self._document_id,
|
||||
retain_async=self._config.retain_async,
|
||||
)
|
||||
|
||||
_run_coro(self._run_with_client(_op), timeout=15)
|
||||
|
||||
def reflect(self, query: str, *, use_user_bank: bool = True) -> str:
|
||||
"""对某 bank 做跨记忆综合 (LLM 推理)。供 hindsight_reflect 工具调用。"""
|
||||
bank = self._user_bank if use_user_bank else self._work_bank
|
||||
|
||||
async def _op(client: Any) -> Any:
|
||||
return await client.areflect(
|
||||
bank_id=bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
)
|
||||
|
||||
resp = _run_coro(self._run_with_client(_op), timeout=30)
|
||||
return getattr(resp, "text", "") or ""
|
||||
|
||||
def recall(self, query: str) -> list[str]:
|
||||
"""召回双 bank 并返回文本列表。供 hindsight_recall 工具调用。"""
|
||||
return self._recall_both(query)
|
||||
|
||||
def retain_to_user_bank(self, content: str) -> None:
|
||||
"""主动写入 user bank。供 hindsight_retain 工具调用。"""
|
||||
self._retain(self._user_bank, content, kind="tool_retain")
|
||||
|
||||
# ---- LLM 工具 --------------------------------------------------------
|
||||
|
||||
def get_tool_schemas(self) -> list[dict[str, Any]]:
|
||||
"""Hindsight 的 3 个工具以 LangChain BaseTool 独立注册,不经 manager 路由。"""
|
||||
return []
|
||||
|
||||
# ---- 可选 hooks ------------------------------------------------------
|
||||
|
||||
def on_session_switch(
|
||||
self,
|
||||
new_thread_id: str,
|
||||
*,
|
||||
parent_thread_id: str = "",
|
||||
reset: bool = False,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""thread 切换:重新解析 work bank,重置 retain 批次。"""
|
||||
self._thread_id = new_thread_id
|
||||
self._work_bank = self._resolve_bank(self._config.work_bank_id_template)
|
||||
self._reset_retain_batch()
|
||||
|
||||
|
||||
__all__ = ["HindsightProvider", "hindsight_client_available", "MIN_CLIENT_VERSION"]
|
||||
@@ -1,277 +0,0 @@
|
||||
"""Memory update queue with debounce mechanism."""
|
||||
|
||||
import logging
|
||||
import threading
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@dataclass
|
||||
class ConversationContext:
|
||||
"""Context for a conversation to be processed for memory update."""
|
||||
|
||||
thread_id: str
|
||||
messages: list[Any]
|
||||
timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
|
||||
agent_name: str | None = None
|
||||
user_id: str | None = None
|
||||
correction_detected: bool = False
|
||||
reinforcement_detected: bool = False
|
||||
|
||||
|
||||
class MemoryUpdateQueue:
|
||||
"""Queue for memory updates with debounce mechanism.
|
||||
|
||||
This queue collects conversation contexts and processes them after
|
||||
a configurable debounce period. Multiple conversations received within
|
||||
the debounce window are batched together.
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""Initialize the memory update queue."""
|
||||
self._queue: list[ConversationContext] = []
|
||||
self._lock = threading.Lock()
|
||||
self._timer: threading.Timer | None = None
|
||||
self._processing = False
|
||||
|
||||
def add(
|
||||
self,
|
||||
thread_id: str,
|
||||
messages: list[Any],
|
||||
agent_name: str | None = None,
|
||||
user_id: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
) -> None:
|
||||
"""Add a conversation to the update queue.
|
||||
|
||||
Args:
|
||||
thread_id: The thread ID.
|
||||
messages: The conversation messages.
|
||||
agent_name: If provided, memory is stored per-agent. If None, uses global memory.
|
||||
user_id: The user ID captured at enqueue time. Stored in ConversationContext so it
|
||||
survives the threading.Timer boundary (ContextVar does not propagate across
|
||||
raw threads).
|
||||
correction_detected: Whether recent turns include an explicit correction signal.
|
||||
reinforcement_detected: Whether recent turns include a positive reinforcement signal.
|
||||
"""
|
||||
config = get_memory_config()
|
||||
if not config.enabled:
|
||||
return
|
||||
|
||||
with self._lock:
|
||||
self._enqueue_locked(
|
||||
thread_id=thread_id,
|
||||
messages=messages,
|
||||
agent_name=agent_name,
|
||||
user_id=user_id,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
)
|
||||
self._reset_timer()
|
||||
|
||||
logger.info("Memory update queued for thread %s, queue size: %d", thread_id, len(self._queue))
|
||||
|
||||
def add_nowait(
|
||||
self,
|
||||
thread_id: str,
|
||||
messages: list[Any],
|
||||
agent_name: str | None = None,
|
||||
user_id: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
) -> None:
|
||||
"""Add a conversation and start processing immediately in the background."""
|
||||
config = get_memory_config()
|
||||
if not config.enabled:
|
||||
return
|
||||
|
||||
with self._lock:
|
||||
self._enqueue_locked(
|
||||
thread_id=thread_id,
|
||||
messages=messages,
|
||||
agent_name=agent_name,
|
||||
user_id=user_id,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
)
|
||||
self._schedule_timer(0)
|
||||
|
||||
logger.info("Memory update queued for immediate processing on thread %s, queue size: %d", thread_id, len(self._queue))
|
||||
|
||||
def _enqueue_locked(
|
||||
self,
|
||||
*,
|
||||
thread_id: str,
|
||||
messages: list[Any],
|
||||
agent_name: str | None,
|
||||
user_id: str | None,
|
||||
correction_detected: bool,
|
||||
reinforcement_detected: bool,
|
||||
) -> None:
|
||||
existing_context = next(
|
||||
(context for context in self._queue if context.thread_id == thread_id),
|
||||
None,
|
||||
)
|
||||
merged_correction_detected = correction_detected or (existing_context.correction_detected if existing_context is not None else False)
|
||||
merged_reinforcement_detected = reinforcement_detected or (existing_context.reinforcement_detected if existing_context is not None else False)
|
||||
context = ConversationContext(
|
||||
thread_id=thread_id,
|
||||
messages=messages,
|
||||
agent_name=agent_name,
|
||||
user_id=user_id,
|
||||
correction_detected=merged_correction_detected,
|
||||
reinforcement_detected=merged_reinforcement_detected,
|
||||
)
|
||||
|
||||
self._queue = [c for c in self._queue if c.thread_id != thread_id]
|
||||
self._queue.append(context)
|
||||
|
||||
def _reset_timer(self) -> None:
|
||||
"""Reset the debounce timer."""
|
||||
config = get_memory_config()
|
||||
self._schedule_timer(config.debounce_seconds)
|
||||
|
||||
logger.debug("Memory update timer set for %ss", config.debounce_seconds)
|
||||
|
||||
def _schedule_timer(self, delay_seconds: float) -> None:
|
||||
"""Schedule queue processing after the provided delay."""
|
||||
# Cancel existing timer if any
|
||||
if self._timer is not None:
|
||||
self._timer.cancel()
|
||||
|
||||
self._timer = threading.Timer(
|
||||
delay_seconds,
|
||||
self._process_queue,
|
||||
)
|
||||
self._timer.daemon = True
|
||||
self._timer.start()
|
||||
|
||||
def _process_queue(self) -> None:
|
||||
"""Process all queued conversation contexts."""
|
||||
# Import here to avoid circular dependency
|
||||
from deerflow.agents.memory.updater import MemoryUpdater
|
||||
|
||||
with self._lock:
|
||||
if self._processing:
|
||||
# Preserve immediate flush semantics even if another worker is active.
|
||||
self._schedule_timer(0)
|
||||
return
|
||||
|
||||
if not self._queue:
|
||||
return
|
||||
|
||||
self._processing = True
|
||||
contexts_to_process = self._queue.copy()
|
||||
self._queue.clear()
|
||||
self._timer = None
|
||||
|
||||
logger.info("Processing %d queued memory updates", len(contexts_to_process))
|
||||
|
||||
try:
|
||||
updater = MemoryUpdater()
|
||||
|
||||
for context in contexts_to_process:
|
||||
try:
|
||||
logger.info("Updating memory for thread %s", context.thread_id)
|
||||
success = updater.update_memory(
|
||||
messages=context.messages,
|
||||
thread_id=context.thread_id,
|
||||
agent_name=context.agent_name,
|
||||
correction_detected=context.correction_detected,
|
||||
reinforcement_detected=context.reinforcement_detected,
|
||||
user_id=context.user_id,
|
||||
)
|
||||
if success:
|
||||
logger.info("Memory updated successfully for thread %s", context.thread_id)
|
||||
else:
|
||||
logger.warning("Memory update skipped/failed for thread %s", context.thread_id)
|
||||
except Exception as e:
|
||||
logger.error("Error updating memory for thread %s: %s", context.thread_id, e)
|
||||
|
||||
# Small delay between updates to avoid rate limiting
|
||||
if len(contexts_to_process) > 1:
|
||||
time.sleep(0.5)
|
||||
|
||||
finally:
|
||||
with self._lock:
|
||||
self._processing = False
|
||||
|
||||
def flush(self) -> None:
|
||||
"""Force immediate processing of the queue.
|
||||
|
||||
This is useful for testing or graceful shutdown.
|
||||
"""
|
||||
with self._lock:
|
||||
if self._timer is not None:
|
||||
self._timer.cancel()
|
||||
self._timer = None
|
||||
|
||||
self._process_queue()
|
||||
|
||||
def flush_nowait(self) -> None:
|
||||
"""Start queue processing immediately in a background thread."""
|
||||
with self._lock:
|
||||
# Daemon thread: queued messages may be lost if the process exits
|
||||
# before _process_queue completes. Acceptable for best-effort memory updates.
|
||||
self._schedule_timer(0)
|
||||
|
||||
def clear(self) -> None:
|
||||
"""Clear the queue without processing.
|
||||
|
||||
This is useful for testing.
|
||||
"""
|
||||
with self._lock:
|
||||
if self._timer is not None:
|
||||
self._timer.cancel()
|
||||
self._timer = None
|
||||
self._queue.clear()
|
||||
self._processing = False
|
||||
|
||||
@property
|
||||
def pending_count(self) -> int:
|
||||
"""Get the number of pending updates."""
|
||||
with self._lock:
|
||||
return len(self._queue)
|
||||
|
||||
@property
|
||||
def is_processing(self) -> bool:
|
||||
"""Check if the queue is currently being processed."""
|
||||
with self._lock:
|
||||
return self._processing
|
||||
|
||||
|
||||
# Global singleton instance
|
||||
_memory_queue: MemoryUpdateQueue | None = None
|
||||
_queue_lock = threading.Lock()
|
||||
|
||||
|
||||
def get_memory_queue() -> MemoryUpdateQueue:
|
||||
"""Get the global memory update queue singleton.
|
||||
|
||||
Returns:
|
||||
The memory update queue instance.
|
||||
"""
|
||||
global _memory_queue
|
||||
with _queue_lock:
|
||||
if _memory_queue is None:
|
||||
_memory_queue = MemoryUpdateQueue()
|
||||
return _memory_queue
|
||||
|
||||
|
||||
def reset_memory_queue() -> None:
|
||||
"""Reset the global memory queue.
|
||||
|
||||
This is useful for testing.
|
||||
"""
|
||||
global _memory_queue
|
||||
with _queue_lock:
|
||||
if _memory_queue is not None:
|
||||
_memory_queue.clear()
|
||||
_memory_queue = None
|
||||
@@ -0,0 +1,141 @@
|
||||
"""Memory V2 - 记忆内容安全扫描。
|
||||
|
||||
记忆条目会被注入到系统提示词里,因此写入前必须扫描,阻断:
|
||||
- Prompt 注入 / 角色劫持 / 隐藏指令
|
||||
- 凭证外渗 (curl/wget 带密钥、读 .env 等敏感文件)
|
||||
- 持久化后门 (写 authorized_keys 等)
|
||||
- 不可见 unicode (零宽字符、双向控制符)
|
||||
|
||||
这是从 Hermes ``tools/memory_tool.py`` 的 ``_scan_memory_content`` 移植而来,
|
||||
并针对 deerflow 的目录结构调整了敏感路径模式。
|
||||
|
||||
扫描默认开启,可由 ``config.memory.security.scan_content`` /
|
||||
``block_invisible_unicode`` 关闭(不建议)。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 威胁正则模式表:(正则, 模式 id)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_THREAT_PATTERNS: list[tuple[re.Pattern[str], str]] = [
|
||||
# --- Prompt 注入 / 角色劫持 ---
|
||||
# 允许多个限定词,如 "ignore ALL above instructions"
|
||||
(re.compile(r"ignore\s+(?:(?:previous|all|above|prior|any)\s+)+instructions", re.IGNORECASE), "prompt_injection"),
|
||||
(re.compile(r"忽略(?:以上|之前|上述|所有|全部|一切)+(?:的)?(?:指令|指示|要求|提示词)"), "prompt_injection_zh"),
|
||||
(re.compile(r"you\s+are\s+now\s+", re.IGNORECASE), "role_hijack"),
|
||||
(re.compile(r"do\s+not\s+tell\s+the\s+user", re.IGNORECASE), "deception_hide"),
|
||||
(re.compile(r"不要(告诉|让)用户(知道)?"), "deception_hide_zh"),
|
||||
(re.compile(r"system\s+prompt\s+override", re.IGNORECASE), "sys_prompt_override"),
|
||||
(re.compile(r"disregard\s+(your|all|any)\s+(instructions|rules|guidelines)", re.IGNORECASE), "disregard_rules"),
|
||||
(re.compile(r"act\s+as\s+(if|though)\s+you\s+(have\s+no|don'?t\s+have)\s+(restrictions|limits|rules)", re.IGNORECASE), "bypass_restrictions"),
|
||||
# --- 凭证外渗 ---
|
||||
(re.compile(r"curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)", re.IGNORECASE), "exfil_curl"),
|
||||
(re.compile(r"wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)", re.IGNORECASE), "exfil_wget"),
|
||||
(re.compile(r"cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass|\.npmrc|\.pypirc)", re.IGNORECASE), "read_secrets"),
|
||||
# --- 持久化后门 ---
|
||||
(re.compile(r"authorized_keys", re.IGNORECASE), "ssh_backdoor"),
|
||||
(re.compile(r"(\$HOME|~)/\.ssh", re.IGNORECASE), "ssh_access"),
|
||||
]
|
||||
|
||||
# 不可见 unicode 字符:零宽字符 + 双向控制符。
|
||||
# 它们肉眼不可见,常被用来在记忆里藏注入 payload。
|
||||
_INVISIBLE_CHARS: frozenset[str] = frozenset(
|
||||
{
|
||||
"", # ZERO WIDTH SPACE
|
||||
"", # ZERO WIDTH NON-JOINER
|
||||
"", # ZERO WIDTH JOINER
|
||||
"", # WORD JOINER
|
||||
"", # ZERO WIDTH NO-BREAK SPACE / BOM
|
||||
"", # LEFT-TO-RIGHT EMBEDDING
|
||||
"", # RIGHT-TO-LEFT EMBEDDING
|
||||
"", # POP DIRECTIONAL FORMATTING
|
||||
"", # LEFT-TO-RIGHT OVERRIDE
|
||||
"", # RIGHT-TO-LEFT OVERRIDE
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
class MemoryContentBlocked(ValueError):
|
||||
"""记忆内容被安全扫描阻断时抛出。
|
||||
|
||||
``pattern_id`` 标明命中的威胁模式,便于上层返回结构化错误。
|
||||
"""
|
||||
|
||||
def __init__(self, pattern_id: str, message: str) -> None:
|
||||
self.pattern_id = pattern_id
|
||||
super().__init__(message)
|
||||
|
||||
|
||||
def scan_memory_content(
|
||||
content: str,
|
||||
*,
|
||||
scan_threats: bool = True,
|
||||
block_invisible_unicode: bool = True,
|
||||
) -> str | None:
|
||||
"""扫描记忆内容,命中威胁时返回错误描述,干净则返回 ``None``。
|
||||
|
||||
不抛异常 —— 返回字符串方便工具层直接塞进 ``{"success": False, "error": ...}``。
|
||||
需要异常语义时用 :func:`assert_memory_content_safe`。
|
||||
|
||||
Parameters
|
||||
----------
|
||||
content:
|
||||
待写入的记忆条目内容。
|
||||
scan_threats:
|
||||
是否扫描注入/外渗模式。对应 ``config.memory.security.scan_content``。
|
||||
block_invisible_unicode:
|
||||
是否阻断不可见 unicode。对应 ``config.memory.security.block_invisible_unicode``。
|
||||
"""
|
||||
if block_invisible_unicode:
|
||||
for char in _INVISIBLE_CHARS:
|
||||
if char in content:
|
||||
return (
|
||||
f"已阻断:内容包含不可见 unicode 字符 U+{ord(char):04X},"
|
||||
"可能是注入 payload。"
|
||||
)
|
||||
|
||||
if scan_threats:
|
||||
for pattern, pattern_id in _THREAT_PATTERNS:
|
||||
if pattern.search(content):
|
||||
return (
|
||||
f"已阻断:内容命中威胁模式 '{pattern_id}'。"
|
||||
"记忆条目会被注入系统提示词,不允许包含注入或外渗内容。"
|
||||
)
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def assert_memory_content_safe(
|
||||
content: str,
|
||||
*,
|
||||
scan_threats: bool = True,
|
||||
block_invisible_unicode: bool = True,
|
||||
) -> None:
|
||||
"""扫描记忆内容,命中威胁时抛出 :class:`MemoryContentBlocked`。
|
||||
|
||||
:func:`scan_memory_content` 的异常版本,供需要异常语义的调用方使用。
|
||||
"""
|
||||
error = scan_memory_content(
|
||||
content,
|
||||
scan_threats=scan_threats,
|
||||
block_invisible_unicode=block_invisible_unicode,
|
||||
)
|
||||
if error is not None:
|
||||
# 从错误描述里反推 pattern_id 不可靠,这里重新扫一遍拿确切 id。
|
||||
pattern_id = "invisible_unicode"
|
||||
for pattern, pid in _THREAT_PATTERNS:
|
||||
if pattern.search(content):
|
||||
pattern_id = pid
|
||||
break
|
||||
raise MemoryContentBlocked(pattern_id, error)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"MemoryContentBlocked",
|
||||
"scan_memory_content",
|
||||
"assert_memory_content_safe",
|
||||
]
|
||||
@@ -1,231 +0,0 @@
|
||||
"""Memory storage providers."""
|
||||
|
||||
import abc
|
||||
import json
|
||||
import logging
|
||||
import threading
|
||||
import uuid
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from deerflow.config.agents_config import AGENT_NAME_PATTERN
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def utc_now_iso_z() -> str:
|
||||
"""Current UTC time as ISO-8601 with ``Z`` suffix (matches prior naive-UTC output)."""
|
||||
return datetime.now(UTC).isoformat().removesuffix("+00:00") + "Z"
|
||||
|
||||
|
||||
def create_empty_memory() -> dict[str, Any]:
|
||||
"""Create an empty memory structure."""
|
||||
return {
|
||||
"version": "1.0",
|
||||
"lastUpdated": utc_now_iso_z(),
|
||||
"user": {
|
||||
"workContext": {"summary": "", "updatedAt": ""},
|
||||
"personalContext": {"summary": "", "updatedAt": ""},
|
||||
"topOfMind": {"summary": "", "updatedAt": ""},
|
||||
},
|
||||
"history": {
|
||||
"recentMonths": {"summary": "", "updatedAt": ""},
|
||||
"earlierContext": {"summary": "", "updatedAt": ""},
|
||||
"longTermBackground": {"summary": "", "updatedAt": ""},
|
||||
},
|
||||
"facts": [],
|
||||
}
|
||||
|
||||
|
||||
class MemoryStorage(abc.ABC):
|
||||
"""Abstract base class for memory storage providers."""
|
||||
|
||||
@abc.abstractmethod
|
||||
def load(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Load memory data for the given agent."""
|
||||
pass
|
||||
|
||||
@abc.abstractmethod
|
||||
def reload(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Force reload memory data for the given agent."""
|
||||
pass
|
||||
|
||||
@abc.abstractmethod
|
||||
def save(self, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
|
||||
"""Save memory data for the given agent."""
|
||||
pass
|
||||
|
||||
|
||||
class FileMemoryStorage(MemoryStorage):
|
||||
"""File-based memory storage provider."""
|
||||
|
||||
def __init__(self):
|
||||
"""Initialize the file memory storage."""
|
||||
# Per-user/agent memory cache: keyed by (user_id, agent_name) tuple (None = global)
|
||||
# Value: (memory_data, file_mtime)
|
||||
self._memory_cache: dict[tuple[str | None, str | None], tuple[dict[str, Any], float | None]] = {}
|
||||
# Guards all reads and writes to _memory_cache across concurrent callers.
|
||||
self._cache_lock = threading.Lock()
|
||||
|
||||
def _validate_agent_name(self, agent_name: str) -> None:
|
||||
"""Validate that the agent name is safe to use in filesystem paths.
|
||||
|
||||
Uses the repository's established AGENT_NAME_PATTERN to ensure consistency
|
||||
across the codebase and prevent path traversal or other problematic characters.
|
||||
"""
|
||||
if not agent_name:
|
||||
raise ValueError("Agent name must be a non-empty string.")
|
||||
if not AGENT_NAME_PATTERN.match(agent_name):
|
||||
raise ValueError(f"Invalid agent name {agent_name!r}: names must match {AGENT_NAME_PATTERN.pattern}")
|
||||
|
||||
def _get_memory_file_path(self, agent_name: str | None = None, *, user_id: str | None = None) -> Path:
|
||||
"""Get the path to the memory file."""
|
||||
if user_id is not None:
|
||||
if agent_name is not None:
|
||||
self._validate_agent_name(agent_name)
|
||||
return get_paths().user_agent_memory_file(user_id, agent_name)
|
||||
config = get_memory_config()
|
||||
if config.storage_path and Path(config.storage_path).is_absolute():
|
||||
return Path(config.storage_path)
|
||||
return get_paths().user_memory_file(user_id)
|
||||
# Legacy: no user_id
|
||||
if agent_name is not None:
|
||||
self._validate_agent_name(agent_name)
|
||||
return get_paths().agent_memory_file(agent_name)
|
||||
config = get_memory_config()
|
||||
if config.storage_path:
|
||||
p = Path(config.storage_path)
|
||||
return p if p.is_absolute() else get_paths().base_dir / p
|
||||
return get_paths().memory_file
|
||||
|
||||
def _load_memory_from_file(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Load memory data from file."""
|
||||
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
|
||||
|
||||
if not file_path.exists():
|
||||
return create_empty_memory()
|
||||
|
||||
try:
|
||||
with open(file_path, encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
return data
|
||||
except (json.JSONDecodeError, OSError) as e:
|
||||
logger.warning("Failed to load memory file: %s", e)
|
||||
return create_empty_memory()
|
||||
|
||||
@staticmethod
|
||||
def _cache_key(agent_name: str | None = None, *, user_id: str | None = None) -> tuple[str | None, str | None]:
|
||||
return (user_id, agent_name)
|
||||
|
||||
def load(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Load memory data (cached with file modification time check)."""
|
||||
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
|
||||
cache_key = self._cache_key(agent_name, user_id=user_id)
|
||||
|
||||
try:
|
||||
current_mtime = file_path.stat().st_mtime if file_path.exists() else None
|
||||
except OSError:
|
||||
current_mtime = None
|
||||
|
||||
with self._cache_lock:
|
||||
cached = self._memory_cache.get(cache_key)
|
||||
if cached is not None and cached[1] == current_mtime:
|
||||
return cached[0]
|
||||
|
||||
memory_data = self._load_memory_from_file(agent_name, user_id=user_id)
|
||||
|
||||
with self._cache_lock:
|
||||
self._memory_cache[cache_key] = (memory_data, current_mtime)
|
||||
|
||||
return memory_data
|
||||
|
||||
def reload(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Reload memory data from file, forcing cache invalidation."""
|
||||
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
|
||||
memory_data = self._load_memory_from_file(agent_name, user_id=user_id)
|
||||
cache_key = self._cache_key(agent_name, user_id=user_id)
|
||||
|
||||
try:
|
||||
mtime = file_path.stat().st_mtime if file_path.exists() else None
|
||||
except OSError:
|
||||
mtime = None
|
||||
|
||||
with self._cache_lock:
|
||||
self._memory_cache[cache_key] = (memory_data, mtime)
|
||||
return memory_data
|
||||
|
||||
def save(self, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
|
||||
"""Save memory data to file and update cache."""
|
||||
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
|
||||
cache_key = self._cache_key(agent_name, user_id=user_id)
|
||||
|
||||
try:
|
||||
file_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
# Shallow-copy before adding lastUpdated so the caller's dict is not
|
||||
# mutated as a side-effect, and the cache reference is not silently
|
||||
# updated before the file write succeeds.
|
||||
memory_data = {**memory_data, "lastUpdated": utc_now_iso_z()}
|
||||
|
||||
temp_path = file_path.with_suffix(f".{uuid.uuid4().hex}.tmp")
|
||||
with open(temp_path, "w", encoding="utf-8") as f:
|
||||
json.dump(memory_data, f, indent=2, ensure_ascii=False)
|
||||
|
||||
temp_path.replace(file_path)
|
||||
|
||||
try:
|
||||
mtime = file_path.stat().st_mtime
|
||||
except OSError:
|
||||
mtime = None
|
||||
|
||||
with self._cache_lock:
|
||||
self._memory_cache[cache_key] = (memory_data, mtime)
|
||||
logger.info("Memory saved to %s", file_path)
|
||||
return True
|
||||
except OSError as e:
|
||||
logger.error("Failed to save memory file: %s", e)
|
||||
return False
|
||||
|
||||
|
||||
_storage_instance: MemoryStorage | None = None
|
||||
_storage_lock = threading.Lock()
|
||||
|
||||
|
||||
def get_memory_storage() -> MemoryStorage:
|
||||
"""Get the configured memory storage instance."""
|
||||
global _storage_instance
|
||||
if _storage_instance is not None:
|
||||
return _storage_instance
|
||||
|
||||
with _storage_lock:
|
||||
if _storage_instance is not None:
|
||||
return _storage_instance
|
||||
|
||||
config = get_memory_config()
|
||||
storage_class_path = config.storage_class
|
||||
|
||||
try:
|
||||
module_path, class_name = storage_class_path.rsplit(".", 1)
|
||||
import importlib
|
||||
|
||||
module = importlib.import_module(module_path)
|
||||
storage_class = getattr(module, class_name)
|
||||
|
||||
# Validate that the configured storage is a MemoryStorage implementation
|
||||
if not isinstance(storage_class, type):
|
||||
raise TypeError(f"Configured memory storage '{storage_class_path}' is not a class: {storage_class!r}")
|
||||
if not issubclass(storage_class, MemoryStorage):
|
||||
raise TypeError(f"Configured memory storage '{storage_class_path}' is not a subclass of MemoryStorage")
|
||||
|
||||
_storage_instance = storage_class()
|
||||
except Exception as e:
|
||||
logger.error(
|
||||
"Failed to load memory storage %s, falling back to FileMemoryStorage: %s",
|
||||
storage_class_path,
|
||||
e,
|
||||
)
|
||||
_storage_instance = FileMemoryStorage()
|
||||
|
||||
return _storage_instance
|
||||
-31
@@ -1,31 +0,0 @@
|
||||
"""Hooks fired before summarization removes messages from state."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
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.middlewares.summarization_middleware import SummarizationEvent
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
|
||||
|
||||
def memory_flush_hook(event: SummarizationEvent) -> None:
|
||||
"""Flush messages about to be summarized into the memory queue."""
|
||||
if not get_memory_config().enabled or not event.thread_id:
|
||||
return
|
||||
|
||||
filtered_messages = filter_messages_for_memory(list(event.messages_to_summarize))
|
||||
user_messages = [message for message in filtered_messages if getattr(message, "type", None) == "human"]
|
||||
assistant_messages = [message for message in filtered_messages if getattr(message, "type", None) == "ai"]
|
||||
if not user_messages or not assistant_messages:
|
||||
return
|
||||
|
||||
correction_detected = detect_correction(filtered_messages)
|
||||
reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
|
||||
queue = get_memory_queue()
|
||||
queue.add_nowait(
|
||||
thread_id=event.thread_id,
|
||||
messages=filtered_messages,
|
||||
agent_name=event.agent_name,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
)
|
||||
@@ -1,723 +0,0 @@
|
||||
"""Memory updater for reading, writing, and updating memory data."""
|
||||
|
||||
import asyncio
|
||||
import atexit
|
||||
import concurrent.futures
|
||||
import copy
|
||||
import json
|
||||
import logging
|
||||
import math
|
||||
import re
|
||||
import uuid
|
||||
from typing import Any
|
||||
|
||||
from deerflow.agents.memory.prompt import (
|
||||
MEMORY_UPDATE_PROMPT,
|
||||
format_conversation_for_update,
|
||||
)
|
||||
from deerflow.agents.memory.storage import (
|
||||
create_empty_memory,
|
||||
get_memory_storage,
|
||||
utc_now_iso_z,
|
||||
)
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
from deerflow.models import create_chat_model
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# Thread pool for offloading sync memory updates when called from an async
|
||||
# context. Unlike the previous asyncio.run() approach, this runs *sync*
|
||||
# model.invoke() calls — no event loop is created, so the langchain async
|
||||
# httpx client pool (globally cached via @lru_cache) is never touched and
|
||||
# cross-loop connection reuse is impossible.
|
||||
_SYNC_MEMORY_UPDATER_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
|
||||
max_workers=4,
|
||||
thread_name_prefix="memory-updater-sync",
|
||||
)
|
||||
atexit.register(lambda: _SYNC_MEMORY_UPDATER_EXECUTOR.shutdown(wait=False))
|
||||
|
||||
|
||||
def _create_empty_memory() -> dict[str, Any]:
|
||||
"""Backward-compatible wrapper around the storage-layer empty-memory factory."""
|
||||
return create_empty_memory()
|
||||
|
||||
|
||||
def _save_memory_to_file(memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
|
||||
"""Backward-compatible wrapper around the configured memory storage save path."""
|
||||
return get_memory_storage().save(memory_data, agent_name, user_id=user_id)
|
||||
|
||||
|
||||
def get_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Get the current memory data via storage provider."""
|
||||
return get_memory_storage().load(agent_name, user_id=user_id)
|
||||
|
||||
|
||||
def reload_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Reload memory data via storage provider."""
|
||||
return get_memory_storage().reload(agent_name, user_id=user_id)
|
||||
|
||||
|
||||
def import_memory_data(memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Persist imported memory data via storage provider.
|
||||
|
||||
Args:
|
||||
memory_data: Full memory payload to persist.
|
||||
agent_name: If provided, imports into per-agent memory.
|
||||
user_id: If provided, scopes memory to a specific user.
|
||||
|
||||
Returns:
|
||||
The saved memory data after storage normalization.
|
||||
|
||||
Raises:
|
||||
OSError: If persisting the imported memory fails.
|
||||
"""
|
||||
storage = get_memory_storage()
|
||||
if not storage.save(memory_data, agent_name, user_id=user_id):
|
||||
raise OSError("Failed to save imported memory data")
|
||||
return storage.load(agent_name, user_id=user_id)
|
||||
|
||||
|
||||
def clear_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Clear all stored memory data and persist an empty structure."""
|
||||
cleared_memory = create_empty_memory()
|
||||
if not _save_memory_to_file(cleared_memory, agent_name, user_id=user_id):
|
||||
raise OSError("Failed to save cleared memory data")
|
||||
return cleared_memory
|
||||
|
||||
|
||||
def _validate_confidence(confidence: float) -> float:
|
||||
"""Validate persisted fact confidence so stored JSON stays standards-compliant."""
|
||||
if not math.isfinite(confidence) or confidence < 0 or confidence > 1:
|
||||
raise ValueError("confidence")
|
||||
return confidence
|
||||
|
||||
|
||||
def create_memory_fact(
|
||||
content: str,
|
||||
category: str = "context",
|
||||
confidence: float = 0.5,
|
||||
agent_name: str | None = None,
|
||||
*,
|
||||
user_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Create a new fact and persist the updated memory data."""
|
||||
normalized_content = content.strip()
|
||||
if not normalized_content:
|
||||
raise ValueError("content")
|
||||
|
||||
normalized_category = category.strip() or "context"
|
||||
validated_confidence = _validate_confidence(confidence)
|
||||
now = utc_now_iso_z()
|
||||
memory_data = get_memory_data(agent_name, user_id=user_id)
|
||||
updated_memory = dict(memory_data)
|
||||
facts = list(memory_data.get("facts", []))
|
||||
facts.append(
|
||||
{
|
||||
"id": f"fact_{uuid.uuid4().hex[:8]}",
|
||||
"content": normalized_content,
|
||||
"category": normalized_category,
|
||||
"confidence": validated_confidence,
|
||||
"createdAt": now,
|
||||
"source": "manual",
|
||||
}
|
||||
)
|
||||
updated_memory["facts"] = facts
|
||||
|
||||
if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
|
||||
raise OSError("Failed to save memory data after creating fact")
|
||||
|
||||
return updated_memory
|
||||
|
||||
|
||||
def delete_memory_fact(fact_id: str, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
|
||||
"""Delete a fact by its id and persist the updated memory data."""
|
||||
memory_data = get_memory_data(agent_name, user_id=user_id)
|
||||
facts = memory_data.get("facts", [])
|
||||
updated_facts = [fact for fact in facts if fact.get("id") != fact_id]
|
||||
if len(updated_facts) == len(facts):
|
||||
raise KeyError(fact_id)
|
||||
|
||||
updated_memory = dict(memory_data)
|
||||
updated_memory["facts"] = updated_facts
|
||||
|
||||
if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
|
||||
raise OSError(f"Failed to save memory data after deleting fact '{fact_id}'")
|
||||
|
||||
return updated_memory
|
||||
|
||||
|
||||
def update_memory_fact(
|
||||
fact_id: str,
|
||||
content: str | None = None,
|
||||
category: str | None = None,
|
||||
confidence: float | None = None,
|
||||
agent_name: str | None = None,
|
||||
*,
|
||||
user_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Update an existing fact and persist the updated memory data."""
|
||||
memory_data = get_memory_data(agent_name, user_id=user_id)
|
||||
updated_memory = dict(memory_data)
|
||||
updated_facts: list[dict[str, Any]] = []
|
||||
found = False
|
||||
|
||||
for fact in memory_data.get("facts", []):
|
||||
if fact.get("id") == fact_id:
|
||||
found = True
|
||||
updated_fact = dict(fact)
|
||||
if content is not None:
|
||||
normalized_content = content.strip()
|
||||
if not normalized_content:
|
||||
raise ValueError("content")
|
||||
updated_fact["content"] = normalized_content
|
||||
if category is not None:
|
||||
updated_fact["category"] = category.strip() or "context"
|
||||
if confidence is not None:
|
||||
updated_fact["confidence"] = _validate_confidence(confidence)
|
||||
updated_facts.append(updated_fact)
|
||||
else:
|
||||
updated_facts.append(fact)
|
||||
|
||||
if not found:
|
||||
raise KeyError(fact_id)
|
||||
|
||||
updated_memory["facts"] = updated_facts
|
||||
|
||||
if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
|
||||
raise OSError(f"Failed to save memory data after updating fact '{fact_id}'")
|
||||
|
||||
return updated_memory
|
||||
|
||||
|
||||
def _extract_text(content: Any) -> str:
|
||||
"""Extract plain text from LLM response content (str or list of content blocks).
|
||||
|
||||
Modern LLMs may return structured content as a list of blocks instead of a
|
||||
plain string, e.g. [{"type": "text", "text": "..."}]. Using str() on such
|
||||
content produces Python repr instead of the actual text, breaking JSON
|
||||
parsing downstream.
|
||||
|
||||
String chunks are concatenated without separators to avoid corrupting
|
||||
chunked JSON/text payloads. Dict-based text blocks are treated as full text
|
||||
blocks and joined with newlines for readability.
|
||||
"""
|
||||
if isinstance(content, str):
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
pieces: list[str] = []
|
||||
pending_str_parts: list[str] = []
|
||||
|
||||
def flush_pending_str_parts() -> None:
|
||||
if pending_str_parts:
|
||||
pieces.append("".join(pending_str_parts))
|
||||
pending_str_parts.clear()
|
||||
|
||||
for block in content:
|
||||
if isinstance(block, str):
|
||||
pending_str_parts.append(block)
|
||||
elif isinstance(block, dict):
|
||||
flush_pending_str_parts()
|
||||
text_val = block.get("text")
|
||||
if isinstance(text_val, str):
|
||||
pieces.append(text_val)
|
||||
|
||||
flush_pending_str_parts()
|
||||
return "\n".join(pieces)
|
||||
return str(content)
|
||||
|
||||
|
||||
# Matches sentences that describe a file-upload *event* rather than general
|
||||
# file-related work. Deliberately narrow to avoid removing legitimate facts
|
||||
# such as "User works with CSV files" or "prefers PDF export".
|
||||
_UPLOAD_SENTENCE_RE = re.compile(
|
||||
r"[^.!?]*\b(?:"
|
||||
r"upload(?:ed|ing)?(?:\s+\w+){0,3}\s+(?:file|files?|document|documents?|attachment|attachments?)"
|
||||
r"|file\s+upload"
|
||||
r"|/mnt/user-data/uploads/"
|
||||
r"|<uploaded_files>"
|
||||
r")[^.!?]*[.!?]?\s*",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def _strip_upload_mentions_from_memory(memory_data: dict[str, Any]) -> dict[str, Any]:
|
||||
"""Remove sentences about file uploads from all memory summaries and facts.
|
||||
|
||||
Uploaded files are session-scoped; persisting upload events in long-term
|
||||
memory causes the agent to search for non-existent files in future sessions.
|
||||
"""
|
||||
# Scrub summaries in user/history sections
|
||||
for section in ("user", "history"):
|
||||
section_data = memory_data.get(section, {})
|
||||
for _key, val in section_data.items():
|
||||
if isinstance(val, dict) and "summary" in val:
|
||||
cleaned = _UPLOAD_SENTENCE_RE.sub("", val["summary"]).strip()
|
||||
cleaned = re.sub(r" +", " ", cleaned)
|
||||
val["summary"] = cleaned
|
||||
|
||||
# Also remove any facts that describe upload events
|
||||
facts = memory_data.get("facts", [])
|
||||
if facts:
|
||||
memory_data["facts"] = [f for f in facts if not _UPLOAD_SENTENCE_RE.search(f.get("content", ""))]
|
||||
|
||||
return memory_data
|
||||
|
||||
|
||||
def _fact_content_key(content: Any) -> str | None:
|
||||
if not isinstance(content, str):
|
||||
return None
|
||||
stripped = content.strip()
|
||||
if not stripped:
|
||||
return None
|
||||
return stripped.casefold()
|
||||
|
||||
|
||||
# Match a fenced code block, optionally with an info string (e.g. ```json).
|
||||
# We deliberately use a non-greedy DOTALL pattern so that *only* the contents
|
||||
# are kept — no leading prose like "Here is the updated memory:" and no
|
||||
# trailing chatter that would break ``json.loads``.
|
||||
_FENCED_BLOCK_RE = re.compile(r"```[a-zA-Z0-9_-]*\s*\n?(.*?)```", re.DOTALL)
|
||||
|
||||
# Match common "thinking" wrappers that some Chinese-domestic LLMs emit even
|
||||
# when the system prompt asks for JSON only (GLM, Qwen, MindIE-served models,
|
||||
# and others). Stripping these *before* JSON extraction prevents the body of
|
||||
# the reasoning text from being mistakenly parsed as the payload.
|
||||
_THINK_BLOCK_RE = re.compile(
|
||||
r"<\s*(think|thinking|reasoning|analysis)\s*>.*?<\s*/\s*\1\s*>",
|
||||
re.DOTALL | re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def _extract_first_json_object(text: str) -> str | None:
|
||||
"""Return the substring spanning the first balanced ``{...}`` JSON object.
|
||||
|
||||
Walks the text once tracking brace depth, ignoring braces that appear
|
||||
inside double-quoted strings (with backslash-escape awareness). This is
|
||||
sufficient for the JSON dialect the prompt asks for; we deliberately do
|
||||
not handle single-quoted "JSON" because that would silently accept
|
||||
invalid responses we'd rather reject and retry on.
|
||||
"""
|
||||
start = text.find("{")
|
||||
if start == -1:
|
||||
return None
|
||||
|
||||
depth = 0
|
||||
in_string = False
|
||||
escape = False
|
||||
for index in range(start, len(text)):
|
||||
char = text[index]
|
||||
if in_string:
|
||||
if escape:
|
||||
escape = False
|
||||
continue
|
||||
if char == "\\":
|
||||
escape = True
|
||||
continue
|
||||
if char == '"':
|
||||
in_string = False
|
||||
continue
|
||||
if char == '"':
|
||||
in_string = True
|
||||
continue
|
||||
if char == "{":
|
||||
depth += 1
|
||||
elif char == "}":
|
||||
depth -= 1
|
||||
if depth == 0:
|
||||
return text[start : index + 1]
|
||||
return None
|
||||
|
||||
|
||||
def _parse_memory_update_response(response_text: str) -> dict[str, Any]:
|
||||
"""Best-effort extraction of the JSON payload from a memory-update response.
|
||||
|
||||
Models served by ``vllm`` / ``MindIE`` (e.g. the GLM_5 endpoint at
|
||||
``http://10.106.57.108:8010/GLM_5/v1/chat/completions`` users have hit
|
||||
in production) routinely:
|
||||
|
||||
1. Wrap the JSON in a fenced code block (\\`\\`\\`json ... \\`\\`\\`)
|
||||
even though the prompt forbids it.
|
||||
2. Emit a ``<think>...</think>`` reasoning block before the answer.
|
||||
3. Add prose ("Here is the updated memory:") before/after the JSON.
|
||||
4. Return an empty body when the upstream model produced only reasoning
|
||||
and no answer (the original cause of "Expecting value: line 1
|
||||
column 1 (char 0)" reports).
|
||||
|
||||
This helper normalizes all four cases and surfaces a clear error
|
||||
message containing a truncated response snippet so future failures are
|
||||
diagnosable from the log alone.
|
||||
"""
|
||||
if not isinstance(response_text, str):
|
||||
raise json.JSONDecodeError("Empty memory update response (non-string content)", "", 0)
|
||||
|
||||
cleaned = _THINK_BLOCK_RE.sub("", response_text).strip()
|
||||
if not cleaned:
|
||||
raise json.JSONDecodeError("Empty memory update response (only reasoning content)", response_text, 0)
|
||||
|
||||
# 1. Try fenced code block first — favours the model's explicit framing.
|
||||
fenced_match = _FENCED_BLOCK_RE.search(cleaned)
|
||||
if fenced_match:
|
||||
candidate = fenced_match.group(1).strip()
|
||||
if candidate:
|
||||
try:
|
||||
return json.loads(candidate)
|
||||
except json.JSONDecodeError:
|
||||
# Fall through to balanced-brace extraction; the fenced block
|
||||
# may have contained truncated JSON or interleaved prose.
|
||||
pass
|
||||
|
||||
# 2. Try balanced-brace JSON extraction anywhere in the text.
|
||||
balanced = _extract_first_json_object(cleaned)
|
||||
if balanced is not None:
|
||||
try:
|
||||
return json.loads(balanced)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
# 3. Last resort: try parsing the whole cleaned text directly. This
|
||||
# covers responses that already are pure JSON.
|
||||
try:
|
||||
return json.loads(cleaned)
|
||||
except json.JSONDecodeError as exc:
|
||||
snippet = response_text.strip()
|
||||
if len(snippet) > 400:
|
||||
snippet = snippet[:400] + "...[truncated]"
|
||||
raise json.JSONDecodeError(
|
||||
f"{exc.msg}; raw response head: {snippet!r}",
|
||||
exc.doc,
|
||||
exc.pos,
|
||||
) from exc
|
||||
|
||||
|
||||
class MemoryUpdater:
|
||||
"""Updates memory using LLM based on conversation context."""
|
||||
|
||||
def __init__(self, model_name: str | None = None):
|
||||
"""Initialize the memory updater.
|
||||
|
||||
Args:
|
||||
model_name: Optional model name to use. If None, uses config or default.
|
||||
"""
|
||||
self._model_name = model_name
|
||||
|
||||
def _get_model(self):
|
||||
"""Get the model for memory updates."""
|
||||
config = get_memory_config()
|
||||
model_name = self._model_name or config.model_name
|
||||
return create_chat_model(name=model_name, thinking_enabled=False)
|
||||
|
||||
def _build_correction_hint(
|
||||
self,
|
||||
correction_detected: bool,
|
||||
reinforcement_detected: bool,
|
||||
) -> str:
|
||||
"""Build optional prompt hints for correction and reinforcement signals."""
|
||||
correction_hint = ""
|
||||
if correction_detected:
|
||||
correction_hint = (
|
||||
"IMPORTANT: Explicit correction signals were detected in this conversation. "
|
||||
"Pay special attention to what the agent got wrong, what the user corrected, "
|
||||
"and record the correct approach as a fact with category "
|
||||
'"correction" and confidence >= 0.95 when appropriate.'
|
||||
)
|
||||
if reinforcement_detected:
|
||||
reinforcement_hint = (
|
||||
"IMPORTANT: Positive reinforcement signals were detected in this conversation. "
|
||||
"The user explicitly confirmed the agent's approach was correct or helpful. "
|
||||
"Record the confirmed approach, style, or preference as a fact with category "
|
||||
'"preference" or "behavior" and confidence >= 0.9 when appropriate.'
|
||||
)
|
||||
correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
|
||||
|
||||
return correction_hint
|
||||
|
||||
def _prepare_update_prompt(
|
||||
self,
|
||||
messages: list[Any],
|
||||
agent_name: str | None,
|
||||
correction_detected: bool,
|
||||
reinforcement_detected: bool,
|
||||
user_id: str | None = None,
|
||||
) -> tuple[dict[str, Any], str] | None:
|
||||
"""Load memory and build the update prompt for a conversation."""
|
||||
config = get_memory_config()
|
||||
if not config.enabled or not messages:
|
||||
return None
|
||||
|
||||
current_memory = get_memory_data(agent_name, user_id=user_id)
|
||||
conversation_text = format_conversation_for_update(messages)
|
||||
if not conversation_text.strip():
|
||||
return None
|
||||
|
||||
correction_hint = self._build_correction_hint(
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
)
|
||||
prompt = MEMORY_UPDATE_PROMPT.format(
|
||||
current_memory=json.dumps(current_memory, indent=2),
|
||||
conversation=conversation_text,
|
||||
correction_hint=correction_hint,
|
||||
)
|
||||
return current_memory, prompt
|
||||
|
||||
def _finalize_update(
|
||||
self,
|
||||
current_memory: dict[str, Any],
|
||||
response_content: Any,
|
||||
thread_id: str | None,
|
||||
agent_name: str | None,
|
||||
user_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Parse the model response, apply updates, and persist memory."""
|
||||
response_text = _extract_text(response_content)
|
||||
update_data = _parse_memory_update_response(response_text)
|
||||
# Deep-copy before in-place mutation so a subsequent save() failure
|
||||
# cannot corrupt the still-cached original object reference.
|
||||
updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
|
||||
updated_memory = _strip_upload_mentions_from_memory(updated_memory)
|
||||
return get_memory_storage().save(updated_memory, agent_name, user_id=user_id)
|
||||
|
||||
async def aupdate_memory(
|
||||
self,
|
||||
messages: list[Any],
|
||||
thread_id: str | None = None,
|
||||
agent_name: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
user_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Update memory asynchronously by delegating to the sync path.
|
||||
|
||||
Uses ``asyncio.to_thread`` to run the *sync* ``model.invoke()`` path
|
||||
in a worker thread so no second event loop is created and the
|
||||
langchain async httpx client pool (shared with the lead agent) is
|
||||
never touched. This eliminates the cross-loop connection-reuse bug
|
||||
described in issue #2615.
|
||||
"""
|
||||
return await asyncio.to_thread(
|
||||
self._do_update_memory_sync,
|
||||
messages=messages,
|
||||
thread_id=thread_id,
|
||||
agent_name=agent_name,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
user_id=user_id,
|
||||
)
|
||||
|
||||
def _do_update_memory_sync(
|
||||
self,
|
||||
messages: list[Any],
|
||||
thread_id: str | None = None,
|
||||
agent_name: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
user_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Pure-sync memory update using ``model.invoke()``.
|
||||
|
||||
Uses the *sync* LLM call path so no event loop is created. This
|
||||
guarantees that the langchain provider's globally cached async
|
||||
httpx ``AsyncClient`` / connection pool (the one shared with the
|
||||
lead agent) is never touched — no cross-loop connection reuse is
|
||||
possible.
|
||||
"""
|
||||
try:
|
||||
prepared = self._prepare_update_prompt(
|
||||
messages=messages,
|
||||
agent_name=agent_name,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
user_id=user_id,
|
||||
)
|
||||
if prepared is None:
|
||||
return False
|
||||
|
||||
current_memory, prompt = prepared
|
||||
model = self._get_model()
|
||||
response = model.invoke(prompt, config={"run_name": "memory_agent"})
|
||||
return self._finalize_update(
|
||||
current_memory=current_memory,
|
||||
response_content=response.content,
|
||||
thread_id=thread_id,
|
||||
agent_name=agent_name,
|
||||
user_id=user_id,
|
||||
)
|
||||
except json.JSONDecodeError as e:
|
||||
logger.warning("Failed to parse LLM response for memory update: %s", e)
|
||||
return False
|
||||
except Exception as e:
|
||||
logger.exception("Memory update failed: %s", e)
|
||||
return False
|
||||
|
||||
def update_memory(
|
||||
self,
|
||||
messages: list[Any],
|
||||
thread_id: str | None = None,
|
||||
agent_name: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
user_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Synchronously update memory using the sync LLM path.
|
||||
|
||||
Uses ``model.invoke()`` (sync HTTP) which operates on a completely
|
||||
separate connection pool from the async ``AsyncClient`` shared by
|
||||
the lead agent. This eliminates the cross-loop connection-reuse
|
||||
bug described in issue #2615.
|
||||
|
||||
When called from within a running event loop (e.g. from a LangGraph
|
||||
node), the blocking sync call is offloaded to a thread pool so the
|
||||
caller's loop is not blocked.
|
||||
|
||||
Args:
|
||||
messages: List of conversation messages.
|
||||
thread_id: Optional thread ID for tracking source.
|
||||
agent_name: If provided, updates per-agent memory. If None, updates global memory.
|
||||
correction_detected: Whether recent turns include an explicit correction signal.
|
||||
reinforcement_detected: Whether recent turns include a positive reinforcement signal.
|
||||
user_id: If provided, scopes memory to a specific user.
|
||||
|
||||
Returns:
|
||||
True if update was successful, False otherwise.
|
||||
"""
|
||||
try:
|
||||
loop = asyncio.get_running_loop()
|
||||
except RuntimeError:
|
||||
loop = None
|
||||
|
||||
if loop is not None and loop.is_running():
|
||||
try:
|
||||
future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(
|
||||
self._do_update_memory_sync,
|
||||
messages=messages,
|
||||
thread_id=thread_id,
|
||||
agent_name=agent_name,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
user_id=user_id,
|
||||
)
|
||||
return future.result()
|
||||
except Exception:
|
||||
logger.exception("Failed to offload memory update to executor")
|
||||
return False
|
||||
|
||||
return self._do_update_memory_sync(
|
||||
messages=messages,
|
||||
thread_id=thread_id,
|
||||
agent_name=agent_name,
|
||||
correction_detected=correction_detected,
|
||||
reinforcement_detected=reinforcement_detected,
|
||||
user_id=user_id,
|
||||
)
|
||||
|
||||
def _apply_updates(
|
||||
self,
|
||||
current_memory: dict[str, Any],
|
||||
update_data: dict[str, Any],
|
||||
thread_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Apply LLM-generated updates to memory.
|
||||
|
||||
Args:
|
||||
current_memory: Current memory data.
|
||||
update_data: Updates from LLM.
|
||||
thread_id: Optional thread ID for tracking.
|
||||
|
||||
Returns:
|
||||
Updated memory data.
|
||||
"""
|
||||
config = get_memory_config()
|
||||
now = utc_now_iso_z()
|
||||
|
||||
# Update user sections
|
||||
user_updates = update_data.get("user", {})
|
||||
for section in ["workContext", "personalContext", "topOfMind"]:
|
||||
section_data = user_updates.get(section, {})
|
||||
if section_data.get("shouldUpdate") and section_data.get("summary"):
|
||||
current_memory["user"][section] = {
|
||||
"summary": section_data["summary"],
|
||||
"updatedAt": now,
|
||||
}
|
||||
|
||||
# Update history sections
|
||||
history_updates = update_data.get("history", {})
|
||||
for section in ["recentMonths", "earlierContext", "longTermBackground"]:
|
||||
section_data = history_updates.get(section, {})
|
||||
if section_data.get("shouldUpdate") and section_data.get("summary"):
|
||||
current_memory["history"][section] = {
|
||||
"summary": section_data["summary"],
|
||||
"updatedAt": now,
|
||||
}
|
||||
|
||||
# Remove facts
|
||||
facts_to_remove = set(update_data.get("factsToRemove", []))
|
||||
if facts_to_remove:
|
||||
current_memory["facts"] = [f for f in current_memory.get("facts", []) if f.get("id") not in facts_to_remove]
|
||||
|
||||
# Add new facts
|
||||
existing_fact_keys = {fact_key for fact_key in (_fact_content_key(fact.get("content")) for fact in current_memory.get("facts", [])) if fact_key is not None}
|
||||
new_facts = update_data.get("newFacts", [])
|
||||
for fact in new_facts:
|
||||
confidence = fact.get("confidence", 0.5)
|
||||
if confidence >= config.fact_confidence_threshold:
|
||||
raw_content = fact.get("content", "")
|
||||
if not isinstance(raw_content, str):
|
||||
continue
|
||||
normalized_content = raw_content.strip()
|
||||
fact_key = _fact_content_key(normalized_content)
|
||||
if fact_key is not None and fact_key in existing_fact_keys:
|
||||
continue
|
||||
|
||||
fact_entry = {
|
||||
"id": f"fact_{uuid.uuid4().hex[:8]}",
|
||||
"content": normalized_content,
|
||||
"category": fact.get("category", "context"),
|
||||
"confidence": confidence,
|
||||
"createdAt": now,
|
||||
"source": thread_id or "unknown",
|
||||
}
|
||||
source_error = fact.get("sourceError")
|
||||
if isinstance(source_error, str):
|
||||
normalized_source_error = source_error.strip()
|
||||
if normalized_source_error:
|
||||
fact_entry["sourceError"] = normalized_source_error
|
||||
current_memory["facts"].append(fact_entry)
|
||||
if fact_key is not None:
|
||||
existing_fact_keys.add(fact_key)
|
||||
|
||||
# Enforce max facts limit
|
||||
if len(current_memory["facts"]) > config.max_facts:
|
||||
# Sort by confidence and keep top ones
|
||||
current_memory["facts"] = sorted(
|
||||
current_memory["facts"],
|
||||
key=lambda f: f.get("confidence", 0),
|
||||
reverse=True,
|
||||
)[: config.max_facts]
|
||||
|
||||
return current_memory
|
||||
|
||||
|
||||
def update_memory_from_conversation(
|
||||
messages: list[Any],
|
||||
thread_id: str | None = None,
|
||||
agent_name: str | None = None,
|
||||
correction_detected: bool = False,
|
||||
reinforcement_detected: bool = False,
|
||||
user_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Convenience function to update memory from a conversation.
|
||||
|
||||
Args:
|
||||
messages: List of conversation messages.
|
||||
thread_id: Optional thread ID.
|
||||
agent_name: If provided, updates per-agent memory. If None, updates global memory.
|
||||
correction_detected: Whether recent turns include an explicit correction signal.
|
||||
reinforcement_detected: Whether recent turns include a positive reinforcement signal.
|
||||
user_id: If provided, scopes memory to a specific user.
|
||||
|
||||
Returns:
|
||||
True if successful, False otherwise.
|
||||
"""
|
||||
updater = MemoryUpdater()
|
||||
return updater.update_memory(messages, thread_id, agent_name, correction_detected, reinforcement_detected, user_id=user_id)
|
||||
+245
-110
@@ -1,110 +1,245 @@
|
||||
"""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. **wrap_model_call** —— Hindsight 动态召回注入。
|
||||
每次 LLM 调用前,用最近一条用户消息作为 query 召回 Hindsight 记忆,
|
||||
作为一条带 ``<memory-context>`` 标签的消息**临时**追加到本次模型请求里。
|
||||
关键:用 ``wrap_model_call`` 而非 ``before_model`` —— 注入只作用于这一次
|
||||
模型调用,不写入持久 state,因此不会泄漏给前端、也不会在历史里堆积。
|
||||
仅在 ``provider="hindsight"`` 且配置允许时生效;builtin 的 frozen
|
||||
snapshot 走系统提示词,不在这里。
|
||||
|
||||
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
|
||||
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 count_user_turns, 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
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.config.memory_config import MemoryConfig
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
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):
|
||||
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]):
|
||||
"""记忆中间件:wrap_model_call 注入 Hindsight 召回,after_agent 自动 retain。
|
||||
|
||||
Memory V2 说明:
|
||||
- builtin 本地记忆的 frozen snapshot 走系统提示词 (``_get_memory_context``)。
|
||||
- Hindsight 动态召回走本中间件 ``wrap_model_call`` —— 临时注入,不落 state。
|
||||
"""
|
||||
|
||||
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 | None) -> str | None:
|
||||
"""从 runtime context 取 thread_id,回退到 LangGraph configurable。"""
|
||||
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:
|
||||
return get_config().get("configurable", {}).get("thread_id")
|
||||
except RuntimeError:
|
||||
return None
|
||||
|
||||
def _resolve_agent_id(self, runtime: Runtime | None) -> str:
|
||||
"""解析 agent_id;优先 middleware 构造时的 agent_name,再 runtime context。"""
|
||||
if self._agent_name:
|
||||
return self._agent_name
|
||||
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"
|
||||
|
||||
# ---- wrap_model_call: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
|
||||
|
||||
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 = 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(
|
||||
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
|
||||
|
||||
if not recall or not recall.strip():
|
||||
return None
|
||||
|
||||
tag = effective_config.injection.context_tag
|
||||
fenced = (
|
||||
f"<{tag}>\n"
|
||||
"[系统提示:以下是召回的记忆上下文,不是用户的新输入,作为背景信息参考。]\n\n"
|
||||
f"{recall}\n"
|
||||
f"</{tag}>"
|
||||
)
|
||||
return HumanMessage(content=fenced)
|
||||
|
||||
@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 工作 bank。
|
||||
|
||||
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)
|
||||
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_text, assistant_text = _last_exchange(filtered_messages)
|
||||
if not user_text or not assistant_text:
|
||||
return None
|
||||
|
||||
# 轮次序号按对话历史算出 —— provider 每轮被重建、无法自行计数,
|
||||
# retain_every_n_turns 的节流必须靠这个外部传入的值。
|
||||
turn_index = count_user_turns(filtered_messages)
|
||||
|
||||
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,
|
||||
)
|
||||
manager.sync_all(
|
||||
user_text,
|
||||
assistant_text,
|
||||
thread_id=thread_id or "",
|
||||
turn_index=turn_index,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
|
||||
logger.warning("Hindsight retain 失败:%s", exc)
|
||||
|
||||
return None
|
||||
+8
@@ -131,6 +131,14 @@ def _build_runtime_middlewares(
|
||||
|
||||
middlewares.append(SandboxAuditMiddleware())
|
||||
middlewares.append(ToolErrorHandlingMiddleware())
|
||||
|
||||
# Tool / skill call metrics — appended last so it sits *deepest* in the
|
||||
# wrap_tool_call chain: its handler is the raw tool, so it observes the
|
||||
# unconverted exception (before ToolErrorHandlingMiddleware turns it into
|
||||
# an error ToolMessage) and the raw return value.
|
||||
from deerflow.agents.middlewares.tool_metrics_middleware import ToolMetricsMiddleware
|
||||
|
||||
middlewares.append(ToolMetricsMiddleware())
|
||||
return middlewares
|
||||
|
||||
|
||||
|
||||
+319
@@ -0,0 +1,319 @@
|
||||
"""Middleware that records per-tool-call metrics for the admin audit page.
|
||||
|
||||
Every tool / skill invocation ends with one row in ``tool_call_metrics``:
|
||||
- Successes record the wall-clock duration.
|
||||
- Failures record a coarse ``error_category`` plus a one-line message.
|
||||
|
||||
Two failure shapes are captured:
|
||||
|
||||
1. **Raised exceptions** — the tool blew up. We record, then re-raise so the
|
||||
outer :class:`ToolErrorHandlingMiddleware` still converts it into an error
|
||||
``ToolMessage`` for the model.
|
||||
2. **Self-handled errors** — search/retrieval tools (Serper, Tavily, Jina, …)
|
||||
catch their own HTTP 429/403/timeout and *return* an error payload instead
|
||||
of raising. Those never reach an ``except`` block, so we also inspect the
|
||||
returned ``ToolMessage``: an ``status == "error"`` message, or content that
|
||||
looks like an error string, is bucketed too.
|
||||
|
||||
This middleware is appended **after** ``ToolErrorHandlingMiddleware`` so it
|
||||
sits deepest in the ``wrap_tool_call`` chain — its handler is the raw tool, so
|
||||
it observes the unconverted exception and the raw return value.
|
||||
|
||||
Writes go through a best-effort store: a DB outage logs a warning and the
|
||||
agent runtime keeps running.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import re
|
||||
import time
|
||||
import uuid
|
||||
from collections.abc import Awaitable, Callable
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any, override
|
||||
|
||||
from langchain.agents import AgentState
|
||||
from langchain.agents.middleware import AgentMiddleware
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langgraph.errors import GraphBubbleUp
|
||||
from langgraph.prebuilt.tool_node import ToolCallRequest
|
||||
from langgraph.types import Command
|
||||
|
||||
from deerflow.persistence.engine import get_session_factory
|
||||
from deerflow.persistence.tool_metrics import ToolMetricRecord, make_tool_metrics_store
|
||||
from deerflow.persistence.tool_metrics.base import ToolMetricsStore
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _now() -> datetime:
|
||||
return datetime.now(UTC)
|
||||
|
||||
|
||||
def _trim(text: str, limit: int = 500) -> str:
|
||||
text = (text or "").strip()
|
||||
return text if len(text) <= limit else text[: limit - 3] + "..."
|
||||
|
||||
|
||||
def _classify_error(text: str) -> str:
|
||||
"""Bucket an error string into a coarse, admin-friendly category."""
|
||||
t = (text or "").lower()
|
||||
if any(k in t for k in ("429", "rate limit", "ratelimit", "too many request", "quota")):
|
||||
return "rate_limited"
|
||||
if any(k in t for k in ("403", "forbidden", "ip ban", "ip block", "blocked", "access denied", "banned")):
|
||||
return "ip_blocked"
|
||||
if any(k in t for k in ("401", "unauthorized", "api key", "apikey", "invalid key", "authentication", "credential")):
|
||||
return "auth_error"
|
||||
if any(k in t for k in ("timeout", "timed out", "deadline")):
|
||||
return "timeout"
|
||||
if any(k in t for k in ("connecterror", "connection error", "connection refused", "network", "dns", "unreachable", "ssl", "proxy")):
|
||||
return "network_error"
|
||||
if any(k in t for k in ("404", "not found")):
|
||||
return "not_found"
|
||||
if any(k in t for k in ("no results", "no result", "0 results", "empty result")):
|
||||
return "empty_result"
|
||||
return "tool_error"
|
||||
|
||||
|
||||
def _content_text(content: Any) -> str:
|
||||
"""Flatten a tool result's content (string or block list) into text."""
|
||||
if content is None:
|
||||
return ""
|
||||
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):
|
||||
text = block.get("text")
|
||||
if isinstance(text, str):
|
||||
parts.append(text)
|
||||
return " ".join(parts)
|
||||
return str(content)
|
||||
|
||||
|
||||
def _looks_like_error(text: str) -> bool:
|
||||
"""Heuristically detect a self-handled error payload returned as content.
|
||||
|
||||
Deliberately conservative — only an explicit ``Error:`` prefix or a JSON
|
||||
object whose first key is ``error`` counts, so a normal result that merely
|
||||
mentions the word "error" is not misclassified.
|
||||
"""
|
||||
head = (text or "").lstrip()[:64].lower()
|
||||
return head.startswith("error:") or head.startswith('{"error"') or head.startswith("{'error'")
|
||||
|
||||
|
||||
# Skill tools whose ``name`` argument names one specific Agent Skill directly.
|
||||
_SKILL_NAME_ARG_TOOLS = {"skill_view", "skill_manage", "skill_archive"}
|
||||
|
||||
# Matches a skill directory embedded in any tool-argument path. Skills live
|
||||
# under ``skills/{public,custom}/{name}/`` — both inside the sandbox
|
||||
# (``/mnt/skills/...``) and on the host. The lead agent's system prompt tells
|
||||
# it to load a skill by calling ``read_file`` on that SKILL.md path (it does
|
||||
# NOT call a dedicated "use skill" tool), so the skill name has to be recovered
|
||||
# from the path argument of whatever tool touched it (read_file / bash / ls /
|
||||
# str_replace / write_file ...).
|
||||
_SKILL_PATH_RE = re.compile(r"[\\/]skills[\\/](?:public|custom)[\\/]([^\\/]+)(?:[\\/]|$)")
|
||||
|
||||
|
||||
def _skill_name_from_call(tool_name: str | None, tool_call: Any) -> str | None:
|
||||
"""Recover the Agent Skill a tool call targets, or ``None``.
|
||||
|
||||
Two detection paths:
|
||||
|
||||
1. ``skill_view`` / ``skill_manage`` / ``skill_archive`` take an explicit
|
||||
``name`` argument.
|
||||
2. Every other tool references a skill by *path*. The canonical skill
|
||||
invocation is ``read_file('/mnt/skills/<cat>/<name>/SKILL.md')``; helper
|
||||
files and ``bash`` script runs hit the same directory. So we scan the
|
||||
string arguments for the ``skills/{public,custom}/{name}/`` shape.
|
||||
"""
|
||||
if not isinstance(tool_call, dict):
|
||||
return None
|
||||
args = tool_call.get("args")
|
||||
if not isinstance(args, dict):
|
||||
return None
|
||||
|
||||
# Case 1 — explicit ``name`` argument on the skill tools.
|
||||
if tool_name in _SKILL_NAME_ARG_TOOLS:
|
||||
raw = args.get("name")
|
||||
if isinstance(raw, str) and raw.strip():
|
||||
return raw.strip()
|
||||
|
||||
# Case 2 — a skill path inside any string argument.
|
||||
for value in args.values():
|
||||
if isinstance(value, str):
|
||||
match = _SKILL_PATH_RE.search(value)
|
||||
if match:
|
||||
return match.group(1)
|
||||
return None
|
||||
|
||||
|
||||
def _evaluate_skill_view(text: str) -> tuple[str, str | None, str | None]:
|
||||
"""Classify a ``skill_view`` return.
|
||||
|
||||
``skill_view`` never raises — on failure it returns a plain string
|
||||
(``Skill 'x' not found.`` / ``Error reading skill 'x': ...``); on success
|
||||
it returns the SKILL.md content. So success/failure must be read off the
|
||||
returned text, not an exception or ``status`` flag.
|
||||
"""
|
||||
head = (text or "").lstrip()
|
||||
low = head[:200].lower()
|
||||
if head.startswith("Skill '") and "not found" in low:
|
||||
return "error", "not_found", _trim(text)
|
||||
if low.startswith("error reading skill"):
|
||||
return "error", _classify_error(text), _trim(text)
|
||||
return "success", None, None
|
||||
|
||||
|
||||
def _evaluate_result(result: Any, tool_name: str | None) -> tuple[str, str | None, str | None]:
|
||||
"""Return ``(status, error_category, error_message)`` for a tool return."""
|
||||
if isinstance(result, ToolMessage):
|
||||
text = _content_text(result.content)
|
||||
if getattr(result, "status", None) == "error":
|
||||
return "error", _classify_error(text), _trim(text)
|
||||
# skill_view swallows its own failures into a plain string return.
|
||||
if tool_name == "skill_view":
|
||||
return _evaluate_skill_view(text)
|
||||
if _looks_like_error(text):
|
||||
return "error", _classify_error(text), _trim(text)
|
||||
return "success", None, None
|
||||
# Command (control flow) or any other shape — treat as a successful call.
|
||||
return "success", None, None
|
||||
|
||||
|
||||
class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
|
||||
"""Wrap each tool call to time it and persist a metric row."""
|
||||
|
||||
def __init__(self, *, store: ToolMetricsStore | None = None, **kwargs: Any) -> None:
|
||||
super().__init__(**kwargs)
|
||||
self._store_override = store
|
||||
|
||||
# -- store / context ----------------------------------------------------
|
||||
|
||||
def _store(self) -> ToolMetricsStore | None:
|
||||
if self._store_override is not None:
|
||||
return self._store_override
|
||||
try:
|
||||
sf = get_session_factory()
|
||||
except Exception:
|
||||
return None
|
||||
return make_tool_metrics_store(sf)
|
||||
|
||||
@staticmethod
|
||||
def _runtime_lookup(request: ToolCallRequest, keys: tuple[str, ...]) -> str | None:
|
||||
runtime = getattr(request, "runtime", None)
|
||||
if runtime is None:
|
||||
return None
|
||||
context = getattr(runtime, "context", None)
|
||||
if isinstance(context, dict):
|
||||
for key in keys:
|
||||
value = context.get(key)
|
||||
if isinstance(value, str) and value:
|
||||
return value
|
||||
config = getattr(runtime, "config", None)
|
||||
if isinstance(config, dict):
|
||||
configurable = config.get("configurable") if isinstance(config.get("configurable"), dict) else {}
|
||||
metadata = config.get("metadata") if isinstance(config.get("metadata"), dict) else {}
|
||||
for bucket in (configurable, metadata):
|
||||
for key in keys:
|
||||
value = bucket.get(key)
|
||||
if isinstance(value, str) and value:
|
||||
return value
|
||||
return None
|
||||
|
||||
def _build_base_record(self, request: ToolCallRequest) -> ToolMetricRecord:
|
||||
tool_call = getattr(request, "tool_call", None) or {}
|
||||
tool_name = tool_call.get("name") if isinstance(tool_call, dict) else None
|
||||
tool_name = str(tool_name) if tool_name else None
|
||||
return ToolMetricRecord(
|
||||
id=uuid.uuid4().hex,
|
||||
created_at=_now(),
|
||||
user_id=get_effective_user_id(),
|
||||
thread_id=self._runtime_lookup(request, ("thread_id",)),
|
||||
run_id=self._runtime_lookup(request, ("run_id", "langgraph_run_id")),
|
||||
agent_name=self._runtime_lookup(request, ("agent_name", "agent_id")),
|
||||
skill_name=_skill_name_from_call(tool_name, tool_call),
|
||||
tool_name=tool_name,
|
||||
)
|
||||
|
||||
# -- finalize -----------------------------------------------------------
|
||||
|
||||
def _finalize_result(self, record: ToolMetricRecord, result: Any, started: float) -> None:
|
||||
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
|
||||
record.status, record.error_category, record.error_message = _evaluate_result(
|
||||
result, record.tool_name
|
||||
)
|
||||
|
||||
def _finalize_error(self, record: ToolMetricRecord, exc: BaseException, started: float) -> None:
|
||||
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
|
||||
record.status = "error"
|
||||
name = exc.__class__.__name__
|
||||
combined = f"{name}: {(str(exc) or name).strip()}"
|
||||
record.error_category = _classify_error(combined)
|
||||
record.error_message = _trim(combined)
|
||||
|
||||
def _flush(self, record: ToolMetricRecord) -> None:
|
||||
store = self._store()
|
||||
if store is None:
|
||||
return
|
||||
try:
|
||||
try:
|
||||
loop = asyncio.get_running_loop()
|
||||
except RuntimeError:
|
||||
loop = None
|
||||
if loop is not None and loop.is_running():
|
||||
# Fire-and-forget — never let metric IO block the tool path.
|
||||
loop.create_task(store.record(record))
|
||||
else:
|
||||
asyncio.run(store.record(record))
|
||||
except Exception:
|
||||
logger.warning("ToolMetricsMiddleware: failed to flush metric %s", record.id, exc_info=True)
|
||||
|
||||
# -- wrap ---------------------------------------------------------------
|
||||
|
||||
@override
|
||||
def wrap_tool_call(
|
||||
self,
|
||||
request: ToolCallRequest,
|
||||
handler: Callable[[ToolCallRequest], ToolMessage | Command],
|
||||
) -> ToolMessage | Command:
|
||||
record = self._build_base_record(request)
|
||||
started = time.monotonic()
|
||||
try:
|
||||
result = handler(request)
|
||||
except GraphBubbleUp:
|
||||
# LangGraph control flow — not a tool failure.
|
||||
raise
|
||||
except Exception as exc:
|
||||
self._finalize_error(record, exc, started)
|
||||
self._flush(record)
|
||||
raise
|
||||
self._finalize_result(record, result, started)
|
||||
self._flush(record)
|
||||
return result
|
||||
|
||||
@override
|
||||
async def awrap_tool_call(
|
||||
self,
|
||||
request: ToolCallRequest,
|
||||
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
|
||||
) -> ToolMessage | Command:
|
||||
record = self._build_base_record(request)
|
||||
started = time.monotonic()
|
||||
try:
|
||||
result = await handler(request)
|
||||
except GraphBubbleUp:
|
||||
raise
|
||||
except Exception as exc:
|
||||
self._finalize_error(record, exc, started)
|
||||
self._flush(record)
|
||||
raise
|
||||
self._finalize_result(record, result, started)
|
||||
self._flush(record)
|
||||
return result
|
||||
@@ -765,27 +765,22 @@ class DeerFlowClient:
|
||||
]
|
||||
}
|
||||
|
||||
def get_memory(self) -> dict:
|
||||
"""Get current memory data.
|
||||
def get_memory(self, agent: str | None = None) -> dict:
|
||||
"""读取 Memory V2 本地记忆 (USER.md / MEMORY.md)。
|
||||
|
||||
Args:
|
||||
agent: 可选 agent 名;省略表示默认 agent。
|
||||
|
||||
Returns:
|
||||
Memory data dict (see src/agents/memory/updater.py for structure).
|
||||
``{user_entries, memory_entries, user_usage, memory_usage}``。
|
||||
"""
|
||||
from deerflow.agents.memory.updater import get_memory_data
|
||||
|
||||
return get_memory_data(user_id=get_effective_user_id())
|
||||
|
||||
def export_memory(self) -> dict:
|
||||
"""Export current memory data for backup or transfer."""
|
||||
from deerflow.agents.memory.updater import get_memory_data
|
||||
|
||||
return get_memory_data(user_id=get_effective_user_id())
|
||||
|
||||
def import_memory(self, memory_data: dict) -> dict:
|
||||
"""Import and persist full memory data."""
|
||||
from deerflow.agents.memory.updater import import_memory_data
|
||||
|
||||
return import_memory_data(memory_data, user_id=get_effective_user_id())
|
||||
provider = self._build_memory_provider(agent)
|
||||
return {
|
||||
"user_entries": provider.read("user"),
|
||||
"memory_entries": provider.read("memory"),
|
||||
"user_usage": provider.usage("user"),
|
||||
"memory_usage": provider.usage("memory"),
|
||||
}
|
||||
|
||||
def get_model(self, name: str) -> dict | None:
|
||||
"""Get a specific model's configuration by name.
|
||||
@@ -949,83 +944,73 @@ class DeerFlowClient:
|
||||
return get_or_new_skill_storage().install_skill_from_archive(skill_path)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Public API — memory management
|
||||
# Public API — memory management (Memory V2)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def reload_memory(self) -> dict:
|
||||
"""Reload memory data from file, forcing cache invalidation.
|
||||
def _build_memory_provider(self, agent: str | None = None):
|
||||
"""按生效配置构建并初始化一个 V2 builtin provider。"""
|
||||
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
Returns:
|
||||
The reloaded memory data dict.
|
||||
"""
|
||||
from deerflow.agents.memory.updater import reload_memory_data
|
||||
|
||||
return reload_memory_data(user_id=get_effective_user_id())
|
||||
|
||||
def clear_memory(self) -> dict:
|
||||
"""Clear all persisted memory data."""
|
||||
from deerflow.agents.memory.updater import clear_memory_data
|
||||
|
||||
return clear_memory_data(user_id=get_effective_user_id())
|
||||
|
||||
def create_memory_fact(self, content: str, category: str = "context", confidence: float = 0.5) -> dict:
|
||||
"""Create a single fact manually."""
|
||||
from deerflow.agents.memory.updater import create_memory_fact
|
||||
|
||||
return create_memory_fact(content=content, category=category, confidence=confidence)
|
||||
|
||||
def delete_memory_fact(self, fact_id: str) -> dict:
|
||||
"""Delete a single fact from memory by fact id."""
|
||||
from deerflow.agents.memory.updater import delete_memory_fact
|
||||
|
||||
return delete_memory_fact(fact_id)
|
||||
|
||||
def update_memory_fact(
|
||||
self,
|
||||
fact_id: str,
|
||||
content: str | None = None,
|
||||
category: str | None = None,
|
||||
confidence: float | None = None,
|
||||
) -> dict:
|
||||
"""Update a single fact manually, preserving omitted fields."""
|
||||
from deerflow.agents.memory.updater import update_memory_fact
|
||||
|
||||
return update_memory_fact(
|
||||
fact_id=fact_id,
|
||||
content=content,
|
||||
category=category,
|
||||
confidence=confidence,
|
||||
user_id = get_effective_user_id()
|
||||
config = get_effective_memory_config(user_id)
|
||||
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,
|
||||
)
|
||||
provider.initialize(
|
||||
user_id=user_id,
|
||||
agent_id=agent or "default",
|
||||
base_dir=str(get_paths().base_dir),
|
||||
)
|
||||
return provider
|
||||
|
||||
def add_memory_entry(self, target: str, content: str, agent: str | None = None) -> dict:
|
||||
"""新增一条记忆条目。``target`` 为 'user'(用户画像) 或 'memory'(工作笔记)。"""
|
||||
return self._build_memory_provider(agent).add(target, content)
|
||||
|
||||
def replace_memory_entry(self, target: str, old_text: str, content: str, agent: str | None = None) -> dict:
|
||||
"""用 ``old_text`` 短串定位并替换一条记忆条目。"""
|
||||
return self._build_memory_provider(agent).replace(target, old_text, content)
|
||||
|
||||
def remove_memory_entry(self, target: str, old_text: str, agent: str | None = None) -> dict:
|
||||
"""用 ``old_text`` 短串定位并删除一条记忆条目。"""
|
||||
return self._build_memory_provider(agent).remove(target, old_text)
|
||||
|
||||
def get_memory_config(self) -> dict:
|
||||
"""Get memory system configuration.
|
||||
"""读取当前用户的生效记忆配置 (含 per-user 覆盖)。"""
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
|
||||
return get_effective_memory_config(get_effective_user_id()).model_dump()
|
||||
|
||||
def search_memory(self, query: str, mode: str = "recall", agent: str | None = None) -> dict:
|
||||
"""代理 Hindsight 检索。
|
||||
|
||||
Args:
|
||||
query: 检索查询。
|
||||
mode: ``recall`` 返回原始片段;``reflect`` 返回 LLM 综合结论。
|
||||
agent: 可选 agent 名。
|
||||
|
||||
Returns:
|
||||
Memory config dict.
|
||||
``{available, results, text}``;Hindsight 不可用时 available=False。
|
||||
"""
|
||||
from deerflow.config.memory_config import get_memory_config
|
||||
from deerflow.agents.memory.providers.hindsight import HindsightProvider
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
|
||||
config = get_memory_config()
|
||||
return {
|
||||
"enabled": config.enabled,
|
||||
"storage_path": config.storage_path,
|
||||
"debounce_seconds": config.debounce_seconds,
|
||||
"max_facts": config.max_facts,
|
||||
"fact_confidence_threshold": config.fact_confidence_threshold,
|
||||
"injection_enabled": config.injection_enabled,
|
||||
"max_injection_tokens": config.max_injection_tokens,
|
||||
}
|
||||
|
||||
def get_memory_status(self) -> dict:
|
||||
"""Get memory status: config + current data.
|
||||
|
||||
Returns:
|
||||
Dict with "config" and "data" keys.
|
||||
"""
|
||||
return {
|
||||
"config": self.get_memory_config(),
|
||||
"data": self.get_memory(),
|
||||
}
|
||||
user_id = get_effective_user_id()
|
||||
config = get_effective_memory_config(user_id)
|
||||
if not config.enabled or config.provider != "hindsight":
|
||||
return {"available": False, "results": [], "text": ""}
|
||||
provider = HindsightProvider(config.hindsight)
|
||||
if not provider.is_available():
|
||||
return {"available": False, "results": [], "text": ""}
|
||||
provider.initialize(user_id=user_id, agent_id=agent or "default", thread_id="", base_dir="")
|
||||
if mode == "reflect":
|
||||
return {"available": True, "results": [], "text": provider.reflect(query)}
|
||||
return {"available": True, "results": provider.recall(query), "text": ""}
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Public API — file uploads
|
||||
|
||||
+315
-83
@@ -1,83 +1,315 @@
|
||||
"""Configuration for memory mechanism."""
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class MemoryConfig(BaseModel):
|
||||
"""Configuration for global memory mechanism."""
|
||||
|
||||
enabled: bool = Field(
|
||||
default=True,
|
||||
description="Whether to enable memory mechanism",
|
||||
)
|
||||
storage_path: str = Field(
|
||||
default="",
|
||||
description=(
|
||||
"Path to store memory data. "
|
||||
"If empty, defaults to per-user memory at `{base_dir}/users/{user_id}/memory.json`. "
|
||||
"Absolute paths are used as-is and opt out of per-user isolation "
|
||||
"(all users share the same file). "
|
||||
"Relative paths are resolved against `Paths.base_dir` "
|
||||
"(not the backend working directory). "
|
||||
"Note: if you previously set this to `.deer-flow/memory.json`, "
|
||||
"the file will now be resolved as `{base_dir}/.deer-flow/memory.json`; "
|
||||
"migrate existing data or use an absolute path to preserve the old location."
|
||||
),
|
||||
)
|
||||
storage_class: str = Field(
|
||||
default="deerflow.agents.memory.storage.FileMemoryStorage",
|
||||
description="The class path for memory storage provider",
|
||||
)
|
||||
debounce_seconds: int = Field(
|
||||
default=30,
|
||||
ge=1,
|
||||
le=300,
|
||||
description="Seconds to wait before processing queued updates (debounce)",
|
||||
)
|
||||
model_name: str | None = Field(
|
||||
default=None,
|
||||
description="Model name to use for memory updates (None = use default model)",
|
||||
)
|
||||
max_facts: int = Field(
|
||||
default=100,
|
||||
ge=10,
|
||||
le=500,
|
||||
description="Maximum number of facts to store",
|
||||
)
|
||||
fact_confidence_threshold: float = Field(
|
||||
default=0.7,
|
||||
ge=0.0,
|
||||
le=1.0,
|
||||
description="Minimum confidence threshold for storing facts",
|
||||
)
|
||||
injection_enabled: bool = Field(
|
||||
default=True,
|
||||
description="Whether to inject memory into system prompt",
|
||||
)
|
||||
max_injection_tokens: int = Field(
|
||||
default=2000,
|
||||
ge=100,
|
||||
le=8000,
|
||||
description="Maximum tokens to use for memory injection",
|
||||
)
|
||||
|
||||
|
||||
# Global configuration instance
|
||||
_memory_config: MemoryConfig = MemoryConfig()
|
||||
|
||||
|
||||
def get_memory_config() -> MemoryConfig:
|
||||
"""Get the current memory configuration."""
|
||||
return _memory_config
|
||||
|
||||
|
||||
def set_memory_config(config: MemoryConfig) -> None:
|
||||
"""Set the memory configuration."""
|
||||
global _memory_config
|
||||
_memory_config = config
|
||||
|
||||
|
||||
def load_memory_config_from_dict(config_dict: dict) -> None:
|
||||
"""Load memory configuration from a dictionary."""
|
||||
global _memory_config
|
||||
_memory_config = MemoryConfig(**config_dict)
|
||||
"""Memory V2 - 记忆子系统配置。
|
||||
|
||||
配置结构 (详见 docs/MEMORY_V2_DESIGN_ZH.md §9)
|
||||
==============================================
|
||||
``MemoryConfig`` 采用嵌套结构::
|
||||
|
||||
memory:
|
||||
enabled: true
|
||||
provider: hindsight # 外部 provider 选哪个 (builtin 始终启用)
|
||||
builtin: {...} # 本地 USER.md / MEMORY.md
|
||||
hindsight: {...} # Hindsight HTTP 客户端
|
||||
injection: {...} # 系统提示词注入
|
||||
security: {...} # 内容安全扫描
|
||||
|
||||
三层配置覆盖
|
||||
============
|
||||
``get_effective_memory_config(user_id)`` 按优先级合并 (高 -> 低):
|
||||
1. per-user 覆盖 ``{base_dir}/users/{user_id}/memory_config.json``
|
||||
2. 全局覆盖 ``{base_dir}/memory_user_overrides.json``
|
||||
3. config.yaml ``memory:`` 段 (即 ``get_memory_config()``)
|
||||
4. Pydantic 默认值
|
||||
|
||||
第 1、2 层只允许覆盖 :data:`USER_WRITABLE_FIELDS` 白名单内的字段。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# ===========================================================================
|
||||
# 嵌套子配置
|
||||
# ===========================================================================
|
||||
|
||||
|
||||
class BuiltinMemoryConfig(BaseModel):
|
||||
"""本地文件 provider (USER.md / MEMORY.md) 配置。"""
|
||||
|
||||
enabled: bool = Field(default=True, description="是否启用 builtin 本地记忆 provider")
|
||||
memory_char_limit: int = Field(
|
||||
default=2200, ge=200, le=20000, description="MEMORY.md 字符配额"
|
||||
)
|
||||
user_char_limit: int = Field(
|
||||
default=1375, ge=200, le=20000, description="USER.md 字符配额"
|
||||
)
|
||||
deduplicate_on_load: bool = Field(
|
||||
default=True, description="加载时是否对条目去重"
|
||||
)
|
||||
|
||||
|
||||
class HindsightMemoryConfig(BaseModel):
|
||||
"""Hindsight 外部 provider 配置。"""
|
||||
|
||||
mode: str = Field(
|
||||
default="local_external",
|
||||
description="连接模式:cloud / local_embedded / local_external",
|
||||
)
|
||||
api_url: str = Field(default="http://localhost:8765", description="Hindsight API 地址")
|
||||
api_key: str = Field(default="", description="API key,建议用 $HINDSIGHT_API_KEY 环境变量")
|
||||
bank_id_template: str = Field(
|
||||
default="deerflow-user-{user_id}",
|
||||
description="全局 user bank 命名模板,占位符 {user_id}/{agent_id}/{thread_id}",
|
||||
)
|
||||
work_bank_id_template: str = Field(
|
||||
default="deerflow-work-{user_id}-{agent_id}",
|
||||
description="agent 私有工作 bank 命名模板",
|
||||
)
|
||||
memory_mode: str = Field(
|
||||
default="context",
|
||||
description="工具暴露策略:context(仅自动) / tools(仅工具) / hybrid(两者)",
|
||||
)
|
||||
bank_mission: str = Field(default="", description="reflect 推理的身份/框架描述")
|
||||
bank_retain_mission: str = Field(default="", description="引导抽取内容的 mission")
|
||||
recall_budget: str = Field(default="mid", description="召回深度:low / mid / high")
|
||||
recall_max_tokens: int = Field(default=4096, ge=256, le=32768, description="召回结果 token 上限")
|
||||
recall_max_input_chars: int = Field(default=800, ge=64, le=8000, description="召回 query 长度上限")
|
||||
auto_recall: bool = Field(default=True, description="每轮对话前是否自动召回")
|
||||
auto_retain: bool = Field(default=True, description="是否自动写入对话")
|
||||
retain_async: bool = Field(default=True, description="retain 是否在 Hindsight 服务端异步处理")
|
||||
retain_every_n_turns: int = Field(default=1, ge=1, le=50, description="每 N 轮 retain 一次")
|
||||
retain_user_prefix: str = Field(default="User", description="自动 retain 时用户发言前缀")
|
||||
retain_assistant_prefix: str = Field(default="Assistant", description="自动 retain 时助手发言前缀")
|
||||
|
||||
|
||||
class InjectionConfig(BaseModel):
|
||||
"""系统提示词记忆注入配置。"""
|
||||
|
||||
enabled: bool = Field(default=True, description="是否往系统提示词注入记忆")
|
||||
max_tokens: int = Field(default=2000, ge=100, le=8000, description="注入 token 上限")
|
||||
include_builtin: bool = Field(default=True, description="是否注入 builtin 本地记忆")
|
||||
include_hindsight: bool = Field(default=True, description="是否注入 Hindsight 召回结果")
|
||||
context_tag: str = Field(
|
||||
default="memory-context", description="包裹外部召回内容的标签名"
|
||||
)
|
||||
|
||||
|
||||
class SecurityConfig(BaseModel):
|
||||
"""记忆内容安全配置。"""
|
||||
|
||||
scan_content: bool = Field(default=True, description="是否扫描注入/外渗模式")
|
||||
block_invisible_unicode: bool = Field(default=True, description="是否阻断不可见 unicode")
|
||||
|
||||
|
||||
# ===========================================================================
|
||||
# 顶层配置
|
||||
# ===========================================================================
|
||||
|
||||
|
||||
class MemoryConfig(BaseModel):
|
||||
"""记忆子系统的全局配置 (config.yaml 的 ``memory:`` 段)。"""
|
||||
|
||||
enabled: bool = Field(default=True, description="记忆子系统总开关")
|
||||
provider: str = Field(
|
||||
default="builtin",
|
||||
description="启用的外部 provider 名:builtin(无外部) 或 hindsight",
|
||||
)
|
||||
|
||||
builtin: BuiltinMemoryConfig = Field(default_factory=BuiltinMemoryConfig)
|
||||
hindsight: HindsightMemoryConfig = Field(default_factory=HindsightMemoryConfig)
|
||||
injection: InjectionConfig = Field(default_factory=InjectionConfig)
|
||||
security: SecurityConfig = Field(default_factory=SecurityConfig)
|
||||
|
||||
|
||||
# ===========================================================================
|
||||
# per-user 运行时覆盖
|
||||
# ===========================================================================
|
||||
|
||||
# 用户可在运行时覆盖的字段白名单 (点号路径)。
|
||||
# 不在此表中的字段必须改 config.yaml 并重启 (例如 provider / api_key / 字符配额)。
|
||||
USER_WRITABLE_FIELDS: frozenset[str] = frozenset(
|
||||
{
|
||||
"injection.enabled",
|
||||
"injection.max_tokens",
|
||||
"injection.include_builtin",
|
||||
"injection.include_hindsight",
|
||||
"hindsight.memory_mode",
|
||||
"hindsight.recall_budget",
|
||||
"hindsight.bank_mission",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def _filter_to_whitelist(overrides: dict[str, Any]) -> dict[str, Any]:
|
||||
"""把覆盖 dict 过滤为只含白名单字段的嵌套 dict。
|
||||
|
||||
输入既支持嵌套形式 ``{"injection": {"enabled": false}}``,也支持
|
||||
点号扁平形式 ``{"injection.enabled": false}``。非白名单字段被丢弃并 log。
|
||||
"""
|
||||
result: dict[str, Any] = {}
|
||||
|
||||
def _set_nested(path: str, value: Any) -> None:
|
||||
if path not in USER_WRITABLE_FIELDS:
|
||||
logger.warning("忽略非白名单的记忆配置覆盖字段:%s", path)
|
||||
return
|
||||
section, field = path.split(".", 1)
|
||||
result.setdefault(section, {})[field] = value
|
||||
|
||||
for key, value in overrides.items():
|
||||
if isinstance(value, dict):
|
||||
for sub_key, sub_value in value.items():
|
||||
_set_nested(f"{key}.{sub_key}", sub_value)
|
||||
else:
|
||||
_set_nested(key, value)
|
||||
return result
|
||||
|
||||
|
||||
def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
|
||||
"""递归合并两个 dict,``override`` 优先。返回新 dict,不修改入参。"""
|
||||
merged = copy.deepcopy(base)
|
||||
for key, value in override.items():
|
||||
if isinstance(value, dict) and isinstance(merged.get(key), dict):
|
||||
merged[key] = _deep_merge(merged[key], value)
|
||||
else:
|
||||
merged[key] = value
|
||||
return merged
|
||||
|
||||
|
||||
def _load_json_file(path: Any) -> dict[str, Any]:
|
||||
"""读取一个 JSON 覆盖文件;不存在或解析失败时返回空 dict。"""
|
||||
try:
|
||||
from pathlib import Path
|
||||
|
||||
p = Path(path)
|
||||
if not p.exists():
|
||||
return {}
|
||||
data = json.loads(p.read_text(encoding="utf-8"))
|
||||
return data if isinstance(data, dict) else {}
|
||||
except (OSError, json.JSONDecodeError) as exc:
|
||||
logger.warning("读取记忆配置覆盖文件失败 %s: %s", path, exc)
|
||||
return {}
|
||||
|
||||
|
||||
# ===========================================================================
|
||||
# 全局单例 + 加载入口
|
||||
# ===========================================================================
|
||||
|
||||
_memory_config: MemoryConfig = MemoryConfig()
|
||||
|
||||
|
||||
def get_memory_config() -> MemoryConfig:
|
||||
"""返回 config.yaml 级别的记忆配置 (不含 per-user 覆盖)。"""
|
||||
return _memory_config
|
||||
|
||||
|
||||
def set_memory_config(config: MemoryConfig) -> None:
|
||||
"""设置 config.yaml 级别的记忆配置 (测试与运行时重载用)。"""
|
||||
global _memory_config
|
||||
_memory_config = config
|
||||
|
||||
|
||||
def load_memory_config_from_dict(config_dict: dict) -> None:
|
||||
"""从 dict 加载记忆配置。"""
|
||||
global _memory_config
|
||||
_memory_config = MemoryConfig(**config_dict)
|
||||
|
||||
|
||||
def get_effective_memory_config(user_id: str) -> MemoryConfig:
|
||||
"""按三层覆盖优先级,返回某用户的生效记忆配置。
|
||||
|
||||
优先级 (高 -> 低):per-user 覆盖 > 全局覆盖 > config.yaml > 默认值。
|
||||
第 1、2 层只应用 :data:`USER_WRITABLE_FIELDS` 白名单内的字段。
|
||||
|
||||
覆盖文件读取失败不会抛异常 —— 退化为只用 config.yaml 级别配置。
|
||||
"""
|
||||
base = _memory_config.model_dump()
|
||||
|
||||
try:
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
paths = get_paths()
|
||||
global_overrides = _filter_to_whitelist(
|
||||
_load_json_file(paths.memory_global_overrides_file)
|
||||
)
|
||||
user_overrides = _filter_to_whitelist(
|
||||
_load_json_file(paths.user_memory_config_file(user_id))
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - 配置覆盖失败必须降级,不能阻断对话
|
||||
logger.warning("加载 per-user 记忆配置覆盖失败,退回 config.yaml: %s", exc)
|
||||
return _memory_config
|
||||
|
||||
merged = _deep_merge(_deep_merge(base, global_overrides), user_overrides)
|
||||
try:
|
||||
return MemoryConfig(**merged)
|
||||
except Exception as exc: # noqa: BLE001 - 覆盖产生非法配置时降级
|
||||
logger.warning("合并后的记忆配置非法,退回 config.yaml: %s", exc)
|
||||
return _memory_config
|
||||
|
||||
|
||||
def save_user_memory_override(user_id: str, patch: dict[str, Any]) -> dict[str, Any]:
|
||||
"""把白名单字段写入某用户的 per-user 覆盖文件,返回写入后的完整覆盖 dict。
|
||||
|
||||
``patch`` 支持嵌套或点号扁平形式;非白名单字段被忽略。
|
||||
"""
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
path = get_paths().user_memory_config_file(user_id)
|
||||
current = _load_json_file(path)
|
||||
filtered = _filter_to_whitelist(patch)
|
||||
merged = _deep_merge(current, filtered)
|
||||
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(json.dumps(merged, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
return merged
|
||||
|
||||
|
||||
def delete_user_memory_override(user_id: str, field: str | None = None) -> dict[str, Any]:
|
||||
"""撤销某用户的 per-user 覆盖。
|
||||
|
||||
``field`` 为点号路径 (如 ``injection.enabled``) 时只删该字段;
|
||||
为 ``None`` 时清空整个 per-user 覆盖文件。返回剩余的覆盖 dict。
|
||||
"""
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
path = get_paths().user_memory_config_file(user_id)
|
||||
if field is None:
|
||||
if path.exists():
|
||||
path.unlink()
|
||||
return {}
|
||||
|
||||
current = _load_json_file(path)
|
||||
if "." in field:
|
||||
section, sub_field = field.split(".", 1)
|
||||
if isinstance(current.get(section), dict):
|
||||
current[section].pop(sub_field, None)
|
||||
if not current[section]:
|
||||
current.pop(section, None)
|
||||
else:
|
||||
current.pop(field, None)
|
||||
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(json.dumps(current, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
return current
|
||||
|
||||
|
||||
__all__ = [
|
||||
"BuiltinMemoryConfig",
|
||||
"HindsightMemoryConfig",
|
||||
"InjectionConfig",
|
||||
"SecurityConfig",
|
||||
"MemoryConfig",
|
||||
"USER_WRITABLE_FIELDS",
|
||||
"get_memory_config",
|
||||
"set_memory_config",
|
||||
"load_memory_config_from_dict",
|
||||
"get_effective_memory_config",
|
||||
"save_user_memory_override",
|
||||
"delete_user_memory_override",
|
||||
]
|
||||
@@ -155,6 +155,33 @@ class Paths:
|
||||
"""Per-user per-agent memory: `{base_dir}/users/{user_id}/agents/{id}/memory.json`."""
|
||||
return self.user_dir(user_id) / "agents" / agent_name.lower() / "memory.json"
|
||||
|
||||
# --- Memory V2 布局 (USER.md / MEMORY.md / per-user 配置覆盖) ---
|
||||
# 详见 docs/MEMORY_V2_DESIGN_ZH.md §5.1。注意与 ``user_md_file`` 区分:
|
||||
# 后者是 base_dir 下的全局 USER.md (旧布局),这里是 per-user 的 V2 布局。
|
||||
|
||||
def user_profile_md_file(self, user_id: str) -> Path:
|
||||
"""Memory V2 用户画像文件:`{base_dir}/users/{user_id}/USER.md`。
|
||||
|
||||
存放 LLM 主动写入的 ``target="user"`` 记忆 (用户身份、偏好,跨 agent 共享)。
|
||||
"""
|
||||
return self.user_dir(user_id) / "USER.md"
|
||||
|
||||
def user_agent_memory_md_file(self, user_id: str, agent_name: str) -> Path:
|
||||
"""Memory V2 agent 工作笔记文件:`{base_dir}/users/{user_id}/agents/{id}/MEMORY.md`。
|
||||
|
||||
存放 LLM 主动写入的 ``target="memory"`` 记忆 (agent 私有工作笔记)。
|
||||
"""
|
||||
return self.user_dir(user_id) / "agents" / agent_name.lower() / "MEMORY.md"
|
||||
|
||||
def user_memory_config_file(self, user_id: str) -> Path:
|
||||
"""Memory V2 per-user 运行时配置覆盖:`{base_dir}/users/{user_id}/memory_config.json`。"""
|
||||
return self.user_dir(user_id) / "memory_config.json"
|
||||
|
||||
@property
|
||||
def memory_global_overrides_file(self) -> Path:
|
||||
"""Memory V2 全局配置覆盖 (管理员配):`{base_dir}/memory_user_overrides.json`。"""
|
||||
return self.base_dir / "memory_user_overrides.json"
|
||||
|
||||
def thread_dir(self, thread_id: str, *, user_id: str | None = None) -> Path:
|
||||
"""
|
||||
Host path for a thread's data.
|
||||
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
"""Create tool_call_metrics table.
|
||||
|
||||
Revision ID: 20260518_07
|
||||
Revises: 20260518_06
|
||||
Create Date: 2026-05-18
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
from sqlalchemy import inspect
|
||||
|
||||
|
||||
revision = "20260518_07"
|
||||
down_revision = "20260518_06"
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def _has_table(table_name: str) -> bool:
|
||||
inspector = inspect(op.get_bind())
|
||||
return table_name in inspector.get_table_names()
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
if _has_table("tool_call_metrics"):
|
||||
return
|
||||
|
||||
op.create_table(
|
||||
"tool_call_metrics",
|
||||
sa.Column("id", sa.String(64), primary_key=True),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
|
||||
sa.Column("user_id", sa.String(64), nullable=True),
|
||||
sa.Column("thread_id", sa.String(64), nullable=True),
|
||||
sa.Column("run_id", sa.String(64), nullable=True),
|
||||
sa.Column("agent_name", sa.String(128), nullable=True),
|
||||
sa.Column("tool_name", sa.String(128), nullable=True),
|
||||
sa.Column("skill_name", sa.String(128), nullable=True),
|
||||
sa.Column("duration_ms", sa.Integer(), nullable=False, server_default="0"),
|
||||
sa.Column("status", sa.String(16), nullable=False, server_default="success"),
|
||||
sa.Column("error_category", sa.String(32), nullable=True),
|
||||
sa.Column("error_message", sa.Text(), nullable=True),
|
||||
)
|
||||
op.create_index("ix_tool_call_metrics_created_at", "tool_call_metrics", ["created_at"])
|
||||
op.create_index("ix_tool_call_metrics_user_id", "tool_call_metrics", ["user_id"])
|
||||
op.create_index("ix_tool_call_metrics_thread_id", "tool_call_metrics", ["thread_id"])
|
||||
op.create_index("ix_tool_call_metrics_run_id", "tool_call_metrics", ["run_id"])
|
||||
op.create_index("ix_tool_call_metrics_agent_name", "tool_call_metrics", ["agent_name"])
|
||||
op.create_index("ix_tool_call_metrics_tool_name", "tool_call_metrics", ["tool_name"])
|
||||
op.create_index("ix_tool_call_metrics_skill_name", "tool_call_metrics", ["skill_name"])
|
||||
op.create_index("ix_tool_call_metrics_status", "tool_call_metrics", ["status"])
|
||||
op.create_index("ix_tool_call_metrics_error_category", "tool_call_metrics", ["error_category"])
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
if _has_table("tool_call_metrics"):
|
||||
op.drop_table("tool_call_metrics")
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
"""Add skill_name column to tool_call_metrics.
|
||||
|
||||
``tool_call_metrics`` is created by ``create_all`` at startup. On deployments
|
||||
where the table was materialised *before* the ``skill_name`` column existed,
|
||||
neither ``create_all`` (it never ALTERs) nor revision ``20260518_07`` (it skips
|
||||
when the table already exists) adds the column — leaving MySQL/Postgres with a
|
||||
schema that the ORM model expects a column it does not have. This revision
|
||||
patches the existing table.
|
||||
|
||||
Revision ID: 20260519_01
|
||||
Revises: 20260518_07
|
||||
Create Date: 2026-05-19
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
from sqlalchemy import inspect
|
||||
|
||||
|
||||
revision = "20260519_01"
|
||||
down_revision = "20260518_07"
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def _has_table(table_name: str) -> bool:
|
||||
inspector = inspect(op.get_bind())
|
||||
return table_name in inspector.get_table_names()
|
||||
|
||||
|
||||
def _has_column(table_name: str, column_name: str) -> bool:
|
||||
if not _has_table(table_name):
|
||||
return False
|
||||
inspector = inspect(op.get_bind())
|
||||
return any(col["name"] == column_name for col in inspector.get_columns(table_name))
|
||||
|
||||
|
||||
def _has_index(table_name: str, index_name: str) -> bool:
|
||||
if not _has_table(table_name):
|
||||
return False
|
||||
inspector = inspect(op.get_bind())
|
||||
return any(idx["name"] == index_name for idx in inspector.get_indexes(table_name))
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
# Brand-new DBs: the table is created with the column already present
|
||||
# (by create_all / revision 20260518_07) — nothing to patch.
|
||||
if not _has_table("tool_call_metrics"):
|
||||
return
|
||||
if not _has_column("tool_call_metrics", "skill_name"):
|
||||
op.add_column("tool_call_metrics", sa.Column("skill_name", sa.String(128), nullable=True))
|
||||
if not _has_index("tool_call_metrics", "ix_tool_call_metrics_skill_name"):
|
||||
op.create_index("ix_tool_call_metrics_skill_name", "tool_call_metrics", ["skill_name"])
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
if _has_index("tool_call_metrics", "ix_tool_call_metrics_skill_name"):
|
||||
op.drop_index("ix_tool_call_metrics_skill_name", table_name="tool_call_metrics")
|
||||
if _has_column("tool_call_metrics", "skill_name"):
|
||||
op.drop_column("tool_call_metrics", "skill_name")
|
||||
+2
@@ -33,6 +33,7 @@ from deerflow.persistence.skills.model import SkillRow
|
||||
from deerflow.persistence.tags.model import TagAssignmentRow, TagRow
|
||||
from deerflow.persistence.thread_meta.model import ThreadMetaRow
|
||||
from deerflow.persistence.thread_shares.model import ThreadShareRow
|
||||
from deerflow.persistence.tool_metrics.model import ToolCallMetricRow
|
||||
from deerflow.persistence.user.model import UserRow
|
||||
|
||||
__all__ = [
|
||||
@@ -53,5 +54,6 @@ __all__ = [
|
||||
"TagRow",
|
||||
"ThreadMetaRow",
|
||||
"ThreadShareRow",
|
||||
"ToolCallMetricRow",
|
||||
"UserRow",
|
||||
]
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
"""Persistence layer for per-tool-call (skill-call) metrics.
|
||||
|
||||
Every tool invocation — built-in tools, skills, MCP tools, subagent calls —
|
||||
writes one row recording duration and outcome. Failures are bucketed into a
|
||||
coarse ``error_category`` (rate_limited / ip_blocked / auth_error / timeout /
|
||||
network_error / not_found / empty_result / tool_error) so administrators can
|
||||
spot retrieval outages, blocked IPs, and quota problems at a glance.
|
||||
|
||||
**Skill-call merging**: a skill is often touched by several tool calls inside
|
||||
one run (read ``SKILL.md``, run a script, retry after a failure). Rather than
|
||||
one row per call, ``SqlToolMetricsStore.record`` upserts a single row per
|
||||
``(run_id, skill_name)``: any success in the run wins (a skill that failed then
|
||||
finally succeeded is recorded as one success), and a skill that only ever
|
||||
failed yields one ``error`` row whose ``error_message`` accumulates every
|
||||
attempt's message. Non-skill tool calls keep one row each.
|
||||
"""
|
||||
|
||||
from deerflow.persistence.tool_metrics.base import ToolMetricRecord, ToolMetricsStore
|
||||
from deerflow.persistence.tool_metrics.model import ToolCallMetricRow
|
||||
from deerflow.persistence.tool_metrics.sql import SqlToolMetricsStore
|
||||
|
||||
__all__ = [
|
||||
"ToolCallMetricRow",
|
||||
"ToolMetricRecord",
|
||||
"ToolMetricsStore",
|
||||
"SqlToolMetricsStore",
|
||||
"make_tool_metrics_store",
|
||||
]
|
||||
|
||||
|
||||
def make_tool_metrics_store(session_factory) -> ToolMetricsStore | None:
|
||||
"""Return a SQL-backed metrics store, or ``None`` when no DB is configured."""
|
||||
if session_factory is None:
|
||||
return None
|
||||
return SqlToolMetricsStore(session_factory)
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
"""Abstract repository contract for tool / skill call metrics."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolMetricRecord:
|
||||
"""In-memory shape of a tool-call metric row before persistence."""
|
||||
|
||||
id: str
|
||||
created_at: datetime
|
||||
user_id: str | None = None
|
||||
thread_id: str | None = None
|
||||
run_id: str | None = None
|
||||
agent_name: str | None = None
|
||||
tool_name: str | None = None
|
||||
# The specific Agent Skill this call targets, when the tool is a skill tool
|
||||
# (``skill_view`` / ``skill_manage`` / ``skill_archive``) — taken from the
|
||||
# call's ``name`` argument. Null for every non-skill tool call. This is
|
||||
# what lets the admin see "skill X was invoked, and succeeded/failed".
|
||||
skill_name: str | None = None
|
||||
duration_ms: int = 0
|
||||
status: str = "success"
|
||||
# Coarse failure bucket: rate_limited / ip_blocked / auth_error / timeout /
|
||||
# network_error / not_found / empty_result / tool_error. Null on success.
|
||||
error_category: str | None = None
|
||||
error_message: str | None = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolMetricsQuery:
|
||||
"""Filter set for the admin list / export endpoints."""
|
||||
|
||||
user_id: str | None = None
|
||||
tool_name: str | None = None
|
||||
# When True, keep only rows that target a specific Agent Skill
|
||||
# (``skill_name IS NOT NULL``) — the ``kind=skill`` filter.
|
||||
skill_only: bool = False
|
||||
# Filter to one specific skill by name.
|
||||
skill_name: str | None = None
|
||||
status: str | None = None
|
||||
error_category: str | None = None
|
||||
since: datetime | None = None
|
||||
until: datetime | None = None
|
||||
limit: int = 100
|
||||
offset: int = 0
|
||||
|
||||
|
||||
class ToolMetricsStore(ABC):
|
||||
"""Persistence contract for the tool-metrics middleware + admin API."""
|
||||
|
||||
@abstractmethod
|
||||
async def record(self, metric: ToolMetricRecord) -> None:
|
||||
"""Persist one metric row. Must never raise on best-effort writes."""
|
||||
raise NotImplementedError
|
||||
|
||||
@abstractmethod
|
||||
async def list(self, query: ToolMetricsQuery) -> list[dict[str, Any]]:
|
||||
"""Return the matching rows (newest first), paginated by ``query``."""
|
||||
raise NotImplementedError
|
||||
|
||||
@abstractmethod
|
||||
async def count(self, query: ToolMetricsQuery) -> int:
|
||||
"""Return the unpaginated row count for ``query``."""
|
||||
raise NotImplementedError
|
||||
|
||||
@abstractmethod
|
||||
async def iter_all(self, query: ToolMetricsQuery):
|
||||
"""Yield rows matching ``query`` without pagination — used by export."""
|
||||
raise NotImplementedError
|
||||
|
||||
@abstractmethod
|
||||
async def skill_breakdown(self, query: ToolMetricsQuery) -> list[dict[str, Any]]:
|
||||
"""Per-skill aggregate: ``[{skill_name, total, success, error}, ...]``.
|
||||
|
||||
Only rows with a non-null ``skill_name`` are counted, so this answers
|
||||
"which skills were invoked, and how often did each succeed/fail".
|
||||
"""
|
||||
raise NotImplementedError
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
"""ORM model for per-tool-call (skill-call) metrics."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import UTC, datetime
|
||||
|
||||
from sqlalchemy import Integer, String, Text
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from deerflow.persistence.base import Base
|
||||
from deerflow.persistence.types import BeijingDateTime
|
||||
|
||||
|
||||
class ToolCallMetricRow(Base):
|
||||
"""One row per completed (or failed) tool / skill invocation.
|
||||
|
||||
Unlike :class:`LlmCallMetricRow` this also captures *self-handled*
|
||||
failures — search tools that swallow an HTTP 429/403 and return an error
|
||||
payload instead of raising — so an admin can see "retrieval failed" /
|
||||
"IP blocked" events that never surfaced as exceptions.
|
||||
"""
|
||||
|
||||
__tablename__ = "tool_call_metrics"
|
||||
|
||||
id: Mapped[str] = mapped_column(String(64), primary_key=True)
|
||||
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), default=lambda: datetime.now(UTC), index=True)
|
||||
|
||||
user_id: Mapped[str | None] = mapped_column(String(64), index=True)
|
||||
thread_id: Mapped[str | None] = mapped_column(String(64), index=True)
|
||||
run_id: Mapped[str | None] = mapped_column(String(64), index=True)
|
||||
agent_name: Mapped[str | None] = mapped_column(String(128), index=True)
|
||||
tool_name: Mapped[str | None] = mapped_column(String(128), index=True)
|
||||
# The specific Agent Skill targeted by a skill tool call (from the call's
|
||||
# ``name`` argument); null for non-skill tool calls.
|
||||
skill_name: Mapped[str | None] = mapped_column(String(128), index=True)
|
||||
|
||||
duration_ms: Mapped[int] = mapped_column(Integer, default=0)
|
||||
|
||||
# "success" or "error".
|
||||
status: Mapped[str] = mapped_column(String(16), default="success", index=True)
|
||||
# Coarse failure bucket; null on success.
|
||||
error_category: Mapped[str | None] = mapped_column(String(32), index=True)
|
||||
error_message: Mapped[str | None] = mapped_column(Text)
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
return {
|
||||
"id": self.id,
|
||||
"created_at": self.created_at.isoformat() if isinstance(self.created_at, datetime) else self.created_at,
|
||||
"user_id": self.user_id,
|
||||
"thread_id": self.thread_id,
|
||||
"run_id": self.run_id,
|
||||
"agent_name": self.agent_name,
|
||||
"tool_name": self.tool_name,
|
||||
"skill_name": self.skill_name,
|
||||
"duration_ms": self.duration_ms,
|
||||
"status": self.status,
|
||||
"error_category": self.error_category,
|
||||
"error_message": self.error_message,
|
||||
}
|
||||
+247
@@ -0,0 +1,247 @@
|
||||
"""SQLAlchemy-backed tool metrics repository."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from collections.abc import AsyncIterator
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy import desc, func, select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.tool_metrics.base import ToolMetricRecord, ToolMetricsQuery, ToolMetricsStore
|
||||
from deerflow.persistence.tool_metrics.model import ToolCallMetricRow
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Separator joining every failed attempt's message inside one merged skill row.
|
||||
_ERROR_SEP = "\n--- \n"
|
||||
# Hard cap on the accumulated ``error_message`` of a merged row.
|
||||
_MERGED_ERROR_LIMIT = 2000
|
||||
|
||||
# A single skill invocation often spans several tool calls (read SKILL.md, run
|
||||
# a script, ...), and the model may retry a skill within the same run. Those
|
||||
# fire-and-forget writes can interleave on the event loop, so the read → merge →
|
||||
# write of a skill row is guarded by a lock. ``asyncio.Lock`` binds to the loop
|
||||
# it is used on; the lock is therefore (re)created whenever the running loop
|
||||
# changes (the Gateway keeps one persistent loop, while the ``asyncio.run``
|
||||
# fallback path spins up a throwaway loop per call — already serialized).
|
||||
_merge_lock: asyncio.Lock | None = None
|
||||
_merge_lock_loop: object = None
|
||||
|
||||
|
||||
def _skill_merge_lock() -> asyncio.Lock:
|
||||
global _merge_lock, _merge_lock_loop
|
||||
loop = asyncio.get_running_loop()
|
||||
if _merge_lock is None or _merge_lock_loop is not loop:
|
||||
_merge_lock = asyncio.Lock()
|
||||
_merge_lock_loop = loop
|
||||
return _merge_lock
|
||||
|
||||
|
||||
def _normalize_created_at(value: datetime) -> datetime:
|
||||
return value if value.tzinfo else value.replace(tzinfo=UTC)
|
||||
|
||||
|
||||
def _merge_error_messages(existing: str | None, new: str | None) -> str | None:
|
||||
"""Append a failed attempt's message to the accumulated error text.
|
||||
|
||||
All failures are kept ("都统计下来"), separated and capped at
|
||||
:data:`_MERGED_ERROR_LIMIT` characters.
|
||||
"""
|
||||
new = (new or "").strip()
|
||||
if not new:
|
||||
return existing
|
||||
existing = (existing or "").strip()
|
||||
if not existing:
|
||||
return new
|
||||
if new in existing:
|
||||
# Identical retry failure — no point storing the same line twice.
|
||||
return existing
|
||||
combined = existing + _ERROR_SEP + new
|
||||
if len(combined) > _MERGED_ERROR_LIMIT:
|
||||
combined = combined[: _MERGED_ERROR_LIMIT - 3] + "..."
|
||||
return combined
|
||||
|
||||
|
||||
def _merge_skill_row(existing: ToolCallMetricRow, metric: ToolMetricRecord) -> None:
|
||||
"""Fold another same-run, same-skill call into an existing metric row.
|
||||
|
||||
Outcome rules:
|
||||
- any success in the run -> the row becomes a single ``success`` and earlier
|
||||
failures are dropped ("先报错、最后成功 -> 记一次成功");
|
||||
- all calls failed -> a single ``error`` row whose ``error_message``
|
||||
accumulates every attempt's message ("一直报错 -> 记一次,报错信息都统计下来").
|
||||
"""
|
||||
existing.duration_ms = (existing.duration_ms or 0) + (metric.duration_ms or 0)
|
||||
if metric.status == "success":
|
||||
if existing.status != "success":
|
||||
existing.status = "success"
|
||||
existing.error_category = None
|
||||
existing.error_message = None
|
||||
return
|
||||
# metric.status == "error"
|
||||
if existing.status == "success":
|
||||
# The skill already succeeded once this run — keep that outcome.
|
||||
return
|
||||
existing.status = "error"
|
||||
if metric.error_category:
|
||||
existing.error_category = metric.error_category
|
||||
existing.error_message = _merge_error_messages(existing.error_message, metric.error_message)
|
||||
|
||||
|
||||
def _row_from_metric(metric: ToolMetricRecord) -> ToolCallMetricRow:
|
||||
return ToolCallMetricRow(
|
||||
id=metric.id,
|
||||
created_at=_normalize_created_at(metric.created_at),
|
||||
user_id=metric.user_id,
|
||||
thread_id=metric.thread_id,
|
||||
run_id=metric.run_id,
|
||||
agent_name=metric.agent_name,
|
||||
tool_name=metric.tool_name,
|
||||
skill_name=metric.skill_name,
|
||||
duration_ms=metric.duration_ms,
|
||||
status=metric.status,
|
||||
error_category=metric.error_category,
|
||||
error_message=metric.error_message,
|
||||
)
|
||||
|
||||
|
||||
class SqlToolMetricsStore(ToolMetricsStore):
|
||||
"""SQLite/Postgres/MySQL-backed implementation; writes are fire-and-forget."""
|
||||
|
||||
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
|
||||
self._sf = session_factory
|
||||
|
||||
async def record(self, metric: ToolMetricRecord) -> None:
|
||||
# Skill calls are merged per run: the model may touch one skill across
|
||||
# several tool calls / retries, and the admin wants a single row per
|
||||
# (run, skill) instead of one per call. Non-skill tool calls, and skill
|
||||
# calls with no run_id, fall back to a plain insert.
|
||||
if metric.skill_name and metric.run_id:
|
||||
await self._record_skill_merged(metric)
|
||||
return
|
||||
try:
|
||||
async with self._sf() as session:
|
||||
session.add(_row_from_metric(metric))
|
||||
await session.commit()
|
||||
except Exception:
|
||||
# Metrics are best-effort; never surface a write failure to the runtime.
|
||||
logger.warning("Failed to persist tool_call_metrics row %s", metric.id, exc_info=True)
|
||||
|
||||
async def _record_skill_merged(self, metric: ToolMetricRecord) -> None:
|
||||
"""Upsert a per-(run, skill) row, folding repeated calls into one."""
|
||||
try:
|
||||
async with _skill_merge_lock():
|
||||
async with self._sf() as session:
|
||||
existing = await session.scalar(
|
||||
select(ToolCallMetricRow)
|
||||
.where(
|
||||
ToolCallMetricRow.run_id == metric.run_id,
|
||||
ToolCallMetricRow.skill_name == metric.skill_name,
|
||||
)
|
||||
.order_by(ToolCallMetricRow.created_at)
|
||||
.limit(1)
|
||||
)
|
||||
if existing is None:
|
||||
session.add(_row_from_metric(metric))
|
||||
else:
|
||||
_merge_skill_row(existing, metric)
|
||||
await session.commit()
|
||||
except Exception:
|
||||
logger.warning(
|
||||
"Failed to merge tool_call_metrics for skill %s (run %s)",
|
||||
metric.skill_name,
|
||||
metric.run_id,
|
||||
exc_info=True,
|
||||
)
|
||||
|
||||
def _apply_filters(self, stmt, query: ToolMetricsQuery):
|
||||
if query.user_id:
|
||||
stmt = stmt.where(ToolCallMetricRow.user_id == query.user_id)
|
||||
if query.tool_name:
|
||||
stmt = stmt.where(ToolCallMetricRow.tool_name == query.tool_name)
|
||||
if query.skill_only:
|
||||
stmt = stmt.where(ToolCallMetricRow.skill_name.is_not(None))
|
||||
if query.skill_name:
|
||||
stmt = stmt.where(ToolCallMetricRow.skill_name == query.skill_name)
|
||||
if query.status:
|
||||
stmt = stmt.where(ToolCallMetricRow.status == query.status)
|
||||
if query.error_category:
|
||||
stmt = stmt.where(ToolCallMetricRow.error_category == query.error_category)
|
||||
if query.since is not None:
|
||||
stmt = stmt.where(ToolCallMetricRow.created_at >= _normalize_created_at(query.since))
|
||||
if query.until is not None:
|
||||
stmt = stmt.where(ToolCallMetricRow.created_at <= _normalize_created_at(query.until))
|
||||
return stmt
|
||||
|
||||
async def list(self, query: ToolMetricsQuery) -> list[dict[str, Any]]:
|
||||
stmt = select(ToolCallMetricRow)
|
||||
stmt = self._apply_filters(stmt, query)
|
||||
stmt = stmt.order_by(desc(ToolCallMetricRow.created_at)).limit(max(1, min(query.limit, 1000))).offset(max(0, query.offset))
|
||||
async with self._sf() as session:
|
||||
result = await session.execute(stmt)
|
||||
return [row.to_dict() for row in result.scalars()]
|
||||
|
||||
async def count(self, query: ToolMetricsQuery) -> int:
|
||||
stmt = select(func.count()).select_from(ToolCallMetricRow)
|
||||
stmt = self._apply_filters(stmt, query)
|
||||
async with self._sf() as session:
|
||||
return (await session.scalar(stmt)) or 0
|
||||
|
||||
async def iter_all(self, query: ToolMetricsQuery) -> AsyncIterator[dict[str, Any]]:
|
||||
page_size = 500
|
||||
offset = 0
|
||||
while True:
|
||||
page = await self.list(
|
||||
ToolMetricsQuery(
|
||||
user_id=query.user_id,
|
||||
tool_name=query.tool_name,
|
||||
skill_only=query.skill_only,
|
||||
skill_name=query.skill_name,
|
||||
status=query.status,
|
||||
error_category=query.error_category,
|
||||
since=query.since,
|
||||
until=query.until,
|
||||
limit=page_size,
|
||||
offset=offset,
|
||||
)
|
||||
)
|
||||
if not page:
|
||||
return
|
||||
for item in page:
|
||||
yield item
|
||||
if len(page) < page_size:
|
||||
return
|
||||
offset += page_size
|
||||
|
||||
async def skill_breakdown(self, query: ToolMetricsQuery) -> list[dict[str, Any]]:
|
||||
# Count success/error per skill. Force the skill-only filter so rows
|
||||
# without a skill_name (plain tool calls) never leak into the result.
|
||||
scoped = ToolMetricsQuery(
|
||||
user_id=query.user_id,
|
||||
skill_only=True,
|
||||
skill_name=query.skill_name,
|
||||
since=query.since,
|
||||
until=query.until,
|
||||
)
|
||||
stmt = select(
|
||||
ToolCallMetricRow.skill_name,
|
||||
ToolCallMetricRow.status,
|
||||
func.count().label("n"),
|
||||
)
|
||||
stmt = self._apply_filters(stmt, scoped).group_by(
|
||||
ToolCallMetricRow.skill_name, ToolCallMetricRow.status
|
||||
)
|
||||
agg: dict[str, dict[str, int]] = {}
|
||||
async with self._sf() as session:
|
||||
for skill_name, status, n in (await session.execute(stmt)).all():
|
||||
bucket = agg.setdefault(skill_name, {"total": 0, "success": 0, "error": 0})
|
||||
bucket["total"] += n
|
||||
bucket["success" if status == "success" else "error"] += n
|
||||
return [
|
||||
{"skill_name": name, **counts}
|
||||
for name, counts in sorted(agg.items(), key=lambda kv: kv[1]["total"], reverse=True)
|
||||
]
|
||||
@@ -556,6 +556,41 @@ def _render_candidate_list(user_id: str) -> str:
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _candidate_skill_names(candidate_list: str) -> list[str]:
|
||||
"""从 :func:`_render_candidate_list` 的文本里抽出技能名。
|
||||
|
||||
候选行形如 ``- {name} [state=..., ...]``,技能名是 ``- `` 之后的第一个 token。
|
||||
"""
|
||||
return [
|
||||
line[2:].split(" ", 1)[0]
|
||||
for line in candidate_list.splitlines()
|
||||
if line.startswith("- ")
|
||||
]
|
||||
|
||||
|
||||
def _log_scanned_skills(user_id: str) -> list[str]:
|
||||
"""记录并返回本次策展扫描到的技能名(Agent 创建、属于该用户)。
|
||||
|
||||
每次技能进化运行时调用 —— 把涉及的技能名打到日志,便于排查"哪些技能
|
||||
被策展程序处理了"。返回排序后的技能名列表。
|
||||
"""
|
||||
from deerflow.skills import curator_log
|
||||
from deerflow.skills.usage import agent_created_entries
|
||||
|
||||
owned = _list_user_owned_skill_names(user_id)
|
||||
scanned = agent_created_entries()
|
||||
if owned is not None:
|
||||
scanned = {n: e for n, e in scanned.items() if n in owned}
|
||||
names = sorted(scanned)
|
||||
logger.info("Curator[%s]: 本次扫描到 %d 个技能 — %s", user_id, len(names), names)
|
||||
curator_log.record(
|
||||
"info",
|
||||
f"本次扫描到 {len(names)} 个 Agent 创建的技能:{', '.join(names) or '(无)'}",
|
||||
user_id=user_id,
|
||||
)
|
||||
return names
|
||||
|
||||
|
||||
_CURATOR_REVIEW_PROMPT = (
|
||||
"You are running as DeerFlow's background skill CURATOR. This is an "
|
||||
"UMBRELLA-BUILDING consolidation pass, not a passive audit and not a "
|
||||
@@ -959,6 +994,9 @@ def run_curator_review(user_id: str) -> dict:
|
||||
logger.info("Curator[%s]: starting run at %s", user_id, now.isoformat())
|
||||
curator_log.record("info", f"本次策展开始,启动时间 {now.isoformat()}", user_id=user_id)
|
||||
|
||||
# 输出本次技能进化涉及的技能名,便于排查。
|
||||
_log_scanned_skills(user_id)
|
||||
|
||||
transition_counters = apply_automatic_transitions(user_id, now)
|
||||
logger.info("Curator[%s]: transitions=%s", user_id, transition_counters)
|
||||
curator_log.record(
|
||||
@@ -972,9 +1010,19 @@ def run_curator_review(user_id: str) -> dict:
|
||||
)
|
||||
|
||||
candidate_list = _render_candidate_list(user_id)
|
||||
candidate_line_count = 0 if not candidate_list.strip() else len([line for line in candidate_list.splitlines() if line.startswith("- ")])
|
||||
candidate_names = _candidate_skill_names(candidate_list)
|
||||
candidate_line_count = len(candidate_names)
|
||||
logger.info(
|
||||
"Curator[%s]: %d 个候选技能进入 LLM 评审 — %s",
|
||||
user_id,
|
||||
candidate_line_count,
|
||||
candidate_names,
|
||||
)
|
||||
curator_log.record(
|
||||
"info", f"进入 LLM 评审的候选技能:共 {candidate_line_count} 个", user_id=user_id
|
||||
"info",
|
||||
f"进入 LLM 评审的候选技能:共 {candidate_line_count} 个"
|
||||
+ (f" —— {', '.join(candidate_names)}" if candidate_names else ""),
|
||||
user_id=user_id,
|
||||
)
|
||||
|
||||
if candidate_line_count == 0:
|
||||
@@ -1168,9 +1216,13 @@ def get_curator_status(user_id: str) -> dict:
|
||||
if owned is not None:
|
||||
entries = {name: entry for name, entry in entries.items() if name in owned}
|
||||
counts: dict[str, int] = {STATE_ACTIVE: 0, STATE_STALE: 0, STATE_ARCHIVED: 0}
|
||||
pinned_count = 0
|
||||
for entry in entries.values():
|
||||
s = entry.get("state", STATE_ACTIVE)
|
||||
counts[s] = counts.get(s, 0) + 1
|
||||
# pinned 与生命周期状态正交 —— 单独计数。
|
||||
if entry.get("pinned"):
|
||||
pinned_count += 1
|
||||
|
||||
cfg = _get_curator_config(user_id)
|
||||
return {
|
||||
@@ -1184,6 +1236,8 @@ def get_curator_status(user_id: str) -> dict:
|
||||
"active": counts[STATE_ACTIVE],
|
||||
"stale": counts[STATE_STALE],
|
||||
"archived": counts[STATE_ARCHIVED],
|
||||
# 被 pin 的数量;与 active/stale/archived 正交,不计入它们的和。
|
||||
"pinned": pinned_count,
|
||||
},
|
||||
# 上次运行的两份记录:LLM 自述的建议 + 实际发生的工具调用,供前端对照展示。
|
||||
"last_consolidation_suggestions": state.get("last_consolidation_suggestions")
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
+159
@@ -0,0 +1,159 @@
|
||||
"""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 —— 拿不准时优先选 memory:
|
||||
- memory:当前 agent 的私有记忆 (agent 隔离)。**默认选这个。**
|
||||
只要用户是在对当前这个 agent 说话 —— 例如 "你以后……"、"和我说话时……"、
|
||||
针对本助手的语气/开场白/回复风格/处理方式,以及环境事实、约定、踩过的坑 —— 一律记到 memory,
|
||||
这样只影响当前 agent。
|
||||
- user:用户画像 (跨所有 agent 共享)。仅当信息是**跨所有 agent 都通用**的客观身份事实时才用 ——
|
||||
姓名、角色、时区、惯用语言。除非用户明确说 "所有助手都……",否则不要把沟通风格/偏好记到 user。
|
||||
|
||||
不要记:一次性任务进度、可以重新查到的信息、临时 TODO 状态。
|
||||
|
||||
Args:
|
||||
action: 操作类型。add 新增条目;replace 替换 (用 old_text 定位);remove 删除 (用 old_text 定位)。
|
||||
target: 记忆类别。默认用 memory (当前 agent 私有);只有跨所有 agent 通用的用户身份事实才用 user。
|
||||
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,25 @@ 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)
|
||||
# skill_list / skill_view 是只读工具(发现、查看技能),与"自我进化"写能力无关,
|
||||
# 始终提供给 agent。
|
||||
from deerflow.tools.builtins.skill_tools import skill_list_tool, skill_view_tool
|
||||
|
||||
@@ -39,6 +39,7 @@ dependencies = [
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
hindsight = ["hindsight-client>=0.4.22"]
|
||||
ollama = ["langchain-ollama>=0.3.0"]
|
||||
postgres = [
|
||||
"asyncpg>=0.29",
|
||||
|
||||
Reference in new issue
Block a user