Docs
Contents

Multi-layer memory partitioning: three-tier time-sensitive memory, L0–L3 cognitive architecture, and progressive retrieval

Feature overview and core scenarios

In long-cycle production runs of enterprise-grade agents, if all conversation history, temporary troubleshooting parameters, personal preferences, project conventions, and historical support ticket conclusions are indiscriminately flattened into a single flat vector store, as interaction rounds grow, the agent will inevitably face three major engineering bottlenecks:

  1. Context Window Pollution: Intermediate parameters used in a temporary support ticket troubleshooting session weeks ago (such as temporary test ports or deprecated rate-limit thresholds) get mixed with the long-term stable production architecture baseline, causing the signal-to-noise ratio of vector retrieval to drop sharply;

  2. Loss of Macro Context: flat, fragmented atomic facts struggle to answer cross-session global questions such as “What staged changes did the core accounting cluster undergo over the past month?” or “What unclosed blocking issues does the current user have?”;

  3. Scope & Compliance Leakage: sensitive debugging context within a single session, personal preferences shared across agents, team/group collaboration memory, and compliance texts that should not pass through LLM vectorization all lack fine-grained isolation.

To address the issues above, Agentbase Memory (v2.10.0) abandons the traditional flat storage model. Drawing on human cognitive psychology and enterprise security governance standards, it partitions the memory system along Three Orthogonal Dimensions and provides millisecond-level, controlled Progressive Recall:

In the flagship project 企业智能客服与知识中台 (project ID: enterprise-ai-hub-210, based on the OceanBase Shared V2 storage mode) under Agentbase 企业智能中台 (organization ID: 69c6d1aa00062e6bb60), the system leverages the above three-dimensional multi-tier memory architecture to precisely distinguish one-time support-ticket temporary context from long-term architectural preferences for VIP core accounting architect user_zhangwei_001 and frontline operations engineer user_lina_002, and, using an example retrieval budget of 450ms, provides high-signal, strongly fenced memory injection via L3 -> L2 -> L1 -> L0 progressive recall.


Core Concepts and Architecture

The three-dimensional orthogonal tiered architecture of Agentbase Memory and the Progressive Recall data flow are illustrated below:

Multi-layer memory partitioning: three-tier time-sensitive memory, L0–L3 cognitive architecture, and progressive retrieval: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

1. First Dimension: Time-Decay & Retention Tiers

When a memory is created or inferred, each entry is assigned—via memoryType (or automatic pipeline classification)—to one of three time-decay tiers with different decay multipliers (decay_rate_multipliers) and forgetting thresholds (threshold):

Time-Decay Memory TierEnum Value (memoryType)Default Decay Multiplier (decay_rate_multipliers)Default Forgetting Threshold (threshold)Core Positioning, Typical Business Data, and Cross-Tier Transition Mechanism
Working Memoryworking2.0 (fast decay)working_threshold = 0.15Short-cycle task / single-turn Scratchpad: records temporary ticket parameters currently under investigation and intermediate states of multi-step tool calls (e.g., “currently checking the connection pool watermark of OBProxy node 10.0.4.12:2883”). If it is not retrieved again after the task ends, it rapidly decays and is archived at 2 times the base decay rate; if it is repeatedly retrieved and reinforced within the spaced repetition window, it is automatically promoted to short_term.
Short-Term Memoryshort_term1.0 (standard decay)short_term_threshold = 0.25Recent cross-session active context: records items the user has continuously followed in recent days, phased focus areas, or backgrounds of tickets not yet closed (e.g., “user_lina_002 is verifying the incremental Yuque sync strategy of knowledge base kb_enterprise_support this week”). It features a standard decay rate (1.0) and a higher relevance admission threshold (0.25).
Long-Term Memorylong_term (including consolidated preference / fact)0.3 (slow decay)long_term_threshold = 0.10Enterprise-grade persistent cognitive baseline: stores consolidated user core responsibilities, long-term technology stack preferences, production cluster topology facts (e.g., “user_zhangwei_001 is responsible for the core accounting OceanBase Shared V2 cluster with SLA tier P0-VIP”), activated troubleshooting experience (Experience), and standard skills (Skill). It is doubly protected by a minimum protection period (minimum_protection_hours) and the 0.3 low decay multiplier.

Cross-Tier Automatic Promotion Mechanism Based on Spaced Repetition:

2. Second Dimension: L0–L3 Four-Tier Cognitive Abstraction Pyramid (Cognitive Hierarchy)

To balance “precise traceability of micro facts” with “rapid grasp of the macro picture”, Agentbase Memory divides cognitive assets within a project from concrete to abstract into four cognitive tiers, L0 through L3:

Cognitive TierInternal Identifier and Backing ObjectGeneration and Update MechanismTraceability Associations and Core Structure Description
L0 Raw Evidence Tier
(Raw Source & Multimodal Evidence)
sources table (src_*)Frozen and generated synchronously/asynchronously on each memory write, profile extraction, or knowledge distillation call, immutable.Stores raw conversation turns (messages), tool call traces (toolEvents), and parsing snapshots of PNG/JPEG/WebP images or PDF documents in the same project's Storage (e.g., agent_multimedia_bucket), consolidated in _appbaseMemoryMedia metadata (including file SHA-256, page boundaries, and character offsets).
L1 Atomic Memories & Knowledge Tier
(Atomic Memories & Knowledge)
- Atomic memories (mem_*)
- User profiles (Profile)
- Experience and skills (Experience / Skill)
Extracted via direct writes (infer=false) or the add-memory/profile/distillation Pipelines (calling qwen-plus and text-embedding-v3), with deduplication and merging.- Atomic memories: subdivided by recordKind into objective facts (fact), user preferences (preference), temporal events (event), raw conversation snippets (conversation), and tool actions (action);
- Structured profiles, experience, and skills: each L1 record strictly points, via sourceIds, to the L0 raw evidence supporting it.
L2 Aggregated Contexts Tier
(Aggregated Contexts)
contexts table (ctx_*):
- L2 Topic (memory_topic)
- L2 Episode (memory_episode)
- L2 State (memory_state)
Generated by the background Dreaming (context aggregation engine) asynchronously scanning and summarizing changed L1 memory clusters.- L2 Topic (topic context): aggregates cross-session cognition for a specific technical domain or business module (e.g., “OceanBase 1024-dim HNSW vector index tuning topic”);
- L2 Episode (episodic context): reconstructs a complete event or milestone by time span and causal chain (e.g., “the full troubleshooting process of ticket TK-20261022-001 vector memory exhaustion”);
- L2 State (state context): reflects the latest valid state and unresolved blocking items of the user or system (automatically removing outdated states that have been overturned).
L3 Global Overview Tier
(Global Overview)
contexts table (ctx_*):
- L3 Overview (memory_overview)
Generated by the background Dreaming further summarizing multiple L2 topics, episodes, and states under the same user or agent.Provides a bird's-eye cognitive map at the highest level of abstraction, serving as the first-hop navigation entry of Progressive Recall.

3. Third Dimension: Five-Level Visibility Scopes and Safe Handling Policies (Visibility Scopes & Handling Policies)

When any memory or derived context is written or retrieved, it must be subject simultaneously to the orthogonal constraints of the visibility scope (scope) and the model handling policy (handlingPolicy):

(1) Five-Level Visibility Scopes (scope: from strictest to broadest)

Visibility Scope (scope)Isolation Boundary and Ownership KeysHistorical Session Backfill (sessionId)Typical Use Cases and Retrieval Visibility Rules
strict_privateStrictly limited to the owner of the current single run/sessionMandatorily disabled (to prevent implicit cross-turn association)Contains highly private temporary authentication parameters or one-off sandbox debugging contexts. Never exposed even in accessMode="accessible" authorized union queries.
privatePrivate to a single user (userId) + a specific agent (agentId)Mandatorily disabledRead/write allowed only within the same userId and the same dedicated agentId; sharing across agents is not permitted.
userUser-level sharing across agents (isolated by userId)Supported (same project, same user, same agentId, most recent ≤12 turns / ≤4096 tokens)The most commonly used enterprise default scope. For example, technology stack preferences registered by user_zhangwei_001 in the architecture consulting Agent are equally visible in the ticket troubleshooting Agent.
groupBusiness group/team-level sharing (must carry groupId / metadata.groupId)Supported (within the same group governance boundary)Suitable for project teams and on-call groups (e.g., the core accounting DBA operations group) to share troubleshooting memos; the server verifies the caller's group membership in real time at retrieval.
projectProject-wide sharing (e.g., enterprise-ai-hub-210 entire project)SupportedSuitable for project-wide architecture standards, global terminology conventions, or common operations baselines, visible to all authorized principals within the project.

(2) Three-Tier Safe Model Handling Policies (handlingPolicy)

Handling Policy (handlingPolicy)Whether Chat LLM Extraction/Rewriting Is AllowedWhether Dense/Sparse Vector Projections Are GeneratedWhether Image/PDF Multimodal Parsing Is AllowedApplicable Compliance Scenarios and Constraint Notes
standard (default)Allowed (qwen-plus)Allowed (text-embedding-v3 1024 dimensions + Sparse)Allowed (qwen-vl-max)Standard intelligent memory mode, supporting infer=true automatic fact extraction, conflict resolution, vector/hybrid/knowledge graph retrieval, as well as upward derivation of L2/L3 contexts.
no_embeddingAllowedGenerating any vector projection is forbiddenText processing allowed, no vectors generatedSuitable for data that the large model may understand for comprehension but that security and compliance requirements forbid writing feature vectors for; readable only via keyword full-text search or exact metadata filtering.
no_modelAny large model is strictly forbidden from touching the dataGenerating any vector projection is forbiddenMultimodal media parsing is strictly forbiddenZero-LLM Compliance, strict compliance mode: on write you must explicitly specify infer=false (if infer=true is passed or a media is provided, the request is directly rejected with 400); data is only encrypted and stored as-is in the OceanBase primary table, and is forbidden from participating in profiling, Dreaming, or distillation.

Feature Entrypoints and Permission Matrix

In the Agentbase Console, writing of multi-layer memory, layer filtering, L2/L3 context governance, and decay/promotion configuration are distributed across the collaborative tabs of the Memory module (base route: /console/project-{region}-enterprise-ai-hub-210/memory):

Function / operation scenarioConsole UI entry and sub-routeCorresponding REST API endpointServer SDK method (agentbase-node-sdk@2.10.0)Required RBAC / API Key ScopeCross-module dependencies
Write memory by layer/type/scopeMemory → Memory → Add Memory (?tab=memories)POST /v1/memory/memoriesmemory.creatememories.write (requires files.read when media is included)Depends on Model Gateway (dashscope-prod) and Storage (agent_multimedia_bucket)
View the multi-layer memory list and governance statusMemory → Memory list filter area (?tab=memories)GET /v1/memory/memoriesmemory.listmemories.readDisplays memoryType (working/short_term/long_term), recordKind, scope, and handlingPolicy
Perform L3->L2->L1->L0 progressive retrievalMemory → Memory search bar (?tab=memories)POST /v1/memory/memories/searchmemory.searchmemories.readDepends on activated L2/L3 nodes from Context Governance and text-embedding-v3
Perform cross-layer unified retrieval with a token budgetAutomatic injection in the agent workbench / API callPOST /v1/memory/memories/recallmemory.recallKnowledgememories.readSimultaneously aggregates L1 facts, user profile (Profile), and activated experiences/skills (Experience & Skills)
Trace L1/L2/L3 back to associated L0 raw evidenceMemory details / Context details → Source EvidenceGET /v1/memory/memories/{memoryId}/sourcesmemory.listSourcesmemories.readAssociated with the immutable sources table and _appbaseMemoryMedia
Manage L2/L3 Dreaming aggregated contextsMemory → Context (?tab=governance)GET/POST /v1/memory/memories/contexts*memory.listContexts / createContextRun / confirmContextmemories.read / memories.write (confirmation requires manage permission)Depends on evolution.dreaming configuration and qwen-plus
Configure three-layer decay thresholds and automatic promotion rulesMemory → Configuration → Forgetting Pipeline / Basic Configuration (?tab=configuration)PUT /v1/projects/{projectId}/memory/config/policy, PATCH /v1/memory/pipelines/{id}Control-plane HTTP APIConsole administrator or projects.writeAssociated with Memory Forgetting Mechanism and Memory Configuration Center

Feature Details and Operation Guide

Step One: Write and inspect multi-layer memory in the Console by three-dimensional attributes

  1. Log in to the Agentbase Console, enter the project 企业智能客服与知识中台 (enterprise-ai-hub-210) under organization Agentbase 企业智能中台 (69c6d1aa00062e6bb60), and click Memory in the left navigation bar.

  2. In the default Memory tab, enter the target user ID (e.g., user_zhangwei_001 or user_lina_002) and click Query. The list clearly displays the project's multi-layer memory records organized by different time-horizon layers (long_term, short_term, working, preference preference), record kinds (fact, conversation, action), and visibility scopes (user, group, project).

  3. Click Add Memory in the upper-right corner to explicitly specify the three-dimensional coordinates of a memory for different business scenarios:

    • Scenario A (writing long-term architecture baselines long_term + standard): Set scope: "user", memoryType: "long_term", recordKind: "fact", handlingPolicy: "standard" for user_zhangwei_001, and write the core billing OceanBase cluster topology parameters; the system will synchronously generate 1024-dimension dense and sparse vector projections;

    • Scenario B (writing single support-ticket temporary working memory working): Set memoryType: "working" while troubleshooting support ticket TK-20261022-001, recording the current temporary packet-capture node and session watermark;

    • Scenario C (writing zero-model-contact compliance records no_model): For compliance filing numbers strictly forbidden from being sent to large models, set handlingPolicy: "no_model" and choose Direct Write (infer=false) as the processing method.

Step Two: Write memories of different time-horizon layers and security policies via the REST API

The following curl example demonstrates how to write working memory (working), long-term multimodal evidence memory (L0 -> L1 long_term), and zero-LLM compliance memory (no_model) separately for user_zhangwei_001 and user_lina_002:

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

# 1. Write to working memory (captures the intermediate troubleshooting state of ticket TK-20261022-001, fast decay 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. Write L0 multimodal evidence and asynchronously extract L1 long-term memory (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. Write a strict compliance record with handlingPolicy=no_model (zero LLM contact, zero vectorization; infer=false is required)
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 .

Step Three: Principle and practice of progressive layered recall (Progressive Recall: L3 -> L2 -> L1 -> L0)

When an agent faces a complex question, stuffing hundreds of L1 atomic facts into the context at once wastes tokens and easily loses focus. Agentbase Memory provides a retrieval.strategy = "progressive" (progressive layered recall) mechanism in POST /v1/memory/memories/search:

1. Execution mechanism and security boundaries of progressive layered recall

Stage / parameterField name and value rangeDefault / budgetArchitectural behavior and Fail-Closed security guarantees
Retrieval strategyretrieval.strategy"flat" (set to "progressive" to enable)When enabled, assembles layered context results top-down along the cognitive pyramid (L3 Overview -> L2 Context -> L1 Fact -> L0 Source).
Starting entry layerretrieval.entryLevel"auto" (options: "overview" / "context" / "fact")In auto mode, preferentially matches activated (user-active / agent-active) L3 Overview and L2 Topic/Episode/State with complete sources; if no high-level aggregation is currently activated or the request carries precise metadata/sessionId filters only supported at L1, it smoothly degrades to retrieval from L1 Fact.
Maximum drill-down depthretrieval.maxDepth1 ~ 3 (default 2)Controls the cognitive span automatically expanded downward in a single retrieval (e.g., from L3 Overview expanding to associated L2 Topic and core L1 Fact).
Token budget controlretrieval.tokenBudgetPositive integer (e.g., 1200)Strictly trims the total token count of returned contexts by layer priority, ensuring the result can be safely injected directly into the agent's System Prompt.
Retrieval time budgetretrieval.deadlineMsMax 450 msControls the internal time budget for progressive retrieval; this value is not an end-to-end latency SLA. Authorization, dependency, or other failures can still cause a request to fail, so partial results are not guaranteed.
Signed drill-down tokenexpansionTokenValidity 2 minutes (120s)Each returned L3 / L2 node with further expandable child layers (canExpand: true) carries an HMAC-signed expansionToken. When the client initiates a secondary drill-down, it passes in this token, and the server re-verifies in real time the project, caller principal, target userId, groupId membership, liveness of the underlying L1/L0 sources, and policy version; if any underlying memory has since been deleted or its permission revoked, the token is immediately rejected following Fail-closed.

2. Using agentbase-node-sdk@2.10.0 to perform progressive recall and secondary drill-down

// Use the official server 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. First-hop progressive hierarchical retrieval: prioritize fetching the L3 Overview and L2 Topic/Episode/State context
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,       // e.g. 'L3', 'L2', 'L1'
    kind: item.kind,         // e.g. 'memory_overview', 'memory_topic', 'memory_state', 'fact'
    canExpand: item.canExpand
})));

// 2. Use the 2-minute signed expansionToken as needed to drill down into the underlying L1 facts and L0 evidence
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 (Frequently Asked Questions and Troubleshooting)

1. Why does the create call return 400 Bad Request after setting memory to handlingPolicy: "no_model"?

2. Under what conditions is working (working memory) automatically promoted to short_term or long_term? Why does freshly written memory not immediately decay or get promoted?

3. When using expansionToken to drill down and expand L2/L3 contexts, why does it return a token invalid or expansion denied error?

4. What is the fundamental difference between strict_private and private scopes? Why do neither support sessionId historical session context backfill?