記憶儲存服務 HTTP JSON 介面規範、參數與 Scope 必填規則速查 - Tablestore

記憶儲存服務通過 HTTP JSON 協議提供 13 個介面，覆蓋記憶庫管理、長期記憶讀寫、短期記憶與審計查詢，適用於無 SDK 的自訂整合情境。

介面列表

按功能分類，全部介面如下。

記憶庫管理

介面	說明
`CreateMemoryStore`	建立記憶庫。
`GetMemoryStore`	擷取記憶庫詳情。
`UpdateMemoryStore`	更新記憶庫描述。
`DeleteMemoryStore`	刪除記憶庫。
`ListMemoryStores`	列出記憶庫。

長期記憶

介面	說明
`AddMemories`	寫入對話訊息或文本，並產生長期記憶。
`SearchMemories`	檢索長期記憶。
`ListMemories`	列出長期記憶。
`GetMemory`	擷取單條長期記憶。
`UpdateMemory`	更新單條長期記憶。
`DeleteMemory`	刪除單條長期記憶。

短期記憶與審計

介面	說明
`ListMemoryStoreMessages`	查詢短期記憶，即原始會話訊息。
`ListMemoryStoreRequests`	查詢記憶程式庫要求審計記錄。

通用對象

記憶庫介面在請求和響應中複用以下資料結構。

Scope

Scope 表示記憶資料的歸屬層級，由四級欄位組成。

欄位	類型	說明
`appId`	string	應用標識。
`tenantId`	string	租戶或使用者標識。
`agentId`	string	Agent 標識。
`runId`	string	會話、運行或任務標識。

不同介面對 Scope 欄位的必填性和萬用字元 * 支援規則不同。

情境	必要欄位	萬用字元 `*` 規則
寫入（`AddMemories`）	`appId`	其他欄位為空白時補 `__default__`，不允許使用 `*`。
檢索長期記憶（`SearchMemories`）	`appId`、`tenantId`	`agentId` 和 `runId` 可使用 `*`。
查詢短期記憶（`ListMemoryStoreMessages`）	四級 Scope 全部必填	不允許使用 `*`。
擷取、更新、刪除單條長期記憶（`GetMemory`、`UpdateMemory`、`DeleteMemory`）	四級 Scope 全部必填	不允許使用 `*`。
列表查詢（`ListMemories`、`ListMemoryStoreRequests`）	`appId`	支援按層級使用 `*`。

樣本：

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

Message

AddMemories 介面的 messages 欄位使用以下結構。

欄位	類型	必填	說明
`role`	string	是	訊息角色，例如 `user`、`assistant`、`system`。
`content`	string	是	訊息內容。
`messageId`	string	否	訊息 ID，最長 256 個字元。
`timestamp`	string	否	RFC3339 格式時間。
`metadata`	object	否	訊息級中繼資料，鍵和值均為字串。

Metadata

Metadata 為字串索引值對，用於附加業務標籤。在檢索介面中，Metadata 用於字串索引值的精確匹配過濾。

限制項	取值
單次請求最多鍵數	16 個
鍵長度上限	64 個字元
值長度上限	1024 個字元

樣本：

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

CreateMemoryStore

建立一個記憶庫。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱，只能包含字母、數字和底線，最長 32 個字元。
`description`	string	否	記憶庫描述，最長 1024 個字元。

請求樣本

{
  "memoryStoreName": "agent_memory",
  "description": "Agent 長期記憶庫"
}

GetMemoryStore

擷取記憶庫詳情。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。

請求樣本

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

更新記憶庫描述。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`description`	string	是	新描述，最長 1024 個字元。

DeleteMemoryStore

刪除記憶庫。

警告

刪除記憶庫會一併刪除該記憶庫下的全部資料，操作無法復原。生產環境請謹慎執行。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。

ListMemoryStores

列出記憶庫。

請求參數

欄位	類型	必填	說明
`limit`	int	否	返回數量。
`nextToken`	string	否	下一頁標記。

AddMemories

寫入對話訊息或文本。服務儲存原始訊息作為短期記憶，並從輸入中提取長期記憶。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	目標記憶庫名稱。
`scope`	object	是	Scope。寫入時 `appId` 必填，不允許使用萬用字元 `*`。
`messages`	array	與 `text` 二選一	對話訊息數組，最多 20 條；總內容長度不超過 32000 個字元。
`text`	string	與 `messages` 二選一	常值內容，最長 32000 個字元。
`metadata`	object	否	寫入級中繼資料，最多 16 個鍵，鍵最長 64 個字元，值最長 1024 個字元。
`sync`	boolean	否	是否同步等待記憶抽取完成，預設 `false`。

各項上限的完整說明，請參見限制與注意事項。

請求樣本：寫入訊息

{
  "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": true
}

請求樣本：寫入文本

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "使用者喜歡喝咖啡，偏好簡潔的回答風格"
}

響應欄位

欄位	說明
`requestId`	請求 ID。
`status`	請求狀態。非同步寫入通常返回 `running`。
`acceptedMessages`	接收的訊息數量。
`scope`	實際寫入使用的 Scope。
`memoryStoreName`	記憶庫名稱。
`memcellsCreated`	同步寫入時返回，表示建立的記憶片段數量。
`unitsCreated`	同步寫入時返回，表示建立的長期記憶單元數量。

SearchMemories

檢索長期記憶。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	目標記憶庫名稱。
`query`	string	是	查詢文本。
`scope`	object	是	Scope。檢索時 `appId` 和 `tenantId` 必填，`agentId` 和 `runId` 可使用萬用字元 `*`。
`topK`	int	否	返回數量，預設 `10`，取值範圍 `1~50`。
`enableRerank`	boolean	否	是否啟用 Rerank，預設 `true`。
`metadata`	object	否	中繼資料精確匹配過濾條件，鍵和值均為字串。

topK 取值上限的完整說明，請參見限制與注意事項。

請求樣本

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "query": "使用者喜歡什麼飲品",
  "topK": 5,
  "enableRerank": true,
  "metadata": {
    "source": "chat"
  }
}

響應欄位

欄位	說明
`results`	檢索結果清單。
`results[].unit`	長期記憶單元，欄位定義見下表。
`results[].score`	相關性分數。
`scope`	查詢使用的 Scope。
`memoryStoreName`	記憶庫名稱。

results[].unit 內部欄位如下。

欄位	說明
`id`	長期記憶單元 ID。
`conversation_key`	關聯的會話鍵。
`scope`	記憶所屬 Scope，對象包含 `appId`、`tenantId`、`agentId`、`runId` 四個欄位。
`memcell_id`	記憶片段 ID。
`unit_type`	記憶單元類型。
`text`	記憶文本。
`search_text`	用於檢索的文本。
`source_turn_ids`	來源訊息 ID 列表。
`type_label`	類型標籤。
`date_bucket`	日期分桶。
`metadata_json`	中繼資料，JSON 字串。
`deleted`	是否已刪除。
`created_at`	建立時間。
`salience`	顯著性分數。
`version`	版本號碼。

ListMemories

列出長期記憶。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`scope`	object	是	Scope。`appId` 和 `tenantId` 必填，`agentId` 和 `runId` 可使用萬用字元 `*`。
`limit`	int	否	返回數量。
`nextToken`	string	否	下一頁標記。

請求樣本

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

GetMemory

擷取單條長期記憶。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`memoryId`	string	是	記憶 ID。
`scope`	object	是	完整 Scope，4 欄位全部必填，不允許使用萬用字元 `*`。

UpdateMemory

更新單條長期記憶。text 和 metadata 至少提供一個。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`memoryId`	string	是	記憶 ID。
`scope`	object	是	完整 Scope，4 欄位全部必填，不允許使用萬用字元 `*`。
`text`	string	否	新記憶文本。
`metadata`	object	否	新中繼資料。

DeleteMemory

刪除單條長期記憶。

警告

刪除單條長期記憶為無法復原操作。生產環境請謹慎執行。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`memoryId`	string	是	記憶 ID。
`scope`	object	是	完整 Scope，4 欄位全部必填，不允許使用萬用字元 `*`。

ListMemoryStoreMessages

查詢短期記憶，即原始會話訊息。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`scope`	object	是	完整 Scope，4 欄位全部必填，不允許使用萬用字元 `*`。
`limit`	int	否	返回數量。
`nextToken`	string	否	下一頁標記。
`minTimestamp`	string	否	最小時間，RFC3339 格式。
`maxTimestamp`	string	否	最大時間，RFC3339 格式。

請求樣本

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

ListMemoryStoreRequests

查詢記憶程式庫要求審計記錄。

請求參數

欄位	類型	必填	說明
`memoryStoreName`	string	是	記憶庫名稱。
`scope`	object	是	Scope，可按層級使用萬用字元 `*`。
`operation`	string	否	操作名稱，例如 `AddMemories` 或 `SearchMemories`。
`limit`	int	否	返回數量。
`nextToken`	string	否	下一頁標記。
`minTimestamp`	string	否	最小時間，RFC3339 格式。
`maxTimestamp`	string	否	最大時間，RFC3339 格式。

請求樣本

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

響應欄位

欄位	說明
`requestId`	請求 ID。
`operation`	操作名稱。
`scope`	請求使用的 Scope。
`requestSummary`	請求摘要。
`responseStatus`	響應狀態。
`latencyMs`	處理耗時，單位毫秒。
`targetId`	操作目標 ID，例如記憶 ID。
`createdAt`	記錄建立時間。