AddMemories 写入记忆 - 表格存储

使用 AddMemories 接口向 inputType=messages 的记忆库写入对话消息或文本。服务保存原始消息作为短期记忆，并根据记忆库的 outputTypes 异步生成结构化记忆、只读记忆文件或两种结果。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
目标记忆库的 inputType 必须为 messages。
Scope 规则：写入时 appId 必填，不允许使用通配符 *；其他字段省略时按 __default__ 处理。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	目标记忆库名称。
`scope`	object	是	Scope。写入时 `appId` 必填，不允许使用通配符 `*`。
`messages`	array	与 `text` 二选一	对话消息数组，最多 20 条；总内容长度不超过 32000 字节（UTF-8）。
`text`	string	与 `messages` 二选一	文本内容，最长 32000 字节（UTF-8）。
`metadata`	object	否	写入级字符串键值对，最多 16 个键，键最长 64 个 Unicode 字符；JSON 编码后的总大小不超过 65536 字节（UTF-8，64 KiB）。
`sync`	boolean	否	是否同步等待结构化记忆生成完成，默认 `false`。记忆库包含 `file` 输出时必须为 `false`，否则返回 `400 INVALID_PARAMETER`。
`referenceTime`	string	否	RFC3339 格式的会话基准时间（"as-of"锚点）。设置后，未携带 `timestamp` 的消息以该时间作为事件时间（而非服务器当前时间），适用于历史或批量导入场景。

AddMemories 的各项上限以使用限制为准。

写入成功表示服务已接收消息；是否已经生成全部输出以对应任务状态为准。异步调用方应保存响应中的 requestId，不要在请求体中自行生成该字段。文件生成完成后，使用精确 Scope 调用 ListItems，再通过 GetItem(view=full) 读取内容。

请求示例

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

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": "我喜欢喝咖啡"
    },
    {
      "role": "assistant",
      "content": "好的，我记住了"
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": false
}'

写入文本：

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "用户喜欢喝咖啡，偏好简洁的回答风格"
}

响应

字段	说明
`requestId`	请求 ID。
`status`	请求状态。异步写入通常返回 `running`。
`acceptedMessages`	接收的消息数量。
`scope`	实际写入使用的 Scope。
`memoryStoreName`	记忆库名称。
`memcellsCreated`	同步写入时返回，表示创建的记忆片段数量。
`unitsCreated`	同步写入时返回，表示创建的长期记忆单元数量。
`memoryIds`	仅在 `sync=true` 时返回。最终成功生成的长期记忆 ID 数组，顺序与最终处理结果一致，长度等于 `unitsCreated`；没有生成长期记忆时返回空数组。

当请求指定 sync=true 时，可以直接从响应的 memoryIds 数组获取生成的长期记忆 ID。

{
  "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"
  ]
}