記憶體 API 參考

此頁面是管理代理記憶體的 REST API 參考。它涵蓋了管理記憶體的端點、請求欄位與回應欄位：

記憶體儲存是一種 Unity 目錄可保護的可儲存裝置，作為記憶體條目的容器。使用 Memory store API 來建立和管理儲存庫。
記憶體條目是儲存在記憶體儲存中的單一內容。使用 Memory entry API 來讀寫條目。
對話是 OpenAI 相容的對話狀態——訊息與工具呼叫——由記憶體儲存支持並釘選為範圍。使用 Conversation API 來建立和管理對話及其項目。

先決條件

使用 Databricks CLI 產生 OAuth 令牌以呼叫 API：

databricks auth login --host ${DATABRICKS_HOST}
databricks auth token

記憶體儲存 API

記憶體儲存是一種 Unity 目錄可保護的可儲存裝置，作為記憶體條目的容器。記憶體儲存使用三層命名： catalog.schema.memory_store_name。

運算	終點	必要特權
創造	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` 在父結構描述中
獲取	`GET /api/2.1/unity-catalog/memory-stores/{full_name}`	`READ MEMORY STORE` 在商店裡
清單	`GET /api/2.1/unity-catalog/memory-stores`	`USE SCHEMA` 在父結構描述中
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` 在商店裡
Delete	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` 在商店裡

建立記憶體儲存

在父架構下建立新的記憶體儲存。

端點：POST /api/2.1/unity-catalog/memory-stores
必要權限： CREATE MEMORY STORE 在父架構上

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Memory store for customer support agents"
  }'

請求欄位：

Field	類型	必須	Description
`name`	`string`	Yes	記憶儲存的簡稱。必須匹配 `[A-Za-z0-9_-]+`，1-255 字元。在父架構中獨一無二。
`catalog_name`	`string`	Yes	母目錄名稱。
`schema_name`	`string`	Yes	相對於目錄的父結構名稱。
`description`	`string`	No	人類可讀的記憶儲存描述。

建立一個記憶儲存

透過三部分的完全限定名稱檢索記憶體儲存。

端點：GET /api/2.1/unity-catalog/memory-stores/{full_name}
必要權限： READ MEMORY STORE 在店裡

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

請列出記憶體儲存器

在結構中列出記憶體儲存。結果會被篩選到來電者能閱讀的儲存庫。

端點：GET /api/2.1/unity-catalog/memory-stores
必要權限： USE SCHEMA 在父架構上

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores?catalog_name=main&schema_name=default" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

查詢參數：

Parameter	類型	必須	Description
`catalog_name`	`string`	Yes	母目錄名稱。
`schema_name`	`string`	Yes	父架構名稱。
`page_token`	`string`	No	分頁標記來自之前的回覆。
`max_results`	`integer`	No	每頁最大儲存數。預設是100，最高1000。

更新記憶體儲存

更新記憶體儲存庫上的可變欄位。目前只有 description 可變。

端點：PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
必要權限： MANAGE 在店裡

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": {
      "description": "Updated description for the memory store"
    },
    "update_mask": "description"
  }'

刪除記憶體儲存

刪除一個記憶體儲存及其所有記憶體條目。

端點：DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
必要權限： MANAGE 在店裡

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

記憶體儲存回應欄位

Field	類型	Description
`name`	`string`	記憶儲存的簡稱。
`catalog_name`	`string`	母目錄名稱。
`schema_name`	`string`	父架構名稱。
`description`	`string`	人類易讀的描述。
`owner`	`string`	UC校長擁有這家店。設定在創建。
`full_name`	`string`	三部分完整限定名稱： `catalog.schema.name`
`memory_store_id`	`string`	伺服器指派的 UUID。
`securable_type`	`string`	一律為 `MEMORY_STORE`。
`created_at`	`integer`	建立時間以 Unix 紀元毫秒計算。
`updated_at`	`integer`	最後更新時間以 Unix 百萬毫秒計。
`created_by`	`string`	創立這家店的校長。

記憶體輸入 API

記憶體條目是儲存在記憶體儲存中的各個內容片段。每個項目由 作用域 與路徑識別： scope 是呼叫者指派的分割鍵（例如終端使用者 ID）， path 是該範圍內必須以 /memories/ 為起始的軟路徑（例如， /memories/preferences.md）。 scope 每個記憶體輸入請求都必須如此。

運算	終點	必要特權
創造	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` 在商店裡
獲取	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get`	`READ MEMORY STORE` 在商店裡
清單	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`READ MEMORY STORE` 在商店裡
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` 在商店裡
Delete	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` 在商店裡
搜尋	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search`	`READ MEMORY STORE` 在商店裡

建立記憶體條目

在記憶體儲存中建立新的記憶體條目。

端點：POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
必要權限： WRITE MEMORY STORE 在店裡

scope 是一個查詢參數;請求主體就是條目本身。

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "The user prefers responses in English and uses formal tone.",
    "description": "User language and tone preferences"
  }'

請求欄位：

Field	在	類型	必須	Description
`scope`	查詢	`string`	Yes	分區由呼叫者指派，該條目屬於（例如終端使用者 ID）。
`path`	body	`string`	Yes	軟路徑標示範圍內的條目。必須以 `/memories/`開頭。不可改變。
`contents`	body	`string`	No	自由形式的記憶文字內容。
`description`	body	`string`	No	記憶條目的一行摘要。作為清單回應中的索引鉤子。

取得記憶條目

可透過和 scope取得單一記憶體條目path。

端點：GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
必要權限： READ MEMORY STORE 在店裡

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:get?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

清單記憶體條目

在作用波中列出記憶體條目。

端點：GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
必要權限： READ MEMORY STORE 在店裡

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

查詢參數：

Parameter	類型	必須	Description
`scope`	`string`	Yes	範圍（分割區）用來列出從中列入的項目。
`path_prefix`	`string`	No	僅回傳路徑以此前綴開頭的條目。
`page_size`	`integer`	No	每頁最多條目數。伺服器會限制頁面大小。
`page_token`	`string`	No	分頁標記來自之前的回覆。

列表回應會contents省略（僅元資料），並在還有更多頁面時加入。next_page_token

更新記憶體條目

對現有條目 contents、及 scopepath進行單一編輯操作。提供其中一個str_replace、insertreplace_all或。 description 可編輯：設定它取代條目的描述，或省略以保持描述不變。

端點：PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
必要權限： WRITE MEMORY STORE 在店裡

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "path": "/memories/preferences.md",
    "replace_all": { "contents": "The user prefers responses in Spanish and uses casual tone." }
  }'

編輯操作 （設定恰好一個：

運算	Fields	行為
`replace_all`	`contents`	覆寫該條目的完整內容。
`str_replace`	`old_str`、`new_str`	將單一出現的替 `old_str` 換為 `new_str` （必須恰好匹配一次）。
`insert`	`insert_line`、`insert_text`	插入 `insert_text`; `insert_line` 0 = 頂部，省略 = 附加到末尾。

刪除記憶體條目

刪除一個以和 scopepath為標示的記憶體條目。

端點：DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
必要權限： WRITE MEMORY STORE 在店裡

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

搜尋記憶體條目

依關鍵字搜尋路徑、內容及描述欄位的記憶體條目。

端點：POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
必要權限： READ MEMORY STORE 在店裡

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "query": "language preferences"
  }'

請求欄位： scope （必需）、 query （必填）、 path_prefix （可選）、 top_k （可選;預設為 10，最多 50）。

記憶體輸入回應欄位

Field	類型	Description
`path`	`string`	入口在其範圍內的柔和路徑。
`contents`	`string`	記憶文字。在清單回覆中省略。
`description`	`string`	一句話總結。
`scope`	`string`	該條目所屬的範圍（分割區）。
`memory_store_name`	`string`	父記憶體儲存的三部分名稱。
`has_contents`	`boolean`	該條目是否為非空 `contents` （在 List 中有用）。
`create_time`	`string`	建立時間戳記（RFC 3339）。
`update_time`	`string`	最後更新時間戳記（RFC 3339）。

對話 API

對話會將相容於 OpenAI 的對話狀態——訊息、工具呼叫及其他項目——在單一範圍內儲存在記憶體中。透過對話，代理會持續存在並重新載入伺服器端的會話狀態。你要在記憶體儲存（三部分名稱）和一個 scope、之間建立每一次對話，而對話操作需要與底層記憶儲存相同的權限。

運算	終點	必要特權
創造	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` 在商店裡
獲取	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` 在商店裡
Update	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` 在商店裡
Delete	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` 在商店裡

建立對話

建立綁定到記憶體儲存區和作用域的對話。

端點：POST /api/2.1/unity-catalog/conversations
必要權限： WRITE MEMORY STORE 在店裡

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": { "name": "main.default.support_agent_memory" },
    "scope": { "kind": "user", "value": "user-123" },
    "metadata": { "source": "support-chat" }
  }'

請求欄位：

Field	類型	必須	Description
`memory_store`	`object`	Yes	記憶儲存支持對話。
`memory_store.name`	`string`	Yes	記憶體儲存的三部分全限定名稱： `catalog.schema.memory_store`。
`scope`	`object`	Yes	討論範圍。
`scope.kind`	`string`	Yes	例如 `user` 範圍類型，或 `user_defined`。
`scope.value`	`string`	Yes	類別特定的範圍值，例如終端使用者 ID。
`metadata`	`object`	No	來電者控制的鍵值元資料。最多可達16鍵;鍵碼最多 64 字元，數值最高可達 512 字元。
`items`	`array`	No	初始的 OpenAI 對話項目用來播種對話（最多 20 個）。沒有的 `type` 項目會以訊息項目形式儲存。

聊聊吧

透過 ID 擷取對話。

端點：GET /api/2.1/unity-catalog/conversations/{conversation_id}
必要權限： READ MEMORY STORE 在店裡

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

更新對話

更新對話的 metadata.

端點：POST /api/2.1/unity-catalog/conversations/{conversation_id}
必要權限： WRITE MEMORY STORE 在店裡

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "source": "support-chat", "resolved": "true" } }'

刪除對話

刪除對話及其相關內容。

端點：DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
必要權限： WRITE MEMORY STORE 在店裡

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

對話回應欄位

Field	類型	Description
`id`	`string`	伺服器分配的對話 ID。
`object`	`string`	一律為 `conversation`。
`created_at`	`integer`	建立時間以 Unix 紀元秒計算。
`metadata`	`object`	呼叫者提供的鍵值元資料。

對話項目 API

項目是對話中個別的訊息和工具呼叫。它們遵循 OpenAI 對話項目的形狀，並使用 OpenAI 相容的頁碼（after， limit， has_more）。

運算	終點	必要特權
建立項目	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` 在商店裡
取得項目	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` 在商店裡
清單項目	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` 在商店裡
刪除項目	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` 在商店裡

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-01

記憶體 API 參考

先決條件

記憶體儲存 API

建立記憶體儲存

建立一個記憶儲存

請列出記憶體儲存器

更新記憶體儲存

刪除記憶體儲存

記憶體儲存回應欄位

記憶體輸入 API

建立記憶體條目

取得記憶條目

清單記憶體條目

更新記憶體條目

刪除記憶體條目

搜尋記憶體條目

記憶體輸入回應欄位

對話 API

建立對話

聊聊吧

更新對話

刪除對話

對話回應欄位

對話項目 API

意見反應

其他資源