AddMemories Write memories - Tablestore - Alibaba Cloud Documentation Center

Use the AddMemories operation to write conversation messages or text to a memory store that has inputType=messages. The service stores the original messages as short-term memory and asynchronously generates structured memory, read-only memory files, or both based on the outputTypes of the memory store.

Prerequisites

An AgentStorage instance has been created and is in the normal state, and the instance endpoint and instance name have been obtained.
An API Key has been created.
The inputType of the target memory store must be messages.
Scope rules: When you write data, appId is required, and wildcards (*) are not allowed. If other fields are omitted, they are set to __default__.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the target memory store.
`scope`	object	Yes	The scope. When you write data, `appId` is required, and wildcards (`*`) are not allowed.
`messages`	array	Either `text` or messages	An array of conversation messages. The array can contain up to 20 messages, and the total content length cannot exceed 32,000 bytes (UTF-8).
`text`	string	Either `messages` or text	The text content. The maximum length is 32,000 bytes (UTF-8).
`metadata`	object	No	Write-level string key-value pairs. Up to 16 keys are allowed. Each key can be up to 64 Unicode characters in length. The total size after JSON encoding cannot exceed 65,536 bytes (UTF-8, 64 KiB).
`sync`	boolean	No	Specifies whether to synchronously wait for structured memory generation to complete. Default value: `false`. If the memory store uses `file` output, this parameter must be set to `false`. Otherwise, the `400 INVALID_PARAMETER` error is returned.
`referenceTime`	string	No	The session reference time in RFC3339 format (an "as-of" anchor). After this parameter is set, messages that do not contain a `timestamp` use this time as the event time instead of the server time. This parameter applies to historical or batch import scenarios.

The limits of AddMemories are subject to Limitations and notes.

A successful write indicates that the service has received the messages. Whether all outputs have been generated is determined by the task status. For asynchronous calls, save the requestId from the response. Do not generate this field in the request body. After the files are generated, call ListItems with the exact scope, and then read the content by calling GetItem(view=full).

Request examples

When you use API Key authentication, pass the instance name and API Key in the x-ots-instancename and x-ots-apikey request headers.

curl -X POST https://<endpoint>/AddMemories \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "I like drinking coffee."
    },
    {
      "role": "assistant",
      "content": "OK, I noted that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": false
}'

Write text:

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

Response

Field	Description
`requestId`	The request ID.
`status`	The request status. Asynchronous writes typically return `running`.
`acceptedMessages`	The number of received messages.
`scope`	The scope used for the actual write.
`memoryStoreName`	The name of the memory store.
`memcellsCreated`	Returned for synchronous writes. Indicates the number of memory segments created.
`unitsCreated`	Returned for synchronous writes. Indicates the number of long-term memory units created.
`memoryIds`	Returned only when `sync=true`. An array of IDs of the successfully generated long-term memory. The order is the same as the final processing result, and the length is equal to `unitsCreated`. If no long-term memory is generated, an empty array is returned.

When the request specifies sync=true, you can directly obtain the generated long-term memory IDs from the memoryIds array in the response.

{
  "requestId": "req-001",
  "status": "completed",
  "acceptedMessages": 2,
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "memoryStoreName": "agent_memory",
  "memcellsCreated": 1,
  "unitsCreated": 1,
  "memoryIds": [
    "memory-001"
  ]
}