fix(memory): 修复 Hindsight provider 生命周期的三处缺陷

HindsightProvider 被 build_memory_manager 每轮重新构造,以下三个问题
都源于这个无状态特性未被正确处理:

1. document_id 每轮漂移 —— 原 _reset_retain_batch 用微秒时间戳拼接,
   导致同一 thread 的每轮 retain 落到不同文档,文档数随对话轮数线性膨胀。
   改为按 thread_id 确定性派生 (thread-{thread_id}),同一 thread 累积成一份。

2. retain_every_n_turns 失效 —— 进程内 _turn_counter 每轮被 initialize
   重置,retain_every_n_turns > 1 时永不触发。新增 turn_index 参数贯穿
   sync_turn/sync_all,由 MemoryMiddleware 按对话历史 (count_user_turns)
   算出并传入;_turn_counter 仅作缺省退路。

3. aiohttp ClientSession 泄漏 —— 缓存的客户端从不 shutdown,且 _run_coro
   每次新建事件循环使缓存客户端失效,触发 "Unclosed client session"。
   改为客户端即开即关:_run_with_client 在 finally 保证关闭,_client_factory
   作为可覆盖的测试注入点。

测试:test_hindsight_provider.py 全量重写 (含 TestDocumentId /
TestRetainEveryNTurnsAcrossRecreation / TestClientLifecycle),
新增 test_memory_message_processing.py,test_memory_manager.py 补
turn_index 透传用例。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@
This commit is contained in:
xuhd committed 2026-05-18 14:34:22 +08:00
1 parent 8f88427d4e
commit dba821a70e
8 files changed
+770 -61

No files matched your search

@@ -153,11 +153,20 @@ class MemoryManager:
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""把一轮完成的对话同步到所有 provider。"""
"""把一轮完成的对话同步到所有 provider。
``turn_index`` 是当前对话的轮次序号,透传给各 provider 用于轮次节流。
"""
for provider in self._providers:
try:
provider.sync_turn(user_content, assistant_content, thread_id=thread_id)
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)
@@ -29,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 = []
@@ -117,11 +117,17 @@ class MemoryProvider(ABC):
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""每轮对话结束后把对话持久化到后端。
实现应当非阻塞 —— 如果后端有延迟,排队到后台处理而不是直接调用。
默认 no-op。
``turn_index`` 是当前对话的轮次序号 (从 1 开始,由编排层按对话历史算出)。
provider 通常被每轮重新构造、无法靠自身计数,需要按轮次节流写入
(例如 "每 N 轮 retain 一次") 的实现应当用它而非进程内计数器。
缺省 ``None`` 表示调用方未提供。
"""
# ---- LLM 工具 --------------------------------------------------------
@@ -17,6 +17,21 @@ HTTP 客户端方式接入一个用户自起的 Hindsight Docker 实例 (``local
召回:``prefetch`` 并发查两个 bank,合并结果。
document_id 与轮次计数
======================
本 provider 被 ``build_memory_manager`` 每轮重新构造 —— 是无状态的。因此:
- ``document_id`` 由 ``thread_id`` **确定性**派生,同一 thread 的所有轮次 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`
@@ -90,7 +105,6 @@ class HindsightProvider(MemoryProvider):
def __init__(self, config: HindsightMemoryConfig | None = None) -> None:
self._config = config or HindsightMemoryConfig()
self._client: Any = None
self._user_id: str = ""
self._agent_id: str = "default"
@@ -129,7 +143,7 @@ class HindsightProvider(MemoryProvider):
base_dir: str = "",
**kwargs: Any,
) -> None:
"""解析双 bank 名称,准备 retain 批次状态。客户端按需懒创建。"""
"""解析双 bank 名称,准备 retain 批次状态。客户端每次操作即开即关。"""
self._user_id = user_id or "default"
self._agent_id = (agent_id or "default").lower()
self._thread_id = thread_id or ""
@@ -154,41 +168,63 @@ class HindsightProvider(MemoryProvider):
return name.strip("-") or "deerflow"
def _reset_retain_batch(self) -> None:
"""重置 retain 批次状态 (新的 document_id + 轮次清零)。"""
ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
self._document_id = f"{self._thread_id or 'thread'}-{ts}"
"""重置 retain 批次状态。
``document_id`` 由 ``thread_id`` **确定性**派生 —— provider 虽然被每轮
重新构造,同一 thread 的所有轮次仍落到同一个 Hindsight 文档,累积成一份
而不是碎片化成一轮一个文档。无 thread 时 (例如 memory 工具镜像) 用统一
的兜底 id。轮次计数清零,仅作为 ``turn_index`` 缺失时的退路。
"""
self._document_id = f"thread-{self._thread_id}" if self._thread_id else "thread-default"
self._turn_counter = 0
def _get_client(self) -> Any:
"""懒创建并缓存 Hindsight HTTP 客户端。"""
if self._client is None:
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
self._client = Hindsight(**kwargs)
return self._client
def shutdown(self) -> None:
"""关闭客户端 (如果客户端暴露了 close)。"""
client = self._client
self._client = None
if client is None:
return
"""无需清理 —— 客户端在每次操作内即开即关,不缓存。"""
# ---- 客户端生命周期 --------------------------------------------------
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):
_run_coro(result, timeout=10)
except Exception as exc: # noqa: BLE001
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:
@@ -226,13 +262,11 @@ class HindsightProvider(MemoryProvider):
query = query[: self._config.recall_max_input_chars]
try:
user_results = self._recall_bank(self._user_bank, query)
work_results = self._recall_bank(self._work_bank, query)
merged = self._recall_both(query)
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
logger.debug("Hindsight 召回失败 (非致命):%s", exc)
return ""
merged = self._merge_results(user_results, work_results)
if not merged:
return ""
lines = "\n".join(f"- {text}" for text in merged)
@@ -242,18 +276,34 @@ class HindsightProvider(MemoryProvider):
f"{lines}"
)
def _recall_bank(self, bank_id: str, query: str) -> list[tuple[float, str]]:
"""召回单个 bank,返回 ``[(score, text), ...]``。"""
client = self._get_client()
resp = _run_coro(
client.arecall(
bank_id=bank_id,
query=query,
budget=self._config.recall_budget,
max_tokens=self._config.recall_max_tokens,
),
timeout=15,
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:
@@ -285,15 +335,28 @@ class HindsightProvider(MemoryProvider):
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
self._turn_counter += 1
if self._turn_counter % self._config.retain_every_n_turns != 0:
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 = (
@@ -330,8 +393,7 @@ class HindsightProvider(MemoryProvider):
logger.debug("Hindsight on_memory_write 镜像失败:%s", exc)
def _retain(self, bank_id: str, content: str, *, kind: str) -> None:
"""向某 bank 写入一条记忆。"""
client = self._get_client()
"""向某 bank 写入一条记忆。客户端即开即关。"""
metadata = {
"retained_at": _utc_now_iso(),
"kind": kind,
@@ -340,33 +402,36 @@ class HindsightProvider(MemoryProvider):
}
if self._thread_id:
metadata["thread_id"] = self._thread_id
_run_coro(
client.aretain(
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,
),
timeout=15,
)
)
_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
client = self._get_client()
resp = _run_coro(
client.areflect(bank_id=bank, query=query, budget=self._config.recall_budget),
timeout=30,
)
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 工具调用。"""
user_results = self._recall_bank(self._user_bank, query)
work_results = self._recall_bank(self._work_bank, query)
return self._merge_results(user_results, work_results)
return self._recall_both(query)
def retain_to_user_bank(self, content: str) -> None:
"""主动写入 user bank。供 hindsight_retain 工具调用。"""
@@ -27,7 +27,7 @@ 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 filter_messages_for_memory
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
@@ -221,6 +221,10 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
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(
@@ -229,7 +233,12 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
thread_id=thread_id,
config=effective_config,
)
manager.sync_all(user_text, assistant_text, thread_id=thread_id or "")
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)