管理エージェントメモリ

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

マネージドエージェントメモリにより、AI エージェントは会話全体で長期メモリを持つことができます。Databricksがインフラストラクチャを実行し、各スコープのメモリを分離するため、ストレージやパーティション分割を自分で管理する必要はありません。

マネージドメモリを使用すると、エージェントは次のことができます。

ユーザー設定、過去の決定、および会話全体で蓄積されたコンテキストを記憶します。
その知識を Unity Catalog のガバナンスで保護します。
エージェントとプロジェクト間で共有します。
時間の経過とともに精度と効率が向上します。

要件

Unity Catalogが有効になっているDatabricksワークスペース。
メモリストアを作成するための親スキーマに対するCREATE MEMORY STORE権限。

マネージドメモリの仕組み

マネージドメモリには 2 つのレベルがあります：

メモリストア は、メモリエントリのコンテナとして機能する Unity Catalog のセキュリティ保護可能なオブジェクトです。メモリストアは、他の Unity Catalog アセットと同様に、同じガバナンス、アクセス制御、およびリネージを継承します。
メモリ入力とは、メモリストア内に保存される個々のコンテンツです。各入力は、スコープとパスによって識別されます。スコープは入力がどのメモリに属するかを決定し、パスはファイルパス（例：/memories/preferences.md）と同様にスコープ内の入力を整理します。

範囲

スコープとは、管理メモリが、異なるユーザーまたはグループに対してエージェントのメモリを分離する方法です。すべてのメモリ入力は厳密に1つのスコープに属し、検索はクエリするスコープ内の入力のみを返します。

パーソナルメモリ: 各ユーザーが独自の設定や過去の決定など、プライベートメモリを取得するように、スコープとしてエンドユーザーIDを使用します。ユーザーは自身の入力のみを表示できます。
組織の知識: 組織 ID やチーム ID などの共有キーを使用して、エージェントのどのユーザーでも利用できる、企業情報、用語集、ベストプラクティスなどの知識を保存します。

単一のエージェントは、同じ会話内でユーザーの個人スコープと共有組織スコープの両方を一度に使用できます。scopeは、すべてのメモリ入力リクエストで必要です。

警告

スコープはユーザー間の分離境界です。信頼されたコードでスコープを構成し、モデルで設定させないでください。アプリのDatabricksサービスプリンシパルは、すべてのスコープを読み取ることができます。

マネージドメモリを開始する

エージェントにマネージドメモリを追加する最も簡単な方法は、managed-memory Claude Code スキルです。全体のセットアップを処理します。このスキルは、OpenAI Agents SDK と LangGraph の両方で機能します。

スキルをプロジェクトに組み込む方法は2つあります。

Start from a template
Add the skill to an existing project

このスキルは、Databricks アプリテンプレートに含まれています。エージェントテンプレートのいずれかから新しいエージェントをスキャフォールドし、スキルは .claude/skills/managed-memory/ の下にあります。

テンプレートリポジトリをクローンします。
Bash
```
git clone https://github.com/databricks/app-templates.git
```
app-templates を参照し、開始するエージェントテンプレートを選択します。たとえば、OpenAI Agents SDK テンプレートを使用するには:
Bash
```
cd app-templates/agent-openai-agents-sdk
```

注記

「advanced」アプリテンプレートの場合、デプロイ後に、アプリのサービスプリンシパルにLakebase Postgresの特権を付与する必要があります。そうしないと、セッション設定で502エラーが返されます。

スキルがプロジェクトに配置されたら、やりたいことを記述すると、コーディングアシスタントが残りの処理を行います:

プロンプト

Add Databricks managed long-term memory to my agent.

エージェントプロジェクトを既に持っている場合は、それにスキルを追加してください。

スキルディレクトリが存在しない場合は作成します。
Bash
```
mkdir -p .claude/skills/managed-memory
```
SKILL.mdmanaged-memoryスキルディレクトリからファイルをダウンロードし、.claude/skills/managed-memory/ に保存します。
スキルがプロジェクトに配置されたら、やりたいことを記述すると、コーディングアシスタントが残りの処理を行います:

プロンプト

Add Databricks managed long-term memory to my agent.

メモリストアを作成して使用します

以下の例では、顧客サポートエージェント向けにマネージドメモリを設定します。これにより、ユーザーの好み（設定）を保存し、後の会話でそれらを取得できます。

Databricks CLI を使用して OAuth トークンを生成し、API を呼び出します:
Bash
```
databricks auth login --host ${DATABRICKS_HOST}
databricks auth token
```

エージェントのメモリを保持するためのメモリストアを作成します。

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": "support_agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Long-term memory for the customer support agent"
  }'

エージェントがユーザーについて何かを学習した後、メモリエントリを書き込みます。scope はエントリを単一のユーザーにパーティション分割します。contents フィールドを完全なメモリテキストに使用し、description を検索（取得）を改善する短い要約として使用します:

Bash
curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
    "description": "User 123 communication preferences and account details"
  }'

後続の会話でそのユーザーのメモリエントリを検索し、エージェントが学習した内容を取得します。

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

エンドポイント、リクエストフィールド、レスポンスフィールドを含む完全なREST APIについては、Memory APIリファレンスを参照してください。

会話を使用してエージェントにメモリを追加

上記の REST ワークフローは、メモリストアおよび APIs を直接呼び出します。Databricks モデルサービングエンドポイント上でエージェントを構築する場合、代わりに SDKdatabricks-openai内の OpenAI 互換クライアントを使用して、メモリストアを「会話」に接続します。

会話とは、メモリストアによってバックアップされ、単一のスコープにピン留めされた、OpenAI互換の会話状態、つまりメッセージとツール呼び出しの実行履歴です。エージェントに以前のターンのメモリを持たせるために、同じ会話をリクエスト間で再利用します。

既存のメモリストアとスコープを新しい会話にバインドします。memory_store.name はストアの 3 レベル名であり、scope は通常エンドユーザーによって会話の状態をパーティション分割します：

Python
from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

workspace_client = WorkspaceClient()
user_id = str(workspace_client.current_user.me().id)

client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)

conversation = client.conversations.create(
    extra_body={
     &quot;memory_store&quot;: {&quot;name&quot;: &quot;main.default.support_agent_memory&quot;},
     &quot;scope&quot;: {&quot;kind&quot;: &quot;user&quot;, &quot;value&quot;: user_id},
 },
)

会話IDをresponses.createに渡します。エージェントは、そのスコープの下にあるバインドされたメモリストアで会話の状態を読み書きします。

Python
response = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
    stream=True,
)

for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

後のリクエストで同じ会話 ID を再利用します。これにより、エージェントが以前のターンを記憶します。ターンごとに新しい会話を作成しないでください:

Python
followup = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
    stream=True,
)

for event in followup:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

会話エンドポイントとリクエストフィールドについては、Conversation APIs を参照してください。

メモリのアクセス制御

メモリストアはUnity Catalogのセキュリティ保護可能なオブジェクトです。次の権限がアクセスを制御します。

権限	適用対象	説明
`CREATE MEMORY STORE`	親スキーマ	スキーマの下に新しいメモリストアを作成します。
`READ MEMORY STORE`	メモリストア	メモリストアのメタデータとそのエントリを読み取ります。
`WRITE MEMORY STORE`	メモリストア	ストアでメモリのエントリを作成、更新、削除します。
`MANAGE`	メモリストア	メモリストア自体を更新または削除します。他のユーザーに権限を付与します。
`USE SCHEMA`	親スキーマ	スキーマ内のメモリストアを一覧表示します。

短期メモリを実装する

メモリエントリ APIs は長期メモリのみを提供します。セッション内でエージェントに短期メモリを与えるには、次のいずれかを使用します：

会話を使用して、セッション状態をサーバー側で永続化します。
OpenAI session=パラメーターやLangGraphチェックポインターなど、エージェントフレームワークのセッションメモリを保持します。
セルフマネージドエージェントメモリを使用します。

制限事項

メモリエントリは長期メモリのみを提供します。短期メモリと長期メモリの違いについては、短期メモリと長期メモリを参照してください。
メモリストアとエントリは、Unity Catalog REST API を介してのみ作成および管理されます。これらの API 用の Python SDK はありません。エージェントからメモリストアを使用するには、OpenAI 互換クライアントを使用して会話に接続します。会話を使用してエージェントにメモリを追加するを参照してください。

次のステップ

メモリAPIリファレンス

要件​

マネージドメモリの仕組み​

範囲​

マネージド メモリを開始する​

メモリ ストアを作成して使用します​

会話を使用してエージェントにメモリを追加​

メモリのアクセス制御​

短期メモリを実装する​

制限事項​

次のステップ​

要件