Memory Store
A memory store is a persistent mount resource for cross-session memory, supporting built-in file memory and Bailian memory stores. Mount it at session creation, and the agent reads and writes memory based on the mount configuration.
Concepts
A memory store is a mount resource managed independently of sessions, used to retain an agent's memory across sessions. Managed Agents supports two providers:
| Item | Built-in memory | Bailian memory store |
|---|---|---|
provider | Omitted or default | agentstudio_memory |
| Usage | Mounts files and reads/writes through file tools | Stores and retrieves through the Bailian memory service |
| Data scope | Determined by the built-in Memory Store | Determined by the memory store and entity ID |
| Mount path | Existing /mnt/memory/... path | No file path |
| Memory capabilities | Existing file memory, versions, and Dreaming | Factual memory, skill memory, and user profiles |
Noteprovider=default refers to built-in memory, not the default store of the Bailian memory service. Omitting provider in existing requests keeps using built-in memory.
Quotas and Limits
- A single built-in memory file is limited to 102400 UTF-8 bytes.
- A session can have at most 8 memory mounts.
- All memory mounts in a session must use the same provider; built-in memory and Bailian memory stores cannot be mixed.
- A built-in memory store can be mounted to multiple sessions at the same time, with its content shared across sessions.
- Bailian memory stores support mounting multiple stores and binding the same store to different entity IDs; the same store and entity ID combination cannot be mounted more than once.
- Each built-in memory mount instruction is limited to 4096 characters.
- Memory mounts are set only at session creation; after creation, they cannot be added, removed, or changed. Create a new session to make adjustments.
Built-in Memory
Built-in memory keeps an agent's long-term working notes and is a path-based file tree:
| Layer | Description |
|---|---|
| Memory Store | A logical container with a name and description. A workspace can contain multiple memory stores. |
| Memory | A single file inside a memory store, consisting of a path and a UTF-8 text body, such as a Markdown note. |
| Version | A historical version automatically produced on every create, modify, or delete of a memory. Versions can be listed and viewed. |
Creating a Memory Store
On the Memory Stores page, click Create Memory and enter a name and description. The name is 1–255 characters.
NoteThe console supports creating, editing, and archiving memory stores. Writing memory files, querying versions, and deletion are done via API—see below and the Memory Store API.
Create one via API; the response returns an ID with the memstore_ prefix. For full parameters and response fields, see the Create Memory Store API.
curl -X POST "$AGENTSTUDIO_URL/memory_stores" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Project Knowledge",
"description": "Project conventions, decisions, and troubleshooting notes"
}'
Writing and Managing Memories
Memory files are managed via API. Paths start with /, for example /notes/project.md.
Write a memory; the response returns an ID with the mem_ prefix. For full parameters and response fields, see the Create Memory API.
curl -X POST "$AGENTSTUDIO_URL/memory_stores/memstore_xxx/memories" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"path": "/notes/project.md",
"content": "# Project Conventions\nThe default development environment is staging.\n"
}'
Read and modify:
- Read:
GET /memory_stores/{memory_store_id}/memories/{memory_id}returns the body; an archived but undeleted store can still be read. - Modify:
POST /memory_stores/{memory_store_id}/memories/{memory_id}— pass newcontentto update the body, a newpathto rename, or both for an atomic change. A real change automatically produces amodifiedversion. - Concurrency protection: On update, include the
content_sha256obtained at read time inprecondition; if the content has been changed by someone else, the request returns a conflict—re-read, merge, and retry. - List:
GET /memory_stores/{memory_store_id}/memoriessupportspath_prefixfiltering,depth(0 recursive / 1 current level), andview(basic without body / full with body). Results are sorted by path; keyword search over bodies is not supported. - Delete:
DELETE /memory_stores/{memory_store_id}/memories/{memory_id}deletes the current file while keeping historical versions, which remain queryable via the version APIs.
Write operations require the memory store to be unarchived. For full parameters and response fields, see the Memory API.
Mounting to a Session
Console
In the Resources section of New Session, click +, choose Memory, then choose Built-in memory. Configure the following options and click Create Session:
| Field | Description |
|---|---|
| Memory | Select the built-in memory store to mount |
| Access | Read-only (retrieve only) or read-write (Dreaming can also consolidate the conversation back into the store after the session ends) |
| Instructions | Provided to the agent together with the mount, helping it decide when to retrieve this memory |
API
Specify built-in memory in resources when creating the session. provider can be omitted and defaults to default; access defaults to read_write when omitted:
curl -X POST "$AGENTSTUDIO_URL/sessions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {"type": "agent", "id": "agent_xxx"},
"resources": [
{
"type": "memory_store",
"memory_store_id": "memstore_xxx",
"access": "read_write",
"instructions": "Check the project conventions in this store first; save new findings to the relevant notes."
}
]
}'
For built-in memory, the resources array in the response contains the server-generated mount_path, for example /mnt/memory/<name>. Reference the full path directly in the system prompt.
How the Agent Uses Memory
When a session has built-in memory mounts, the platform automatically injects memory instructions into the agent, including mount paths, access, and the instructions you filled in. The agent works as follows:
- Uses Glob and Grep to search under the mount paths, Read to load relevant files, and Write and Edit to save information worth keeping after completing the task.
- Read-only mounts support query and read only; read-write mounts support all file operations.
- Shell commands cannot access memory paths; only the file tools above can.
WarningDo not store keys, tokens, or other credentials in memory. Mount instructions are business-defined content and cannot override platform security policies.
Historical Versions
Every create, modify, and delete of a built-in memory automatically produces a version record. Version queries do not require the current memory to still exist:
- List versions:
GET /memory_stores/{memory_store_id}/memory_versions— filter bymemory_idfor a single memory, or byoperation(created/modified/deleted) and creation time range; results are in reverse chronological order. - View a version:
GET /memory_stores/{memory_store_id}/memory_versions/{memory_version_id}returns that version's body for reviewing old content; it does not roll back the current memory. - Redact a body:
POST /memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redacterases the body of the specified version. Irreversible and does not affect the current memory.
For full parameters and response fields, see the Memory Version API.
Archiving
Click Archive on the Memory Stores page, or call POST /memory_stores/{memory_store_id}/archive. Archiving is irreversible: the store can no longer be written or bound to new sessions, and existing session mounts become read-only. The list does not return archived stores by default; pass include_archived=true to include them. Repeated archive calls are idempotent.
Bailian Memory Store
A Bailian memory store provides factual memory, skill memory, and user profiles through the Bailian memory service. Stores, memory rules, and profile schemas are managed in the memory service; Managed Agents handles mounting and usage.
Prerequisites
Activate the Bailian memory service, then create a Bailian memory store. Configure memory rules and profile schemas as needed. When creating a session, you need the store ID; rule IDs and the profile schema ID are optional:
- Memory stores and rules: see Bailian Memory and Configure memory rules.
- Profile schemas: see Create Profile Schema.
NoteIf the memory service is not activated, memory service APIs (for example, AddMemoryAsync) return 403 ServiceNotOpened, and the console does not show the Bailian memory store mount option.
Mounting to a Session
Console
In the Resources section of New Session, click +, choose Memory, then choose Bailian memory store (whether this option appears depends on whether the memory service is activated). Configure the following options and click Create Session:
| Field | Description |
|---|---|
| Memory | Select the Bailian memory store to mount |
| Entity ID | The entity ID bound to this mount; different mounts can use different values |
| Access | Read-only (retrieve only) or read-write (retrieve and write) |
| Description | Description of the mount purpose, helping the model decide when to retrieve this store |
| Memory Rules | Factual memory and skill memory rules; at most 5 rules per mount in total |
| Profile Schema | Select one profile schema; if not selected, the profile capability is not enabled |
API
When creating a session, set type to memory_store and provider to agentstudio_memory in resources. Replace the example IDs with actual resources:
{
"agent": {
"type": "agent",
"id": "agent_xxx"
},
"environment_id": "env_xxx",
"resources": [
{
"type": "memory_store",
"provider": "agentstudio_memory",
"memory_store_id": "0123456789abcdef0123456789abcdef",
"entity_id": "customer_001",
"access": "read_write",
"description": "Save customer-confirmed business agreements, reusable experience, and communication preferences",
"project_ids": ["fact_rule_demo", "skill_rule_demo"],
"profile_schema": "profile_schema_demo"
}
]
}
Field descriptions:
| Field | Required | Type | Description |
|---|---|---|---|
type | Yes | string | Fixed as memory_store |
provider | No | string | agentstudio_memory indicates a Bailian memory store. If omitted, defaults to default (built-in memory). The create request does not accept an explicit null, an empty string, or any other value |
memory_store_id | Yes | string | Bailian memory store ID; the memstore_ prefix is not required |
entity_id | Yes | string | The entity ID bound to this mount. It cannot be empty after trimming leading and trailing whitespace. It is not the cloud account UID, nor a top-level Session field. Different mounts can use different entity IDs |
access | No | string | read_only or read_write; defaults to read_write |
description | No | string | Description of the mount purpose, provided and stored by the caller to help the model select a store. It is not overwritten by the description in the store metadata |
project_ids | No | string[] | Factual and skill memory rule IDs, combined in one array. At most 5 per mount in total, and rule IDs in the array cannot be empty or duplicated |
profile_schema | No | string | Profile schema ID. Must be a non-empty string; only one is supported; arrays and schema objects are not accepted; does not count toward the 5-rule limit |
Default behavior for rules and profile schemas:
- If
project_idsis omitted or an empty array, the default Bailian memory rules are used; an empty array does not disable extraction. - If
profile_schemais omitted, the profile capability is not enabled for this mount, and no default profile schema is added.
How the Agent Uses Bailian Memory
After mounting, the platform provides retrieval and write capabilities for the store. The agent retrieves factual memory, skill memory, and user profiles as needed; read-only mounts support retrieval only, and read-write mounts support both retrieval and writes. Extraction rules and profile schemas are managed in the memory service.
Common Errors
| HTTP | error.code | Cause |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, path, limit, or pagination cursor |
| 401 | InvalidApiKey | API key missing, invalid, or expired |
| 403 | permission_error | Insufficient identity or resource access permissions |
| 404 | not_found_error | Store, memory, or version does not exist or does not belong to the current workspace |
| 409 | memory_path_conflict_error | Duplicate file path or conflict with an existing file/directory |
| 409 | memory_precondition_failed_error | Condition update conflict caused by concurrent modification |
| 409 | memory_store_archived_error | Write attempted on an archived memory store |
| 429 | rate_limit_error | Request rate limited |
Next Steps
- Delegate Work to an Agent: Mount a memory store at session creation.
- Manage Agent Context: Learn about all mountable resource types.
- Memory Store API: The complete API for built-in stores, memories, and versions.
- Bailian Memory Store: Manage Bailian memory stores, memory rules, and profile schemas.