マネージドエージェントメモリ（レガシー）

警告

レガシー

これはマネージドエージェントメモリストアの以前のバージョンであり、まもなく提供が終了します。その上で新しいエージェントを構築しないでください。長期的なエージェントメモリには、代わりにマネージドエージェントメモリを使用してください。

マネージドエージェントメモリを使用すると、エージェントは会話を跨いで長期的なメモリを維持できます。Databricks がインフラストラクチャを実行し、各スコープのメモリを分離するため、ストレージやパーティショニングをご自身で管理する必要はありません。

マネージドメモリを使用すると、エージェントは次のことが可能になります。

会話全体で、ユーザーの好み、過去の決定、および蓄積されたコンテキストを記憶します。
Unity Catalogガバナンスでそのナレッジを保護します。
エージェントやプロジェクト間でメモリを共有します。
時間の経過とともに、それらの正確性と効率を向上させます。

要件

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

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

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

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

スコープ

スコープは、メモリを1人のユーザー専用にするか、グループ全体で共有するように設定する方法です。アプリケーションは読み取りおよび書き込みごとにスコープを設定し、検索では一致するスコープを持つエントリのみが返されます。エージェントが記憶する必要がある内容に一致する戦略を選択します。

各ユーザーのプライベートメモリ： スコープを検証済みエンドユーザーのIDに設定します。各ユーザーには独自のパーティションが割り当てられ、自分自身のエントリのみが表示されます。値 user_client により、エンドユーザーのIDが自動的に解決されます。
- 例: サポートエージェントは、ユーザーの1つの通信設定と過去のチケットを記憶します。
グループの共有メモリ： スコープを、組織、チーム、プロジェクト ID など、選択した固定キーに設定します。すべてのユーザーが同じメモリを読み書きします。
- 例: チームエージェントは、社内用語や社内ポリシーの共有用語集を記憶します。
別の要素によるメモリの分割： テナント ID や user_id:project の複合など、独自の値からスコープを構築します。
- 例: マルチテナントアプリでは各顧客のメモリが個別に保持されるか、単一ユーザーのメモリがプロジェクトごとに隔離されます。

単一のエージェントは、1つの会話の中で戦略を組み合わせることができます。たとえば、同じリクエスト内でユーザーのプライベートメモリと共有チームメモリを読み取ることができます。

リクエストが改ざんできない信頼できる呼び出し元のコンテキストから、アプリケーションコードでスコープを設定します。ユーザーごとのメモリ用のOBOトークンからの検証済みのエンドユーザーID、または共有メモリ用の信頼できるテナント、チーム、プロジェクトキーを設定します。モデルに選択させないようにしてください。スコープ戦略がエンドユーザーのIDに依存している場合は、共有スコープにフォールバックするのではなく、IDを持たないリクエストを拒否してください。managed-memory スキルを使用してセットを進めます。

スコープによってメモリは分離されますが、ストアへのアクセス権は付与されません。これを開くには、呼び出し元に引き続き READ MEMORY STORE または WRITE MEMORY STORE 権限が必要です。メモリアクセス制御を参照してください。

警告

スコープはユーザー間の分離境界ですが、アクセス制御ではありません。アプリの Databricks Service Principal はすべてのスコープを読み取ることができるため、それに応じて資格情報を保護してください。

エージェントが保存および思い出す内容

Managed memoryは、メモリストアと、エントリーの読み取りおよび書き込みを行うためのAPIsを提供します。アプリケーションは、エージェントが保存する内容、メモリを取得するタイミング、およびその結果の使用方法を制御します。

この動作をエージェントのシステムプロンプトで定義します。保存する永続的な情報とそれを取得するタイミングをエージェントに指示します。managed-memoryスキルとTemplateにより、このシステムプロンプトがMEMORY_INSTRUCTIONSという名前の定数に保持されます。スコープは信頼できるアプリケーションコード内で個別に構成され、モデルによって選択されることはありません。

スコープ戦略に合わせて文言を調整します。ユーザーごとの戦略の例は次のとおりです。

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

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

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

プロジェクトにスキルを組み込むには、次の2つの方法のいずれかを使用します。

Start from a template
Add the skill to an existing project

このスキルは、Databricks app templatesに同梱されています。.claude/skills/managed-memory/の下にあるエージェントTemplateのいずれかから新しいエージェントを構築し、スキルを見つけます。

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

注記

「高度な」アプリ Template の場合、デプロイ後にアプリの Service Principal に Lakebase Postgres の権限を付与する必要があります。付与しない場合、セッションのセットアップで 502 エラーが返されます。

スキルがプロジェクトに追加されたら、必要な内容を説明すると、コーディングアシスタントが残りの処理を行います：

プロンプト

Add Databricks managed long-term memory to my agent.

すでにエージェントプロジェクトがある場合は、そこにスキルを追加します。

スキルディレクトリが存在しない場合は作成します。
Bash
```
mkdir -p .claude/skills/managed-memory
```
SKILL.md ファイルを managed-memory スキルディレクトリからdownloadし、.claude/skills/managed-memory/ に保存します。
スキルがプロジェクトに追加されたら、必要な内容を説明すると、コーディングアシスタントが残りの処理を行います：

プロンプト

Add Databricks managed long-term memory to my agent.

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

このセクションでは、managed-memory Claude Code スキルを使用せずにメモリストアを作成および使用する方法について説明します。

次の例では、ユーザーの好みを保存し、後の会話でそれらを取得するカスタマーサポートエージェント用にマネージドメモリを設定します。

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

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

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

上記のRESTワークフローでは、メモリストアとエントリーAPIを直接呼び出します。DatabricksのモデルサービングEndpointでエージェントを構築する場合は、代わりに SDK内のOpenAI互換クライアントを使用して、メモリストアを会話 databricks-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)

会話のEndpointとリクエストフィールドについては、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 の付与は最小限にとどめ、人間ユーザーや大規模グループへの広範な付与は避けてください。
Protect the app Databricks Service Principal credential: it is the key to the store's data plane.高価値なサービス資格情報と同様に扱い、短期トークンを使用し、ログへの記録を避け、アプリに SSRF 防御を追加します。

制限事項

メモリエントリーは、長期記憶のみを提供します。会話履歴については、管理対象エージェントセッションをご覧ください。
メモリストアとエントリは Unity Catalog REST API を通じてのみ作成および管理されます。これらに対する Python SDK はありません。エージェントからメモリストアを使用するには、OpenAI 互換クライアントを使用して会話に接続します。会話機能を使用したエージェントへのメモリの追加については、Add memory to an agent with conversations を参照してください。

次のステップ

メモリ API リファレンス

要件​

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

スコープ​

エージェントが保存および思い出す内容​

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

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

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

メモリのアクセス制御​

短期メモリの実装​

セキュリティに関する推奨事項​

制限事項​

次のステップ​

要件