feat: V1记忆系统支持、管理员记忆编辑及对话记忆注入开关

- 新增 V1 记忆系统(memory.json)支持:提取结果强制中文、历史字段修复为增量累积日志
- 用户设置页面:V1 模式下新增 agent 选择器,可查看各 agent 的私有记忆
- 管理员记忆页面:区分 V1/V2 渲染,V1 支持完整 CRUD(用户画像/历史摘要/事实记录)
- 后端新增 V1 记忆 CRUD API(sections/facts),前端同步添加对应 hooks 和 API 调用
- 新建专家页面:标记 bootstrap 线程类型,跳过记忆保存,侧边栏过滤该类线程
- 输入框工具栏新增「记忆」开关:关闭时 V1/V2 均不注入,开启时按 config.yaml 版本正常注入
- 修复 agent 目录不存在时的 FileNotFoundError,回退至默认配置

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
xuhdandClaude Sonnet 4.6 committed 2026-05-22 12:32:47 +08:00
1 parent d59e0514b3
commit b3a39cbdf7
27 files changed
+2725 -92

No files matched your search

@@ -27,6 +27,7 @@ from app.gateway.deps import (
from deerflow.agents.memory import BuiltinFileProvider
from deerflow.config.paths import get_paths
from deerflow.runtime import serialize_channel_values
from app.gateway.routers.memory import _build_v1_provider, _is_v1
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/users", tags=["admin-users"])
@@ -145,36 +146,29 @@ class AdminMemoryEntryReplaceRequest(BaseModel):
class AdminMemoryResponse(BaseModel):
user_id: str
version: str = Field(default="v2", description="记忆版本:v1 或 v2")
buckets: list[AdminMemoryBucket] = Field(default_factory=list)
def _read_memory_bucket(user_id: str, agent_id: str | None) -> dict:
"""Read one Memory V2 file into a JSON-able ``{"entries": [...]}`` dict.
``agent_id is None`` -> the user's ``USER.md`` (profile, cross-agent);
otherwise that agent's ``MEMORY.md`` (per-agent working notes).
"""
"""Read one Memory V2 file into a JSON-able ``{"entries": [...]}`` dict."""
provider = BuiltinFileProvider()
provider.initialize(user_id=user_id, agent_id=agent_id)
target = "user" if agent_id is None else "memory"
return {"entries": provider.read(target)}
def _read_v1_memory_bucket(user_id: str, agent_id: str | None) -> dict:
"""Read one V1 memory.json into its raw dict (facts / user / history)."""
provider = _build_v1_provider(user_id, agent_id)
return provider.read_v1_data()
@router.get("/{user_id}/memory", response_model=AdminMemoryResponse)
async def get_user_memory(user_id: str, request: Request) -> AdminMemoryResponse:
"""Return every memory bucket for one user.
Memory V2 layout: the ``global`` bucket is ``USER.md`` (user profile);
each per-agent bucket is that agent's ``MEMORY.md`` working notes.
Agent list is sourced from the database (all agents owned by this user)
so agents without any existing MEMORY.md still appear.
"""
"""Return every memory bucket for one user (V1 or V2 depending on config)."""
await _require_admin(request)
buckets: list[AdminMemoryBucket] = [
AdminMemoryBucket(name="global", display_name="用户画像", data=_read_memory_bucket(user_id, None))
]
# Source agents from the database: only agents owned by this specific user.
agent_store = get_agent_store(request)
all_agents = await agent_store.list_visible(user_id)
@@ -183,16 +177,39 @@ async def get_user_memory(user_id: str, request: Request) -> AdminMemoryResponse
key=lambda a: (a.get("name") or a["id"]).lower(),
)
if _is_v1(user_id):
# V1 模式:每个桶读 memory.json,内容为 {facts, user, history}
buckets: list[AdminMemoryBucket] = []
try:
buckets.append(AdminMemoryBucket(name="global", display_name="用户记忆", data=_read_v1_memory_bucket(user_id, None)))
except Exception:
buckets.append(AdminMemoryBucket(name="global", display_name="用户记忆", data={}))
for agent in owned_agents:
agent_id: str = agent["id"]
display_name: str = agent.get("name") or agent_id
try:
data = _read_v1_memory_bucket(user_id, agent_id)
except Exception:
data = {}
buckets.append(AdminMemoryBucket(name=agent_id, display_name=display_name, data=data))
return AdminMemoryResponse(user_id=user_id, version="v1", buckets=buckets)
# V2 模式:读 USER.md / MEMORY.md,内容为 {entries: [...]}
buckets = [
AdminMemoryBucket(name="global", display_name="用户画像", data=_read_memory_bucket(user_id, None))
]
for agent in owned_agents:
agent_id: str = agent["id"]
display_name: str = agent.get("name") or agent_id
agent_id = agent["id"]
display_name = agent.get("name") or agent_id
try:
data = _read_memory_bucket(user_id, agent_id)
except Exception:
data = {"entries": []}
buckets.append(AdminMemoryBucket(name=agent_id, display_name=display_name, data=data))
return AdminMemoryResponse(user_id=user_id, buckets=buckets)
return AdminMemoryResponse(user_id=user_id, version="v2", buckets=buckets)
@router.post("/{user_id}/memory/entries", response_model=AdminMemoryBucket)
@@ -266,3 +283,133 @@ async def admin_delete_memory_entry(
raise HTTPException(status_code=500, detail="Failed to delete memory entry") from exc
bucket_name = "global" if agent is None else agent
return AdminMemoryBucket(name=bucket_name, data=_read_memory_bucket(user_id, agent))
# ── V1 Memory CRUD (admin) ─────────────────────────────────────────────────
_V1_USER_FIELDS = {"workContext", "personalContext", "topOfMind"}
_V1_HISTORY_FIELDS = {"recentMonths", "earlierContext", "longTermBackground"}
class AdminV1SectionUpdateRequest(BaseModel):
section_type: str = Field(..., description="'user' 或 'history'")
field: str = Field(..., description="字段名,如 workContext / recentMonths")
summary: str = Field(..., description="新的摘要文本")
agent: str | None = Field(None, description="Agent id;None 表示用户级全局记忆")
class AdminV1FactAddRequest(BaseModel):
content: str = Field(..., min_length=1)
category: str = Field(default="context")
confidence: float = Field(default=0.8, ge=0.0, le=1.0)
agent: str | None = Field(None)
class AdminV1FactUpdateRequest(BaseModel):
content: str | None = Field(None)
category: str | None = Field(None)
confidence: float | None = Field(None, ge=0.0, le=1.0)
agent: str | None = Field(None)
@router.put("/{user_id}/memory/v1/sections", response_model=AdminMemoryBucket)
async def admin_update_v1_section(
user_id: str,
body: AdminV1SectionUpdateRequest,
request: Request,
) -> AdminMemoryBucket:
"""更新 V1 记忆的某个摘要字段(用户画像 / 历史)。"""
await _require_admin(request)
if body.section_type == "user" and body.field not in _V1_USER_FIELDS:
raise HTTPException(status_code=400, detail=f"无效 user 字段:{body.field}")
if body.section_type == "history" and body.field not in _V1_HISTORY_FIELDS:
raise HTTPException(status_code=400, detail=f"无效 history 字段:{body.field}")
if body.section_type not in ("user", "history"):
raise HTTPException(status_code=400, detail="section_type 须为 'user' 或 'history'")
from deerflow.agents.memory.v1.storage import get_memory_storage, utc_now_iso_z
storage = get_memory_storage()
data = storage.load(body.agent, user_id=user_id)
data.setdefault(body.section_type, {})[body.field] = {
"summary": body.summary,
"updatedAt": utc_now_iso_z(),
}
if not storage.save(data, body.agent, user_id=user_id):
raise HTTPException(status_code=500, detail="写入失败")
bucket_name = "global" if body.agent is None else body.agent
return AdminMemoryBucket(name=bucket_name, data=_read_v1_memory_bucket(user_id, body.agent))
@router.post("/{user_id}/memory/v1/facts", response_model=AdminMemoryBucket)
async def admin_add_v1_fact(
user_id: str,
body: AdminV1FactAddRequest,
request: Request,
) -> AdminMemoryBucket:
"""新增一条 V1 事实记录。"""
await _require_admin(request)
try:
from deerflow.agents.memory.v1.updater import create_memory_fact
create_memory_fact(
body.content,
category=body.category,
confidence=body.confidence,
agent_name=body.agent,
user_id=user_id,
)
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
except Exception as exc:
raise HTTPException(status_code=500, detail="新增失败") from exc
bucket_name = "global" if body.agent is None else body.agent
return AdminMemoryBucket(name=bucket_name, data=_read_v1_memory_bucket(user_id, body.agent))
@router.put("/{user_id}/memory/v1/facts/{fact_id}", response_model=AdminMemoryBucket)
async def admin_update_v1_fact(
user_id: str,
fact_id: str,
body: AdminV1FactUpdateRequest,
request: Request,
) -> AdminMemoryBucket:
"""更新一条 V1 事实记录(内容 / 类别 / 置信度)。"""
await _require_admin(request)
try:
from deerflow.agents.memory.v1.updater import update_memory_fact
update_memory_fact(
fact_id,
content=body.content,
category=body.category,
confidence=body.confidence,
agent_name=body.agent,
user_id=user_id,
)
except KeyError:
raise HTTPException(status_code=404, detail=f"事实 '{fact_id}' 不存在")
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
except Exception as exc:
raise HTTPException(status_code=500, detail="更新失败") from exc
bucket_name = "global" if body.agent is None else body.agent
return AdminMemoryBucket(name=bucket_name, data=_read_v1_memory_bucket(user_id, body.agent))
@router.delete("/{user_id}/memory/v1/facts/{fact_id}", response_model=AdminMemoryBucket)
async def admin_delete_v1_fact(
user_id: str,
fact_id: str,
request: Request,
agent: str | None = Query(None, description="Agent id;None 表示用户级全局记忆"),
) -> AdminMemoryBucket:
"""删除一条 V1 事实记录。"""
await _require_admin(request)
try:
from deerflow.agents.memory.v1.updater import delete_memory_fact
delete_memory_fact(fact_id, agent_name=agent, user_id=user_id)
except KeyError:
raise HTTPException(status_code=404, detail=f"事实 '{fact_id}' 不存在")
except Exception as exc:
raise HTTPException(status_code=500, detail="删除失败") from exc
bucket_name = "global" if agent is None else agent
return AdminMemoryBucket(name=bucket_name, data=_read_v1_memory_bucket(user_id, agent))
@@ -73,20 +73,38 @@ _AgentQuery = Query(
# ===========================================================================
class MemoryV2DataResponse(BaseModel):
"""Memory V2 builtin provider 的数据视图。"""
class MemoryFact(BaseModel):
"""V1 记忆中的单条事实。"""
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 字符用量")
id: str = Field(default="", description="事实 UUID")
content: str = Field(default="", description="事实文本")
category: str = Field(default="knowledge", description="事实类别")
confidence: float = Field(default=0.0, description="置信度 0-1")
createdAt: str = Field(default="", description="创建时间 ISO 格式")
sourceError: str = Field(default="", description="纠错类事实:被纠正的原错误描述")
class MemoryV2DataResponse(BaseModel):
"""Memory 数据视图 —— V1/V2 共用,多余字段各版本置空。"""
# V2 字段
user_entries: list[str] = Field(default_factory=list, description="V2: USER.md 条目 (用户画像)")
memory_entries: list[str] = Field(default_factory=list, description="V2: MEMORY.md 条目 (agent 工作笔记)")
user_usage: str = Field(default="", description="字符/计数用量描述")
memory_usage: str = Field(default="", description="字符/计数用量描述")
# V1 字段
facts: list[MemoryFact] = Field(default_factory=list, description="V1: facts 列表 (含置信度)")
user_context: dict[str, str] = Field(default_factory=dict, description="V1: userContext 摘要")
history: dict[str, str] = Field(default_factory=dict, description="V1: history 历史摘要")
class MemoryV2ConfigResponse(BaseModel):
"""Memory V2 生效配置 (含三层覆盖合并结果) + 用户可改字段白名单。"""
"""Memory 生效配置 (含三层覆盖合并结果) + 用户可改字段白名单 + 版本号。"""
config: dict[str, Any] = Field(..., description="按 per-user 覆盖合并后的生效配置")
writable_fields: list[str] = Field(..., description="用户可在运行时覆盖的字段 (点号路径)")
version: str = Field(default="v2", description="当前记忆版本:v1 或 v2")
class MemoryConfigPatchRequest(BaseModel):
@@ -134,6 +152,33 @@ class MemorySearchResponse(BaseModel):
# ===========================================================================
def _is_v1(user_id: str) -> bool:
"""判断当前用户是否处于 V1 记忆模式。"""
config = get_effective_memory_config(user_id)
return getattr(config, "version", "v2") == "v1"
def _build_v1_provider(user_id: str, agent_name: str | None = None):
"""构建并初始化 V1BuiltinProvider。"""
from deerflow.agents.memory.providers.v1_builtin import V1BuiltinProvider
config = get_effective_memory_config(user_id)
v1_cfg = config.v1
provider = V1BuiltinProvider(
max_facts=v1_cfg.max_facts,
fact_confidence_threshold=v1_cfg.fact_confidence_threshold,
debounce_seconds=v1_cfg.debounce_seconds,
model_name=v1_cfg.model_name,
token_budget=v1_cfg.token_budget,
)
provider.initialize(
user_id=user_id,
agent_id=agent_name,
base_dir=str(get_paths().base_dir),
)
return provider
def _build_builtin_provider(user_id: str, agent_name: str | None):
"""按生效配置构建并初始化一个 V2 builtin provider。"""
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
@@ -161,7 +206,7 @@ def _validate_v2_target(target: str) -> str:
def _v2_data_response(provider) -> MemoryV2DataResponse:
"""从 builtin provider 读出当前数据,组装成 MemoryV2DataResponse。"""
"""从 V2 builtin provider 读出当前数据。"""
return MemoryV2DataResponse(
user_entries=provider.read("user"),
memory_entries=provider.read("memory"),
@@ -170,6 +215,49 @@ def _v2_data_response(provider) -> MemoryV2DataResponse:
)
def _v1_data_response(provider) -> MemoryV2DataResponse:
"""从 V1 provider 读出当前数据,转换为统一响应格式。
支持新格式 {user: {workContext: {summary, updatedAt}}} 和老格式 {userContext: {workContext: str}}。
"""
data = provider.read_v1_data()
raw_facts = data.get("facts", [])
facts = [
MemoryFact(
id=str(f.get("id", "")),
content=str(f.get("content", "")),
category=str(f.get("category", "knowledge")),
confidence=float(f.get("confidence", 0)),
createdAt=str(f.get("createdAt", "")),
sourceError=str(f.get("sourceError", "")),
)
for f in raw_facts
]
def _extract_section(section: dict) -> dict[str, str]:
"""从 {key: {summary: str, updatedAt: str}} 或 {key: str} 中提取摘要字符串。"""
result = {}
for k, v in section.items():
if isinstance(v, dict):
summary = v.get("summary", "")
else:
summary = str(v)
if summary:
result[k] = summary
return result
# 新格式用 "user" key,老格式用 "userContext" key(已由 storage 迁移,此处兜底)
ctx_raw = data.get("user") or data.get("userContext") or {}
history_raw = data.get("history") or {}
return MemoryV2DataResponse(
facts=sorted(facts, key=lambda f: f.confidence, reverse=True),
user_context=_extract_section(ctx_raw),
history=_extract_section(history_raw),
memory_usage=provider.usage_text(),
)
def _raise_if_write_failed(result: dict) -> None:
"""builtin provider 写操作失败时抛 400。"""
if not result.get("success"):
@@ -184,33 +272,43 @@ def _raise_if_write_failed(result: dict) -> None:
@router.get(
"/memory/v2",
response_model=MemoryV2DataResponse,
summary="Get Memory V2 Data",
description="读取 Memory V2 builtin provider 的 USER.md / MEMORY.md 条目。",
summary="Get Memory Data",
description="读取记忆数据。V1 模式返回 facts 列表;V2 模式返回 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:
if _is_v1(user_id):
provider = _build_v1_provider(user_id, agent_name)
return _v1_data_response(provider)
provider = _build_builtin_provider(user_id, agent_name)
return _v2_data_response(provider)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to read memory V2 data.") from exc
raise HTTPException(status_code=500, detail="Failed to read memory data.") from exc
def _assert_not_v1(user_id: str) -> None:
"""V1 模式下写入操作返回 400。"""
if _is_v1(user_id):
raise HTTPException(status_code=400, detail="V1 模式下记忆由系统自动提取,不支持手动修改。")
@router.post(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Add Memory V2 Entry",
description="手动往 USER.md / MEMORY.md 新增一条记忆条目。",
description="手动往 USER.md / MEMORY.md 新增一条记忆条目 (仅 V2 模式)。",
)
async def add_memory_v2_entry(
request: MemoryEntryCreateRequest,
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动新增一条 V2 记忆条目。"""
_validate_v2_target(request.target)
user_id = get_effective_user_id()
_assert_not_v1(user_id)
_validate_v2_target(request.target)
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.add(request.target, request.content)
@@ -226,15 +324,16 @@ async def add_memory_v2_entry(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Replace Memory V2 Entry",
description="用 old_text 定位一条记忆条目并替换为新内容。",
description="用 old_text 定位一条记忆条目并替换为新内容 (仅 V2 模式)。",
)
async def replace_memory_v2_entry(
request: MemoryEntryReplaceRequest,
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动替换一条 V2 记忆条目。"""
_validate_v2_target(request.target)
user_id = get_effective_user_id()
_assert_not_v1(user_id)
_validate_v2_target(request.target)
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.replace(request.target, request.old_text, request.content)
@@ -250,7 +349,7 @@ async def replace_memory_v2_entry(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Delete Memory V2 Entry",
description="用 old_text 定位并删除一条记忆条目。",
description="用 old_text 定位并删除一条记忆条目 (仅 V2 模式)。",
)
async def delete_memory_v2_entry(
target: str = Query(..., description="memory 或 user"),
@@ -258,8 +357,9 @@ async def delete_memory_v2_entry(
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动删除一条 V2 记忆条目。"""
_validate_v2_target(target)
user_id = get_effective_user_id()
_assert_not_v1(user_id)
_validate_v2_target(target)
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.remove(target, old_text)
@@ -289,6 +389,7 @@ async def get_memory_v2_config() -> MemoryV2ConfigResponse:
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
version=getattr(config, "version", "v2"),
)
@@ -313,6 +414,7 @@ async def patch_memory_v2_config(request: MemoryConfigPatchRequest, req: Request
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
version=getattr(config, "version", "v2"),
)
@@ -341,6 +443,7 @@ async def delete_memory_v2_config(
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
version=getattr(config, "version", "v2"),
)