Memory storage instances persist conversation history, session state, and long-term memory for your agents. You can create and manage these instances in the console and bind them to agents.
What is memory storage
Memory storage, known as MemoryCollection in the API, is an AgentRun service that provides data persistence for the following three memory types:
-
Long-term memory: Stores user preferences and knowledge accumulated over multiple conversations, enabling semantic search through an LLM and an embedding model.
-
Session history: Records the complete conversation history to maintain contextual coherence in multi-turn dialogues.
-
Session state: Maintains real-time state information during a conversation, such as task progress and intermediate variables.
When you create a memory storage instance, you can choose either Table Store (OTS) or RDS as the underlying storage engine for the vector database. Both engines support the long-term memory feature. However, only the OTS engine supports the session history and session state features.
Prerequisites
-
You have activated AgentRun and created a workspace.
-
If you choose a custom OTS configuration, you must have activated the Table Store (OTS) service.
-
If you choose a custom RDS configuration, you must have created an RDS for MySQL instance and enabled the
Vector Storefeature (supported on MySQL 8.0.30 and later). -
If you enable the long-term memory feature, you must have configured an LLM service and an embedding model service.
Create memory storage in the console
Procedure
-
Log on to the AgentRun console. In the left-side navigation pane, choose Memory.
-
Click Create Memory Collection.
-
Configure the basic information:
-
Memory Collection Name: The system automatically generates a name in the
mem-xxxxformat, which you can modify. The name must comply with the naming conventions. -
Description: Optional. Enter a description of the memory storage instance's purpose.
-
-
Configure the vector database. Two configuration methods are supported:
-
Automatic Configuration (Recommended): The system automatically creates and configures an OTS instance, enabling one-click deployment.
-
Custom Configuration: Manually select a vector database type (OTS or RDS) and specify the detailed parameters. For more information, see Vector database parameters below.
-
-
Configure feature toggles. Enable the Session History and Session Status features as needed.
ImportantThe session history and session state features are available only for memory storage instances that use OTS. If you select an RDS-based vector database, these toggles are not displayed.
-
Configure the network. You can choose either the public network or a VPC. If you select an RDS-based vector database, you must use a VPC. For more information, see Network configuration below.
-
After you confirm that the configuration is correct, click Start Deployment.
Vector database parameters
OTS configuration
When you select Custom Configuration → OTS, you must configure the following parameters:
|
Parameter |
Description |
Example |
|
OTS instance |
Select an existing Table Store instance. Each instance can be bound to only one memory storage instance. |
my-ots-instance |
|
Table name |
The default value is |
mem0 |
|
Vector dimension |
Automatically set based on the selected embedding model. Valid values: 64 to 2048. |
1536 |
RDS configuration
When you select Custom Configuration → RDS, you must configure the following parameters:
|
Parameter |
Description |
Example |
|
RDS instance |
Select an RDS for MySQL instance that has the Vector Store feature enabled. |
rm-bp1xxxxx |
|
Database name |
Select the target database within the RDS instance. |
my_database |
|
Table name |
Specify a custom table name for storing memory data. The name must start with a letter or an underscore and can contain only letters, digits, and underscores. |
mem0 |
|
Username |
The username for accessing the RDS database. |
admin |
|
Credential |
For RDS mode, you must select an existing credential or create a new one to securely store the database password. |
my-credential |
|
Port |
The connection port for the RDS database. The default is 3306. |
3306 |
|
Vector dimension |
Automatically set based on the selected embedding model, or you can enter a value manually. Valid values: 64 to 2048. |
1536 |
The RDS instance must have the Vector Store feature enabled. If it is not, go to the RDS console to enable Vector Store.
Model configuration
When you enable the long-term memory feature, you must configure a large language model (LLM) for semantic understanding and an embedding model for vectorization.
LLM configuration
|
Parameter |
Description |
Example |
|
Model service |
Select a configured model service provider, such as Model Studio or OpenAI. |
Model Studio |
|
Model |
Select a specific model, such as qwen-plus or qwen-max. |
qwen-plus |
Embedding model configuration
|
Parameter |
Description |
Example |
|
Model service |
Select a configured embedding model service provider. |
Model Studio |
|
Model |
Select a specific embedding model. Different models support different vector dimensions, which affects the vector dimension configuration of the vector database. |
text-embedding-v4 |
Embedding model compatibility
Each embedding model supports specific vector dimensions. After you select a model, the system sets the default dimension automatically. With a custom RDS configuration, you can adjust this value manually within the supported range.
|
Embedding model |
Supported dimensions |
Default dimension |
|
|
2048, 1536, 1024, 768, 512, 256, 128, 64 |
1536 |
|
|
1024, 768, 512, 256, 128, 64 |
768 |
|
|
1536 |
1536 |
|
|
1536 |
1536 |
Execution role
When you enable the long-term memory feature, you must configure an execution role (ExecutionRoleArn) that authorizes AgentRun to access the model services and vector database. You can select an existing role or create a new one.
Network configuration
Network settings determine how agents and services connect to the memory storage instance.
|
Network type |
Description |
Configuration |
|
Public network |
Access over the public internet. No additional network configuration is required. This is the default for automatic configuration. |
None required |
|
VPC |
Access through a VPC for lower latency and higher security. This is mandatory if you select RDS. |
VPC ID, vSwitch, security group |
If you select an RDS-based vector database, the network type is restricted to VPC, and the VPC must be the one that contains your RDS instance.
Enable session history and session state
You can enable the following features when creating a memory storage instance:
-
Session History: Records the complete conversation history, including user inputs and agent replies. When enabled, the agent can maintain context across multiple turns in a conversation.
-
Session Status: Maintains real-time state information during a conversation, such as task progress or intermediate variables. When enabled, the agent can track and manage state changes throughout the conversation.
Once enabled, the session history and session state features cannot be disabled. Decide whether to enable them based on your requirements before creating the memory storage instance.
The Session History and Session Status features are available only for memory storage instances that use OTS. If you select an RDS-based vector database, these feature toggles are not displayed.
Edit memory storage
You can modify certain settings of a memory storage instance, such as its description and network configuration.
-
In the Memory Collections list, find the target memory storage instance.
-
Click the name of the memory storage instance to go to its details page.
-
On the Overview tab, find the setting you want to modify and click the edit icon in the corresponding section.
-
After you make your changes, save the configuration.
Some core settings, such as the vector database type and instance, cannot be changed after creation.
Reset memory storage
Resetting a memory storage instance clears all its data, including session history, session state, and long-term memory, but preserves the configuration settings.
-
On the details page of the memory storage instance, find the Reset option.
-
In the confirmation dialog box that appears, review the impact of the reset operation.
-
After you confirm, the system deletes all memory data.
Delete memory storage
Deleting a memory storage instance is an irreversible operation. All associated data, including long-term memory, session history, and session state, will be permanently deleted. Proceed with caution.
-
In the Memory Collections list, find the target memory storage instance.
-
In the Actions column, click Delete.
-
In the confirmation dialog box that appears, enter the name of the memory storage instance to confirm.
-
Click Delete Memory Storage and wait for the deletion to complete.
Bind memory storage to an agent
Bind a memory storage instance to an agent on the agent creation or configuration page to give the agent persistent memory capabilities.
-
When creating or editing an agent, find the Context Resources configuration section.
-
From the list of available instances on the right, select a memory storage instance and click the Add button to move it to the bound list.
-
You can use the search box to quickly filter instances by name.
-
To unbind an instance, click the Remove button next to it in the bound list.
Memory type tags
Each bound memory storage instance displays a type tag that the system infers from the instance's configuration:
|
Memory type |
Inference condition |
Description |
|
|
The session history feature is enabled. |
Maintains conversational context consistency, suitable for multi-turn dialogue scenarios. |
|
|
A vector database is configured. |
Provides structured knowledge storage and semantic memory retrieval through vector search. |
|
|
Session history is not enabled, and a vector database is not configured (default type). |
Manages persistent long-term memory, storing user preferences and knowledge across sessions. |