多层记忆划分:三层时效记忆、L0–L3 认知架构与渐进式召回
功能概述与核心场景
在企业级智能体(Agent)的长周期生产运行中,如果将所有对话历史、临时排障参数、个人偏好、项目规范与历史工单结论无差别地平铺存储在单一的扁平向量库(Flat Vector Store)中,随着交互轮次增长,智能体将不可避免地面临三大工程瓶颈:
- 上下文窗口污染(Context Window Pollution):几周前某次临时工单排障使用的中间参数(如临时测试端口或已废弃的限流阈值)与长期稳定的生产架构基线混杂,导致向量召回信噪比急剧下降;
- 宏观脉络缺失(Loss of Macro Context):扁平的碎片化事实(Atomic Facts)难以回答“过去一个月核心账务集群经历了哪些阶段性变更?”或“当前用户有哪些未闭环的阻塞问题?”等跨会话全局问题;
- 多租户与隐私边界混同(Scope & Compliance Leakage):单次会话内部的敏感调试上下文、跨智能体共享的个人偏好、团队群组协同记忆以及不希望经过大模型向量化的合规文本缺乏细粒度隔离。
为解决上述问题,Agentbase Memory(v2.10.0)摒弃了传统的扁平存储模型,参考人类认知心理学与企业安全治理规范,将记忆体系沿着三个正交维度(Three Orthogonal Dimensions)进行立体划分,并配套提供毫秒级受控的渐进式分层召回(Progressive Recall):
- 第一维度:时间衰减与保留层级(Time-Decay & Retention Tiers)——按时效与复用频率划分为
working(工作记忆)、short_term(短期记忆)与long_term(长期记忆),结合艾宾浩斯遗忘曲线与间隔复习(Spaced Repetition)实现working -> short_term -> long_term的自动跨层晋升; - 第二维度:L0–L3 四层认知抽象金字塔(Cognitive Hierarchy)——自底向上构建
L0(原始多模态证据)、L1(原子记忆、画像与经验技能)、L2(Dreaming 聚合的主题Topic、情节Episode、状态State)与L3(全局概览Overview); - 第三维度:五级可见性作用域与安全处理策略(Visibility Scopes & Handling Policies)——提供从
strict_private、private、user、group到project的五级访问隔离围栏,以及standard、no_embedding、no_model三种模型接触治理策略。
在 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)数据流如下图所示:
flowchart TB
subgraph Dim1["第一维度:时间衰减与保留层级 (Time-Decay & Retention Tiers)"]
W["working (工作记忆)\ndecay multiplier = 2.0 | threshold = 0.15\n单次任务/工单临时参数与工具状态"]
ST["short_term (短期记忆)\ndecay multiplier = 1.0 | threshold = 0.25\n近期跨天会话上下文与活跃工单进展"]
LT["long_term (长期记忆)\ndecay multiplier = 0.3 | threshold = 0.10\n固化架构事实、个人偏好、已验证 Experience & Skill"]
W -->|"间隔复习强化 (reinforcement_factor)\nreview_intervals: [1, 2, 4, 7, 14, 30]"| ST
ST -->|"高频召回与正向反馈自动晋升"| LT
end
subgraph Dim2["第二维度:L0–L3 四层认知抽象金字塔 (Cognitive Hierarchy)"]
L3["L3 全局概览层 (Global Overview)\nkind = memory_overview\n跨主题/跨周期的全局认知脉络图"]
L2["L2 聚合上下文层 (Aggregated Contexts - Dreaming)\n• L2 Topic (memory_topic:领域主题聚类)\n• L2 Episode (memory_episode:时序事件/工单始末)\n• L2 State (memory_state:当前活跃状态与阻塞项)"]
L1["L1 原子记忆与知识层 (Atomic Memories & Knowledge)\n• 原子记录 (recordKind: fact / preference / event / conversation / action)\n• 用户画像 (Profile: content / topics)\n• 排障经验与标准技能 (Experience & Skill)"]
L0["L0 原始证据层 (Raw Source & Multimodal Evidence)\n不可变 messages 对话轮次 / toolEvents 工具轨迹 /\nStorage 多模态解析证据 (_appbaseMemoryMedia: PNG/JPEG/WebP/PDF)"]
L0 -->|"sourceIds 溯源绑定 &\nqwen-plus 抽取"| L1
L1 -->|"后台 Dreaming 异步聚类"| L2
L2 -->|"后台 Dreaming 顶层归纳"| L3
end
subgraph Dim3["第三维度:五级可见性作用域与安全策略 (Scopes & Handling Policies)"]
Scopes["五级可见性作用域 (scope)\nstrict_private -> private -> user -> group (groupId) -> project"]
Policies["三档模型处理策略 (handlingPolicy)\n• standard:完整 LLM 提取 + Dense/Sparse/Graph 投影\n• no_embedding:跳过向量化,仅允许关键词/精确过滤\n• no_model:零大模型接触合规模式 (强制 infer=false, 拒绝多模态)"]
end
subgraph ProgressiveRecall["在线渐进式分层召回 (retrieval.strategy = progressive, deadlineMs ≤ 450ms)"]
Entry["查询入口 (entryLevel = auto / overview / context)\n先检索 L3 Overview 与 L2 Context 高层摘要"]
Expand["受控逐层下钻 (maxDepth = 1..3)\n校验 2 分钟有效期的签名 expansionToken (Fail-closed)"]
Leaf["按需展开底层 L1 Fact 与 L0 原始 Source 证据"]
Entry --> Expand --> Leaf
end
L3 --> Entry
L2 --> Expand
L1 --> Leaf
L0 --> Leaf
Dim1 -.->|"生命周期衰减与晋升"| L1
Dim3 -.->|"访问控制与投影门禁"| ProgressiveRecall1. 第一维度:时间衰减与保留层级(Time-Decay & Retention Tiers)
在创建或推断记忆时,每条记忆通过 memoryType(或流水线自动分类)落入三个具有不同时间衰减乘数(decay_rate_multipliers)和遗忘阈值(threshold)的时效层级:
| 时效记忆层级 | 枚举值 (memoryType) | 默认衰减乘数 (decay_rate_multipliers) | 默认遗忘阈值 (threshold) | 核心定位、典型业务数据与跨层流转机制 |
|---|---|---|---|---|
| 工作记忆 | working | 2.0(快速衰减) | working_threshold = 0.15 | 短周期任务/单轮草稿区(Scratchpad):记录当前正在排查的临时工单参数、多步工具调用的中间状态(如“当前正在检查 OBProxy 节点 10.0.4.12:2883 的连接池水位”)。若任务结束后未再被召回,会以 2 倍基准衰减率迅速衰减归档;若在间隔复习窗口内被反复召回强化,则自动晋升至 short_term。 |
| 短期记忆 | short_term | 1.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)的跨层自动晋升机制:
- Agentbase Memory 内置了间隔复习周期数组
review_intervals: [1, 2, 4, 7, 14, 30](单位:天)以及强化因子reinforcement_factor(默认1.35)与复习调整系数review_adjustment_factor(默认0.85)。 - 当某条处于
working或short_term的记忆在后续对话中被在线检索(search)或统一召回(recall)命中,或者收到业务侧的正向反馈(POST /v1/memory/memories/feedback)时,系统不仅会提升其当前保留率 $R(t)$ 并推进复习阶段,还会由后台遗忘与晋升流水线(Forgetting Pipeline)评估其累计访问频次与跨会话复用度,执行 **working -> short_term -> long_term** 的自动跨层晋升(action: "promote")。关于衰减数学公式与遗忘流水线的详细配置,请参阅 记忆遗忘机制、艾宾浩斯衰减与数据保留治理。
2. 第二维度:L0–L3 四层认知抽象金字塔(Cognitive Hierarchy)
为兼顾“微观事实精确溯源”与“宏观脉络快速把握”,Agentbase Memory 将项目内的认知资产由具体到抽象划分为 L0 至 L3 四个认知层级:
| 认知层级 | 内部标识与承载对象 | 生成与更新机制 | 关联溯源与核心结构说明 |
|---|---|---|---|
**L0 原始证据层**<br>(Raw Source & Multimodal Evidence) | sources 表(src_*) | 每次调用记忆写入、画像提取或知识蒸馏时同步/异步冻结生成,不可篡改(Immutable)。 | 保存原始对话轮次(messages)、工具调用轨迹(toolEvents)以及同项目 Storage(如 agent_multimedia_bucket)中 PNG/JPEG/WebP 图片或 PDF 文档的解析快照(固化在 _appbaseMemoryMedia 元数据中,含文件 SHA-256、页码边界与字符偏移)。 |
**L1 原子记忆与知识层**<br>(Atomic Memories & Knowledge) | - 原子记忆(mem_*)<br>- 用户画像(Profile)<br>- 经验与技能(Experience / Skill) | 由直写(infer=false)或新增记忆/画像/蒸馏 Pipeline(调用 qwen-plus 与 text-embedding-v3)抽取并去重合并。 | - 原子记忆:按 recordKind 细分为客观事实(fact)、用户偏好(preference)、时序事件(event)、原始对话片段(conversation)与工具动作(action);<br>- 结构化画像与经验技能:每条 L1 记录均通过 sourceIds 严格指向支撑它的 L0 原始证据。 |
**L2 聚合上下文层**<br>(Aggregated Contexts) | contexts 表(ctx_*):<br>- L2 Topic(memory_topic)<br>- L2 Episode(memory_episode)<br>- L2 State(memory_state) | 由后台 Dreaming(上下文聚合引擎) 异步扫描变化的 L1 记忆聚类归纳而成。 | - **L2 Topic(主题上下文):聚合特定技术领域或业务模块的跨会话认知(如“OceanBase 1024 维 HNSW 向量索引调优主题”);<br>- L2 Episode(情节上下文)**:按时间起止与因果链条还原一次完整事件或里程碑(如“工单 TK-20261022-001 向量内存耗尽排障全过程”);<br>- **L2 State(状态上下文)**:反映用户或系统当前的最新有效状态与待解决阻塞项(自动剔除已被推翻的旧状态)。 |
**L3 全局概览层**<br>(Global Overview) | contexts 表(ctx_*):<br>- 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/memories | memory.create | memories.write(含 media 时需 files.read) | 依赖 模型网关(dashscope-prod)与 存储(agent_multimedia_bucket) |
| 查看多层记忆列表与治理状态 | 记忆 → 记忆 列表筛选区(?tab=memories) | GET /v1/memory/memories | memory.list | memories.read | 展示 memoryType(working/short_term/long_term)、recordKind、scope 与 handlingPolicy |
| 执行 L3->L2->L1->L0 渐进式检索 | 记忆 → 记忆 搜索栏(?tab=memories) | POST /v1/memory/memories/search | memory.search | memories.read | 依赖 上下文治理 已激活的 L2/L3 节点与 text-embedding-v3 |
| 执行带 Token 预算的跨层统一召回 | 智能体工作台自动注入 / API 调用 | POST /v1/memory/memories/recall | memory.recallKnowledge | memories.read | 同时聚合 L1 事实、用户画像(画像)与已激活经验/技能(经验与技能) |
| 追溯 L1/L2/L3 关联的 L0 原始证据 | 记忆详情 / 上下文详情 → 来源证据 | GET /v1/memory/memories/{memoryId}/sources | memory.listSources | memories.read | 关联不可变 sources 表与 _appbaseMemoryMedia |
| 管理 L2/L3 Dreaming 聚合上下文 | 记忆 → 上下文(?tab=governance) | GET/POST /v1/memory/memories/contexts* | memory.listContexts / createContextRun / confirmContext | memories.read / memories.write(确认需管理权限) | 依赖 evolution.dreaming 配置与 qwen-plus |
| 配置三层衰减阈值与自动晋升规则 | 记忆 → 配置 → 遗忘 Pipeline / 基础配置(?tab=configuration) | PUT /v1/projects/{projectId}/memory/config/policy、PATCH /v1/memory/pipelines/{id} | 控制面 HTTP API | Console 管理员或 projects.write | 关联 记忆遗忘机制 与 记忆配置中心 |
功能详解与操作指南
步骤一:在控制台按三维属性写入并检视多层记忆
- 登录 Agentbase 控制台,进入组织
Agentbase 企业智能中台(69c6d1aa00062e6bb60)下的项目 **企业智能客服与知识中台**(enterprise-ai-hub-210),在左侧导航栏单击 记忆(Memory)。 - 在默认的 记忆 页签中,输入目标用户 ID(如
user_zhangwei_001或user_lina_002)并单击 查询。列表清晰展示该项目下按不同时效层级(long_term、short_term、working、偏好preference)、记录种类(fact、conversation、action)与可见范围(user、group、project)组织的多层记忆记录。
- 单击右上角 添加记忆,可针对不同业务场景显式指定记忆的三维坐标:
- **场景 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)**。
- **场景 A(写入长期架构基线
步骤二:通过 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.maxDepth | 1 ~ 3(默认 2) | 控制单次检索自动向下展开的认知跨度(如从 L3 Overview 展开到关联的 L2 Topic 及核心 L1 Fact)。 |
| Token 预算控制 | retrieval.tokenBudget | 正整数(如 1200) | 按层级优先级严格裁剪返回的上下文总 Token 数,确保可直接安全注入智能体 System Prompt。 |
| 硬延迟截止保护 | retrieval.deadlineMs | 最大 450 ms | 在线检索硬性 SLA 守卫:渐进式检索全程采用 OceanBase 向量/全文索引与预构建层级边,绝不在在线搜索链路中同步调用慢速生成式 LLM;一旦接近 450ms 截止预算,立即返回已就绪层级结果并标记预算状态。 |
| 签名下钻令牌 | 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?
- 原因分析:
handlingPolicy: "no_model"代表最严格的“零大模型接触”合规承诺。如果请求中同时传入了infer: true(需要调用qwen-plus抽取事实与检测冲突)或传入了media多模态文件引用(需要调用qwen-vl-max视觉解析),都会违反零模型接触约束,因此服务端按 Fail-closed 原则直接拒绝请求。 - 解决措施:使用
handlingPolicy: "no_model"时,必须在请求体中显式传入"infer": false且不携带media字段;读取该记录时请使用列表查询或searchMode: "keyword"全文检索,不要使用纯向量检索(vector)。
2. working(工作记忆)在什么条件下会自动晋升为 short_term 或 long_term?为什么刚写入的记忆没有立刻发生衰减或晋升?
- 原因分析:新写入的记忆处于最短保护期(
minimum_protection_hours,默认24小时,配置中心可按业务调优)内,在此期间保留率恒定受到保护,不会被后台遗忘流水线清理。当该条working记忆在后续会话中多次被检索召回或收到正向反馈,且命中了间隔复习周期(review_intervals: [1, 2, 4, 7, 14, 30])时,后台遗忘 Pipeline 的forgetting_decision节点会将其保留率乘以reinforcement_factor并自动执行跨层晋升(working -> short_term -> long_term)。 - 解决措施:可通过 记忆 → 配置 → 遗忘 Pipeline 的 运行样例(Dry-run) 功能(
POST /v1/memory/pipelines/{pipelineId}/validate),预览指定用户(如user_zhangwei_001)名下各层级记忆的当前保留率及预计执行的retain/promote/archive动作。
3. 使用 expansionToken 下钻展开 L2/L3 上下文时,为什么返回令牌失效或拒绝展开?
- 原因分析:
expansionToken的设计目标是保障分层摘要绝不成为绕过底层权限或隐私删除的后门。以下四种情况均会触发令牌立即失效(Fail-closed):① 距离生成该令牌已超过 2 分钟(120 秒);② 支撑该 L2/L3 节点的某条底层L1记忆或L0来源刚被用户删除或遗忘;③ 项目的安全策略版本(policy)发生了变更;④ 调用者的身份、目标userId或groupId群组成员资格与签发令牌时不一致。 - 解决措施:捕获下钻异常后,重新发起一次顶层
strategy: "progressive"搜索请求以获取基于最新存活证据与最新权限快照的检索结果;若某条 L2/L3 上下文因底层来源删除已变为stale或quarantine,请前往 分层上下文治理与 Dreaming 执行 重建(Rebuild)。
4. strict_private 与 private 作用域有什么本质区别?为什么它们都不支持 sessionId 历史会话补水?
- 原因分析:
private允许同一个用户在同一个专属agentId下跨会话检索自己的私有记忆,并且在授权并集查询(accessMode: "accessible")中对拥有该用户与 Agent 权限的调用方可见;而strict_private进一步收敛至单次运行/会话拥有者,**永远不进入accessible授权并集**。同时,为了防止大模型在infer=true推断时把同会话前几轮的其他范围对话隐式拼接进严格私有记录中,系统对strict_private和private均强制禁用sessionId历史上下文补水。 - 解决措施:若业务需要利用同会话最近 12 轮历史对话辅助消解代词指代(如“我选方案 A”),请将
scope设置为user、group或project。