Memory Storage API: Specifications, parameters, and scope requirements - Tablestore

The Memory Storage Service offers 13 APIs via the HTTP JSON protocol, covering memory store management, long-term memory reads and writes, short-term memory, and audit queries for custom integrations without an SDK.

API list

The following APIs are categorized by function.

Memory store management

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

Long-term memory

API	Description
`AddMemories`	Adds conversation messages or text and generates long-term memories.
`SearchMemories`	Searches long-term memories.
`ListMemories`	Lists long-term memories.
`GetMemory`	Retrieves a long-term memory.
`UpdateMemory`	Updates a long-term memory.
`DeleteMemory`	Deletes a long-term memory.

Short-term memory and audit

API	Description
`ListMemoryStoreMessages`	Queries short-term memories (raw session messages).
`ListMemoryStoreRequests`	Queries the request audit records of a memory store.

Common objects

The memory store APIs reuse the following data structures in requests and responses.

Scope

A Scope represents the ownership hierarchy for memory data and contains four fields.

Parameter	Type	Description
`appId`	string	The application ID.
`tenantId`	string	The tenant or user ID.
`agentId`	string	The Agent ID.
`runId`	string	The session, run, or task ID.

Scope field requirements and support for the * wildcard vary by API.

Scenario	Required fields	Wildcard `` rules*
Write (`AddMemories`)	`appId`	If optional fields are empty, they default to `__default__`. The `*` wildcard is not allowed.
Search long-term memory (`SearchMemories`)	`appId`, `tenantId`	The `*` wildcard can be used for `agentId` and `runId`.
Query short-term memory (`ListMemoryStoreMessages`)	All four Scope fields are required.	The `*` wildcard is not allowed.
Get, update, or delete a single long-term memory (`GetMemory`, `UpdateMemory`, `DeleteMemory`)	All four Scope fields are required.	The `*` wildcard is not allowed.
List query (`ListMemories`, `ListMemoryStoreRequests`)	`appId`	The `*` wildcard can be used hierarchically.

Example:

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

Message

For the AddMemories API, the messages field uses the following structure.

Parameter	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	Timestamp in RFC3339 format.
`metadata`	object	No	Message-level metadata. Both keys and values are strings.

Metadata

Metadata consists of string key-value pairs that function as business tags. Search APIs use this metadata for exact match filtering.

Limit	Value
Maximum keys per request	16
Maximum key length	64 characters
Maximum value length	1024 characters

Example:

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

CreateMemoryStore

Creates a memory store.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store. It must be no longer than 32 characters and contain only letters, numbers, and underscores (_).
`description`	string	No	An optional description of the memory store, with a maximum length of 1024 characters.

Request example

{
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent"
}

GetMemoryStore

Returns the details of a memory store.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	true	The name of the memory store.

Request example

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

Updates the description of a memory store.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`description`	string	Yes	The new description, with a maximum length of 1024 characters.

DeleteMemoryStore

Deletes a memory store.

Warning

This is an irreversible operation that permanently deletes the memory store and all its data. Use caution in a production environment.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store to delete.

ListMemoryStores

Lists memory stores.

Request parameters

Parameter	Type	Required	Description
`limit`	int	No	The number of memory stores to return.
`nextToken`	string	No	A token to retrieve the next page of results.

AddMemories

Writes dialogue messages or text. The service saves the original messages as short-term memory and extracts long-term memory from the input.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the target memory store.
`scope`	object	Yes	Scope. For write operations, `appId` is required, and the wildcard `*` is not allowed.
`messages`	array	Required if `text` is not provided	An array of dialogue messages. A maximum of 20 messages, with a total content length of up to 32,000 characters.
`text`	string	Required if `messages` is not provided	The text content. Maximum length: 32,000 characters.
`metadata`	object	No	Metadata for the write operation. A maximum of 16 key-value pairs. Keys are limited to 64 characters, and values are limited to 1,024 characters.
`sync`	boolean	No	Specifies whether to wait for the memory extraction to complete synchronously. Defaults to `false`.

For a full list of limits, see Limits and Notes.

Request example: add 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": "Okay, I'll remember that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": true
}

Request example: add text

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

Response parameters

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

SearchMemories

Retrieves long-term memory.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the target memory store.
`query`	string	Yes	The query text.
`scope`	object	Yes	Scope. When you perform a retrieval, you must provide `appId` and `tenantId`. For `agentId` and `runId`, you can use the wildcard `*`.
`topK`	int	No	The number of items to return, with a default value of `10` and a value range of `1 to 50`.
`enableRerank`	boolean	No	Specifies whether to enable Rerank. The default is `true`.
`metadata`	object	No	A metadata filter for exact-match queries. Both keys and values are strings.

For a full description of the upper limit for topK, see Limits and notes.

Request example

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

Response fields

Field	Description
`results`	A list of search results.
`results[].unit`	A long-term memory unit. See the table below for a description of its fields.
`results[].score`	The relevance score.
`scope`	The scope used for the query.
`memoryStoreName`	The name of the memory store.

The internal fields of results[].unit are as follows.

Field	Description
`id`	The long-term memory unit ID.
`conversation_key`	The associated conversation key.
`scope`	The Scope of the memory is an object with four fields: `appId`, `tenantId`, `agentId`, and `runId`.
`memcell_id`	The memory cell ID.
`unit_type`	The memory unit type.
`text`	The memory text.
`search_text`	The text used for retrieval.
`source_turn_ids`	A list of source message IDs.
`type_label`	The type label.
`date_bucket`	The date bucket.
`metadata_json`	The metadata, as a JSON string.
`deleted`	Indicates whether the unit is deleted.
`created_at`	The creation time.
`salience`	The salience score.
`version`	The version number.

ListMemories

Lists long-term memories.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`scope`	object	Yes	Scope. `appId` and `tenantId` are required. You can use the wildcard character `*` for `agentId` and `runId`.
`limit`	int	No	The maximum number of long-term memories to return.
`nextToken`	string	No	A token to retrieve the next page of results.

Request example

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

GetMemory

Retrieves a single long-term memory.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The memory store name.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	For a full Scope, all 4 fields are required, and the wildcard character `*` is not allowed.

UpdateMemory

Updates a single long-term memory. You must provide at least one of text or metadata.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	For a complete Scope, all 4 fields are required, and the wildcard character `*` is not allowed.
`text`	string	No	The new memory text.
`metadata`	object	No	The new metadata.

DeleteMemory

Deletes a single long-term memory item.

Warning

Deleting a long-term memory item is an irreversible operation. Proceed with caution in a production environment.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`memoryId`	string	Yes	The memory ID.
`scope`	object	Yes	A complete scope requires all four fields and does not allow the wildcard character `*`.

ListMemoryStoreMessages

Lists raw session messages from the short-term memory.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`scope`	object	Yes	For a complete Scope, all 4 fields are required, and wildcards such as `*` are not allowed.
`limit`	int	No	The maximum number of messages to return.
`nextToken`	string	No	The token for the next page of results.
`minTimestamp`	string	No	The minimum timestamp, in RFC3339 format.
`maxTimestamp`	string	No	The maximum timestamp, in RFC3339 format.

Request example

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

ListMemoryStoreRequests

Queries the request audit records for a memory store.

Request parameters

Parameter	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`scope`	object	Yes	Scope. You can use the wildcard `*` hierarchically.
`operation`	string	No	The operation name, such as `AddMemories` or `SearchMemories`.
`limit`	int	No	The maximum number of records to return.
`nextToken`	string	No	The token for the next page of results.
`minTimestamp`	string	No	The minimum timestamp, in RFC 3339 format.
`maxTimestamp`	string	No	The maximum timestamp, in RFC 3339 format.

Request example

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

Response parameters

Parameter	Description
`requestId`	The request ID.
`operation`	The operation name.
`scope`	The scope of the request.
`requestSummary`	The request summary.
`responseStatus`	The response status.
`latencyMs`	The latency in milliseconds.
`targetId`	The ID of the operation target, such as a memory ID.
`createdAt`	The time when the record was created.