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 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 example 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

1. Memory retention tiers

memoryType can describe working memory (working), short-term memory (short_term), or long-term memory (long_term). Each type can have different decay parameters; access and review may affect later state, while actual promotion and archival depend on configuration and conditions. Other types are supported, so not every memory belongs to these three.

The 2.12.0 service fallback decay multipliers are 1, 7, and 60, respectively; the default protection period is 168 hours. Project configuration may override these values. Memory forgetting and data retention explains the defaults, preview batch limit, and deletion boundaries.

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)
Produced through direct writes (infer=false) or add-memory, profile, and distillation pipelines; models depend on project configuration.- 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 (project configuration)Allowed (dense vectors use the project instance configuration; sparse vectors depend on configuration)Allowed (requires a configured model)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_modelDisallows model processing within MemoryNo vector projectionNo multimodal media parsingExplicitly set infer=false and omit media on write. Authorized applications can still retrieve records and send them to other models; downstream use and compliance remain the application’s responsibility. Encryption depends on deployment configuration.

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.12.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.readUses activated contexts or facts depending on the entry and search mode; vector search requires a configured embedding model
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 → GovernanceGET/POST /v1/memory/memories/contexts*memory.listContexts / createContextRun / confirmContextmemories.read / memories.write (confirmation requires manage permission)Depends on evolution.dreaming and the model configured for the project
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 APIA Console user session with administrative access and the permissions required by each operationAssociated 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; vector projections use the project instance model and dimension; sparse vectors depend on configuration;

    • 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 (restrict model processing inside Memory): Set handlingPolicy: "no_model" and choose Direct Write (infer=false); the caller remains responsible for downstream use of retrieved data.

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 memory with internal model processing restricted (no_model) separately for user_zhangwei_001 and user_lina_002:

Set APPBASE_ENDPOINT to the target API endpoint (including /v1), and confirm the project and credentials belong to that environment. Run each operation separately as needed. Set a unique MEMORY_IDEMPOTENCY_KEY for every new write; reuse the original key and identical request content only when retrying the same write.

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

(
  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 .
)

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.strategyOmit for ordinary search; set to "progressive" for progressive searchWhen 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" / "evidence")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.maxDepth0 ~ 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.tokenBudget64 ~ 8192 (default 1200)Limits returned items using an estimated token budget; the estimate is not an exact token count for the target model. The caller must check the model's context window and establish trust boundaries for retrieved content rather than treating untrusted content as system instructions.
Retrieval time budgetretrieval.deadlineMs50 ~ 450 ms (default 450 ms)Controls 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.12.0 to perform progressive recall and secondary drill-down

Before running, replace <APPBASE_ENDPOINT_WITH_V1> and <APPBASE_PROJECT_ID> with the confirmed target API endpoint and project ID. Until replaced, the SDK rejects the invalid endpoint before making a request.

// Use the official server 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. 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.progressive?.items?.map(item => ({
    id: item.id,
    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.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 (Frequently Asked Questions and Troubleshooting)

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

2. Why was a new memory not immediately archived or promoted?

A new memory may still be in its protection period. State transitions also depend on access, review, thresholds, and effective configuration. Use Memory → Configuration → Forgetting Pipeline → Run sample to inspect bounded candidate actions; the result is not a complete inventory of memories.

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?