Docs
Contents

Memory Overview and Quick Start

Feature overview and core scenarios

AI Memory is Agentbase's (v2.10.0) project-level enterprise long-term memory capability. In multi-turn conversations, intelligent customer service, technical support tickets, and complex task orchestration scenarios, large language models are constrained by the single-inference context window and cannot persistently remember a user's personal preferences, historical facts, architecture environment configurations, or troubleshooting operational experience across sessions. Agentbase Memory uses a unified control plane and high-performance data plane to help applications extract, deduplicate, resolve conflicts in, and persist memories from conversations and business events, and precisely retrieve them in subsequent interactions by semantics, sparse terms, keywords, or entity relationship knowledge graphs.

In the example project 企业智能客服与知识中台 (project ID: enterprise-ai-hub-210) under Agentbase 企业智能中台 (organization ID: 69c6d1aa00062e6bb60), Memory runs on top of the OceanBase Shared V2 storage mode, integrating the DashScope model provider (dashscope-prod)'s dense embedding model text-embedding-v3 (1024 dimensions), sparse embedding routes, chat model qwen-plus, rerank model qwen3.7-text-rerank, and multimodal vision model qwen-vl-max. The customer service agent can not only remember the technology stack preferences and cluster topology facts of VIP architect user_zhangwei_001 and front-line engineer user_lina_002, but also automatically summarize user profiles, build layered context through background Dreaming, and distill troubleshooting trajectories into reusable Experience and Skills.

Memory provides the following core capability boundaries:


Core Concepts and Architecture

Agentbase adopts an architecture in which a single logical Memory service serves multiple tenants and multiple projects. External clients or server-side SDKs make calls uniformly through the Agentbase /v1/memory/* Facade; the platform completes project authentication, API Key scope validation, lifecycle state checks, and dynamic data source routing, then issues short-lived trusted contexts for execution by the Memory data plane.

Memory Overview and Quick Start: 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

Core conceptIdentifier and exampleArchitectural responsibilities and key technical constraints
Project Memory (project memory instance)Project enterprise-ai-hub-210The bearer unit for project-level quotas, model routes, database route versions (databaseRouteVersion), and lifecycle version numbers (revision). Must run in a project with the OceanBase Shared V2 table mode.
Memory (memory record)mem_8f92a1c4...A single retrievable memory unit, containing the body (content), memory type (memoryType), record kind (recordKind: fact fact, conversation conversation, action action), visibility scope (scope), and optimistic lock version number (version).
Source (Immutable Source)src_7b31e0d2...The original conversation, text, or multimodal file reference that triggers memory writes, profile updates, or knowledge distillation. Used for provenance explanations, conversation history hydration, and idempotent checkpoint recovery.
Profile (User Profile)User user_zhangwei_001A panoramic description distilled from valid memory sources of the same user, supporting both the body view (content) and the topic view (topics), with incremental merge and full replacement.
Context & Dreaming (Layered Context)L2 Topic / Episode / State, L3 OverviewThe background Dreaming task asynchronously scans changed memories and aggregates them into L2 topics/events/states and an L3 global overview, supporting Progressive Retrieval and manual confirmation.
Experience & Skilldst_3e5b09f456c5d5c332507ec1dbe3eb6dReusable troubleshooting experience (Experience) and standardized operating procedures (Skill) distilled from customer support troubleshooting conversations or tool call traces, supporting shadow -> active state transitions and secondary confirmation.
Pipeline (Business Processing Pipeline)New memory / profile / experience & skill / forgettingA versioned pipeline configuration that fixes the order of processing steps, supporting node-level Prompt and model routing overrides, draft saving, Dry-run sample testing, and one-click publishing.

Project Memory Lifecycle State Machine

The project Memory manages state transitions through the control plane interface /v1/projects/{projectId}/memory and strictly follows optimistic concurrency control (expectedRevision):

State valueConsole display nameState description and allowed operations
null (Not Enabled)Memory not enabledThe project has not yet initialized Memory; the API returns HTTP 200 and project: null. A project administrator can click Enable Memory to launch the configuration wizard.
initializingProvisioningThe enable request has been submitted (HTTP 202), and a background Worker is idempotently creating the _<projectSequence> exclusive table group in the Shared V2 database owned by the project and validating the vector index. The page polls automatically every 1.5 seconds; if it ultimately fails, the lastError error code and stage are displayed, and you can re-enable after fixing the model configuration.
activeActiveWhen project.status=active and project.schema.status=ready, serviceHealth.status=healthy, the data plane is fully ready for reads and writes, and the Console opens all 8 feature tabs.
disabledDisabled / SuspendedThe project enters this state after an administrator performs a suspend/disable (passing enabled: false via PATCH). Data plane read/write access stops immediately, but the underlying physical table data and configuration are fully retained. You can restore to active by re-invoking the enable workflow (POST), or perform a permanent deletion.
deletingDeletingThe project enters this state after an administrator confirms permanent deletion (DELETE). A deletion fence is established in the background and the project Memory's physical table group and artifacts are cleaned up, while project configuration drafts are retained for future re-enabling. Deletion is irreversible.

Feature Entrypoints and Permission Matrix

Console Entry Point and 8 Feature Tabs

Log in to the Agentbase Console, go to project 企业智能客服与知识中台 (enterprise-ai-hub-210) under organization Agentbase 企业智能中台 (69c6d1aa00062e6bb60), and click Memory in the left navigation bar (route: /console/project-{region}-enterprise-ai-hub-210/memory). When the project Memory is in the active state, the top of the Console displays 3 health summary cards (lifecycle state Revision, table schema state Route version, service health state Fixed service endpoint) along with 8 core tabs:

Tab nameInternal view identifierCore functionalityRequired permission / ScopeDetailed documentation entry
MemorymemoriesWrite facts directly, extract memories asynchronously from conversations, retrieve memories in five modes, and delete individual entries.memories.read / memories.write / memories.deleteMemory management, Multi-layer memory division
ProfileprofilesQuery user profiles (content / topics), trigger incremental updates, regenerate or delete profiles based on evidence.memories.read / memories.write / memories.deleteUser profile
Experience & SkillevolutionSubmit execution evidence distillation by user/agent/project scope; view, edit, approve, or roll back experience and skill versions.memories.read / memories.write / projects.write (approval)Experience & skill knowledge distillation, Experience & skill evolution
ModelsmodelsCentrally view and maintain the default model routes (Embedding, Sparse, Chat, Rerank, Vision) for the provider namespace.projects.read / projects.writeMemory model routing
ContextgovernanceView Dreaming watermarks and task statuses, filter layered context by L2/L3, and perform confirmation, rebuilding, and version rollback.memories.read / memories.write / projects.writeContext governance, Multi-layer memory division
ConfigurationconfigurationManage the four business Pipeline types (new memory, profile, experience & skill, forgetting) and 5 system configuration namespaces.projects.read / projects.writeMemory configuration center, Memory forgetting mechanism
AuditauditVerify execution receipts and latency of write, retrieval, governance, and other requests by request ID, task ID, user ID, or operation name.memories.readMemory audit logs
Tracetraces (jump link)Jump to the Agent Operations → Traces page with one click, automatically carrying the ?tag=capability%3Amemory filter condition.observability.traces.readMemory trace tracking, Trace tracking

Cross-Module Dependencies and Mutual Exclusion Rules

  1. Hard requirement on storage table schema (Shared V2): Memory strongly depends on the dynamic project table groups and vector index capabilities of the OceanBase Shared V2 table schema. Existing projects in Collection, Shared V1, and JsonTable schemas do not support enabling Memory. If you see a table-schema-unsupported warning in the Console, go to Project Settings to check the table schema or create a new Shared V2 project.

  2. Dependency on model management (LLM Gateway): Before enabling Memory, you must first configure a model provider (e.g., dashscope-prod) in the project's LLM Gateway. After Memory initialization completes, the dense vector provider (embeddingProviderRef), model name (embeddingModel), and vector dimension (embeddingDims) in the basic configuration will be permanently locked to prevent mixing vector spaces within the same physical table.

  3. Mutual exclusion rules between Memory and PowerContext in the Agent Runtime: In the project's Agent Workbench (configuration interface /v1/agent-runtime/project/config), long-term memory offers two options: Standalone Memory (memory_enabled) and managed PowerContext (powercontext_enabled). The two are strictly mutually exclusive and cannot be enabled at the same time (but both may be disabled at the same time):

    • When Memory is enabled in the Agent Workbench, the system atomically switches powercontext_enabled to false upon saving the configuration;

    • When PowerContext is enabled, the system automatically atomically switches memory_enabled to false;

    • If an API request passes both memory_enabled: true and powercontext_enabled: true at the same time, the server directly rejects it and returns the 400 general_argument_invalid parameter error, protecting the existing configuration from corruption.

    • Knowledge Search (e.g., binding kb_enterprise_support and the lexicon lex_enterprise_synonyms) is independent of the two memory switches above and can be enabled alongside them.


Feature Details and Operation Guide

The following uses the example project 企业智能客服与知识中台 (enterprise-ai-hub-210) to fully demonstrate the entire workflow from confirming the project environment, configuring DashScope model routing, and enabling Memory, to writing the first enterprise-grade user memory.

Step One: Create or Confirm the Shared V2 Project

  1. Log in to the Agentbase Console and go to organization Agentbase 企业智能中台 (69c6d1aa00062e6bb60); if this is your first time, first refer to Organization and account management to complete organization creation.

  2. Click Create Project in the upper-right corner, enter the project name 企业智能客服与知识中台, set a custom project ID of enterprise-ai-hub-210, select the default Shared V2 database resource pool, and submit.

  3. After entering the project, you can confirm in the left navigation bar under Settings that the current project's storage schema is Shared V2.

Create project (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.

Step Two: Prepare the DashScope Models in the LLM Gateway

  1. Open Models (LLM Gateway) in the left navigation bar and add the DashScope provider dashscope-prod (compatible endpoint https://dashscope.aliyuncs.com/compatible-mode/v1, fill in the credential as <DASHSCOPE_API_KEY>).

  2. Register and enable the following five core model capabilities for use by each Memory stage:

    • Dense embedding model (Embedding): text-embedding-v3 (vector dimension 1024)

    • Sparse embedding route (Sparse Embedding): DashScope Sparse route (used for exact term weight matching in hybrid retrieval)

    • Chat generation model (Chat LLM): qwen-plus (primary route) and qwen-turbo (backup)

    • Rerank model (Rerank): qwen3.7-text-rerank

    • Vision multimodal model (Vision LLM): qwen-vl-max (used to parse architecture diagrams and PDF manuals in Storage)

Step Three: Enable Project Memory via the Wizard

  1. Click Memory in the project's left navigation bar. On first entry, the page is in the not-enabled state, showing capability introductions and the Enable Memory button.

Memory not-enabled state (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. Click Enable Memory to open the model routing and quota configuration dialog, and complete the configuration according to the following parameter table:

Configuration groupField nameBenchmark project configuration valueConstraints and notes
Vector index (required)Embedding provider (embeddingProviderRef)project:dashscope-prodLocked after initialization; cannot be changed
Vector index (required)Embedding model (embeddingModel)text-embedding-v3Locked after initialization; cannot be changed
Vector index (required)Vector dimension (embeddingDims)1024Must strictly match the model's actual output dimension; locked after initialization
Sparse vectors (enabled by default)Enable sparse vectors (sparseEmbeddingEnabled)开启 (true)Enabled by default in the new provisioning wizard, bound to the DashScope Sparse route; turn it off manually if not needed
Intelligent processing (required)Chat provider and model (llmProviderRef / chatModel)project:dashscope-prod / qwen-plusUsed for infer=true fact extraction, conflict resolution, profile generation, and experience distillation
Rerank (enabled by default)Enable rerank and model (rerankEnabled / rerankModel)开启 (true) / qwen3.7-text-rerankRerank is enabled by default in the new project wizard; if no Rerank model is prepared yet, turn off the switch first
Quota limits (optional)Maximum number of memories (maxMemories)00 means no additional limit; the instance runs according to its physical capacity
Quota limits (optional)Maximum storage capacity (storageBytes)00 means no additional limit
Quota limits (optional)Requests per minute limit (requestsPerMinute)00 means no additional project-level rate limiting is set

Memory model routing configuration dialog (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. Click Next to open the pre-enabling confirmation dialog, and carefully verify the Embedding provider, model name, and dimensions (confirm they are correct before submitting, to avoid needing to rebuild the instance due to dimension mismatch after initialization).

Memory pre-enabling confirmation dialog (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. Click Confirm Enable. The status changes to initializing; after the background table creation completes in about 3–5 seconds, the page automatically refreshes to the active status, and all three health cards at the top display green ready badges (Active, Ready, Healthy).

Memory ready workbench (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.

Step Four: Verify the lifecycle via API / SDK and write the first memory

Create a server-side API Key in Project Overview → Integration → API keys (granting memories.read, memories.write, memories.delete, memories.export), then integrate via the REST API or agentbase-node-sdk@2.10.0 in your business backend:

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

# 1. Verify Memory data plane health and statistics
curl -fsS "${APPBASE_ENDPOINT}/memory/memories/stats" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" | jq .

# 2. Write the first architecture preference memory for VIP architect user_zhangwei_001
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: init-mem-zhangwei-001" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_zhangwei_001",
    "scope": "user",
    "memoryType": "preference",
    "recordKind": "fact",
    "content": "张伟架构师负责核心账务集群,偏好直接给出 OceanBase 分布式事务与向量索引 SQL 排障命令,不需要基础概念解释。",
    "metadata": {
      "department": "core-banking-arch",
      "slaTier": "P0-VIP"
    },
    "infer": false
  }' | jq .

Returns status: "completed" and the generated memoryId, indicating that project Memory has completed end-to-end production readiness verification.


FAQ (Frequently Asked Questions and Troubleshooting)

1. Why does entering the Memory page in the Console prompt “the current project's table mode does not support enabling Memory”?

2. What to do if Memory is stuck in the initializing status or shows lastError initialization failure?

3. After enabling Memory in the Agent Workbench, why does the previously enabled PowerContext turn off automatically?

4. What is the difference between temporarily disabling (Disable) and permanently deleting (Delete) project Memory?