メモリAPIリファレンス

このページは、マネージドエージェントメモリのREST APIリファレンスです。マネージドメモリのエンドポイント、リクエストフィールド、およびレスポンスフィールドについて説明します：

メモリストア は、メモリのエントリのコンテナとして機能するUnity Catalogのセキュリティ保護可能なオブジェクトです。メモリストアAPIを使用して、ストアを作成および管理します。
**メモリエントリー**は、メモリストア内に保存される個々のコンテンツです。エントリーの読み取りと書き込みを行うには、メモリエントリーAPIを使用します。
**会話**とは、メモリストアに裏打ちされ、スコープにピン留めされた、OpenAI互換の会話状態（メッセージとツール呼び出し）のことです。Conversation APIsを使用して、会話とその項目を作成および管理します。

前提条件

Databricks CLIを使用してAPIを呼び出すOAuthトークンを生成します：

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

メモリストアAPI

メモリストアは、メモリエントリのコンテナとして機能するUnity Catalogのセキュリティ保護可能なオブジェクトです。メモリストアは、3レベルの名前付けを使用します：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` 親スキーマ上。
更新	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` ストアで
削除	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` ストアで

メモリストアを作成

親スキーマの下に新しいメモリストアを作成します。

エンドポイント : POST /api/2.1/unity-catalog/memory-stores
必須の権限 : 親スキーマに対するCREATE MEMORY STOREです。

Bash
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"
  }'

リクエストフィールド：

フィールド	Type	必須	説明
`name`	`string`	はい	メモリストアの短縮名。`[A-Za-z0-9_-]+`と一致する必要があり、1～255文字です。親スキーマ内で一意です。
`catalog_name`	`string`	はい	親カタログの名前。
`schema_name`	`string`	はい	カタログに対する親スキーマの名前です。
`description`	`string`	No	メモリストアの人間にとってわかりやすい説明です。

メモリストアを取得します

3つの部分からなる完全修飾名でメモリストアを取得します。

エンドポイント : GET /api/2.1/unity-catalog/memory-stores/{full_name}
必要な権限 ：ストアのREAD MEMORY STORE

Bash
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です。

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

クエリーパラメーター：

パラメーター	Type	必須	説明
`catalog_name`	`string`	はい	親カタログ名。
`schema_name`	`string`	はい	親スキーマ名。
`page_token`	`string`	No	以前のレスポンスからのページネーショントークン
`max_results`	`integer`	No	ページあたりの最大ストア数。デフォルトは100、最大は1000です。

メモリストアを更新する

メモリストアの変更可能なフィールドを更新します。現在、descriptionのみが変更可能です。

エンドポイント : PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
必要な権限 ：ストアのMANAGE

Bash
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

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

メモリストア応答フィールド

フィールド	Type	説明
`name`	`string`	メモリストアの短縮名です。
`catalog_name`	`string`	親カタログ名。
`schema_name`	`string`	親スキーマ名。
`description`	`string`	人間が読める説明
`owner`	`string`	ストアを所有するUCプリンシパル。作成時に設定されます。
`full_name`	`string`	3部構成の完全修飾名: `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` ストアで
更新	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` ストアで
削除	`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 はクエリパラメーターです。リクエストボディはエントリ自体です。

Bash
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"
  }'

リクエストフィールド：

フィールド	残存有効時間：	Type	必須	説明
`scope`	クエリー	`string`	はい	エントリが属するパーティション（呼び出し元によって割り当てられます。たとえば、エンドユーザーID）。
`path`	本文	`string`	はい	スコープ内でエントリを識別するソフトパス。`/memories/`で始まる必要があります。不変。
`contents`	本文	`string`	No	自由形式のメモリテキストコンテンツ。
`description`	本文	`string`	No	メモリ入力の1行要約リストレスポンスのインデックスフックとして機能します。

メモリのエントリを取得

scopeとpathで単一のメモリエントリを取得します。

エンドポイント : GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
必要な権限 ：ストアのREAD MEMORY STORE

Bash
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

Bash
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}"

クエリーパラメーター：

パラメーター	Type	必須	説明
`scope`	`string`	はい	エントリを一覧表示するスコープ（パーティション）。
`path_prefix`	`string`	No	パスがこのプレフィックスで始まるエントリのみを返します。
`page_size`	`integer`	No	1ページあたりの最大エントリ数。サーバーはページサイズに上限を設定します。
`page_token`	`string`	No	以前のレスポンスからのページネーショントークン

リスト応答はcontents (メタデータのみ) を省略し、さらにページが残っている場合はnext_page_tokenを含めます。

メモリのエントリを更新

scopeとpathで識別される既存エントリのcontentsに、単一の編集操作を適用します。str_replace、insert、replace_allのいずれか1つを指定してください。descriptionは編集可能です。エントリの説明を置き換えるように設定するか、または省略して説明を変更しないままにします。

エンドポイント : PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
必要な権限 ：ストアのWRITE MEMORY STORE

Bash
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." }
  }'

編集操作 (いずれか1つを設定):

オペレーション	フィールド	挙動
`replace_all`	`contents`	エントリの完全な内容を上書きします。
`str_replace`	`old_str`, `new_str`	`old_str`の単一の出現箇所を`new_str`に置き換えます（完全に1回だけ一致する必要があります）。
`insert`	`insert_line`, `insert_text`	`insert_text`を挿入します；`insert_line` 0 = 上部、省略 = 末尾に追加。

メモリのエントリを削除

scopeとpathで識別されるメモリのエントリを削除します。

エンドポイント : DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
必要な権限 ：ストアのWRITE MEMORY STORE

Bash
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

Bash
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).

メモリエントリの応答フィールド

フィールド	Type	説明
`path`	`string`	エントリのスコープ内のソフトパス。
`contents`	`string`	メモリテキスト。リスト応答で省略されます。
`description`	`string`	1行サマリー。
`scope`	`string`	エントリが属するスコープ（パーティション）。
`memory_store_name`	`string`	親メモリストアの3部構成の名前。
`has_contents`	`boolean`	エントリに空でない`contents`があるかどうか (リストで役立つ)
`create_time`	`string`	作成タイムスタンプ（RFC 3339）。
`update_time`	`string`	最終更新タイムスタンプ (RFC 3339)。

会話 APIs

会話は、OpenAI互換の会話状態 — メッセージ、ツール呼び出し、その他の項目 — を、単一スコープ下のメモリストアに保存します。会話により、エージェントはセッション状態をサーバー側で永続化および再ロードします。各会話は、メモリストア (3部構成の名前) と scope に対して作成され、会話操作には基になるメモリストアと同じ権限が必要です。

オペレーション	エンドポイント	必要な権限
作成	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` ストアで
取得	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` ストアで
更新	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` ストアで
削除	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` ストアで

会話を作成します

メモリストアとスコープにバインドされた会話を作成します。

エンドポイント : POST /api/2.1/unity-catalog/conversations
必要な権限 ：ストアのWRITE MEMORY STORE

Bash
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" }
  }'

リクエストフィールド：

フィールド	Type	必須	説明
`memory_store`	`object`	はい	会話を支えるメモリストア。
`memory_store.name`	`string`	はい	メモリストアの3部構成の完全修飾名：`catalog.schema.memory_store`。
`scope`	`object`	はい	会話がピン留めされているスコープ。
`scope.kind`	`string`	はい	スコープの種類（例: `user` または `user_defined`）。
`scope.value`	`string`	はい	種類固有のスコープ値（たとえば、エンドユーザー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

Bash
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

Bash
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

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

会話応答フィールド

フィールド	Type	説明
`id`	`string`	サーバーに割り当てられた会話ID。
`object`	`string`	常に`conversation`です。
`created_at`	`integer`	UNIXエポック秒での作成時間です。
`metadata`	`object`	呼び出し元が提供するキーと値のメタデータ

会話アイテムAPIs

アイテムは、会話内の個々のメッセージとツール呼び出しです。これらは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` ストアで

前提条件​

メモリストアAPI​

メモリストアを作成​

メモリストアを取得します​

メモリストアのリスト​

メモリストアを更新する​

メモリストアを削除します​

メモリストア応答フィールド​

メモリエントリAPI​

メモリのエントリを作成します​

メモリのエントリを取得​

メモリ エントリのリスト​

メモリのエントリを更新​

メモリのエントリを削除​

メモリ エントリを検索します。​

メモリ エントリの応答フィールド​

会話 APIs​

会話を作成します​

会話を取得​

会話を更新します​

会話を削除する​

会話応答フィールド​

会話アイテムAPIs​

前提条件

メモリストアAPI

メモリストアを作成

メモリストアを取得します

メモリストアのリスト

メモリストアを更新する

メモリストアを削除します

メモリストア応答フィールド

メモリエントリAPI

メモリのエントリを作成します

メモリのエントリを取得

メモリエントリのリスト

メモリのエントリを更新

メモリのエントリを削除

メモリエントリを検索します。

メモリエントリの応答フィールド

会話 APIs

会話を作成します

会話を取得

会話を更新します

会話を削除する

会話応答フィールド

会話アイテムAPIs