feat(memory): Memory V2 重写 - 可插拔 provider + Hindsight 集成

以 Hermes 的可插拔记忆架构为骨架重写 deerflow 记忆模块,兼容原有
结构化数据,并新增 Hindsight 作为外部记忆后端。

P1 - 抽象层 + builtin 本地记忆:
- MemoryProvider 抽象基类 + MemoryManager 编排层(builtin + ≤1 外部)
- BuiltinFileProvider:USER.md/MEMORY.md 二元存储、字符配额、文件锁、
  原子写、frozen snapshot
- memory 工具(LangChain @tool):LLM 主动写入用户画像/工作笔记
- 记忆内容安全扫描(注入/外渗模式 + 不可见 unicode)
- memory_config 改为嵌套结构 + 旧扁平字段兼容 + per-user 三层覆盖
- 迁移脚本 migrate_memory_to_v2.py:旧 memory.json -> USER.md/MEMORY.md
- Gateway 新增 /api/memory/v2 与 v2/config 端点(用户可配置白名单字段)

P2 - Hindsight 外部 provider:
- HindsightProvider:双 bank 隔离(user bank 跨 agent 共享 + work bank
  agent 私有)、并发召回合并、auto-retain、on_memory_write 镜像
- hindsight_recall/reflect/retain 三个 LangChain 工具
- MemoryMiddleware.before_model 注入 Hindsight 动态召回
- context/tools/hybrid 三种 memory_mode
- hindsight-client 作为可选依赖,未装时自动退回纯 builtin

注入走系统提示词(builtin frozen snapshot)+ before_model(Hindsight
动态召回)。后台抽取保留但默认关闭,P3 期重接入。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
xuhdandClaude Opus 4.7 committed 2026-05-15 12:15:55 +08:00
1 parent 6947a3ffa7
commit f9d7610679
21 files changed
+3970 -188

No files matched your search

@@ -13,7 +13,7 @@ per-agent) was invisible from the settings page. See ``GET /api/memory/agents``
for discovering which agent-scoped buckets the current user owns.
"""
import re
from typing import Any
from fastapi import APIRouter, HTTPException, Query
from pydantic import BaseModel, Field
@@ -28,7 +28,13 @@ from deerflow.agents.memory.updater import (
update_memory_fact,
)
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.memory_config import get_memory_config
from deerflow.config.memory_config import (
USER_WRITABLE_FIELDS,
delete_user_memory_override,
get_effective_memory_config,
get_memory_config,
save_user_memory_override,
)
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
@@ -529,3 +535,141 @@ async def get_memory_status(agent: str | None = _AgentQuery) -> MemoryStatusResp
),
data=MemoryResponse(**memory_data),
)
# ===========================================================================
# Memory V2 端点
#
# 新增的 V2 端点用 /memory/v2 前缀,与旧端点并存 (旧端点服务后台抽取的
# memory.json,P3 期统一重写)。详见 docs/MEMORY_V2_DESIGN_ZH.md §11。
# ===========================================================================
class MemoryV2DataResponse(BaseModel):
"""Memory V2 builtin provider 的数据视图。"""
user_entries: list[str] = Field(default_factory=list, description="USER.md 条目 (用户画像)")
memory_entries: list[str] = Field(default_factory=list, description="MEMORY.md 条目 (agent 工作笔记)")
user_usage: str = Field(default="", description="USER.md 字符用量,如 '12% — 165/1375 字符'")
memory_usage: str = Field(default="", description="MEMORY.md 字符用量")
class MemoryV2ConfigResponse(BaseModel):
"""Memory V2 生效配置 (含三层覆盖合并结果) + 用户可改字段白名单。"""
config: dict[str, Any] = Field(..., description="按 per-user 覆盖合并后的生效配置")
writable_fields: list[str] = Field(..., description="用户可在运行时覆盖的字段 (点号路径)")
class MemoryConfigPatchRequest(BaseModel):
"""Memory V2 配置覆盖请求。
overrides 支持嵌套形式 ``{"injection": {"enabled": false}}`` 或点号扁平形式
``{"injection.enabled": false}``;非白名单字段会被忽略。
"""
overrides: dict[str, Any] = Field(..., description="要写入 per-user 覆盖的字段")
def _build_builtin_provider(user_id: str, agent_name: str | None):
"""按生效配置构建并初始化一个 V2 builtin provider。"""
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
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_name or "default",
base_dir=str(get_paths().base_dir),
)
return provider
@router.get(
"/memory/v2",
response_model=MemoryV2DataResponse,
summary="Get Memory V2 Data",
description="读取 Memory V2 builtin provider 的 USER.md / MEMORY.md 条目。",
)
async def get_memory_v2(agent: str | None = _AgentQuery) -> MemoryV2DataResponse:
"""读取当前用户的 Memory V2 本地记忆。"""
agent_name = _resolve_agent_name(agent)
user_id = get_effective_user_id()
try:
provider = _build_builtin_provider(user_id, agent_name)
return MemoryV2DataResponse(
user_entries=provider.read("user"),
memory_entries=provider.read("memory"),
user_usage=provider.usage("user"),
memory_usage=provider.usage("memory"),
)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to read memory V2 data.") from exc
@router.get(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Get Memory V2 Effective Config",
description="读取按 per-user 覆盖合并后的生效记忆配置,以及用户可改字段白名单。",
)
async def get_memory_v2_config() -> MemoryV2ConfigResponse:
"""读取当前用户的生效记忆配置。"""
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)
@router.patch(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Patch Memory V2 Config",
description="把白名单字段写入当前用户的 per-user 配置覆盖。非白名单字段被忽略。",
)
async def patch_memory_v2_config(request: MemoryConfigPatchRequest) -> MemoryV2ConfigResponse:
"""更新当前用户的 per-user 记忆配置覆盖。"""
user_id = get_effective_user_id()
try:
save_user_memory_override(user_id, request.overrides)
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to save memory config override.") from exc
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)
@router.delete(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Delete Memory V2 Config Override",
description=(
"撤销当前用户的 per-user 配置覆盖。传 ?field=injection.enabled 只撤销该字段;"
"不传 field 则清空整个 per-user 覆盖。"
),
)
async def delete_memory_v2_config(
field: str | None = Query(None, description="要撤销的点号路径字段;省略则清空全部覆盖"),
) -> MemoryV2ConfigResponse:
"""撤销当前用户的 per-user 记忆配置覆盖。"""
user_id = get_effective_user_id()
try:
delete_user_memory_override(user_id, field)
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to delete memory config override.") from exc
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)