Memory Store

Updated at:

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:

ItemBuilt-in memoryBailian memory store
providerOmitted or defaultagentstudio_memory
UsageMounts files and reads/writes through file toolsStores and retrieves through the Bailian memory service
Data scopeDetermined by the built-in Memory StoreDetermined by the memory store and entity ID
Mount pathExisting /mnt/memory/... pathNo file path
Memory capabilitiesExisting file memory, versions, and DreamingFactual 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:

LayerDescription
Memory StoreA logical container with a name and description. A workspace can contain multiple memory stores.
MemoryA single file inside a memory store, consisting of a path and a UTF-8 text body, such as a Markdown note.
VersionA 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 new content to update the body, a new path to rename, or both for an atomic change. A real change automatically produces a modified version.
  • Concurrency protection: On update, include the content_sha256 obtained at read time in precondition; 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}/memories supports path_prefix filtering, depth (0 recursive / 1 current level), and view (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:

FieldDescription
MemorySelect the built-in memory store to mount
AccessRead-only (retrieve only) or read-write (Dreaming can also consolidate the conversation back into the store after the session ends)
InstructionsProvided 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 by memory_id for a single memory, or by operation (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}/redact erases 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:

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:

FieldDescription
MemorySelect the Bailian memory store to mount
Entity IDThe entity ID bound to this mount; different mounts can use different values
AccessRead-only (retrieve only) or read-write (retrieve and write)
DescriptionDescription of the mount purpose, helping the model decide when to retrieve this store
Memory RulesFactual memory and skill memory rules; at most 5 rules per mount in total
Profile SchemaSelect 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:

FieldRequiredTypeDescription
typeYesstringFixed as memory_store
providerNostringagentstudio_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_idYesstringBailian memory store ID; the memstore_ prefix is not required
entity_idYesstringThe 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
accessNostringread_only or read_write; defaults to read_write
descriptionNostringDescription 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_idsNostring[]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_schemaNostringProfile 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_ids is omitted or an empty array, the default Bailian memory rules are used; an empty array does not disable extraction.
  • If profile_schema is 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

HTTPerror.codeCause
400invalid_request_errorInvalid parameters, path, limit, or pagination cursor
401InvalidApiKeyAPI key missing, invalid, or expired
403permission_errorInsufficient identity or resource access permissions
404not_found_errorStore, memory, or version does not exist or does not belong to the current workspace
409memory_path_conflict_errorDuplicate file path or conflict with an existing file/directory
409memory_precondition_failed_errorCondition update conflict caused by concurrent modification
409memory_store_archived_errorWrite attempted on an archived memory store
429rate_limit_errorRequest rate limited

Next Steps