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:
Project-level independent isolation and lifecycle management: Supports one-click enabling per project, status inspection, quota governance, pausing/disabling, and permanent cleanup, using project-specific
_<projectSequence>physical table groups at the underlying level to isolate business data.Dual-mode memory writing and multimodal ingestion: Supports deterministic direct writing (
infer=false) and Pipeline-based async intelligent inference (infer=true), and supports parsing PNG, JPEG, WebP images and PDF documents in the same project's Storage (e.g.,agent_multimedia_bucket).Multi-path hybrid retrieval and unified recall: Fuses OceanBase dense embeddings, DashScope sparse embeddings, full-text keywords, and entity relationship knowledge graphs, providing unified recall with token budget control.
Full-lifecycle self-evolution and observability: Covers user Profiles, layered context governance (Contexts & Dreaming), Experience and Skill distillation (Evolution), custom processing Pipelines, request Audit, and end-to-end Trace.
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.
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 concept | Identifier and example | Architectural responsibilities and key technical constraints |
|---|---|---|
| Project Memory (project memory instance) | Project enterprise-ai-hub-210 | The 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_001 | A 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 Overview | The 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 & Skill | dst_3e5b09f456c5d5c332507ec1dbe3eb6d | Reusable 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 / forgetting | A 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 value | Console display name | State description and allowed operations |
|---|---|---|
null (Not Enabled) | Memory not enabled | The 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. |
initializing | Provisioning | The 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. |
active | Active | When 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. |
disabled | Disabled / Suspended | The 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. |
deleting | Deleting | The 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 name | Internal view identifier | Core functionality | Required permission / Scope | Detailed documentation entry |
|---|---|---|---|---|
| Memory | memories | Write facts directly, extract memories asynchronously from conversations, retrieve memories in five modes, and delete individual entries. | memories.read / memories.write / memories.delete | Memory management, Multi-layer memory division |
| Profile | profiles | Query user profiles (content / topics), trigger incremental updates, regenerate or delete profiles based on evidence. | memories.read / memories.write / memories.delete | User profile |
| Experience & Skill | evolution | Submit 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 |
| Models | models | Centrally view and maintain the default model routes (Embedding, Sparse, Chat, Rerank, Vision) for the provider namespace. | projects.read / projects.write | Memory model routing |
| Context | governance | View Dreaming watermarks and task statuses, filter layered context by L2/L3, and perform confirmation, rebuilding, and version rollback. | memories.read / memories.write / projects.write | Context governance, Multi-layer memory division |
| Configuration | configuration | Manage the four business Pipeline types (new memory, profile, experience & skill, forgetting) and 5 system configuration namespaces. | projects.read / projects.write | Memory configuration center, Memory forgetting mechanism |
| Audit | audit | Verify execution receipts and latency of write, retrieval, governance, and other requests by request ID, task ID, user ID, or operation name. | memories.read | Memory audit logs |
| Trace | traces (jump link) | Jump to the Agent Operations → Traces page with one click, automatically carrying the ?tag=capability%3Amemory filter condition. | observability.traces.read | Memory trace tracking, Trace tracking |
Cross-Module Dependencies and Mutual Exclusion Rules
Hard requirement on storage table schema (
Shared V2): Memory strongly depends on the dynamic project table groups and vector index capabilities of the OceanBaseShared V2table schema. Existing projects inCollection,Shared V1, andJsonTableschemas 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 newShared V2project.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.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_enabledtofalseupon saving the configuration;When PowerContext is enabled, the system automatically atomically switches
memory_enabledtofalse;If an API request passes both
memory_enabled: trueandpowercontext_enabled: trueat the same time, the server directly rejects it and returns the400 general_argument_invalidparameter error, protecting the existing configuration from corruption.Knowledge Search (e.g., binding
kb_enterprise_supportand the lexiconlex_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
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.Click Create Project in the upper-right corner, enter the project name
企业智能客服与知识中台, set a custom project ID ofenterprise-ai-hub-210, select the defaultShared V2database resource pool, and submit.After entering the project, you can confirm in the left navigation bar under Settings that the current project's storage schema is
Shared V2.
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
Open Models (LLM Gateway) in the left navigation bar and add the DashScope provider
dashscope-prod(compatible endpointhttps://dashscope.aliyuncs.com/compatible-mode/v1, fill in the credential as<DASHSCOPE_API_KEY>).Register and enable the following five core model capabilities for use by each Memory stage:
Dense embedding model (Embedding):
text-embedding-v3(vector dimension1024)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) andqwen-turbo(backup)Rerank model (Rerank):
qwen3.7-text-rerankVision 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
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.
Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.
Click Enable Memory to open the model routing and quota configuration dialog, and complete the configuration according to the following parameter table:
| Configuration group | Field name | Benchmark project configuration value | Constraints and notes |
|---|---|---|---|
| Vector index (required) | Embedding provider (embeddingProviderRef) | project:dashscope-prod | Locked after initialization; cannot be changed |
| Vector index (required) | Embedding model (embeddingModel) | text-embedding-v3 | Locked after initialization; cannot be changed |
| Vector index (required) | Vector dimension (embeddingDims) | 1024 | Must 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-plus | Used 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-rerank | Rerank 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) | 0 | 0 means no additional limit; the instance runs according to its physical capacity |
| Quota limits (optional) | Maximum storage capacity (storageBytes) | 0 | 0 means no additional limit |
| Quota limits (optional) | Requests per minute limit (requestsPerMinute) | 0 | 0 means no additional project-level rate limiting is set |
Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.
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).
Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.
Click Confirm Enable. The status changes to
initializing; after the background table creation completes in about 3–5 seconds, the page automatically refreshes to theactivestatus, and all three health cards at the top display green ready badges (Active,Ready,Healthy).
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”?
Cause analysis: Memory at the underlying layer needs to create 9 relational and vector tables containing vector indexes, full-text indexes, and transaction fences in the project's independent table namespace; currently only the OceanBase
Shared V2storage mode is supported. If the project was created inCollection,Shared V1, orJsonTablemode, the control plane guard will intercept the enable request.Resolution: Go to Project Settings to view the current project's
sourceTableMode. If it is not anShared V2project, we recommend creating a new project based on theShared V2resource pool (e.g.,enterprise-ai-hub-210), or contact the platform administrator to evaluate table mode conversion.
2. What to do if Memory is stuck in the initializing status or shows lastError initialization failure?
Cause analysis: The initialization process verifies model route connectivity (e.g., sending a dimension probing request to
text-embedding-v3) and creates table structures in the database. If thedashscope-prodAPI Key is invalid, the providedembeddingDimsdoes not match (e.g., mistakenly entered as1536when the model actually returns1024), or the database connection pool is momentarily busy, initialization will fail andlastError.codeandlastError.stagewill be recorded.Resolution: Do not delete or recreate the entire project. First, based on the
stageandmessagein the red error banner on the page, go to Model Gateway to correct the Provider credentials or dimension parameters, then return to the Memory page and click Re-enable (Retry Enable) in the upper-right corner; the system will incrementrevisionand idempotently complete the remaining initialization steps.
3. After enabling Memory in the Agent Workbench, why does the previously enabled PowerContext turn off automatically?
Cause analysis: The Agent Runtime's long-term memory provider adopts a single-active mutually exclusive design (
memory_enabledandpowercontext_enabledare mutually exclusive), to avoid the same Agent Run simultaneously writing duplicated content and retrieving conflicting context into two long-term memory engines.Resolution: This is expected behavior by design. If your business uses Agentbase native Memory (including the memory, profiles, Dreaming context, and experience distillation described in this document), keep
memory_enabled: trueandpowercontext_enabled: false.
4. What is the difference between temporarily disabling (Disable) and permanently deleting (Delete) project Memory?
Cause analysis: Some operations personnel worry that the disable operation will lose accumulated customer memories and profiles.
Resolution: Disable only closes the
/v1/memory/*data plane access entry (status changes todisabled); all physical tables, vector indexes, profiles, and knowledge versions are safely retained, and the service can be re-enabled at any time to recover. In contrast, Delete (permanent deletion) (status changes todeleting) asynchronously destroys all Memory physical table groups and generated artifacts under the project, and is irreversible. Before performing permanent deletion, be sure to back up core data via the export API first.





