初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

@@ -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"]
@@ -0,0 +1,420 @@
"""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]
content = "\n\n".join(blocks)
if not content:
return ""
return f"<memory>\n{content}\n</memory>"
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"]
@@ -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"]
@@ -0,0 +1,93 @@
"""Read-only provider for the mounted policy knowledge base.
This provider keeps the current knowledge-base behaviour: inject the lightweight
``routing.md`` guide and let the model decide when to read concrete files. It
does not automatically retrieve snippets and never writes to the knowledge base.
"""
from __future__ import annotations
import logging
from functools import lru_cache
from pathlib import Path
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
logger = logging.getLogger(__name__)
@lru_cache(maxsize=16)
def _read_routing_file(host_path: str) -> str:
path = Path(host_path)
if not path.is_file():
return ""
return path.read_text(encoding="utf-8").strip()
class KnowledgeProvider(MemoryProvider):
"""Injects the knowledge routing guide as a read-only context provider."""
def __init__(self, *, app_config: Any | None = None) -> None:
self._app_config = app_config
self._routing_host_path: Path | None = None
@property
def name(self) -> str:
return "knowledge"
def is_available(self) -> bool:
return True
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str,
**kwargs: Any,
) -> None:
app_config = self._app_config or kwargs.get("app_config")
if app_config is None:
from deerflow.config import get_app_config
app_config = get_app_config()
self._routing_host_path = None
for mount in app_config.sandbox.mounts or []:
if mount.container_path.rstrip("/") == "/mnt/knowledge":
self._routing_host_path = Path(mount.host_path) / "routing.md"
break
def system_prompt_block(self) -> str:
if self._routing_host_path is None:
return ""
content = _read_routing_file(str(self._routing_host_path.resolve()))
if not content:
return ""
logger.debug("Injected knowledge routing memory from %s", self._routing_host_path)
return f"""<knowledge_routing_memory source="/mnt/knowledge/routing.md">
{content}
</knowledge_routing_memory>"""
def prefetch(self, query: str, *, thread_id: str = "") -> str:
return ""
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
return None
def get_tool_schemas(self) -> list[dict[str, Any]]:
return []
__all__ = ["KnowledgeProvider"]
@@ -0,0 +1,161 @@
"""Memory V1 — 原版 DeerFlow JSON-based MemoryProvider 实现。
存储格式:``{base_dir}/users/{user_id}/memory.json``(经 FileMemoryStorage 管理)
JSON 结构使用嵌套 ``{summary, updatedAt}`` 对象,与原版 DeerFlow 完全一致。
LLM 在 V1 模式下不调用 memory 工具 —— 事实完全由异步 LLM 提取。
"""
from __future__ import annotations
import logging
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
logger = logging.getLogger(__name__)
class _FakeMsg:
"""轻量 message 对象,用于将文本传给原版 format_conversation_for_update。"""
__slots__ = ("type", "content")
def __init__(self, type_: str, content: str) -> None:
self.type = type_
self.content = content
class V1BuiltinProvider(MemoryProvider):
"""原版 DeerFlow V1 记忆 provider。"""
def __init__(
self,
*,
max_facts: int = 100,
fact_confidence_threshold: float = 0.7,
debounce_seconds: int = 30,
model_name: str = "",
token_budget: int = 2000,
) -> None:
self._max_facts = max_facts
self._confidence_threshold = fact_confidence_threshold
self._debounce_seconds = debounce_seconds
self._model_name = model_name
self._token_budget = token_budget
self._user_id: str = ""
self._thread_id: str = ""
self._agent_id: str | None = None
self._frozen_block: str = ""
@property
def name(self) -> str:
return "v1_builtin"
def is_available(self) -> bool:
return True
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str,
**kwargs: Any,
) -> None:
_ = base_dir # FileMemoryStorage uses get_paths() internally
self._user_id = user_id
self._thread_id = thread_id or ""
self._agent_id = agent_id
self._frozen_block = self._build_frozen_block()
# ---- 系统提示词 -------------------------------------------------------
def _build_frozen_block(self) -> str:
"""从 memory.json 读取数据,用 format_memory_for_injection 渲染注入块。
当 agent_id 已知时加载 per-agent 记忆;否则加载用户级记忆。
"""
try:
from deerflow.agents.memory.v1.prompt import format_memory_for_injection
from deerflow.agents.memory.v1.storage import get_memory_storage
data = get_memory_storage().load(
agent_name=self._agent_id or None,
user_id=self._user_id,
)
text = format_memory_for_injection(data, max_tokens=self._token_budget)
if not text:
return ""
return f"<memory>\n{text}\n</memory>"
except Exception as exc: # noqa: BLE001
logger.warning("V1 provider 加载 memory.json 失败: %s", exc)
return ""
def system_prompt_block(self) -> str:
return self._frozen_block
# ---- 召回 / 写入 ------------------------------------------------------
def prefetch(self, query: str, *, thread_id: str = "") -> str:
# V1 无动态召回,静态 snapshot 已在 system_prompt_block 里
return ""
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""把本轮对话加入防抖队列,等待 LLM 异步提取事实。"""
if not user_content.strip() and not assistant_content.strip():
return
try:
from deerflow.agents.memory.v1.queue import get_memory_queue
msgs = [
_FakeMsg("human", user_content),
_FakeMsg("ai", assistant_content),
]
queue = get_memory_queue()
queue.add(
thread_id=thread_id or self._thread_id,
messages=msgs,
user_id=self._user_id,
agent_name=self._agent_id or None,
)
except Exception as exc: # noqa: BLE001
logger.warning("V1 provider sync_turn 入队失败: %s", exc)
# ---- 工具 (V1 不暴露工具给 LLM) -------------------------------------
def get_tool_schemas(self) -> list[dict[str, Any]]:
return []
# ---- API 读取接口 (供 Gateway router 用) -----------------------------
def read_v1_data(self) -> dict[str, Any]:
"""读取 memory.json 的当前内容(实时读磁盘,非 frozen snapshot)。
当 agent_id 已知时读取 per-agent 记忆;否则读用户级记忆。
"""
from deerflow.agents.memory.v1.storage import get_memory_storage
return get_memory_storage().load(
agent_name=self._agent_id or None,
user_id=self._user_id,
)
def fact_count(self) -> int:
try:
return len(self.read_v1_data().get("facts", []))
except Exception: # noqa: BLE001
return 0
def usage_text(self) -> str:
return f"{self.fact_count()}/{self._max_facts} 个事实"
__all__ = ["V1BuiltinProvider"]