Docs
文档目录

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

功能概述与核心场景

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

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

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

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

为解决上述问题,Agentbase Memory摒弃了传统的扁平存储模型,参考人类认知心理学与企业安全治理规范,将记忆体系沿着三个正交维度(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 渐进式召回提供高信噪比、强安全围栏的记忆注入。


核心概念与架构

1. 记忆时效层级

memoryType 可以表示工作记忆(working)、短期记忆(short_term)或长期记忆(long_term)。不同类型可配置不同的衰减参数;访问和复习可能影响后续状态,实际晋升与归档取决于配置及条件。类型还支持其他值,不能假定每条记忆都属于这三种之一。

2.12.0 服务的衰减乘数回退默认值分别为 1、7、60;保护期默认 168 小时。项目配置可能覆盖这些值。记忆遗忘与数据保留说明默认值、预览的批次限制和删除边界。

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)或新增记忆、画像与蒸馏流水线产生;模型由项目配置决定。- 原子记忆:按 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(默认)允许(使用项目配置)允许(稠密向量按项目实例配置生成,稀疏向量取决于配置)允许(需配置可用模型)标准智能记忆模式,支持 infer=true 自动事实抽取、冲突消解、向量/混合/图谱检索以及向上派生 L2/L3 上下文。
no_embedding允许禁止生成任何向量投影允许文本处理,不生成向量适用于允许大模型理解文本但因安全合规要求禁止将特征写入向量索引的数据,仅可通过 keyword 全文检索或元数据精确过滤读取。
no_model禁止 Memory 内部模型处理不生成向量不解析多模态媒体写入时显式指定 infer=false 且不传 media;授权应用仍可检索记录并自行传给其他模型,应用需自行控制下游使用和合规。传输及存储加密取决于部署环境的实际配置。

功能入口与权限矩阵

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

功能操作场景控制台 UI 入口与子路由对应 REST API 端点Server SDK 方法 (agentbase-node-sdk@2.12.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根据入口与检索模式使用已激活的 上下文 或事实;向量检索需要配置可用的向量模型
执行带 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 聚合上下文记忆 → 治理策略GET/POST /v1/memory/memories/contexts*memory.listContexts / createContextRun / confirmContextmemories.read / memories.write(确认需管理权限)依赖 evolution.dreaming 及项目配置的模型
配置三层衰减阈值与自动晋升规则记忆 → 配置 → 遗忘 Pipeline / 基础配置(?tab=configuration)PUT /v1/projects/{projectId}/memory/config/policy、PATCH /v1/memory/pipelines/{id}控制面 HTTP API具备管理权限的 Console 用户会话;各接口另需对应操作权限关联 记忆遗忘机制 与 记忆配置中心

功能详解与操作指南

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

  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 集群拓扑参数,向量投影按项目实例模型与维度生成,稀疏向量取决于配置;

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

    • 场景 C(限制 Memory 内部模型处理):设置 handlingPolicy: "no_model" 并选择 直接写入(infer=false);调用方仍需控制检索结果的下游使用。

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

以下 curl 示例演示如何为 user_zhangwei_001 与 user_lina_002 分别写入 工作记忆(working)、长期多模态证据记忆(L0 -> L1 long_term) 以及 限制 Memory 内部模型处理的记忆(no_model):

将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),确认项目和凭据属于该环境。各操作相互独立,请按需执行。每次新写入前设置独立的 MEMORY_IDEMPOTENCY_KEY;仅重试同一次写入时沿用原键及相同请求内容。

  1. 写入 working 工作记忆(捕获工单 TK-20261022-001 临时排障中间状态,快速衰减 multiplier=2.0)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${MEMORY_IDEMPOTENCY_KEY:?Set a unique key for this new write}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Idempotency-Key: ${MEMORY_IDEMPOTENCY_KEY}" \
    -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 .
)
  1. 写入 L0 多模态证据并异步抽取 L1 长期记忆 (Storage: agent_multimedia_bucket -> qwen-vl-max + qwen-plus)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${MEMORY_IDEMPOTENCY_KEY:?Set a unique key for this new write}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Idempotency-Key: ${MEMORY_IDEMPOTENCY_KEY}" \
    -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 .
)
  1. 写入 handlingPolicy=no_model 的记录(限制 Memory 内部模型处理,必须 infer=false)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${MEMORY_IDEMPOTENCY_KEY:?Set a unique key for this new write}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Idempotency-Key: ${MEMORY_IDEMPOTENCY_KEY}" \
    -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省略表示普通检索;设为 "progressive" 启用渐进检索启用后按认知金字塔自顶向下(L3 Overview -> L2 Context -> L1 Fact -> L0 Source)组装分层上下文结果。
起始入口层级retrieval.entryLevel"auto"(可选 "overview" / "context" / "fact" / "evidence")auto 模式下优先匹配已激活(user-active / agent-active)且来源完整的 L3 Overview 与 L2 Topic/Episode/State;若当前无激活的高层聚合或请求携带了仅 L1 支持的精确 metadata/sessionId 过滤,则自动平滑降级从 L1 Fact 检索。
最大下钻深度retrieval.maxDepth0 ~ 3(默认 2)控制单次检索自动向下展开的认知跨度(如从 L3 Overview 展开到关联的 L2 Topic 及核心 L1 Fact)。
Token 预算控制retrieval.tokenBudget64 ~ 8192(默认 1200)按估算的 Token 预算逐项限制返回内容;估算不等同于目标模型的精确分词。调用方应按所用模型核对上下文窗口,并对检索内容设置可信边界,避免将不可信内容当作系统指令。
检索时间预算retrieval.deadlineMs50 ~ 450 ms(默认 450 ms)控制渐进式检索的内部时间预算;该值不是端到端延迟 SLA。请求仍可能因权限、依赖或其他错误失败,不能保证每次都返回部分结果。
签名下钻令牌expansionToken有效期 2 分钟(120s)每条返回的 L3 / L2 节点若存在可继续展开的子层(canExpand: true),会附带 HMAC 签名的 expansionToken。客户端发起二次下钻时传入该令牌,服务端会实时重验项目、调用者主体、目标 userId、groupId 成员关系、底层 L1/L0 来源存活状态及策略版本;若期间任一底层记忆被删除或权限收回,令牌立即按 Fail-closed 拒绝展开。

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

运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。

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

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>')
    .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.progressive?.items?.map(item => ({
    id: item.id,
    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.progressive?.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.progressive?.items);
}

常见问题与排障(FAQ)

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

2. 为什么新记忆没有立即归档或晋升?

新记忆可能仍在保护期内;状态变化还取决于访问、复习、阈值和实际生效的配置。可通过 记忆 → 配置 → 遗忘 Pipeline 的 运行样例检查受批次限制的候选动作;结果不是全部记忆的清单。

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

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


相关文档