Docs
文档目录

多层记忆划分:三层时效记忆、L0–L3 认知架构与渐进式召回

功能概述与核心场景

在企业级智能体(Agent)的长周期生产运行中,如果将所有对话历史、临时排障参数、个人偏好、项目规范与历史工单结论无差别地平铺存储在单一的扁平向量库(Flat Vector Store)中,随着交互轮次增长,智能体将不可避免地面临三大工程瓶颈:

  1. 上下文窗口污染(Context Window Pollution):几周前某次临时工单排障使用的中间参数(如临时测试端口或已废弃的限流阈值)与长期稳定的生产架构基线混杂,导致向量召回信噪比急剧下降;

  2. 宏观脉络缺失(Loss of Macro Context):扁平的碎片化事实(Atomic Facts)难以回答“过去一个月核心账务集群经历了哪些阶段性变更?”或“当前用户有哪些未闭环的阻塞问题?”等跨会话全局问题;

  3. 多租户与隐私边界混同(Scope & Compliance Leakage):单次会话内部的敏感调试上下文、跨智能体共享的个人偏好、团队群组协同记忆以及不希望经过大模型向量化的合规文本缺乏细粒度隔离。

为解决上述问题,Agentbase Memory(v2.10.0)摒弃了传统的扁平存储模型,参考人类认知心理学与企业安全治理规范,将记忆体系沿着三个正交维度(Three Orthogonal Dimensions)进行立体划分,并配套提供毫秒级受控的渐进式分层召回(Progressive Recall):

在 Agentbase 企业智能中台(组织 ID:69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(项目 ID:enterprise-ai-hub-210,基于 OceanBase Shared V2 存储模式)中,系统通过上述三维多层记忆架构,为 VIP 核心账务架构师 user_zhangwei_001 与一线运维工程师 user_lina_002 精准区分单次工单临时上下文与长期架构偏好,并以 450ms 检索预算为例,通过 L3 -> L2 -> L1 -> L0 渐进式召回提供高信噪比、强安全围栏的记忆注入。


核心概念与架构

Agentbase Memory 的三维正交分层架构与渐进式分层召回(Progressive Recall)数据流如下图所示:

多层记忆划分:三层时效记忆、L0–L3 认知架构与渐进式召回:流程示意,不是运行截图

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

查看流程图大图

1. 第一维度:时间衰减与保留层级(Time-Decay & Retention Tiers)

在创建或推断记忆时,每条记忆通过 memoryType(或流水线自动分类)落入三个具有不同时间衰减乘数(decay_rate_multipliers)和遗忘阈值(threshold)的时效层级:

时效记忆层级枚举值 (memoryType)默认衰减乘数 (decay_rate_multipliers)默认遗忘阈值 (threshold)核心定位、典型业务数据与跨层流转机制
工作记忆working2.0(快速衰减)working_threshold = 0.15短周期任务/单轮草稿区(Scratchpad):记录当前正在排查的临时工单参数、多步工具调用的中间状态(如“当前正在检查 OBProxy 节点 10.0.4.12:2883 的连接池水位”)。若任务结束后未再被召回,会以 2 倍基准衰减率迅速衰减归档;若在间隔复习窗口内被反复召回强化,则自动晋升至 short_term。
短期记忆short_term1.0(标准衰减)short_term_threshold = 0.25近期跨会话活跃上下文:记录用户近几日持续跟进的事项、阶段性关注点或尚未结单的工单背景(如“user_lina_002 本周正在验证知识库 kb_enterprise_support 的语雀增量同步策略”)。具备标准衰减速率(1.0)与较高的相关性准入门槛(0.25)。
长期记忆long_term(含固化 preference / fact)0.3(慢速衰减)long_term_threshold = 0.10企业级持久认知基线:存储经过沉淀的用户核心职责、长期技术栈偏好、生产集群拓扑事实(如“user_zhangwei_001 负责核心账务 OceanBase Shared V2 集群,SLA 等级 P0-VIP”)、已激活的排障经验(Experience)与标准技能(Skill)。受最短保护期(minimum_protection_hours)与 0.3 低衰减乘数双重保护。

基于间隔复习(Spaced Repetition)的跨层自动晋升机制:

2. 第二维度:L0–L3 四层认知抽象金字塔(Cognitive Hierarchy)

为兼顾“微观事实精确溯源”与“宏观脉络快速把握”,Agentbase Memory 将项目内的认知资产由具体到抽象划分为 L0 至 L3 四个认知层级:

认知层级内部标识与承载对象生成与更新机制关联溯源与核心结构说明
L0 原始证据层
(Raw Source & Multimodal Evidence)
sources 表(src_*)每次调用记忆写入、画像提取或知识蒸馏时同步/异步冻结生成,不可篡改(Immutable)。保存原始对话轮次(messages)、工具调用轨迹(toolEvents)以及同项目 Storage(如 agent_multimedia_bucket)中 PNG/JPEG/WebP 图片或 PDF 文档的解析快照(固化在 _appbaseMemoryMedia 元数据中,含文件 SHA-256、页码边界与字符偏移)。
L1 原子记忆与知识层
(Atomic Memories & Knowledge)
- 原子记忆(mem_*)
- 用户画像(Profile)
- 经验与技能(Experience / Skill)
由直写(infer=false)或新增记忆/画像/蒸馏 Pipeline(调用 qwen-plus 与 text-embedding-v3)抽取并去重合并。- 原子记忆:按 recordKind 细分为客观事实(fact)、用户偏好(preference)、时序事件(event)、原始对话片段(conversation)与工具动作(action);
- 结构化画像与经验技能:每条 L1 记录均通过 sourceIds 严格指向支撑它的 L0 原始证据。
L2 聚合上下文层
(Aggregated Contexts)
contexts 表(ctx_*):
- L2 Topic(memory_topic)
- L2 Episode(memory_episode)
- L2 State(memory_state)
由后台 Dreaming(上下文聚合引擎) 异步扫描变化的 L1 记忆聚类归纳而成。- L2 Topic(主题上下文):聚合特定技术领域或业务模块的跨会话认知(如“OceanBase 1024 维 HNSW 向量索引调优主题”);
- L2 Episode(情节上下文):按时间起止与因果链条还原一次完整事件或里程碑(如“工单 TK-20261022-001 向量内存耗尽排障全过程”);
- L2 State(状态上下文):反映用户或系统当前的最新有效状态与待解决阻塞项(自动剔除已被推翻的旧状态)。
L3 全局概览层
(Global Overview)
contexts 表(ctx_*):
- L3 Overview(memory_overview)
由后台 Dreaming 进一步汇总同一用户或智能体下的多个 L2 主题、情节与状态生成。提供最高抽象层级的全景认知地图(Bird's-Eye Cognitive Map),作为渐进式召回(Progressive Recall)的首跳导航入口。

3. 第三维度:五级可见性作用域与安全处理策略(Visibility Scopes & Handling Policies)

任何一条记忆或派生上下文在写入与检索时,都必须同时受到 可见性作用域(scope) 与 模型处理策略(handlingPolicy) 的正交约束:

(1)五级可见性作用域(scope:由严到宽)

可见性作用域 (scope)隔离边界与归属键历史会话补水 (sessionId)典型适用场景与检索可见性规则
strict_private严格限定于当前单次运行/会话拥有者强制禁用(防止跨轮次隐式关联)含高度私密的临时认证参数或一次性沙箱调试上下文。即使在 accessMode="accessible" 授权并集查询中也绝不暴露。
private单个用户(userId)+ 特定智能体(agentId)私有强制禁用仅允许在同一个 userId 与同一个专属 agentId 内部读写,不允许跨智能体共享。
user用户级跨智能体共享(按 userId 隔离)支持(同项目、同用户、同 agentId 最近 ≤12 轮 / ≤4096 tokens)企业最常用默认范围。例如 user_zhangwei_001 在架构咨询 Agent 中登记的技术栈偏好,在工单排障 Agent 中同样可见。
group业务群组/团队级共享(须携带 groupId / metadata.groupId)支持(在同群组治理边界内)适用于项目组、值班小组(如核心账务 DBA 运维组)共享排障备忘,检索时服务端实时校验调用者的群组成员身份。
project项目全局共享(如 enterprise-ai-hub-210 全项目)支持适用于全项目通用的架构规范、全局术语约定或公共运维基线,对项目内全体授权主体可见。

(2)三档安全模型处理策略(handlingPolicy)

处理策略 (handlingPolicy)是否允许 Chat LLM 抽取/改写是否生成 Dense/Sparse 向量投影是否允许图片/PDF 多模态解析适用合规场景与约束说明
standard(默认)允许(qwen-plus)允许(text-embedding-v3 1024 维 + Sparse)允许(qwen-vl-max)标准智能记忆模式,支持 infer=true 自动事实抽取、冲突消解、向量/混合/图谱检索以及向上派生 L2/L3 上下文。
no_embedding允许禁止生成任何向量投影允许文本处理,不生成向量适用于允许大模型理解文本但因安全合规要求禁止将特征写入向量索引的数据,仅可通过 keyword 全文检索或元数据精确过滤读取。
no_model严禁任何大模型接触数据禁止生成任何向量投影严禁多模态媒体解析零大模型接触(Zero-LLM Compliance)严格合规模式:写入时必须显式指定 infer=false(若传 infer=true 或传入 media 将直接返回 400 拒绝),数据仅原样加密落盘于 OceanBase 主表,且禁止参与画像、Dreaming 或蒸馏。

功能入口与权限矩阵

在 Agentbase 控制台中,多层记忆的写入、层级筛选、L2/L3 上下文治理与衰减晋升配置分布在 记忆(Memory) 模块的协同页签中(基础路由:/console/project-{region}-enterprise-ai-hub-210/memory):

功能操作场景控制台 UI 入口与子路由对应 REST API 端点Server SDK 方法 (agentbase-node-sdk@2.10.0)所需 RBAC / API Key Scope跨模块依赖关系
按层级/类型/作用域写入记忆记忆 → 记忆 → 添加记忆(?tab=memories)POST /v1/memory/memoriesmemory.creatememories.write(含 media 时需 files.read)依赖 模型网关(dashscope-prod)与 存储(agent_multimedia_bucket)
查看多层记忆列表与治理状态记忆 → 记忆 列表筛选区(?tab=memories)GET /v1/memory/memoriesmemory.listmemories.read展示 memoryType(working/short_term/long_term)、recordKind、scope 与 handlingPolicy
执行 L3->L2->L1->L0 渐进式检索记忆 → 记忆 搜索栏(?tab=memories)POST /v1/memory/memories/searchmemory.searchmemories.read依赖 上下文治理 已激活的 L2/L3 节点与 text-embedding-v3
执行带 Token 预算的跨层统一召回智能体工作台自动注入 / API 调用POST /v1/memory/memories/recallmemory.recallKnowledgememories.read同时聚合 L1 事实、用户画像(画像)与已激活经验/技能(经验与技能)
追溯 L1/L2/L3 关联的 L0 原始证据记忆详情 / 上下文详情 → 来源证据GET /v1/memory/memories/{memoryId}/sourcesmemory.listSourcesmemories.read关联不可变 sources 表与 _appbaseMemoryMedia
管理 L2/L3 Dreaming 聚合上下文记忆 → 上下文(?tab=governance)GET/POST /v1/memory/memories/contexts*memory.listContexts / createContextRun / confirmContextmemories.read / memories.write(确认需管理权限)依赖 evolution.dreaming 配置与 qwen-plus
配置三层衰减阈值与自动晋升规则记忆 → 配置 → 遗忘 Pipeline / 基础配置(?tab=configuration)PUT /v1/projects/{projectId}/memory/config/policy、PATCH /v1/memory/pipelines/{id}控制面 HTTP APIConsole 管理员或 projects.write关联 记忆遗忘机制 与 记忆配置中心

功能详解与操作指南

步骤一:在控制台按三维属性写入并检视多层记忆

  1. 登录 Agentbase 控制台,进入组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60)下的项目 企业智能客服与知识中台(enterprise-ai-hub-210),在左侧导航栏单击 记忆(Memory)。

  2. 在默认的 记忆 页签中,输入目标用户 ID(如 user_zhangwei_001 或 user_lina_002)并单击 查询。列表清晰展示该项目下按不同时效层级(long_term、short_term、working、偏好 preference)、记录种类(fact、conversation、action)与可见范围(user、group、project)组织的多层记忆记录。

  3. 单击右上角 添加记忆,可针对不同业务场景显式指定记忆的三维坐标:

    • 场景 A(写入长期架构基线 long_term + standard):为 user_zhangwei_001 设置 scope: "user"、memoryType: "long_term"、recordKind: "fact"、handlingPolicy: "standard",写入核心账务 OceanBase 集群拓扑参数,系统将同步生成 1024 维稠密向量与稀疏向量投影;

    • 场景 B(写入单次工单临时工作记忆 working):在排查工单 TK-20261022-001 期间设置 memoryType: "working",记录当前临时抓包节点与会话水位;

    • 场景 C(写入零模型接触合规记录 no_model):针对严禁送入大模型的合规备案编号,设置 handlingPolicy: "no_model" 且处理方式选择 直接写入(infer=false)。

步骤二:通过 REST API 写入不同时效层级与安全策略的记忆

以下 curl 示例演示如何为 user_zhangwei_001 与 user_lina_002 分别写入 工作记忆(working)、长期多模态证据记忆(L0 -> L1 long_term) 以及 零大模型合规记忆(no_model):

export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"

# 1. 写入 working 工作记忆(捕获工单 TK-20261022-001 临时排障中间状态,快速衰减 multiplier=2.0)
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Idempotency-Key: layer-working-zhangwei-001" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_zhangwei_001",
    "sessionId": "sess_ticket_TK_20261022_001",
    "scope": "user",
    "memoryType": "working",
    "recordKind": "fact",
    "handlingPolicy": "standard",
    "content": "工单 TK-20261022-001 临时排障状态:正在观测 ob-core-zone2 节点租户向量内存水位,当前临时采样间隔设为 5 秒。",
    "metadata": {
      "ticketId": "TK-20261022-001",
      "tier": "working_scratchpad"
    },
    "infer": false
  }' | jq .

# 2. 写入 L0 多模态证据并异步抽取 L1 长期记忆 (Storage: agent_multimedia_bucket -> qwen-vl-max + qwen-plus)
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Idempotency-Key: layer-l0-multimodal-zhangwei-002" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_zhangwei_001",
    "scope": "user",
    "memoryType": "long_term",
    "recordKind": "fact",
    "handlingPolicy": "standard",
    "media": {
      "bucketId": "agent_multimedia_bucket",
      "fileId": "ob_shared_v2_hnsw_topology.png"
    },
    "content": "核心账务系统 OceanBase Shared V2 生产集群三可用区拓扑图与 1024 维 HNSW 索引内存水位基线",
    "infer": true
  }' | jq .

# 3. 写入 handlingPolicy=no_model 的严格合规记录(零 LLM 接触、零向量化,必须 infer=false)
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Idempotency-Key: layer-nomodel-lina-003" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_lina_002",
    "scope": "private",
    "agentId": "enterprise-support-agent",
    "memoryType": "long_term",
    "recordKind": "fact",
    "sensitivity": "restricted",
    "handlingPolicy": "no_model",
    "content": "合规备案凭据索引号:COMP-AUDIT-2026-88412(仅允许精确审计核验,禁止大模型改写与向量化)。",
    "infer": false
  }' | jq .

步骤三:渐进式分层召回(Progressive Recall:L3 -> L2 -> L1 -> L0)原理与实战

当智能体面对复杂问题时,如果一次性把数百条 L1 原子事实塞入上下文,既浪费 Token 又容易迷失重点。Agentbase Memory 在 POST /v1/memory/memories/search 中提供了 retrieval.strategy = "progressive"(渐进式分层召回) 机制:

1. 渐进式分层召回的执行机制与安全边界

阶段 / 参数字段名与取值范围默认值 / 预算架构行为与 Fail-Closed 安全保证
检索策略retrieval.strategy"flat"(设为 "progressive" 启用)启用后按认知金字塔自顶向下(L3 Overview -> L2 Context -> L1 Fact -> L0 Source)组装分层上下文结果。
起始入口层级retrieval.entryLevel"auto"(可选 "overview" / "context" / "fact")auto 模式下优先匹配已激活(user-active / agent-active)且来源完整的 L3 Overview 与 L2 Topic/Episode/State;若当前无激活的高层聚合或请求携带了仅 L1 支持的精确 metadata/sessionId 过滤,则自动平滑降级从 L1 Fact 检索。
最大下钻深度retrieval.maxDepth1 ~ 3(默认 2)控制单次检索自动向下展开的认知跨度(如从 L3 Overview 展开到关联的 L2 Topic 及核心 L1 Fact)。
Token 预算控制retrieval.tokenBudget正整数(如 1200)按层级优先级严格裁剪返回的上下文总 Token 数,确保可直接安全注入智能体 System Prompt。
检索时间预算retrieval.deadlineMs最高 450 ms控制渐进式检索的内部时间预算;该值不是端到端延迟 SLA。请求仍可能因权限、依赖或其他错误失败,不能保证每次都返回部分结果。
签名下钻令牌expansionToken有效期 2 分钟(120s)每条返回的 L3 / L2 节点若存在可继续展开的子层(canExpand: true),会附带 HMAC 签名的 expansionToken。客户端发起二次下钻时传入该令牌,服务端会实时重验项目、调用者主体、目标 userId、groupId 成员关系、底层 L1/L0 来源存活状态及策略版本;若期间任一底层记忆被删除或权限收回,令牌立即按 Fail-closed 拒绝展开。

2. 使用 agentbase-node-sdk@2.10.0 执行渐进式召回与二次下钻

// 使用官方服务端 SDK: agentbase-node-sdk@2.10.0
import { Client, Memory } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint('https://appbuild.oceanbase.com/v1')
    .setProject('enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY);

const memory = new Memory(client);

// 1. 首跳渐进式分层检索:优先获取 L3 Overview 与 L2 Topic/Episode/State 脉络
const progressiveRes = await memory.search({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: '核心账务集群近期向量索引变更脉络与未闭环工单状态',
    searchMode: 'hybrid',
    limit: 8,
    retrieval: {
        strategy: 'progressive',
        entryLevel: 'auto',
        maxDepth: 2,
        tokenBudget: 1200,
        deadlineMs: 450
    }
});

console.log('命中的认知层级节点:', progressiveRes.items?.map(item => ({
    id: item.memoryId || item.contextId,
    level: item.level,       // 例如 'L3', 'L2', 'L1'
    kind: item.kind,         // 例如 'memory_overview', 'memory_topic', 'memory_state', 'fact'
    canExpand: item.canExpand
})));

// 2. 按需使用 2 分钟有效期的签名 expansionToken 下钻展开底层 L1 事实与 L0 证据
const expandableNode = progressiveRes.items?.find(item => item.canExpand && item.expansionToken);
if (expandableNode) {
    const drillDownRes = await memory.search({
        userId: 'user_zhangwei_001',
        scope: 'user',
        query: '核心账务集群近期向量索引变更脉络与未闭环工单状态',
        retrieval: {
            strategy: 'progressive',
            expansionToken: expandableNode.expansionToken,
            maxDepth: 1,
            tokenBudget: 800,
            deadlineMs: 450
        }
    });
    console.log('下钻展开的底层 L1/L0 详情:', drillDownRes.items);
}

常见问题与排障(FAQ)

1. 为什么将记忆设置为 handlingPolicy: "no_model" 后,调用创建接口返回 400 Bad Request?

2. working(工作记忆)在什么条件下会自动晋升为 short_term 或 long_term?为什么刚写入的记忆没有立刻发生衰减或晋升?

3. 使用 expansionToken 下钻展开 L2/L3 上下文时,为什么返回令牌失效或拒绝展开?

4. strict_private 与 private 作用域有什么本质区别?为什么它们都不支持 sessionId 历史会话补水?


相关文档