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

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

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

• ユーザー設定、過去の決定、会話全体で蓄積されたコンテキストを記憶します。
• Unity カタログ ガバナンスを使用して、その知識をセキュリティで保護します。
• エージェントとプロジェクト間でメモリを共有します。
• 時間の経過とともに精度と効率を向上させます。

Requirements

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

マネージド メモリのしくみ

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

• メモリ ストアは、メモリ エントリのコンテナーとして機能するセキュリティ保護可能な Unity カタログです。 メモリ ストアは、他の Unity カタログ資産と同じガバナンス、アクセス制御、および系列を継承します。
• メモリ エントリは、メモリ ストア内に格納されている個々のコンテンツです。 各エントリは、スコープとパスによって識別されます。 スコープは、エントリが属するメモリを決定し、パスはファイル パス (たとえば、 /memories/preferences.md) と同様に、スコープ内のエントリを整理します。

Scope

スコープとは、メモリを1人のユーザーだけにプライベートにしたり、グループ間で共有したりする方法です。 アプリケーションはすべての読み書きにスコープを設定し、検索は対応するスコープのエントリだけを返してきます。 エージェントが覚えておくべきことに合った戦略を選びましょう:

• 各ユーザーごとのプライベートメモリ: スコープを認証済みのエンドユーザーIDに設定します。 各ユーザーは自分のパーティションを持ち、自分のエントリだけを見ることができます。 値 user_client は、エンドユーザーの ID を自動的に特定します。
  • 例: サポート担当者は、あるユーザーのコミュニケーションの好みや過去のチケットを覚えています。
• グループのための共有メモリ: 組織、チーム、プロジェクトIDなど、選択した固定キーにスコープを設定しましょう。 すべてのユーザーは同じ記憶を読み書きします。
  • 例: チームエージェントは会社の用語集や社内方針の共通用語集を覚えています。
• メモリが他の要素で分割される場合: テナント ID や user_id:project コンポジットなどの独自の値からスコープを構築します。
  • 例: マルチテナントアプリは各顧客のメモリを分離するか、プロジェクトごとに単一のユーザーのメモリを隔離します。

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

リクエストが改ざんできない信頼できる呼び出し元コンテキストから、アプリケーションコード内でスコープを設定します。例えば、ユーザーごとのメモリ用にOBOトークンの検証済みエンドユーザーID、共有メモリ用に信頼できるテナント、チーム、プロジェクトキーなどです。 モデルに決めさせてはいけません。 スコープ戦略がエンドユーザーのアイデンティティに依存している場合は、共有スコープに戻るのではなく、アイデンティティがないリクエストを拒否してください。 managed-memoryスキルがこのセットアップを案内します。

Scopeは記憶を分離しますが、ストアへのアクセスは許可しません。 呼び出し元がそれを開くには、引き続き READ MEMORY STORE または WRITE MEMORY STORE の権限が必要です。 メモリ アクセス制御を参照してください。

エージェントが保存し、呼び戻すもの

マネージドメモリはメモリストアと読み書きのためのAPIを提供します。 アプリケーションはエージェントが何を保存するか、いつメモリを取得するか、そしてその結果の使い方を制御します。

エージェントのシステムプロンプトでこの動作を定義します:どの耐久情報を保存し、いつ取得するかをエージェントに指示します。 managed-memoryスキルとテンプレートにより、このシステムは一定の名前付き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 つの方法のいずれかを使用します。

テンプレートから開始

スキルは Databricks アプリ テンプレート内に付属しています。 エージェント テンプレートの 1 つから新しいエージェントをスキャフォールディングし、 .claude/skills/managed-memory/でスキルを見つけます。

1. テンプレート リポジトリを複製します。

   git clone https://github.com/databricks/app-templates.git
   

2. app-templatesを参照して、開始点として使用するエージェントテンプレートを選択します。 たとえば、OpenAI Agents SDK テンプレートを使用するには、次のようにします。

   cd app-templates/agent-openai-agents-sdk
   

   Note

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

3. スキルがプロジェクト内に入ったら、必要なものを記述し、コーディング アシスタントが残りの処理を行います。

   Tip

   Add Databricks managed long-term memory to my agent.
   

既存のプロジェクトにスキルを追加する

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

1. スキル ディレクトリが存在しない場合は作成します。

   mkdir -p .claude/skills/managed-memory
   

2. SKILL.md スキル ディレクトリからmanaged-memory ファイルをダウンロードし、.claude/skills/managed-memory/に保存します。

3. スキルがプロジェクト内に入ったら、必要なものを記述し、コーディング アシスタントが残りの処理を行います。

   Tip

   Add Databricks managed long-term memory to my agent.
   

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

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

次の例では、ユーザーの設定を格納し、後の会話で取得するカスタマー サポート エージェントのマネージド メモリを設定します。

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

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

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

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

3. エージェントがユーザーについて何かを学習した後、メモリ エントリを書き込みます。 scopeは、エントリを 1 人のユーザーに分割します。 contents フィールドはメモリの全文に使用し、description は検索性を高める短い要約として使用します。

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

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

   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 ワークフローは、メモリ ストアとエントリ API を直接呼び出します。 エンドポイントを提供するAzure Databricks モデルでエージェントを構築する場合は、代わりに、 SDK で OpenAI 互換クライアントとのdatabricks-openaiにメモリ ストアを接続します。

会話とは、メモリ ストアによってサポートされ、1 つのスコープにピン留めされた OpenAI 互換の会話状態 (メッセージとツール呼び出しの実行履歴) です。 要求間で同じ会話を再利用して、エージェントに以前のターンのメモリを提供します。

1. 既存のメモリ ストアとスコープを新しい会話にバインドします。 memory_store.name はストアの 3 階層名で、scope は会話の状態を、通常はエンドユーザーごとに分割します。

   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={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

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

   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)
   

3. エージェントが以前のターンを記憶するように、後の要求で 同じ 会話 ID を再利用します。 ターンごとに新しい会話を作成しないでください。

   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 API」を参照してください。

メモリアクセス制御

メモリストアは、Unity Catalog のセキュリティ保護可能なオブジェクトです。 次の権限によってアクセスが制御されます:

短期メモリを実装する

メモリ エントリ API は、エージェントが使用するツールとして長期的なメモリを提供します。 セッションでエージェントが管理する短期メモリを提供するために、Databricks では、メモリ ストアを 会話にバインドすることをお勧めします。 次のこともできます。

• OpenAI session= パラメーターや LangGraph チェックポイントなどのエージェント フレームワークのセッション メモリを保持します。
• 会話履歴ストア には、自己管理エージェント メモリ を使用します。

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

Azure Databricksは、管理されたストア、暗号化、分離プリミティブ、監査証跡を提供します。 アプリ開発者として、Databricks では次のことをお勧めします。

• 別のパーティション分割の意図的な理由 (プロジェクトごと、アカウントごとのメモリなど) がない限り、ユーザーごとのスコープの既定値 (user_client) を使用します。
• 最小特権を付与する: 必要なのは、エージェントのサービス プリンシパルに対する WRITE MEMORY STORE のみです。 READ MEMORY STOREを狭く付与し、人間のユーザーや大規模なグループに対する広範な許可を回避します。
• アプリ サービス プリンシパルの資格情報を保護する: これは店舗のデータ プレーンのカギとなります。 価値の高いサービス資格情報と同様に扱います。有効期間の短いトークンを使用し、ログ記録を回避し、SSRF 防御をアプリに追加します。

Limitations

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

次のステップ

• メモリ API リファレンス