マネージドエージェントメモリ

備考

ベータ版

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

マネージドエージェントメモリは、AIエージェントに会話全体にわたる長期的なメモリを提供します。Databricksはインフラストラクチャを運用し、各スコープのメモリを分離するため、ストレージやパーティションを自身で管理する必要はありません。

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

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

要件

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

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

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

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

範囲

スコープは、マネージドメモリが異なるユーザーまたはグループに対してエージェントのメモリを分離する方法です。すべてのメモリエントリーは正確に1つのスコープに属し、検索はクエリーしたスコープ内のエントリーのみを返します。

パーソナルメモリ： 各ユーザーが設定や過去の決定などのプライベートメモリを所有できるように、エンドユーザーIDをスコープとして使用します。ユーザーは自身の項目のみを表示できます。スコープ値user_clientは、エンドユーザーの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.

メモリストアを手動で作成して使用する

このセクションでは、managed-memory Claude Code スキルなしで、メモリストアを作成して使用する方法を示します。

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

Databricks CLIを使用してAPIを呼び出すOAuthトークンを生成します：
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`	親スキーマ	スキーマ内のメモリストアを一覧表示します。

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

短期メモリを実装する

メモリエントリーAPIsは、エージェントが使用するツールとして長期メモリを提供します。セッションでエージェントにマネージドの短期メモリを提供するために、Databricksはメモリストアを会話にバインドすることを推奨しています。また、以下も可能です。

OpenAI session=パラメーターやLangGraphチェックポインターなど、エージェントフレームワークのセッションメモリを保持します。
会話履歴ストアには、セルフマネージドエージェントメモリを使用してください。

セキュリティの推奨事項

Databricks は、ガバナンスストア、暗号化、分離プリミティブ、および監査証跡を提供しています。アプリ開発者として、Databricks は次のことを推奨しています。

意図的に異なる方法でパーティション分割する理由がない限り、ユーザーごとのスコープのdefault (user_client) を使用してください（例：プロジェクトごと、またはアカウントごとのメモリなど）。
最小限の特権を付与します：エージェントのDatabricks Service PrincipalのみがWRITE MEMORY STOREを必要とします。READ MEMORY STOREを限定的に付与し、人間のユーザーや大規模なグループへの広範な付与は避けてください。
アプリのDatabricks Service Principal資格情報を保護してください：これはストアのデータプレーンへの鍵です。機密性の高いサービス資格情報と同様に扱ってください。有効期間の短いトークンを使用し、ログに記録することは避け、アプリにSSRF防御を追加してください。

制限事項

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

次のステップ

メモリAPIリファレンス

要件​

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

範囲​

マネージドメモリスキルを使ってみる​

メモリストアを手動で作成して使用する​

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

メモリのアクセス制御​

短期メモリを実装する​

セキュリティの推奨事項​

制限事項​

次のステップ​

要件