Memory Storage is built on Tablestore and provides AI Agents with Serverless memory writing, automatic extraction, and semantic retrieval capabilities, supporting million-tenant-level data isolation and cross-session memory reuse.
What is Memory Storage
Memory Storage is built on Tablestore and provides AI Agents with Serverless memory writing, automatic extraction, and semantic retrieval capabilities. Developers write conversation messages or text into a memory store; the service preserves raw messages as short-term memory and automatically extracts retrievable long-term memory units that are persisted in Tablestore. During retrieval, the service combines semantic search and text search (with optional Rerank) to return relevant long-term memories that an Agent can recall in subsequent conversations as needed.
Compared with building memory extraction and retrieval on your own, developers can use this service without provisioning LLM calls, vector/full-text search, data isolation, or auditing capabilities. The service supports million-tenant-level data isolation and cross-session memory reuse.
For billing details of Memory Storage, see Product Billing. To quickly try Memory Storage, see Write and recall your first memory.
Memory Storage currently supports the following regions: China (Beijing), China (Shanghai), China (Hangzhou), China (Shenzhen), China (Hong Kong), and Singapore. Choose a nearby region for access.
Key Benefits
-
Serverless and Elastic
A fully managed Serverless architecture where users do not need to worry about deploying or operating underlying resources. Pay-as-you-go pricing with zero cost at zero usage. The distributed architecture scales horizontally to meet the needs of million-tenant, billion-memory scenarios.
-
Automatic Memory Extraction, No Extra Development
After conversation messages or text are written, key facts and preferences are automatically extracted to generate structured memory units. Developers do not need to write additional extraction logic or handle memory extraction and organization themselves. You can use memory-store-level custom extraction instructions (
extractInstructions) to guide extraction toward business-critical information. -
Precise Semantic Retrieval, Saving Tokens
A hybrid retrieval mode that combines vector search and full-text search is supported, using natural language as the query input to recall relevant memories. Compared with injecting the full conversation history, this saves approximately 95% of tokens, avoiding O(N²) growth and the "Lost in the Middle" performance degradation.
-
Massive Tenant Isolation
Data isolation is achieved through a four-level Scope consisting of
appId,tenantId,agentId, andrunId. Developers can organize memory data boundaries by application, tenant, Agent, and session, meeting the multi-tenant isolation requirements at the million-tenant level. -
File View Reading
Service-managed structured memory supports two reading methods: structured reading through SDK, CLI, and other interfaces, or reading by directory and file through a file view. The file view presents memory data in read-only file form. Applications still write or modify source memory through structured interfaces, preventing conflicts between file operations and structured memory.
-
File Memory
When you already have Markdown or other UTF-8 text files, or need to organize memory directories yourself, you can write files directly into a file memory store. The application controls file paths and can create, read, update, rename, and delete files, as well as query historical versions. File memory Dream can also merge, correct, and reorganize text files across Scopes, and automatically write the results to a specified output Scope.
-
Knowledge Compilation and Memory Consolidation
Wiki asynchronously builds source documents into interlinked Markdown pages for cross-session reuse. An Agent can first search the Wiki, then read hit pages by path, reusing the same Agent's persistent knowledge across different sessions. Memory consolidation (Dream) runs in the background to perform secondary refinement on ingested content, including merging, deduplication, updating, and extracting skill profiles.
Typical Application Scenarios
|
Scenario |
Description |
|
Multi-turn conversation continuity |
In long-conversation scenarios, historical messages are written into the memory store. The service preserves raw messages and extracts key facts. Subsequent conversations only recall relevant memories as needed, avoiding injecting the full history into the context. |
|
Cross-session preference retention |
Preferences, habits, and constraints expressed by the user across multiple sessions are extracted as long-term memory units. In new sessions, they are recalled through semantic search, enabling the Agent to maintain a consistent response style across different times and entry points. |
|
Multi-Agent knowledge sharing |
By using a wildcard for |
|
Agent knowledge graph |
Product descriptions, operation manuals, and project conventions are continuously maintained as Wiki sources. The service builds the materials into searchable, interlinked pages with source references. Different sessions can share the Wiki of the same Agent Scope while reading only the few pages needed for the current task. |
|
User profile accumulation |
User behaviors, attributes, and historical facts are continuously written into the memory store. The service automatically merges them into structured profile units for downstream Agents in recommendation, customer service, and marketing to recall and use directly. |
-
Memory extraction is an asynchronous process performed automatically by the system. Scenarios that require extremely high real-time write responsiveness or fully customized extraction strategies should be evaluated accordingly.
-
For purely structured data queries, use the Tablestore wide table model or a relational database.
-
For scenarios that only require context window management without persistent memory, use the LLM context window directly.
Glossary
Data in a memory store is organized into the following entities.
|
Entity |
Description |
|
MemoryStore |
The memory store, the top-level container for managing memory data |
|
Memory |
Long-term memory, retrievable information extracted from conversations or text |
|
Message |
Short-term memory, the original conversation message records written to the store |
|
Item |
A memory file with a path and version |
|
Wiki |
A collection of knowledge graph pages organized by three-segment Agent Scope |
|
Dream Task / Action |
An asynchronous consolidation task and its structured memory or file change records |
MemoryStore
A MemoryStore is the memory store, the top-level container for managing memory data. You first create a memory store, then write messages, retrieve memories, or query audit records against it. You can divide memory stores by application, environment (development, testing, production), or business line. The name can only contain letters, numbers, and underscores, with a maximum of 32 characters.
Memory
A Memory is long-term memory. After conversation messages or text are written, the service extracts information that can be persistently stored and retrieved, and generates memory units. Each unit typically contains a memory ID, text, Scope, metadata, creation time, and version management information.
Message
A Message is short-term memory, that is, the original conversation message record written to the memory store. Messages can be queried through ListMemoryStoreMessages. For the Scope rules of short-term memory, see Scope Hierarchy Management.
Item
A memory file with a path and version. In a file memory store, text files (such as Markdown) are organized by path, supporting create, read, update, delete, and historical version queries. For cross-Scope merging, correction, and reorganization in file memory Dream, see Memory Consolidation in Agentic Task.
Wiki
A collection of knowledge graph pages organized by three-segment Agent Scope, allowing the same Agent to reuse persistent knowledge across different sessions. For details, see Knowledge compilation (Wiki).
Dream Task / Action
An asynchronous consolidation task (Dream Task) for ingested content, producing structured memory or file change records (Dream Action). For details, see Memory Dream.
Scope Hierarchy Management
A Scope represents the ownership and isolation boundary of memory data. The memory service uses a four-level Scope consisting of appId, tenantId, agentId, and runId.
|
Field |
Description |
|
|
Application identifier, typically corresponding to a business application or product |
|
|
Tenant or user identifier |
|
|
Agent identifier |
|
|
Session, run, or task identifier |
The Scope hierarchy is:
appId > tenantId > agentId > runIdCore rules:
-
On write,
appIdis required. Other fields default to__default__when empty. Wildcards*are not allowed on write. -
On memory retrieval,
appIdis required and cannot be*. Other fields default to__default__when omitted; explicitly passing*indicates a wildcard. -
When querying short-term memory, all four fields are required and wildcards are not allowed.
Common Retrieval Scope Examples
|
Retrieval scope |
Scope settings |
Applicable scenario |
|
Within the current session |
|
Only want to use the current session history |
|
Cross-session |
|
The same Agent reuses user preferences across multiple sessions |
|
Cross-Agent, cross-session |
|
Multiple Agents share user memory |
Scope and Multiple Memory Stores
MemoryStore supports creating independent memory stores by application, environment, or business line. When data belongs to different users or Agents within the same application, using Scope for isolation within the same memory store is recommended for lower management cost and support for cross-Scope wildcard retrieval. When different business domains require fully independent data spaces, creating multiple memory stores is recommended.
Memory Data Management
Memory Writing
The memory service supports the following two ways to write memory:
-
Conversation message writing: Write through the
AddMemoriesAPI by passing themessagesarray. The service saves raw messages as short-term memory and generates structured memory, read-only memory files, or both, based on the memory store'soutputTypes. -
Text writing: Write through the
AddMemoriesAPI by passing thetextfield to directly submit plain text content and generate the memory store's configured output.
Scope information must be specified when writing, where appId is required. tenantId, agentId, and runId default to __default__ when empty. Wildcards * are not allowed on write.
Writes are asynchronous by default (sync=false): raw messages are persisted first and can be immediately queried as short-term memory, while the configured output is generated in the background. You can use the requestId returned by AddMemories to call GetMemoryTask to track the task status. Memory stores that include file output only support asynchronous writes. The memory store also supports custom extraction instructions (extractInstructions), set when creating or updating the memory store, to inject extraction prompts that guide the store's long-term memory extraction toward business-critical information.
Memory Retrieval
SearchMemories supports retrieving long-term memory using natural language. The service combines semantic search and text search capabilities and supports Rerank, which is enabled by default.
During retrieval, appId and tenantId are required fields. agentId and runId can use the wildcard * to broaden the retrieval scope.
Retrieval results return both a fusion score (score) and a normalized similarity (similarity). You can filter low-relevance results using minSimilarity. Set includeEvidence=true to include original message fragments (evidence) corresponding to hit memories in the results, enhancing the explainability of the answering model.
Long-term memory supports attaching metadata. Metadata can be used to store custom business information such as memory source, tags, and priority. Metadata is stored together with the memory unit, and the corresponding metadata fields are returned in retrieval results.
Agentic Task
Memory Consolidation (Dream)
Memory Consolidation (Dream) is an asynchronous capability for secondary refinement of existing data in a memory store. Structured memory stores and writable file memory stores use different input and write models.
Structured Memory Dream
The service analyzes long-term memory and raw messages in the background to produce applicable consolidation actions. Consolidation targets fall into three categories:
-
Memory consolidation ( memory): Deduplicate, rewrite, and merge long-term memories, and delete outdated entries.
-
Skill extraction ( skill): Extract reusable skills from historical interactions
-
Profile extraction ( profile): Accumulate structured user profiles
Structured memory consolidation supports proposal, safe_auto, and high-intensity plan modes. proposal generates proposals that are applied after manual or programmatic confirmation; safe_auto automatically applies them when a confidence threshold is met; plan first waits for plan approval, then executes the authorized deletion scope.
File Memory Dream
For memory stores with inputType=file and outputTypes=["file"], Dream freezes text file versions from one or more input Scopes and automatically writes the consolidated full results to a deterministic output Scope. File actions include create, update, rename, and delete. All updates and deletes are protected by version preconditions for concurrent write safety.
File memory Dream uses a fixed high-intensity automatic mode and does not produce proposals waiting for manual Apply. Querying tasks and actions still uses GetMemoryDreamTask, ListMemoryDreamTasks, and ListMemoryDreamActions. For the detailed process, see Memory Dream.
Knowledge Compilation (Wiki)
Agent Wiki asynchronously builds source files under /.wiki/raw/ into interlinked Markdown pages. Each Wiki is uniquely owned by a memory store and a three-segment appId / tenantId / agentId Scope. Different sessions of the same Agent share pages.
Applications use GetWiki to query or automatically create a Wiki, use IngestWiki to build, and use ListWikiPages, SearchWikiPages, and GetWikiPage to consume published pages. Before a new build is published, the old page set remains readable. For the detailed process, see Knowledge compilation (Wiki).
Enterprise Capabilities
Request Auditing
The service records memory store requests, which can be queried through ListMemoryStoreRequests. Audit records include fields such as operation type, response status, latency, and failure reason, suitable for troubleshooting write, retrieval, and management operations.
Tasks and Observability
Both memory writing and memory consolidation are asynchronous tasks. The service provides companion query capabilities:
-
GetMemoryTaskandListMemoryTasks: Query the status and output of memory extraction tasks. -
GetMemoryDreamTask,ListMemoryDreamTasks, andListMemoryDreamActions: Query memory consolidation tasks and actions. -
ListMemoryStoreScopes: Use a four-levelscopeor structuredfilterto list registered conversation Scopes. Returns a stablescopeKeyfor discovering and paginating through session ranges. -
ListMemoryStoreRequests: Request audit log query.
Performance Reference
The Tablestore memory service was evaluated across three dimensions—retrieval accuracy, retrieval latency, and storage scale—and compared with Mem0, a mainstream memory solution in the industry.
|
Dimension |
Tablestore Memory Service |
Industry comparison |
|
Overall retrieval accuracy |
88.25% |
Approximately 37.4% higher than Mem0 (64.20%) |
|
P50 retrieval latency |
~155 ms |
Similar solutions typically 200–500 ms, reduced by approximately 75% |
|
Verified storage scale |
Hundreds of millions of memory entries, horizontally scalable with no upper limit |
Similar solutions are typically at the million-to-tens-of-millions level |
|
Token savings |
95% |
Approximately 95% savings compared with Plan A (full injection) |
The above data illustrates the service capability boundaries. Actual performance is affected by data scale, query patterns, network conditions, model configuration, and business data distribution. The following are detailed evaluations for each dimension.