AgentbaseDocs
文档目录

分层上下文治理与 Dreaming

功能概述与核心场景

分层上下文治理(Memory Context Governance,控制台页签为 上下文)是 Agentbase Memory(v2.10.0)提供的多层级记忆归纳、验证与生命周期治理中心。随着企业智能体长期运行,底层的原始证据(L0 Evidence)与离散事实记忆(L1 Fact)会快速增长至数万条。如果仅靠扁平的 L1 事实检索,模型在回答宏观问题(如“过去一个月核心账务集群经历了哪些阶段性变更?”)时容易陷入局部细节而丢失全局脉络。

Agentbase Memory 引入了 Dreaming(后台上下文聚合机制),将记忆体系组织为严格的四层金字塔结构(L0 Evidence -> L1 Fact -> L2 Topic / Episode / State -> L3 Overview)。在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,系统通过 Dreaming 自动扫描 user_zhangwei_001 与 user_lina_002 的新增及变更记忆,生成候选上下文(shadow),并支持管理员在控制台检查来源完整性、执行候选确认激活(confirm)、按最新来源重建(rebuild)以及向历史已验证版本安全回滚(rollback),配合渐进式检索(Progressive Retrieval)实现高信噪比、强权限围栏的分层上下文召回。


核心概念与架构

分层上下文治理通过后台异步 Dreaming 调度器与强一致性治理栅栏(Fence),保证任何进入在线检索的 L2/L3 上下文聚合都具备完整的底层证据链和有效的访问策略。

flowchart TB
    subgraph Pyramid["Memory 四层金字塔上下文架构"]
        L3["L3 Overview (全局概览)\nkind = memory_overview"]
        L2["L2 Context (分层上下文聚合)\nmemory_topic (主题) / memory_episode (事件片段) / memory_state (当前状态)"]
        L1["L1 Fact (原子记忆事实)\n单条偏好、事实与动作记忆"]
        L0["L0 Evidence (不可变原始来源)\n原始对话 messages 与多模态文档解析切片"]
        L0 -->|"事实抽取"| L1
        L1 -->|"Dreaming 聚类与归纳"| L2
        L2 -->|"Dreaming 顶层汇总"| L3
    end

    subgraph DreamingLifecycle["Dreaming 调度与上下文状态流转"]
        Scan["变更记忆扫描与调度\nPOST /v1/memory/memories/contexts/runs"]
        Shadow["候选态 (shadow)\n验证置信度与来源完整性"]
        Active["生效态 (user-active / agent-active)\n正式参与渐进式检索 (progressive)"]
        Quarantine["异常与失效态\nquarantine (隔离) / stale (过期) / deprecated (已弃用)"]

        Scan --> Shadow
        Shadow -->|"自动激活 (mode=active) 或\n人工确认 (POST .../confirm)"| Active
        Shadow -->|"来源缺失 / 策略冲突"| Quarantine
        Active -->|"底层记忆删除 / 策略变更"| Quarantine
        Active -->|"POST .../rebuild"| Shadow
        Active -->|"POST .../rollback"| Active
    end

    L2 -.-> Scan
    L3 -.-> Scan

四层上下文层级与生命周期状态说明

分类维度枚举标识控制台展示名称核心职责与检索可见性规则
**上下文层级 (kind)**memory_topicL2 Topic(主题上下文)围绕特定技术领域或业务主题(如“OceanBase 向量索引调优”)聚合跨会话的多条相关事实。
**上下文层级 (kind)**memory_episodeL2 Episode(事件片段)按时间线与因果脉络归纳一次完整的业务事件(如“工单 TK-20261022-001 死锁排障始末”)。
**上下文层级 (kind)**memory_stateL2 State(状态快照)反映用户或系统在当前时点的最新有效状态集合,自动淘汰已被推翻的历史中间状态。
**上下文层级 (kind)**memory_overviewL3 Overview(顶层概览)汇总多个 L2 上下文形成的全景纲要,作为渐进式检索(entryLevel: "auto" 或 "overview")的首跳入口。
**生命周期状态 (status)**shadow候选待确认(Shadow)Dreaming 新生成的候选版本。在 dreaming.mode="shadow" 模式下需管理员调用 confirm 激活后才对普通检索可见。
**生命周期状态 (status)**user-active / agent-active已激活(Active)来源完整、策略有效且已通过确认的当前生效版本,正式服务于在线渐进式检索。
**生命周期状态 (status)**stale / quarantine / deprecated已过期 / 隔离 / 已弃用当底层支撑记忆被删除遗忘、敏感策略收紧或存在合规冲突时自动进入隔离或过期态,立即停止在线召回(Fail-closed)。

功能入口与权限矩阵

控制台入口与 REST API 映射

控制台入口位于:**项目 enterprise-ai-hub-210 → 记忆(Memory) → 上下文** 页签。

操作能力控制台入口REST API 端点SDK 方法名所需权限 Scope
查询 Dreaming 水位与状态页头 Dreaming 状态面板GET /v1/memory/memories/contexts/statusgetContextStatusmemories.read
扫描变更并调度 Dreaming扫描变化记忆 / 调度运行 按钮POST /v1/memory/memories/contexts/runscreateContextRunmemories.write
列表查询分层上下文状态与层级筛选栏 + 列表GET /v1/memory/memories/contextslistContextsmemories.read
查看单条上下文详情与修订列表项展开详情GET /v1/memory/memories/contexts/{contextId}getContextmemories.read
确认并激活 Shadow 候选详情区 确认激活 按钮POST /v1/memory/memories/contexts/{contextId}/confirmconfirmContextmemories.write(需管理权限)
调度单个上下文重建详情区 重建 按钮POST /v1/memory/memories/contexts/{contextId}/rebuildrebuildContextmemories.write
回滚至历史已验证版本历史修订列表 回滚 按钮POST /v1/memory/memories/contexts/{contextId}/rollbackrollbackContextmemories.write

与其他模块的关联边界


功能详解与操作指南

1. 查看 Dreaming 状态与分层上下文列表

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

2. 配置 Dreaming 参数并手动调度聚合运行(contexts/runs)

在 evolution 配置命名空间中,dreaming 子对象支持以下精细化治理参数:

参数路径类型取值范围 / 枚举默认值参数说明与约束规则
dreaming.enabledbooleantrue / falsefalse是否开启项目级 Dreaming 上下文聚合能力。
dreaming.modestring"shadow" / "active""shadow"shadow 模式下生成候选版本需确认后激活;active 模式下达到置信度门槛且来源完整时自动激活。
dreaming.batchSizeinteger2 ~ 10020单次 Dreaming 任务扫描与聚合的最大变更记忆条数。
dreaming.minimumChangedinteger1 ~ batchSize1触发一次 Dreaming 聚合所需的最小变更记忆数量,**严禁大于 batchSize**。
dreaming.minConfidencenumber0.0 ~ 1.00.75上下文聚合结果准入的最低模型置信度阈值。
dreaming.maxJobsPerCycleinteger正整数5单个后台调度周期内最多并发创建的 Dreaming 任务数。

当为 user_zhangwei_001 批量导入或写入了一批排障记忆后,若希望立即触发上下文归纳而不等待下一个后台周期,可单击页面上的 扫描变化记忆 按钮,或调用 POST /v1/memory/memories/contexts/runs:

# 1. 查询当前 Dreaming 水位与运行状态
curl -fsS "https://appbuild.oceanbase.com/v1/memory/memories/contexts/status" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" | jq .

# 2. 手动触发扫描变更记忆并调度 Dreaming 任务 (返回 HTTP 202 Accepted)
curl -fsS -X POST "https://appbuild.oceanbase.com/v1/memory/memories/contexts/runs" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{}' | jq .

注意:POST /v1/memory/memories/contexts/runs 返回 HTTP 202 仅代表平台已受理变更扫描与任务调度,后台完成模型归纳仍需数秒时间,请通过状态接口或刷新列表观察最终结果。

3. 候选确认(confirm)、重建(rebuild)与版本回滚(rollback)

展开任意一条上下文聚合记录的详情面板,管理员可执行以下三项全生命周期治理动作(所有写操作均需填写治理原因 reason,服务端在提交时会实时重验权限、来源完整性与策略版本):

# 示例:通过 REST API 确认激活 shadow 上下文、触发重建与回滚历史版本
export CONTEXT_ID="ctx_9a4b82e10f3c4d5a"

# 1. 确认激活 shadow 候选版本
curl -fsS -X POST "https://appbuild.oceanbase.com/v1/memory/memories/contexts/${CONTEXT_ID}/confirm" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "reason": "架构师团队已复核 L2 Topic 聚合内容与底层 4 条排障事实一致"
  }' | jq .

# 2. 调度该上下文异步重建 (HTTP 202)
curl -fsS -X POST "https://appbuild.oceanbase.com/v1/memory/memories/contexts/${CONTEXT_ID}/rebuild" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "reason": "底层新增 TK-20261022-003 限流排障记忆,触发重新归纳"
  }' | jq .

# 3. 回滚至指定历史已验证修订版本
curl -fsS -X POST "https://appbuild.oceanbase.com/v1/memory/memories/contexts/${CONTEXT_ID}/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "targetRevisionId": "crev_01hxyz89ab23cd45",
    "reason": "回退至上一版经过生产验证的集群状态摘要"
  }' | jq .

4. 在渐进式检索(Progressive Search)中消费分层上下文

当分层上下文处于激活状态且来源完整时,应用在调用 POST /v1/memory/memories/search 时传入 retrieval.strategy: "progressive",即可按 L3 Overview -> L2 Context -> L1 Fact -> L0 Evidence 逐层下钻读取:


常见问题与排障(FAQ)

1. 为什么在“上下文”页签点击了“扫描变化记忆”,列表里却没有立刻出现新的 L2/L3 上下文?

2. 为什么某条上下文显示为 quarantine(隔离)或 stale(过期),且无法点击“确认激活”?

3. 开启渐进式检索(strategy: "progressive")后,为什么有时直接返回了 L1 Fact 而没有返回 L2/L3 上下文?


相关文档