Docs
文档目录

分层上下文治理与 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 上下文聚合都具备完整的底层证据链和有效的访问策略。

分层上下文治理与 Dreaming:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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

分类维度枚举标识控制台展示名称核心职责与检索可见性规则
上下文层级 (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. 与配置中心(evolution.dreaming)的关系: Dreaming 是否自动开启、运行模式是候选观察(shadow)还是自动激活(active)、单批处理条数(batchSize)与最小变更触发阈值(minimumChanged)均在 记忆 → 配置 → 基础配置(evolution 命名空间) 中管理;上下文聚合提示词(contextAggregationPrompt)在 prompt 命名空间中管理。

  2. 与遗忘 Pipeline 的职责区分: 本页签负责管理记忆向上归纳生成 L2/L3 聚合;而记忆按时间衰减、复习强化与到期清理的规则在 记忆 → 配置 → 遗忘 Pipeline 中维护,二者互补但不在同一入口配置。

  3. 与独立托管 PowerContext 服务的关系: 本页签属于 Agentbase 原生 Memory 的分层上下文(Contexts)治理能力,与侧栏独立的 PowerContext 托管服务并非同一资源或数据存储。


功能详解与操作指南

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

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 上下文 页签。

  2. 在顶部状态栏核对当前项目的 Dreaming 配置与运行指标:

    • Dreaming 开关状态:显示当前是否启用后台 Dreaming(关闭时仍可查阅既有上下文记录,但后台不会自动扫描生成新聚合);

    • 运行模式(mode):shadow(生成的聚合先进入候选态等待确认)或 active(验证通过后直接激活);

    • 变更水位(Watermark)与任务状态:展示待处理的变更记忆数量与最近一次后台聚合任务的执行状态。

  3. 使用筛选器按 状态(shadow、user-active、agent-active、stale、quarantine、deprecated)和 层级(kind)(L2 Topic、L2 Episode、L2 State、L3 Overview)过滤上下文记录。

上下文治理视图(沿用已登记截图)

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

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,服务端在提交时会实时重验权限、来源完整性与策略版本):

  1. 确认并激活候选(POST /v1/memory/memories/contexts/{contextId}/confirm):

    • 核对当前 shadow 候选版本的聚合正文、支撑来源记忆(Source Memories)、证据关系、归属范围(user / agent)以及策略时效。

    • 确认来源完整(无缺失或已删除的底层记忆)后,填写治理原因(如 "已核验张伟核心账务集群架构变更摘要准确无误")并单击 确认激活。该聚合状态将跃迁为 user-active 或 agent-active。

  2. 重新构建上下文(POST /v1/memory/memories/contexts/{contextId}/rebuild):

    • 当某条上下文因部分底层记忆更新而变为 stale(过期),或管理员调整了 contextAggregationPrompt 提示词后,单击 重建(返回 HTTP 202),后台将基于当前仍有效的底层记忆重新计算生成最新聚合版本。

  3. 回滚至历史修订(POST /v1/memory/memories/contexts/{contextId}/rollback):

    • 在详情页展开 历史修订(Revisions) 列表,对比不同历史版本的聚合内容。

    • 若新激活的版本归纳质量不及预期,选择某个曾通过验证且当前底层来源依然合法的历史 revisionId,填写回滚原因并提交,即可将生效指针原子切回该历史版本。

# 示例:通过 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 上下文?


相关文档