UpdateMemory Update a memory - Tablestore - Alibaba Cloud Documentation Center

Use the UpdateMemory operation to update a single long-term memory. This operation uses PATCH semantics: fields that are not sent remain unchanged. Pass an empty string for title, an empty array for keywords, or an empty object for metadata to explicitly clear the value. You must specify at least one updatable field.

Prerequisites

An AgentStorage instance has been created and is in the normal state, and you have obtained the instance endpoint and instance name.
An API Key has been created.
Scope rules: scope is optional. When provided, all four fields (appId, tenantId, agentId, and runId) are required, and the wildcard character * is not allowed.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`memoryId`	string	Yes	The memory ID.
`scope`	object	No	The optional full scope used to verify the ownership of the memory. When provided, all four fields are required, and the wildcard character `*` is not allowed.
`text`	string	No	The new memory text.
`metadata`	object	No	The string key-value pairs to merge. Keys with the same name overwrite the original values, keys that are not sent remain unchanged, and passing `{}` clears all metadata. For limits, see [Metadata].
`title`	string	No	The new memory title, up to 64 characters.
`keywords`	array	No	The new keyword list, up to 8 keywords, with each item up to 32 characters.
`effectiveAt`	string	Must be provided together with `timePrecision`	The new effective time. Use RFC3339 for `second`. Use `YYYY-MM-DD`, `YYYY-MM`, and `YYYY` for `day`, `month`, and `year` respectively.
`timePrecision`	string	Must be provided together with `effectiveAt`	One of `second`, `day`, `month`, or `year`.

The update request uses PATCH semantics. When a concurrency conflict occurs, re-read the current memory first, and then decide whether to retry based on your business rules.

The metadata field can contain up to 16 keys. Each key can be up to 64 Unicode characters long, and the total size after JSON encoding must not exceed 65536 bytes (UTF-8, 64 KiB).

Request example

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>/UpdateMemory \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"memoryStoreName":"agent_memory","memoryId":"<memory-id>","scope":{"appId":"app-001","tenantId":"user-001","agentId":"assistant","runId":"session-001"},"text":"The user likes lattes.","keywords":["latte","coffee","preference"],"title":"User coffee preference","metadata":{"source":"profile"}}'

Response

Field	Description
`memoryStoreName`	The name of the memory store.
`updated`	Whether the update succeeded.
`memory`	The complete long-term memory unit after the update. Its field definitions are the same as `results[].unit` in the SearchMemories response (snake_case naming; the embedding vector is not returned).

{
  "memoryStoreName": "agent_memory",
  "updated": true,
  "memory": {
    "id": "1b88d0d65a5b6c0d9142e9b7c7347048",
    "conversation_key": "app-001/user-001/assistant/session-001",
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "unit_type": "entity_fact",
    "text": "The user likes lattes.",
    "keywords": ["latte", "coffee", "preference"],
    "metadata": { "source": "profile" },
    "title": "User coffee preference",
    "version": 2,
    "salience": 0.8,
    "effective_at": "2026-08-25T05:52:19Z",
    "time_precision": "second",
    "created_at": "2026-08-25T05:52:19.185Z",
    "updated_at": "2026-09-23T11:50:02.679Z"
  }
}