Docs
Contents

Memory Management (Creating, Retrieving, and Deleting Memories)

Feature overview and core scenarios

Memory Management (Memories) is the core data-plane operations center of Agentbase Memory (v2.10.0), responsible for single and batch memory writes, multimodal document/image parsing and ingestion, session historical context inference, five-way hybrid retrieval (Hybrid / Vector / Sparse / Keyword / Graph), unified retrieval with a Token budget (Recall), data import/export, and compliant forgetting and deletion.

In the 企业智能客服与知识中台 (enterprise-ai-hub-210) project of Agentbase 企业智能中台 (69c6d1aa00062e6bb60), the intelligent customer service system serves enterprise customers at different tiers through memory management capabilities:


Core Concepts and Architecture

Memory's write and retrieval pipelines adopt a dual-engine architecture of "synchronous deterministic direct write + asynchronous model inference pipeline" and "multi-way index projection + reranking fusion".

Memory Management (Creating, Retrieving, and Deleting Memories): 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

Core Concepts and Governance Attributes Table

Attribute dimensionParameter fieldEnumerated valuesDetailed semantics and security governance rules
Visibility scopescopeprivate, strict_private, user, group, project- strict_private / private: strictly private memory, sessionId historical session context backfill is disabled, preventing implicit cross-turn association;
- user: attributed to a specific userId (e.g., user_zhangwei_001), the most commonly used personal long-term memory scope;
- group: attributed to a specific business group, groupId must be passed simultaneously, and the caller's group membership is verified at retrieval time;
- project: project-level shared memory, visible to authorized principals within the project.
Sensitivity levelsensitivitynormal (default), confidential, restrictedMarks the business sensitivity level of memory data. Note: passing secret will be rejected outright by the server (Fail-closed); never write keys, passwords, or unmasked private data as memories.
Model processing policyhandlingPolicystandard (default), no_embedding, no_model- standard: allows Chat model inference and Embedding vectorization;
- no_embedding: allows model text processing and keyword retrieval, but no vector projection is generated;
- no_model: any LLM access to this data is strictly forbidden; requires explicitly setting infer=false, and rejects multimodal media parsing.
Record kindrecordKindfact, conversation, actionDistinguishes distilled objective facts (fact), raw conversation fragments (conversation), and agent tool execution actions (action), each subject to different retention-day policies under the retention namespace.
Memory typememoryTypepreference, fact, long_term, short_term, working, conversation, action or a custom stringBusiness classification tag. Specified by the caller during infer=false direct write; automatically classified and generated by the create-memory Pipeline during infer=true workflow processing.
Retrieval modesearchModehybrid (default), vector, sparse, keyword, graph- hybrid: combines dense vectors, sparse vectors, and full-text indexes with RRF fusion;
- vector: pure dense semantic vector retrieval;
- sparse: high-dimensional term-weight retrieval based on DashScope sparse vectors;
- keyword: full-text retrieval (short words of 1–2 characters such as "table lock" automatically trigger a parameterized exact substring fallback);
- graph: performs graph traversal retrieval of up to 2 hops over "entity–relation–entity" directed edges extracted by the model.

Feature Entrypoints and Permission Matrix

Operation Entries and Role Permission Matrix

The Console entry is located at: Project enterprise-ai-hub-210 → Memory → Memory tab.

Operation scenarioConsole operation entryREST API endpointRequired API Key scopeAssociated modules and dependencies
Create a single/conversational memoryAdd Memory buttonPOST /v1/memory/memoriesmemories.write (multimodal additionally requires files.read)Related to the create-memory Pipeline in Configuration Center and Storage
Query asynchronous write tasksSubmission receipt popup auto-pollingGET /v1/memory/jobs/{jobId}memories.write or memories.readRelated to Memory Audit and Tracing
Listing and source traceabilityMemory list QueryGET /v1/memory/memories, GET /v1/memory/memories/{memoryId}/sourcesmemories.readProvides underlying evidence for User Profile and Context Governance
Multi-way retrieval and progressive recallSearch box + retrieval mode dropdownPOST /v1/memory/memories/search, POST /v1/memory/memories/recallmemories.readProvides real-time context injection for the Agent Workbench
Update and single/batch deleteDelete button at the end of memory list rowsPATCH /v1/memory/memories/{memoryId}, DELETE /v1/memory/memories/{memoryId}, DELETE /v1/memory/memoriesmemories.write (update) / memories.delete (delete)Triggers the background Compactor to clean up vector and graph projections
Batch write and import/exportAPI / SDK batch entryPOST /v1/memory/memories/batch, /imports, /exportsmemories.write / memories.exportDepends on the internal Artifact Broker and object storage

Feature Details and Operation Guide

1. Writing deterministic facts directly in the Console (infer=false)

When the business application has already clearly organized user preferences or system environment facts and no LLM rewriting is needed, use the direct write mode (synchronous persistence):

  1. Go to the Memory → Memory tab of project enterprise-ai-hub-210, and click Add Memory in the upper-right corner.

  2. Fill in the parameters in the popup according to the table below:

    • User ID (userId): enter user_zhangwei_001 (or the demo account demo-user).

    • Visibility scope (scope): select user.

    • Processing method: select Direct write (corresponding to API infer: false, async: false).

    • Memory type (memoryType): enter or select preference.

    • Record kind (recordKind): select Fact (fact).

    • Content (content): enter non-empty text (UTF-8 encoded, up to 20,000 bytes), e.g., 用户张伟(核心账务架构师)偏好直接查看 OceanBase V4 分布式死锁排查 SQL 与向量索引 HNSW 参数说明。.

    • Metadata (metadata): enter a valid JSON object, e.g., {"ticketId": "TK-20261022-001", "env": "production"}.

Create memory popup (reusing a registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

  1. Click Save; the page shows an execution receipt with status completed, processing mode simple, the generated memoryId, and action ADD.

Memory write result details (reusing a registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

2. Asynchronous intelligent memory extraction from multi-turn conversations (infer=true and session history backfill)

In real customer service conversations, key user information is often spread across multiple turns of Q&A (e.g., the agent gives options A/B in one turn, and the user replies only "I choose A" in the next). In such cases, use workflow processing (infer=true):

  1. In the Add Memory popup, switch Processing method to Workflow processing.

  2. Select Use default Pipeline or a published create-memory pipeline (draft-state pipelines cannot be used for production writes). At this point you do not need to fill in memoryType manually; it is determined automatically by the fact-extraction node inside the Pipeline (calling qwen-plus).

  3. Enter the conversation content and submit. Intelligent extraction defaults to asynchronous execution (HTTP 202), returning status: "queued", jobId, and sourceId.

  4. Session context inference (sessionId history backfill):

    • When calling via API/SDK and simultaneously satisfying infer=true with non-empty sessionId (up to 128 characters) and scope being user / group / project, Memory automatically reads back the most recent 12 historical turns of the same session (total budget of about 4,096 tokens) as inference background, within the same project, same user, same agentId, and governance boundary.

    • Historical messages only help the model understand references in the current turn (e.g., restoring "I choose A" to "the user chooses to enable the OceanBase vector index asynchronous rebuild strategy"), and never tamper with the current Source original text.

    • After the background task completes fact extraction, it retrieves existing similar memories and the model performs conflict determination:

      • ADD: create an independent new fact;

      • UPDATE: merge into or correct the existing fact (automatically incrementing the target memory's version);

      • DELETE: when the new fact explicitly overturns the old fact, automatically forget the conflicting old memory;

      • NONE: judged as small talk or fully duplicated information; skip the write (in this case the task completes successfully but the number of created entries is 0, which is normal).

3. Multimodal Image and PDF Memory Ingestion and Retrieval

In technical support tickets, customers often upload error screenshots or architecture PDFs. The application can first upload the file to the same project's Storage bucket (e.g., agent_multimedia_bucket), then pass the file reference {bucketId, fileId} to the Memory API:

# Submit an architecture diagram or PDF manual from Storage for asynchronous visual parsing and ingestion
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: multimodal-ticket-001" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_zhangwei_001",
    "scope": "user",
    "memoryType": "long_term",
    "recordKind": "fact",
    "media": {
      "bucketId": "agent_multimedia_bucket",
      "fileId": "ob_cluster_topology_2026.pdf"
    },
    "content": "客户核心账务 OceanBase 集群三中心拓扑与 OBProxy 路由表配置文档",
    "infer": true
  }' | jq .

Multimodal input technical boundaries and constraints:

4. Multi-route hybrid search, progressive retrieval, and unified recall (Recall)

  1. At the top of the Console Memory → Memory tab, enter the target user ID (e.g., user_zhangwei_001 or demo-user).

  2. Enter a natural language question in the search box (e.g., 用户负责哪个集群,排障偏好是什么?), select Hybrid Search (hybrid), Vector (vector), Sparse Vector (sparse), Keyword (keyword), or Graph Search (graph) in the retrieval mode dropdown, and click Query.

Memory retrieval list (reusing the registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

  1. Use agentbase-node-sdk@2.10.0 in the business service backend to perform progressive retrieval and unified recall: When an agent needs to assemble the user's regular memory, user profile, experiences (Experience), and skills (Skill) simultaneously before a single inference run, while strictly controlling the number of tokens injected into the Prompt, the unified recall interface POST /v1/memory/memories/recall or progressive retrieval strategy is recommended:

// 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. Progressive multi-way retrieval (L3 Overview -> L2 Context -> L1 Fact)
const searchResult = await memory.searchMemories({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: 'OceanBase 分布式事务锁冲突与向量索引排障偏好',
    searchMode: 'hybrid',
    limit: 10,
    retrieval: {
        strategy: 'progressive',
        entryLevel: 'auto',
        maxDepth: 2,
        tokenBudget: 1200,
        deadlineMs: 450
    }
});

// 2. Unified retrieval with a Token budget (integrating memory, profile, experience, and skills)
const recallBundle = await memory.recall({
    userId: 'user_zhangwei_001',
    agentId: 'enterprise-support-agent',
    query: '如何处理 TK-20261022-001 工单中的向量索引重建超时问题?',
    tokenBudget: 2000
});

5. Optimistic-lock updates, single/batch deletion, and anti-relearning protection


FAQ (Frequently Asked Questions and Troubleshooting)

1. Why does the task status show succeeded after submitting “process per workflow (infer=true)”, but the new record cannot be found in the memory list?

2. A memory that was just written successfully is visible in the list, but why can't it be found using vector search (vector) or graph search (graph)?

3. How to troubleshoot when a multimodal image/PDF memory write returns 400 or the asynchronous task fails (failed)?