UpdateMemory 更新记忆 - 表格存储

使用 UpdateMemory 接口更新单条长期记忆，采用 PATCH 语义：未传字段保持不变；title 传空字符串、keywords 传空数组、metadata 传空对象可显式清空。至少传入一个可更新字段。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
Scope 规则：scope 为可选字段，提供时 4 个字段（appId、tenantId、agentId、runId）全部必填，不允许使用通配符 *。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`memoryId`	string	是	记忆 ID。
`scope`	object	否	可选的完整 Scope，用于校验记忆归属；提供时 4 个字段全部必填，不允许使用通配符 `*`。
`text`	string	否	新记忆文本。
`metadata`	object	否	要合并的字符串键值对；同名键覆盖原值，未传入的键保持不变，传 `{}` 清空全部 Metadata。限制见 [Metadata]。
`title`	string	否	新记忆名称，最多 64 个字符。
`keywords`	array	否	新关键词列表，最多 8 个，每项最多 32 个字符。
`effectiveAt`	string	与 `timePrecision` 同时提供	新生效时间。`second` 使用 RFC3339；`day`、`month`、`year` 分别使用 `YYYY-MM-DD`、`YYYY-MM`、`YYYY`。
`timePrecision`	string	与 `effectiveAt` 同时提供	`second`、`day`、`month` 或 `year`。

更新请求采用 PATCH 语义。发生并发冲突时，先重新读取当前记忆，再根据业务规则决定是否重试。

metadata 最多包含 16 个键，键最长 64 个 Unicode 字符，JSON 编码后的总大小不超过 65536 字节（UTF-8，64 KiB）。

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

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":"用户喜欢喝拿铁","keywords":["拿铁","咖啡","偏好"],"title":"用户咖啡偏好","metadata":{"source":"profile"}}'

响应

字段	说明
`memoryStoreName`	记忆库名称。
`updated`	是否成功更新。
`memory`	更新后的完整长期记忆单元。字段定义与《检索记忆》（SearchMemories）响应的 `results[].unit` 一致（采用 snake_case 命名，响应中不返回 embedding 向量）。

{
  "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": "用户喜欢喝拿铁",
    "keywords": ["拿铁", "咖啡", "偏好"],
    "metadata": { "source": "profile" },
    "title": "用户咖啡偏好",
    "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"
  }
}