Memory Storage HTTP JSON API reference-Tablestore(Tablestore)-阿里云帮助中心

Memory Storage provides 30 APIs over HTTP JSON for managing memory stores, long-term and short-term memories, audit records, asynchronous tasks, memory consolidation (Dream), file memory, and file views. Use these APIs for custom integrations without an SDK.

API list

All APIs grouped by category:

Memory store management

API	Description
`CreateMemoryStore`	Creates a memory store.
`GetMemoryStore`	Retrieves memory store details.
`UpdateMemoryStore`	Updates the description of a memory store.
`DeleteMemoryStore`	Deletes a memory store.
`ListMemoryStores`	Lists memory stores.

Long-term memory

API	Description
`AddMemories`	Writes conversation messages or text to generate long-term memories.
`SearchMemories`	Searches long-term memories.
`ListMemories`	Lists long-term memories.
`GetMemory`	Retrieves a long-term memory entry.
`UpdateMemory`	Updates a long-term memory entry.
`DeleteMemory`	Deletes a long-term memory entry.

Short-term memory and audit

API	Description
`ListMemoryStoreMessages`	Queries short-term memories (original conversation messages).
`ListMemoryStoreRequests`	Queries audit records of memory store requests.

Asynchronous tasks and Scope

API	Description
`GetMemoryTask`	Queries the status and result of an async extraction task.
`ListMemoryTasks`	Lists async extraction tasks.
`ListMemoryStoreScopes`	Lists the Scopes that exist in a memory store.

Memory consolidation (Dream)

API	Description
`CreateMemoryDreamTask`	Creates a memory consolidation task.
`GetMemoryDreamTask`	Queries the progress of a memory consolidation task.
`ListMemoryDreamTasks`	Lists memory consolidation tasks.
`ListMemoryDreamActions`	Lists the proposed actions generated by a memory consolidation task.
`ApplyMemoryDreamActions`	Applies proposed memory consolidation actions.
`CancelMemoryDreamTask`	Cancels a memory consolidation task.

File memory and file views

API	Description
`AddItem`	Adds a memory file.
`ListItems`	Lists files by path prefix with pagination.
`GetItem`	Retrieves file content or metadata only.
`UpdateItem`	Updates file content or renames a file.
`DeleteItem`	Deletes a file.
`ListItemVersions`	Lists historical file versions with pagination.
`GetItemVersion`	Retrieves a historical file version.
`RedactItemVersion`	Irreversibly redacts a historical file version.

Common objects

Data structures shared across API requests and responses.

Scope

A Scope defines the ownership hierarchy of memory data.

Field	Type	Description
`appId`	string	The application identifier.
`tenantId`	string	The tenant or user identifier.
`agentId`	string	The agent identifier.
`runId`	string	The session, run, or task identifier.

Required Scope fields and wildcard * support vary by API.

Scenario	Required fields	Wildcard `` rules*
Write (`AddMemories`)	`appId`	Empty fields are populated with `__default__`. The wildcard `*` is not allowed.
Search long-term memories (`SearchMemories`)	`appId` and `tenantId`	`agentId` and `runId` support the wildcard `*`.
Query short-term memories (`ListMemoryStoreMessages`)	All four Scope fields	The wildcard `*` is not allowed.
Get, update, or delete a long-term memory entry (`GetMemory`, `UpdateMemory`, `DeleteMemory`)	All four Scope fields	The wildcard `*` is not allowed.
File memory and file views (Item APIs)	All four Scope fields	The wildcard `*` is not allowed.
List operations (`ListMemories`, `ListMemoryStoreScopes`, `ListMemoryTasks`, `ListMemoryStoreRequests`, and `ListMemoryDreamTasks`)	None. We recommend that you provide at least `appId`. Empty fields are treated as `__default__`.	The wildcard `*` is supported at each hierarchy level.

Example:

{
  "appId": "app-001",
  "tenantId": "user-001",
  "agentId": "assistant",
  "runId": "session-001"
}

Message

The messages field of AddMemories uses the following structure.

Field	Type	Required	Description
`role`	string	Yes	The message role, such as `user`, `assistant`, or `system`.
`content`	string	Yes	The message content.
`messageId`	string	No	The message ID. Maximum length: 256 characters.
`timestamp`	string	No	The timestamp in RFC 3339 format.
`metadata`	object	No	Message-level metadata. Keys and values must be strings.

Metadata

String key-value pairs for business tags. Search APIs use metadata for exact-match filtering.

Constraint	Value
Maximum keys per request	16
Maximum key length	64 characters
Maximum value length	1,024 characters

Example:

{
  "source": "chat",
  "topic": "preference"
}

Memory store management

CreateMemoryStore

Creates a memory store.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name. The name can contain only letters, digits, and underscores (_) and can be up to 32 characters in length.
`description`	string	No	The memory store description. Maximum length: 1,024 bytes in UTF-8.
`extractInstructions`	string	No	Custom memory extraction instructions that are injected into the extraction prompt and affect subsequent long-term memory extraction in the memory store. Maximum length: 4,096 characters.
`storageMode`	string	No	The memory capability: `ots` (default, structured memories), `file+ots` (structured memories and read-only file views), or `filemem` (direct input and management of memory files). This value cannot be changed after the memory store is created.

Request example

{
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent",
  "extractInstructions": "Focus on the user's dietary preferences and travel habits"
}

To create a memory store for directly adding memory files:

{
  "memoryStoreName": "agent_files",
  "storageMode": "filemem"
}

Response example

{
  "otsInstance": "mem-test-01",
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent",
  "extractInstructions": "Focus on the user's dietary preferences and travel habits",
  "storageMode": "ots",
  "createdAt": "2026-06-17T07:19:48.935Z",
  "updatedAt": "2026-06-17T07:19:48.935Z"
}

GetMemoryStore

Retrieves memory store details.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.

Request example

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

Updates the memory store description or custom extraction instructions. This API uses PATCH semantics: fields that are not provided remain unchanged, and an empty string clears the corresponding field.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`description`	string	No	The new description. Maximum length: 1,024 bytes in UTF-8. Pass an empty string to clear the description, or omit this field to keep the current description.
`extractInstructions`	string	No	The new custom extraction instructions. Maximum length: 4,096 characters. To clear the value, pass an empty string. To keep the current value, do not pass this field.

DeleteMemoryStore

Deletes a memory store.

Warning

Deleting a memory store permanently removes all its data. This action is irreversible. Proceed with caution in production environments.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.

ListMemoryStores

Lists memory stores.

Request parameters

Field	Type	Required	Description
`limit`	int	No	The maximum number of entries to return.
`nextToken`	string	No	The pagination token for the next page.

Long-term memory

AddMemories

Writes conversation messages or text. Raw messages are stored as short-term memories, and long-term memories are extracted from the input.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The target memory store name.
`scope`	object	Yes	The Scope. `appId` is required for write operations. The wildcard `*` is not allowed.
`messages`	array	One of messages and `text`	An array of up to 20 conversation messages. The total content can be up to 32,000 bytes in UTF-8.
`text`	string	One of `messages` and text	The text content. Maximum length: 32,000 bytes in UTF-8.
`metadata`	object	No	Write-level metadata. Maximum: 16 keys, 64-character keys, 1,024-character values.
`sync`	boolean	No	Whether to wait synchronously for memory extraction to complete. Default: `false`.
`referenceTime`	string	No	The session reference time, or "as-of" anchor, in RFC 3339 format. If this field is set, messages without a `timestamp` use this value as the event time instead of the current server time. Use this field for historical or batch imports.

For AddMemories limits, see Limitations and notes.

When reconcile_enabled is enabled, the write pipeline first retrieves existing vector candidates. The same DecideMemoryActions call then selects ADD, NOOP, UPDATE, DELETE, or MERGE. MERGE does not trigger an additional model call.

Server-side reconcile_merge_mode controls online MERGE behavior: off (default) does not propose merges, shadow validates and observes proposals without applying them, and safe_auto applies safe merges. A merge is accepted only for a high-confidence result that contains two or three sources, including the new memory, within the same complete four-level Scope. The service conservatively checks entities, speakers, polarity, types, explicit times, metadata, and versions.

In off or shadow mode, or when a proposal is rejected or unsafe, the original new memory continues as an ADD. If batch re-embedding fails for an accepted plan or the response format is invalid, all plans in the batch revert to their original ADD operations and the write continues.

If PutMemories fails for a batch that contains a merge result, the API returns a persistence error and does not perform compare-and-swap (CAS) deletion of the sources. The write must not be treated as a successful ADD.

After a merge result is persisted, source finalization errors are nonfatal for the write and the new result remains stored. An ErrConflict or another CAS or backend error that occurs before the row is applied typically leaves the corresponding old source valid for a retry or Dream. Other sources can still complete independently.

A typed row-applied or event-persistence error indicates that the source tombstone is persisted and the deletion is reflected in the cache, but the audit event remains incomplete. An idempotent replay of the same finalization plan or an operations repair fills the event gap. Dream does not reconstruct online audit events. It handles valid old sources, duplicate stored memories, and convergence.

Successful source operations are not rolled back. Search-time semantic deduplication can hide temporary duplicates during the transition.

Use UPDATE when a state changes and a replacement state exists. Use DELETE only to retract a state when no replacement exists. Do not use MERGE for either case. Dream handles larger source sets, cross-session operations, complex conflicts, and repairs.

Request example: Write messages

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "I like coffee."
    },
    {
      "role": "assistant",
      "content": "Got it. I'll remember that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": true
}

Request example: Write text

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "The user likes coffee and prefers concise responses."
}

Response fields

Field	Description
`requestId`	The request ID.
`status`	The request status. Asynchronous writes typically return `running`.
`acceptedMessages`	The number of accepted messages.
`scope`	The Scope used for the write.
`memoryStoreName`	The memory store name.
`memcellsCreated`	Returned for synchronous writes. The number of memcells created.
`unitsCreated`	Returned for synchronous writes. The number of long-term memory units created.

SearchMemories

Searches long-term memories.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The target memory store name.
`query`	string	Yes	The query text.
`scope`	object	Yes	The Scope. `appId` and `tenantId` are required. `agentId` and `runId` support the wildcard `*`.
`contextScope`	object	No	The complete Scope of the current session, used as a soft-ranking signal. All four fields must contain exact values without the wildcard `*`, and the values must be included in `scope`. If this field is omitted, the existing search behavior is preserved.
`topK`	int	No	The maximum number of results to return. Default: 10. Maximum: 50. Relevance filtering or semantic deduplication can result in fewer than topK results.
`enableRerank`	boolean	No	Whether to enable reranking. Default: `true`.
`includeEvidence`	boolean	No	Specifies whether to include short-term memory source evidence (the `evidence` field) in the result. Default: `false`.
`minSimilarity`	float	No	The relevance threshold in the range `0~1`. Default: `0`, which disables filtering. A value greater than `0` filters out results whose `results[].score` is below the threshold. When reranking is enabled, the score is the reranking relevance score. Otherwise, the score is normalized cosine similarity.
`metadata`	object	No	Metadata filters for exact matching. Keys and values must be strings.

When search_semantic_dedup_enabled is enabled on the server, semantic deduplication applies only to the current fused pool of long-term memory candidates for the public SearchMemories API. Answer and internal searches are not affected.

Deduplication runs before reranking and evidence expansion. It uses conservative, structure-aware complete-link clustering and retains one representative per cluster. As a result, duplicate long-term memories do not consume the reranking budget, while short-term evidence remains independent. Deduplication does not expand candidateK, run a second search, generate additional embeddings, backfill results, or use LLM clustering. topK is the maximum number of results. Underfilled results are accepted, and results are not backfilled from the same cluster.

Semantic deduplication does not modify stored rows or ListMemories results. Dream continues to clean up historical duplicates.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "contextScope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "query": "What beverage does the user like?",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "metadata": {
    "source": "chat"
  }
}

Response fields

Field	Description
`results`	The list of search results.
`results[].unit`	The long-term memory unit. See the following table for field definitions.
`results[].score`	The canonical relevance score in the range `0~1`. This value is the reranking relevance score when reranking is enabled and normalized cosine similarity when reranking is disabled. `minSimilarity` always filters on this field first. Session soft ranking does not modify this field.
`results[].similarity`	The normalized cosine similarity between the query and memory in the range `0~1`. This field is provided for reference and equals `score` when reranking is disabled.
`results[].rankingScore`	The optional final ranking score. This field is returned only when the server-side session affinity mode is `on` and the request includes a valid `contextScope`. Results are sorted by this field.
`results[].rankingSignals`	Optional ranking details that include `sameSession` and the server-side `sessionAffinityWeight`. This field is returned with `rankingScore`.
`results[].source`	The hit source. Example: `vector` or `vector+text`.
`evidence`	The list of short-term source evidence returned when `includeEvidence=true`. Each element uses the same structure as `results`. The value is `[]` when no evidence is available.
`scope`	The Scope used for the query.
`memoryStoreName`	The memory store name.

The following table describes the fields in results[].unit. ListMemories and GetMemory return the same memory fields. Embedding vectors are not returned.

Field	Description
`id`	The long-term memory unit ID.
`conversation_key`	The associated conversation key.
`scope`	The Scope to which the memory belongs. The object contains `appId`, `tenantId`, `agentId`, and `runId`.
`memcell_id`	The memcell ID.
`unit_type`	The memory type, such as `atomic_fact`, `entity_fact`, or `temporal_anchor`.
`title`	The memory title. Maximum length: 64 characters. For legacy data or an empty field, clients can display `text` as a fallback.
`text`	The memory text.
`search_text`	The text used for search.
`keywords`	A list of up to eight keywords. Each keyword can be up to 32 characters in length.
`source_turn_ids`	The list of source message IDs.
`type_label`	The type label.
`date_bucket`	The date bucket.
`metadata`	The metadata object that contains the key-value pairs provided during the write.
`metadata_json`	The metadata in JSON string format.
`metadata_flat`	The flattened metadata string used for filtering.
`deleted`	Indicates whether the memory is deleted.
`created_at`	The creation time.
`effective_at`	The effective time described by the fact, event, or plan. This time can be earlier or later than the memory write time.
`updated_at`	The time when the memory was last updated on the server.
`time_source`	The time source, such as `explicit_event`, `source_message`, `legacy_created_at`, or `manual`.
`time_precision`	The original precision of `effective_at`: `second`, `day`, `month`, `year`, or `unknown`.
`salience`	The salience score.
`version`	The version number.
`speaker`	The speaker associated with the memory. Returned when this field is not empty.
`topic`	The topic label. Returned when this field is not empty.
`entities`	The list of related entities. Returned when this field is not empty.
`time_anchor`	The time anchor information. Returned when this field is not empty.
`source_turn_refs`	The list of source message references. Each element contains `messageId` and `timestampMs`. Returned when this field is not empty.
`superseded_by` / `supersedes_id`	The supersession chain created when a memory is merged or updated. Returned when this field is not empty.
`dream_id` / `dream_action_id` / `dream_reason` / `dream_source_message_ids` / `dream_source_memory_ids`	The provenance fields for a memory that was generated or modified by Dream. Returned when these fields are not empty.

The same session receives bounded soft weighting. For an exact match with the complete contextScope, rankingScore = score + (1-score) × sessionAffinityWeight. For other results, rankingScore equals score. The server controls the weight, which defaults to 0.10 and can be up to 0.25. Requests cannot override the weight. This signal breaks ties among candidates with similar relevance and does not replace semantic relevance or the minSimilarity threshold.

Compatibility note: Legacy servers strictly reject unknown JSON fields, including contextScope. During a rolling upgrade, upgrade all service replicas before clients send this field. A read-only SDK can retry once without contextScope only after it receives an explicit unknown-field error. Do not use this fallback for write APIs.

ListMemories

Lists long-term memories.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The Scope. The wildcard `` is supported by hierarchy and must follow the left-prefix rule: all fields after `` must also be `*` or empty. Empty fields are treated as `__default__`. We recommend that you provide at least `appId`.
`limit`	int	No	The maximum number of entries to return.
`nextToken`	string	No	The pagination token for the next page.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}

The response returns long-term memories in the memories array. Each memory has the same fields as results[].unit in SearchMemories. Paginated responses include nextToken.

GetMemory

Retrieves a long-term memory entry.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	The complete Scope. All four fields are required. The wildcard `*` is not allowed.

UpdateMemory

Updates a long-term memory by using PATCH semantics. Fields that are not provided remain unchanged. Pass an empty string for title or an empty array for keywords to clear the field. At least one updatable field is required.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	The complete Scope. All four fields are required. The wildcard `*` is not allowed.
`text`	string	No	The new memory text.
`metadata`	object	No	The new metadata.
`title`	string	No	The new memory title. Maximum length: 64 characters.
`keywords`	array	No	A list of up to eight new keywords. Each keyword can be up to 32 characters in length.
`effectiveAt`	string	Provide with `timePrecision`	The new effective time. Use RFC 3339 when the precision is `second`. For `day`, `month`, and `year`, use `YYYY-MM-DD`, `YYYY-MM`, and `YYYY`, respectively.
`timePrecision`	string	Provide with `effectiveAt`	The time precision: `second`, `day`, `month`, or `year`.

If memory_unit_v2_write_enabled is disabled on the server, an update that includes title, keywords, effectiveAt, or timePrecision returns 409 CONFLICT. This behavior prevents mixed-version replicas from overwriting each other's V2 fields.

DeleteMemory

Deletes a long-term memory entry.

Warning

Deleting a long-term memory entry is irreversible. Proceed with caution in production environments.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	The complete Scope. All four fields are required. The wildcard `*` is not allowed.

Short-term memory and audit

ListMemoryStoreMessages

Queries short-term memories (original conversation messages).

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The complete Scope. All four fields are required. The wildcard `*` is not allowed.
`limit`	int	No	The maximum number of entries to return.
`nextToken`	string	No	The pagination token for the next page.
`minTimestamp`	string	No	The earliest time in RFC 3339 format.
`maxTimestamp`	string	No	The latest time in RFC 3339 format.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "limit": 100
}

Response example

{
  "session": {
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "messages": [
      {
        "messageId": "d0d9dd778a27e8cde773a243a5bab13c",
        "role": "user",
        "speaker": "user",
        "content": "[10:00 AM on May 13, 2026] I prefer a window seat for future business trips.",
        "timestamp": "2026-05-13T10:00:00Z",
        "metadata": { "channel": "chat", "source": "chat" }
      }
    ]
  }
}

If the memory store exists but no messages exist for the Scope, the operation returns 200 with an empty messages list.

ListMemoryStoreRequests

Queries audit records of memory store requests.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The Scope. The wildcard `*` is supported at each hierarchy level.
`operation`	string	No	The operation name, such as `AddMemories` or `SearchMemories`.
`limit`	int	No	The maximum number of entries to return.
`nextToken`	string	No	The pagination token for the next page.
`minTimestamp`	string	No	The earliest time in RFC 3339 format.
`maxTimestamp`	string	No	The latest time in RFC 3339 format.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "operation": "AddMemories",
  "limit": 50
}

Response fields

Field	Description
`requestId`	The request ID.
`operation`	The operation name.
`scope`	The Scope used in the request.
`requestSummary`	The request summary.
`responseStatus`	The response status.
`latencyMs`	The processing latency in milliseconds.
`targetId`	The target ID of the operation, such as a memory ID.
`createdAt`	The creation time of the record.

Asynchronous tasks and Scope

GetMemoryTask

Queries the status and result of an asynchronous extraction task. Pass the requestId returned by AddMemories.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`requestId`	string	Yes	The request ID returned by `AddMemories`.
`scope`	object	No	Validates the Scope of the task. The wildcard `*` is supported at any level.

Request example

{
  "memoryStoreName": "agent_memory",
  "requestId": "4b41a912f8c8a66202896e880a505d4a"
}

Response example

{
  "memoryStoreName": "agent_memory",
  "task": {
    "requestId": "4b41a912f8c8a66202896e880a505d4a",
    "eventType": "ingest",
    "memoryStoreName": "agent_memory",
    "conversationKey": "app-001/user-001/assistant/session-001",
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "status": "completed",
    "acceptedMessages": 2,
    "derivedMemcellId": "98ebdf1de01b620bfa96f55c8925061f",
    "derivedUnitIds": ["9ce29432d101aab04253a862c8a11022", "6172bac2ca37b6b82f5224de116f030f"],
    "createdAt": "2026-06-17T07:19:59.962Z",
    "updatedAt": "2026-06-17T07:20:08.749Z",
    "finishedAt": "2026-06-17T07:20:08.749Z"
  }
}

Valid values for the task status: queued, running, completed, failed, and needs_reconcile. While the ingest task index is being built after the first write, this API may return 409 CONFLICT (ingest task index is still building, please retry shortly). Retry the request after a short delay.

ListMemoryTasks

Lists async extraction tasks.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The Scope. The wildcard `*` is supported at any level.
`status`	string	No	The task status filter: `queued`, `running`, `completed`, `failed`, or `needs_reconcile`.
`limit`	int	No	The maximum number of entries to return. Default: `50`. Maximum: `100`.
`nextToken`	string	No	The pagination token for the next page.
`minTimestamp`	string	No	The earliest time as a Unix timestamp in milliseconds (RFC 3339 is not supported).
`maxTimestamp`	string	No	The latest time as a Unix timestamp in milliseconds (RFC 3339 is not supported).

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
  "limit": 5
}

The response returns task objects in the tasks array. Each object has the same fields as the task object returned by GetMemoryTask.

ListMemoryStoreScopes

Lists existing Scopes in a memory store to identify the agents and sessions that generated memories for an application or tenant.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The Scope. The wildcard `*` is supported at any level.
`limit`	int	No	The maximum number of entries to return. Default: `100`. Maximum: `100`.
`nextToken`	string	No	The pagination token for the next page.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "limit": 10
}

Response example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "scopes": [
    { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
    { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" }
  ]
}

Memory consolidation (Dream)

CreateMemoryDreamTask

Creates an asynchronous memory consolidation (Dream) task to refine and merge stored memories and extract skills or profiles. For the complete workflow, see Memory consolidation.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scopes`	array	Yes	The list of Scopes to organize. Up to 20 Scopes.
`taskType`	string	No	The task type: `memory` (default), `skill`, or `profile`.
`applyMode`	string	No	The application mode: `proposal` (default, generate proposals only) or `safe_auto` (automatically apply safe actions). Only `taskType=memory` supports this field.
`scopeOutputMode`	string	No	The Scope for consolidation results: `preserve_scope` (default) or `promote_scope`.
`confidenceThresholds`	object	No	The confidence thresholds for automatically applying each action. Valid keys are `add`, `update`, and `merge`. Values range from `0~1`.
`minTimestamp` / `maxTimestamp`	string	No	The time range for organization, as Unix timestamps in milliseconds (RFC 3339 is not supported).
`maxSessions` / `maxMessages` / `maxMemories`	int	No	The maximum input scale. For valid ranges, see the limits documentation.
`expandedScopeLimit`	int	No	The Scope expansion limit in the range `0~1000`.
`instructions`	string	No	Custom consolidation instructions. Maximum length: 4,000 bytes in UTF-8.
`incremental`	boolean	No	Specifies whether to continue incremental consolidation from the last successful high-water mark. Default: `false`, which performs a full consolidation.
`clientToken`	string	No	The idempotency token.

Request example

{
  "memoryStoreName": "agent_memory",
  "scopes": [ { "appId": "app-001", "tenantId": "user-001" } ],
  "taskType": "memory",
  "applyMode": "proposal"
}

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "status": "queued",
  "createdAt": "2026-06-17T07:21:25.329Z"
}

GetMemoryDreamTask

Queries the progress and result summary of a memory consolidation task.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`dreamId`	string	Yes	The ID of the memory consolidation task.

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "taskType": "memory",
  "applyMode": "proposal",
  "scopeOutputMode": "preserve_scope",
  "status": "completed",
  "actions": { "total": 2, "proposed": 2, "applied": 0, "skipped": 0, "failed": 0 },
  "input": { "scopes": [ { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" } ], "sessionCount": 1, "messageCount": 1, "memoryCount": 2, "incremental": false },
  "lastError": "",
  "createdAt": "2026-06-17T07:21:25.329Z",
  "updatedAt": "2026-06-17T07:21:32.276Z",
  "finishedAt": "2026-06-17T07:21:32.276Z"
}

Valid values for the task status: queued, running, planning, applying, completed, completed_with_failures, failed, and cancelled.

ListMemoryDreamTasks

Lists memory consolidation tasks.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`scope`	object	Yes	The Scope. The wildcard `*` is supported at any level.
`status`	string	No	Filters by task status.
`limit`	int	No	The maximum number of entries to return. Default: `50`. Maximum: `100`.
`nextToken`	string	No	The pagination token for the next page.
`minTimestamp` / `maxTimestamp`	string	No	The time range as Unix timestamps in milliseconds. RFC 3339 is not supported.

The response returns task objects in the tasks array. Each object includes fields such as dreamId, status, taskType, actionCount, proposedCount, confidenceThresholds, and createdAt.

ListMemoryDreamActions

Lists proposed actions generated by consolidation tasks. Use one of two mutually exclusive query modes: query by dreamId, or query by scope and actionType for EMIT_SKILL or EMIT_PROFILE actions.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`dreamId`	string	No	The ID of the memory consolidation task. This parameter is mutually exclusive with `scope`.
`scope`	object	No	The Scope query, mutually exclusive with `dreamId`. When this field is used, `actionType` is required and supports only `EMIT_SKILL` or `EMIT_PROFILE`.
`actionType`	string	No	Required for a query by `scope`. Valid values: `EMIT_SKILL` and `EMIT_PROFILE`.
`targetScope`	object	No	Filters by the target Scope of the action. The wildcard `*` is supported by hierarchy.
`sourceMemoryId`	string	No	Filters by the source memory ID of the action.
`status`	string	No	The action status filter: `proposed`, `applied`, `skipped`, or `failed`.
`action`	string	No	The action type filter: `ADD`, `UPDATE`, `DELETE`, `MERGE`, or `NOOP`.
`minConfidence` / `maxConfidence`	float	No	The confidence filter in the range `0~1`.
`orderBy`	string	No	The sort order: `created_at_asc` (default), `created_at_desc`, or `confidence_desc`.
`limit`	int	No	The maximum number of entries to return. Default: `100`. Maximum: `100`.
`nextToken`	string	No	The pagination token for the next page.

Request example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "limit": 20
}

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actions": [
    {
      "dreamId": "2a528008111f5dc3500c73fd965089f7",
      "actionId": "968768529cdfde8d56686a71e1c28227",
      "action": "UPDATE",
      "status": "proposed",
      "targetScope": { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
      "targetMemoryId": "d16fd038835d89ae8586f7814e5256c1",
      "newMemory": { "text": "User prefers concise responses.", "unitType": "atomic_fact" },
      "reason": "Rewritten as a more accurate atomic_fact.",
      "confidence": 0.95,
      "createdAt": "2026-06-17T07:21:32.161Z"
    }
  ]
}

ApplyMemoryDreamActions

Applies the proposed actions generated by a memory consolidation task when applyMode=proposal.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`dreamId`	string	Yes	The ID of the memory consolidation task.
`actionIds`	array	Yes	The list of action IDs to apply. Maximum: 100 IDs per request.
`applier`	string	No	The identifier of the applier. This value is recorded in the audit log.

Request example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actionIds": ["968768529cdfde8d56686a71e1c28227", "a0f4715245920ea7b6a34c1828c6f1ae"]
}

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "applied": 2,
  "failed": 0,
  "results": [
    { "actionId": "968768529cdfde8d56686a71e1c28227", "status": "applied", "memoryId": "bd14a67ed215c114896325d912c8fa71" },
    { "actionId": "a0f4715245920ea7b6a34c1828c6f1ae", "status": "applied", "memoryId": "fa253856113f78d51a3b84a1fdf2d110" }
  ]
}

EMIT_SKILL and EMIT_PROFILE actions are written directly by the consolidation task and do not support manual application. A request that includes either type of action ID is rejected.

CancelMemoryDreamTask

Cancels a memory consolidation task that has not finished.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`dreamId`	string	Yes	The ID of the memory consolidation task.

File memory and file view APIs

File memory and file views share eight Item APIs. Each API uses a POST request with a JSON body and a fixed URL. Dynamic URL paths and query parameters are not used.

For directly added memory files, you can add, read, update, rename, and delete files, and query or redact historical versions.
For structured memories, use the same list and read APIs to access read-only file views generated by the service. readOnly: true in a ListItems response indicates that the view is read-only.

The Agent Storage SDK automatically supplies the Item type. When you call the HTTP API directly, explicitly provide the following common fields.

Common request fields

Field	Type	Required	Description
`type`	string	Yes	The value is fixed at `memoryfile`. A missing or different value returns `400 VALIDATION_ERROR`.
`memoryStoreName`	string	Yes	The target memory store name.
`scope`	object	Yes	The Scope that owns the file. Provide exact values for `appId`, `tenantId`, `agentId`, and `runId`. Wildcards are not supported.

Example common fields:

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  }
}

Item response object

Field	Type	Description
`type`	string	The fixed value `memoryfile`. A single-file response returns this field at the top level.
`itemId`	string	The stable file identifier used to query historical versions.
`path`	string	The file path within the Scope.
`content`	string	The file content. `ListItems` and metadata-only reads do not return this field. A content read of an empty file returns an empty string.
`contentSha256`	string	The content SHA-256 digest as lowercase hexadecimal without a prefix.
`contentSizeBytes`	int64	The content size in UTF-8 bytes.
`latestSeq`	int64	The sequence number of the latest file change.
`createdAt`	string	The file creation time in RFC 3339 format.
`updatedAt`	string	The latest file update time in RFC 3339 format.

ItemVersion response object

Field	Type	Description
`type`	string	The fixed value `memoryfile`. A single-version response returns this field at the top level.
`versionId`	string	The version ID.
`itemId`	string	The file ID.
`versionSeq`	int64	The version sequence number. Provide this field with `versionId` when you read or redact a version.
`operation`	string	The operation that created the version: `created`, `modified`, or `deleted`.
`path`	string	The file path for the version. The value is an empty string after redaction.
`content`	string	The content of the version. Version lists and redacted versions do not return this field.
`contentSha256`	string	The content digest of the version. The value is an empty string after redaction.
`contentSizeBytes`	int64	The content size of the version in bytes. The value is `0` after redaction.
`sessionId`	string	The identifier of the caller session that created the version. This field is omitted if no value was provided.
`createdAt`	string	The version creation time in RFC 3339 format.
`redacted`	bool	Indicates whether the version is redacted. Returned only after redaction.
`redactedAt`	string	The time of the first redaction in RFC 3339 format. Returned only after redaction.
`redactedBy`	string	The `sessionId` from the first redaction request. Returned if the request provided `sessionId`.

AddItem

Adds a memory file. File paths must be unique within the same Scope.

Request parameters

In addition to the common request fields, this API supports the following fields.

Field	Type	Required	Description
`path`	string	Yes	The file path. The service adds a leading `/` if it is missing.
`content`	string	No	The UTF-8 file content, which can be empty. If this field is omitted, an empty file is created.
`sessionId`	string	No	The caller session or operation identifier to record in the version.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "sessionId": "session-001"
}

Response example

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

ListItems

Lists files in bytewise path order with pagination. List entries do not include content.

Request parameters

Field	Type	Required	Description
`pathPrefix`	string	No	Lists only files under the specified path prefix. An empty value lists all files.
`nextToken`	string	No	The opaque pagination token returned on the previous page. Use the token with the original `pathPrefix`.
`limit`	int	No	The number of entries per page. Default: `100`. Maximum: `500`.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "pathPrefix": "/profile/",
  "limit": 100
}

Response example

{
  "type": "memoryfile",
  "items": [
    {
      "itemId": "fmem_019c12345678abcd1234",
      "path": "/profile/preferences.md",
      "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
      "contentSizeBytes": 37,
      "latestSeq": 1784786400123456,
      "createdAt": "2026-07-23T10:00:00Z",
      "updatedAt": "2026-07-23T10:00:00Z"
    }
  ],
  "nextToken": "L3Byb2ZpbGUvcHJlZmVyZW5jZXMubWQ"
}

An empty or omitted nextToken indicates that no more files remain. A read-only file view generated from structured memories also returns "readOnly": true at the top level. Directly added file memory does not return this field.

GetItem

Retrieves a file by path. By default, the response includes file content. You can also retrieve metadata only.

Request parameters

Field	Type	Required	Description
`path`	string	Yes	The file path.
`includeContent`	bool	No	Specifies whether to return `content`. Default: `true`. Set this field to `false` to return metadata only.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md"
}

Response example

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

When includeContent=false, the response has the same structure but omits content. A content read of an empty file explicitly returns "content": "".

UpdateItem

Updates file content or renames a file. Provide exactly one of content and newPath. Providing both or neither returns 400 VALIDATION_ERROR.

Request parameters

Field	Type	Required	Description
`path`	string	Yes	The current file path.
`content`	string	Conditionally required	The new UTF-8 content, which can be an empty string. Mutually exclusive with `newPath`.
`newPath`	string	Conditionally required	The new path after the file is renamed. Mutually exclusive with `content`.
`overwrite`	bool	No	Specifies whether a rename can replace an existing destination file. Default: `false`.
`expectedSha256`	string	No	The current content digest. If this value does not match, the API returns `409 SHA_MISMATCH`.
`sessionId`	string	No	The caller session or operation identifier.

Update content example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers latte\n",
  "expectedSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece"
}

Rename example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "newPath": "/profile/user-preferences.md",
  "overwrite": false,
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

Both operations return the complete updated Item, including content. If expectedSha256 is omitted, the service performs a limited number of protected retries against the latest state instead of overwriting the file unconditionally. High concurrency can still result in 409 SHA_MISMATCH. If multiple writers modify the same path, pass the digest from the latest read.

DeleteItem

Deletes the current file and retains a queryable deletion version.

Request parameters

Field	Type	Required	Description
`path`	string	Yes	The path of the file to delete.
`expectedSha256`	string	No	The current content digest used for concurrency protection.
`sessionId`	string	No	The caller session or operation identifier.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/user-preferences.md",
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

Response example

{
  "type": "memoryfile"
}

ListItemVersions

Lists historical versions of a file in reverse chronological order with pagination. List entries do not include content.

Request parameters

Field	Type	Required	Description
`itemId`	string	Yes	The file ID.
`path`	string	No	The current file path. This field is typically not required.
`nextToken`	string	No	The opaque pagination token returned on the previous page.
`limit`	int	No	The number of entries per page. Default: `100`. Maximum: `500`.
`operation`	string	No	Filters by `created`, `modified`, or `deleted`.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "limit": 20
}

Response example

{
  "type": "memoryfile",
  "versions": [
    {
      "versionId": "fmver_019c12349999abcd5678",
      "itemId": "fmem_019c12345678abcd1234",
      "versionSeq": 1784786700123456,
      "operation": "modified",
      "path": "/profile/user-preferences.md",
      "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
      "contentSizeBytes": 31,
      "sessionId": "session-001",
      "createdAt": "2026-07-23T10:05:00Z"
    }
  ]
}

GetItemVersion

Retrieves a historical version. Provide itemId, versionId, and versionSeq from a list response.

Request parameters

Field	Type	Required	Description
`itemId`	string	Yes	The file ID.
`versionId`	string	Yes	The version ID.
`versionSeq`	int64	Yes	The version sequence number, which must be greater than `0`.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456
}

Response example

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "/profile/user-preferences.md",
  "content": "# User preferences\n\n- Prefers latte\n",
  "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
  "contentSizeBytes": 31,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z"
}

A redacted version still returns 200 and includes redaction and audit fields, but does not return content.

RedactItemVersion

Irreversibly redacts a historical version. Redaction does not modify the current file, change latestSeq, or create a new version.

Request parameters

Field	Type	Required	Description
`itemId`	string	Yes	The file ID.
`versionId`	string	Yes	The version ID.
`versionSeq`	int64	Yes	The version sequence number, which must be greater than `0`.
`sessionId`	string	No	The identifier of the redaction caller, recorded in `redactedBy`.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456,
  "sessionId": "privacy-job-001"
}

Response example

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "",
  "contentSha256": "",
  "contentSizeBytes": 0,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z",
  "redacted": true,
  "redactedAt": "2026-07-23T11:00:00Z",
  "redactedBy": "privacy-job-001"
}

Redaction requests are idempotent. A repeated request returns the current redaction state. redactedAt and redactedBy retain the values from the first successful request.

File capability differences

Operation	File memory	File views of structured memories
Add, update, rename, or delete	Supported	Returns `409 READ_ONLY_STORE`
List or read	Supported	Supported. `ListItems` returns `readOnly: true`.
List, read, or redact historical versions	Supported	Not available. Returns `400`.

Common file API errors

HTTP status code	Error code	Condition
`400`	`VALIDATION_ERROR`	The Item type, Scope, path, pagination cursor, update branch, or version parameters are invalid, or the current file view does not provide version capabilities.
`400`	`INVALID_PARAMETER`	An Item API is called for a memory store that does not provide file capabilities.
`404`	`NOT_FOUND`	The file or historical version does not exist.
`409`	`PATH_EXISTS`	The new path or rename destination already exists.
`409`	`SHA_MISMATCH`	`expectedSha256` does not match the current content, or a highly concurrent update cannot complete.
`409`	`LOCK_CONFLICT`	A concurrent change is in progress for the same Scope. Retry after a short backoff.
`409`	`QUOTA_EXCEEDED`	The file count in the current Scope has reached the limit.
`409`	`READ_ONLY_STORE`	A request attempts to modify a read-only file view generated from structured memories.
`413`	`PAYLOAD_TOO_LARGE`	The file content exceeds the per-file size limit.

If SHA_MISMATCH or LOCK_CONFLICT occurs, read the latest file before you decide whether to retry. For all file API limits, see Limitations and notes. For SDK integration, see Agent Storage SDK.