分层上下文治理与 Dreaming
功能概述与核心场景
分层上下文治理(Memory Context Governance,控制台页签为 治理策略)是 Agentbase Memory 提供的多层级记忆归纳、验证与生命周期治理中心。随着企业智能体长期运行,底层的原始证据(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 上下文聚合都具备完整的底层证据链和有效的访问策略。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
四层上下文层级与生命周期状态说明
| 分类维度 | 枚举标识 | 控制台展示名称 | 核心职责与检索可见性规则 |
|---|---|---|---|
上下文层级 (kind) | memory_topic | L2 Topic(主题上下文) | 围绕特定技术领域或业务主题(如“OceanBase 向量索引调优”)聚合跨会话的多条相关事实。 |
上下文层级 (kind) | memory_episode | L2 Episode(事件片段) | 按时间线与因果脉络归纳一次完整的业务事件(如“工单 TK-20261022-001 死锁排障始末”)。 |
上下文层级 (kind) | memory_state | L2 State(状态快照) | 反映用户或系统在当前时点的最新有效状态集合,自动淘汰已被推翻的历史中间状态。 |
上下文层级 (kind) | memory_overview | L3 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/status | getContextStatus | memories.read |
| 扫描变更并调度 Dreaming | 扫描变化记忆 / 调度运行 按钮 | POST /v1/memory/memories/contexts/runs | createContextRun | memories.write |
| 列表查询分层上下文 | 状态与层级筛选栏 + 列表 | GET /v1/memory/memories/contexts | listContexts | memories.read |
| 查看单条上下文详情与修订 | 列表项展开详情 | GET /v1/memory/memories/contexts/{contextId} | getContext | memories.read |
| 确认并激活 Shadow 候选 | 详情区 确认激活 按钮 | POST /v1/memory/memories/contexts/{contextId}/confirm | confirmContext | memories.write(需管理权限) |
| 调度单个上下文重建 | 详情区 重建 按钮 | POST /v1/memory/memories/contexts/{contextId}/rebuild | rebuildContext | memories.write |
| 回滚至历史已验证版本 | 历史修订列表 回滚 按钮 | POST /v1/memory/memories/contexts/{contextId}/rollback | rollbackContext | memories.write |
与其他模块的关联边界
与配置中心(
evolution.dreaming)的关系: Dreaming 是否自动开启、运行模式是候选观察(shadow)还是自动激活(active)、单批处理条数(batchSize)与最小变更触发阈值(minimumChanged)均在 记忆 → 配置 → 基础配置(evolution命名空间) 中管理;上下文聚合提示词(contextAggregationPrompt)在prompt命名空间中管理。与遗忘 Pipeline 的职责区分: 本页签负责管理记忆向上归纳生成 L2/L3 聚合;而记忆按时间衰减、复习强化与到期清理的规则在 记忆 → 配置 → 遗忘 Pipeline 中维护,二者互补但不在同一入口配置。
与独立托管 PowerContext 服务的关系: 本页签属于 Agentbase 原生 Memory 的分层上下文(Contexts)治理能力,与侧栏独立的 PowerContext 托管服务并非同一资源或数据存储。
功能详解与操作指南
1. 查看 Dreaming 状态与分层上下文列表
登录 Agentbase 控制台,进入项目
企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 治理策略页签。在顶部状态栏核对当前项目的 Dreaming 配置与运行指标:
Dreaming 开关状态:显示当前是否启用后台 Dreaming(关闭时仍可查阅既有上下文记录,但后台不会自动扫描生成新聚合);
运行模式(
mode):shadow(生成的聚合先进入候选态等待确认)或active(验证通过后直接激活);变更水位(Watermark)与任务状态:展示待处理的变更记忆数量与最近一次后台聚合任务的执行状态。
使用筛选器按 状态(
shadow、user-active、agent-active、stale、quarantine、deprecated)和 层级(kind)(L2 Topic、L2 Episode、L2 State、L3 Overview)过滤上下文记录。
2. 配置 Dreaming 参数并手动调度聚合运行(contexts/runs)
在 evolution 配置命名空间中,dreaming 子对象支持以下治理参数。启用后台扫描需同时开启 evolution.enabled 与 dreaming.enabled;active 模式还要求 policy.captureMode 为 balanced。以下为服务回退默认值,实际生效配置可能不同:
| 参数路径 | 类型 | 取值范围 / 枚举 | 默认值 | 参数说明与约束规则 |
|---|---|---|---|---|
dreaming.enabled | boolean | true / false | false | 是否开启项目级 Dreaming 上下文聚合能力。 |
dreaming.mode | string | "shadow" / "active" | "shadow" | shadow 模式下生成候选版本需确认后激活;active 模式下达到置信度门槛且来源完整时自动激活。 |
dreaming.batchSize | integer | 2 ~ 100 | 20 | 单次 Dreaming 任务扫描与聚合的最大变更记忆条数。 |
dreaming.minimumChanged | integer | 1 ~ batchSize | 1 | 触发一次 Dreaming 聚合所需的最小变更记忆数量,严禁大于 batchSize。 |
dreaming.minConfidence | number | 0.0 ~ 1.0 | 0.8 | 上下文聚合结果准入的最低模型置信度阈值。 |
dreaming.maxJobsPerCycle | integer | 1 ~ 100 | 5 | 单个后台调度周期内最多创建的 Dreaming 任务数。 |
当为 user_zhangwei_001 批量导入或写入了一批排障记忆后,若希望立即触发上下文归纳而不等待下一个后台周期,可单击页面上的 扫描变化记忆 按钮,或调用 POST /v1/memory/memories/contexts/runs:
设置 APPBASE_ENDPOINT 为目标环境的 API 地址(包含 /v1),确认项目和凭据属于该环境。
查询当前状态:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS "${APPBASE_ENDPOINT}/memory/memories/contexts/status" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- | jq .
)按需提交扫描任务:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/contexts/runs" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
--data '{}' | jq .
)注意:
POST /v1/memory/memories/contexts/runs返回 HTTP 202 仅代表平台已受理变更扫描与任务调度,后台完成模型归纳仍需数秒时间,请通过状态接口或刷新列表观察最终结果。
3. 候选确认(confirm)、重建(rebuild)与版本回滚(rollback)
展开任意一条上下文聚合记录的详情面板,管理员可执行以下三项全生命周期治理动作(所有写操作均需填写治理原因 reason,服务端在提交时会实时重验权限、来源完整性与策略版本):
确认并激活候选(
POST /v1/memory/memories/contexts/{contextId}/confirm):核对当前
shadow候选版本的聚合正文、支撑来源记忆(Source Memories)、证据关系、归属范围(user/agent)以及策略时效。确认来源完整(无缺失或已删除的底层记忆)后,填写治理原因(如
"已核验张伟核心账务集群架构变更摘要准确无误")并单击 确认激活。该聚合状态将跃迁为user-active或agent-active。
重新构建上下文(
POST /v1/memory/memories/contexts/{contextId}/rebuild):当某条上下文因部分底层记忆更新而变为
stale(过期),或管理员调整了contextAggregationPrompt提示词后,单击 重建(返回 HTTP 202),后台将基于当前仍有效的底层记忆重新计算生成最新聚合版本。
回滚至历史修订(
POST /v1/memory/memories/contexts/{contextId}/rollback):在详情页展开 历史修订(Revisions) 列表,对比不同历史版本的聚合内容。
若新激活的版本归纳质量不及预期,选择某个曾通过验证且当前底层来源依然合法的历史
revisionId,填写回滚原因并提交,即可将生效指针原子切回该历史版本。
将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),并确认项目与凭据属于该环境。
将 CONTEXT_ID 设置为当前环境中要操作的上下文 ID。以下操作各自独立,请按实际需要选择。
确认激活候选版本
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${CONTEXT_ID:?Set CONTEXT_ID to the target context}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/contexts/${CONTEXT_ID}/confirm" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"reason": "架构师团队已复核 L2 Topic 聚合内容与底层 4 条排障事实一致"
}' | jq .
)调度该上下文异步重建 (HTTP 202)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${CONTEXT_ID:?Set CONTEXT_ID to the target context}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/contexts/${CONTEXT_ID}/rebuild" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"reason": "底层新增 TK-20261022-003 限流排障记忆,触发重新归纳"
}' | jq .
)回滚至指定历史已验证修订版本。仅在确认目标与影响后单独执行。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${CONTEXT_ID:?Set CONTEXT_ID to the target context}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/contexts/${CONTEXT_ID}/rollback" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-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 逐层下钻读取:
在线渐进式检索链路受到最大
450ms(deadlineMs)的严格延迟保护,不调用慢速生成模型;每条返回的 L3/L2 节点若满足下钻条件(
canExpand: true),会附带有效期最长 2 分钟 的签名expansionToken;expansionToken严格绑定项目、调用主体、目标用户、群组成员快照与策略版本;一旦底层任一来源记忆被删除或权限撤销,旧令牌立即失效关闭(Fail-closed),杜绝越权读取历史残留摘要。
常见问题与排障(FAQ)
1. 为什么在“治理策略”页签点击了“扫描变化记忆”,列表里却没有立刻出现新的 L2/L3 上下文?
原因分析:排查以下三点:① 检查 记忆 → 配置 → 基础配置 中的
evolution.enabled和evolution.dreaming.enabled是否均已开启;② 新增或变化的记忆数量是否达到了dreaming.minimumChanged阈值;③POST /v1/memory/memories/contexts/runs是异步调度接口(HTTP 202),后台任务使用项目配置的模型进行聚合需要一定执行时间。解决措施:先在页头核对 Dreaming 开关与水位状态,等待后台任务执行完成后单击刷新按钮,并切换状态筛选器查看
shadow(候选态)列表。
2. 为什么某条上下文显示为 quarantine(隔离)或 stale(过期),且无法点击“确认激活”?
原因分析:Agentbase Memory 对分层上下文实施严格的来源完整性与策略一致性守卫。如果支撑该 L2/L3 聚合的某条底层 L1 记忆或 L0 来源已被用户主动删除、因到期策略被遗忘,或某条来源的
handlingPolicy被收紧为no_model,系统会自动将该聚合置为隔离或过期,并禁止直接激活,防止智能体通过高层摘要泄露已删除的底层隐私。解决措施:展开该上下文详情核对缺失或失效的来源项。若仍有其余有效来源支撑该主题,可单击 重建(Rebuild),让系统剔除已失效来源后基于当前存活的有效记忆重新生成合规的新候选版本。
3. 开启渐进式检索(strategy: "progressive")后,为什么有时直接返回了 L1 Fact 而没有返回 L2/L3 上下文?
原因分析:当
entryLevel设为"auto"时,若当前用户尚未生成任何已激活(user-active)且来源完整的 L2/L3 上下文,或者查询请求中附带了仅 L1 支持的精确过滤条件(如特定metadata、recordKind、runId或sessionId),检索引擎会在剩余deadlineMs预算内自动降级从 L1 事实层检索,避免用不支持细粒度过滤的上层摘要掩盖精确事实。解决措施:这是保障检索精度的预期行为。若希望优先命中 L2/L3 概览,请确认目标上下文已通过
confirm激活,且不在宏观概览查询中叠加底层单条记录的专属元数据过滤。
