Memory Storage limits and quotas: File memory, Scope, SDKs, and CLI - Tablestore

Service availability and resource limits

Regions

Memory Storage is available only in the China (Beijing) and China (Hangzhou) regions.

Memory store limits

Item	Limit
Memory store name characters	Letters, digits, and underscores only
Memory store name length	Up to 32 characters
Memory store description length	Up to 1,024 bytes in UTF-8
`extractInstructions` custom extraction instruction length	Up to 4,096 characters

After you create a memory store, wait for index initialization to complete before you write or search data.

extractInstructions specifies custom memory extraction instructions at the memory store level. The instructions are injected into the extraction prompt and affect subsequent long-term memory extraction in the memory store. You can set the instructions when you call CreateMemoryStore or modify them by calling UpdateMemoryStore. To clear the instructions, pass an empty string. If you omit the field, the existing instructions remain unchanged.

Memory operation limits

Scope rules

Operation	Scope requirement	Wildcard `` allowed*
Add memories	`appId` is required. Empty lower levels are automatically set to `__default__`.	No
Search long-term memories	`appId` and `tenantId` are required.	Allowed for `agentId` and `runId`
Query short-term memories	All four Scope levels are required.	No
Get a long-term memory	All four Scope levels are required.	No
Update a long-term memory	All four Scope levels are required.	No
Delete a long-term memory	All four Scope levels are required.	No
List long-term memories	Specify Scope by level.	Yes
List Scope values (`ListMemoryStoreScopes`)	Specify Scope by level.	Yes
Query extraction tasks (`ListMemoryTasks`)	Specify Scope by level.	Yes
Query request audits	Specify Scope by level.	Yes

Wildcards must follow the Scope hierarchy. After you use * at a level, all subsequent levels must also use * or be left empty. For example, app-001/user-001/*/* is valid, but app-001/*/agent-001/* is not.

File memory and file view limits

Item	Limit or behavior
Scope	All four levels, `appId`, `tenantId`, `agentId`, and `runId`, are required. The wildcard `*` is not supported.
File path	The canonical path must start with `/` and can be up to 800 bytes in UTF-8. The path cannot be the root directory or contain empty path segments, `.`, `..`, or NUL characters.
File content	Valid UTF-8 text only
File size	Up to 100 KiB (102,400 bytes) per file
Current files in a Scope	Up to 2,000 files by default
File list pagination	`limit` defaults to `100` and can be up to `500`.
Concurrent writes	`expectedSha256` is optional. If multiple writers modify the file, pass the digest from the latest read.
Historical version redaction	Irreversible. Redaction clears only the selected historical versions and does not modify the current file.
File views	Read-only. Maintain memories by using structured interfaces such as the SDK or CLI.

If the file content, path, or file count exceeds the corresponding limit, the service returns PAYLOAD_TOO_LARGE, VALIDATION_ERROR, or QUOTA_EXCEEDED, respectively. If a concurrent write digest does not match, the service returns SHA_MISMATCH. Read the latest file before you decide whether to retry.

Memory write limits

Item	Limit
`messages` count	Up to 20
Total `messages` content length	Up to 32,000 bytes in UTF-8
`text` length	Up to 32,000 bytes in UTF-8
`messageId` length	Up to 256 characters
`metadata` key count	Up to 16
`metadata` key length	Up to 64 characters
`metadata` value length	Up to 1,024 characters

Provide at least one of messages or text. The wildcard * is not allowed in the Scope when you add memories.

Asynchronous write visibility

AddMemories.sync defaults to false, which enables asynchronous writes. Asynchronous writes become visible as follows:

Raw messages are written first and can be queried immediately as short-term memories.
Long-term memory extraction runs in the background.
After long-term memory extraction and index refresh are complete, the memories can be retrieved by calling SearchMemories.

To view extraction results immediately after a write in a test, set sync to true. A brief index refresh delay can still occur before long-term memories become searchable after a synchronous write completes. You can also call GetMemoryTask and pass the requestId returned by AddMemories to query the asynchronous extraction task status and the IDs of the extracted memory units.

Search defaults

Parameter	Default	Description
`topK`	`10`	Maximum number of results to return. The default is 10 and the maximum is 50. Relevance filtering or semantic deduplication can result in fewer than topK results.
`enableRerank`	`true`	Specifies whether to enable reranking.
`includeEvidence`	`false`	Specifies whether to include short-term source evidence in the `evidence` field of each result.
`minSimilarity`	`0`	Relevance threshold in the range `0~1`. A value of `0` disables filtering. A value greater than `0` filters out results whose relevance scores are below the threshold. When reranking is enabled, the score is the reranking relevance score. Otherwise, the score is normalized cosine similarity.

When you search long-term memories, appId and tenantId are required. You can use the wildcard * for agentId and runId.

Short-term memory queries

ListMemoryStoreMessages queries raw session messages. All four Scope levels, appId, tenantId, agentId, and runId, are required. Wildcards are not supported.

Use this API to:

View raw session messages.
Replay a specific session.
Troubleshoot long-term memory extraction.

Memory consolidation (Dream) limits

Memory consolidation (Dream) is an asynchronous task that further refines and merges stored memories, and extracts skills and profiles. The related APIs are CreateMemoryDreamTask, GetMemoryDreamTask, ListMemoryDreamTasks, ListMemoryDreamActions, ApplyMemoryDreamActions, and CancelMemoryDreamTask.

CreateMemoryDreamTask limits

Item	Limit
`scopes` count	Required. Up to 20.
`maxSessions`	`0~100`
`maxMessages`	`0~20000`
`maxMemories`	`0~5000`
`expandedScopeLimit`	`0~1000`
`instructions` length	Up to 4,000 bytes in UTF-8
`actionIds` for `ApplyMemoryDreamActions`	Up to 100 per request

Enum values

Field	Values
`taskType`	`memory` (default) / `skill` / `profile`
`applyMode`	`proposal` (default) / `safe_auto`. Supported only when `taskType`=`memory`.
`scopeOutputMode`	`preserve_scope` (default) / `promote_scope`
`confidenceThresholds` keys	`add` / `update` / `merge`. Values range from `0~1`. `DELETE` does not support an automatic confidence threshold.
Task status (task `status`)	`queued` / `running` / `planning` / `applying` / `completed` / `completed_with_failures` / `failed` / `cancelled`
Action type (`action`)	`ADD` / `UPDATE` / `DELETE` / `MERGE` / `NOOP` / `EMIT_SKILL` / `EMIT_PROFILE`
Action status (action `status`)	`proposed` / `applied` / `skipped` / `failed`

When applyMode=proposal, the task generates actions in the proposed state. Call ApplyMemoryDreamActions to explicitly apply the actions. When safe_auto is used, the service automatically applies safe actions that meet the confidence thresholds. EMIT_SKILL and EMIT_PROFILE actions are written directly by the Dream task and do not require manual application.

Asynchronous tasks and list pagination

API	Default limit	Maximum limit
`ListMemoryTasks`	50	100
`ListMemoryStoreScopes`	100	100
`ListMemoryDreamTasks`	50	100
`ListMemoryDreamActions`	100	100

Extraction task status values for ListMemoryTasks.status or task.status returned by GetMemoryTask are queued / running / completed / failed / needs_reconcile.

GetMemoryTask and ListMemoryTasks depend on the task index. After the first write, the service requires some time to build the task index. During this period, these APIs may return 409 CONFLICT with the message ingest task index is still building, please retry shortly. Retry later.

CLI, SDKs, and plugins

CLI pagination

Memory-related CLI list commands return only one page of results and do not automatically retrieve subsequent pages. To retrieve the next page, use the nextToken from the response.

Example:

tablestore-agent-cli memory list-units \
  --store agent_memory \
  --app-id app-001 \
  --next-token <token>

Automatic Tablestore instance creation

If ots_endpoint and ots_instance_name are not configured, the CLI automatically creates and reuses a managed Tablestore instance in the China (Beijing) or China (Hangzhou) region when you run the doctor command or perform an operation. Instance creation requires some time, and the result is written to the local configuration file.

If you later manually configure an instance endpoint and name, the CLI uses the explicitly configured instance.

SDK and CLI versions

SDK or tool	Version requirement
Python SDK	`tablestore >= 6.4.7` (`6.4.5` and later support basic memory APIs; `6.4.7` and later support task and memory consolidation APIs)
Node.js SDK	`tablestore >= 5.6.5`
Agent Storage SDK for Python	`tablestore-agent-storage >= 1.0.10`
Agent Storage SDK for TypeScript	`@tablestore/agent-storage >= 0.0.11`
Agent Storage SDK for Go	`github.com/aliyun/tablestore-agent-storage-sdk/go`
CLI	`@tablestore/tablestore-agent-cli >= 0.2.5`

Agent plugin notes

The Hermes and OpenClaw plugins search across agents and sessions in the current tenant by default, using agentId=* and runId=*. If your business does not allow memories to be shared across agents or sessions, use the SDK to control the search Scope or modify the plugin configuration.

Rolling upgrade and rollback limits

The following three switches are disabled by default and operate independently:

memory_unit_v2_write_enabled=false: The service does not generate or accept V2 write fields.
memory_unit_v2_projection_enabled=false: The service retains the legacy byte format for file projections.
search_session_affinity_mode=off: The service retains the legacy single-lane search behavior and response fields.

Use a server-first rollout. First, upgrade all replicas to a version that can read V2 columns and recognize contextScope and the new response fields, while keeping the switches disabled. After all legacy replicas are removed, clients can start sending contextScope. Then, change the mode to shadow and then on. Legacy servers strictly reject unknown fields. If clients send contextScope before all replicas are upgraded, the mixed-version cluster returns an HTTP 400 error.

Do not enable V2 writes or V2 file projections in a mixed-version cluster. After any V2 row is written, do not roll back directly to a legacy parser or writer that does not recognize V2 columns. A legacy whole-row write can overwrite or discard new fields. To roll back application behavior, return to a compatible version that can read V2 data with all new switches disabled, instead of returning to a pre-V2 binary.