エージェントメモリーサービス¶

DataRobotのエージェントメモリーサービスでは、異なるユースケースに対応する2つの異なるAPIが提供されています。 お使いのビルドに合った方法を選択し、その方法に関するドキュメントに従ってください。 1つのアプリケーションで2つをマージする必要はありません。

DataRobotモデル（datarobot.models.memory.Sessionまたはdatarobot.models.memory.MemorySpace経由でアクセス）を使用して、DataRobotのREST APIおよびPython APIクライアントを通じてチャットスタイルの履歴（セッション）を保持および取得する必要がある場合は、チャット履歴APIセクションに説明があるチャット履歴APIを利用します。 詳細については、REST APIおよびPython APIクライアントのリファレンスドキュメントを参照してください。

長期的なmem0スタイルのメモリー（オープンソースのmem0スタックからの移行を含む）を使用している場合、またはmem0製品に準拠した例やリクエスト形式が必要な場合は、mem0 APIを利用します。 このインターフェイスの場合、標準のリソースはmem0ドキュメントです。

クイックスタート¶

以下のクイックスタートワークフローを確認します。

前提条件¶

• Python 3.9以降
• DataRobotアカウント、APIキー、エンドポイントURL（例：https://app.datarobot.com/api/v2）
• pip install "datarobot>=3.17" "mem0ai>=2.0"

環境変数（DATAROBOT_API_TOKEN、DATAROBOT_ENDPOINT）または~/.config/datarobot/drconfig.yamlを使用して、資格情報を一度設定します。 以下のスニペットは、それらを明示的に渡します。

接続する¶

import datarobot as dr

dr.Client(token="<YOUR_DATAROBOT_API_TOKEN>", endpoint="https://app.datarobot.com/api/v2") 

メモリー空間の作成¶

メモリー空間とは、1つのアプリケーションまたは1人のエンドユーザーに対する分離境界のことです。

from datarobot.models.memory import MemorySpace

space = MemorySpace.create(
    description="Acme support assistant",
    llm_model_name="vertex_ai/claude-sonnet-4-6",  # used for mem0 fact extraction
)
print(space.id) 

llm_model_nameは、mem0の事実抽出に使用されるLLMを選択します。 DataRobot LLM Gatewayを通じて利用可能なモデルに対して検証が行われます。不明な名前は拒否され、許可されたモデルを一覧表示する422レスポンスが返されます。 プロバイダーごとに提供されているモデルについては、利用可能なLLMを参照してください。 推論モデルは、事実抽出において処理速度が著しく遅くなるだけでなく、結果の品質も向上しないため、推論機能のないモデルの使用をお勧めします。 あるいは、llm_base_urlを設定することで、メモリー空間をLLM Gatewayではなく、OpenAI互換のカスタムエンドポイントに向けることができます。そのホストは、管理者が設定した許可リストと一致している必要があります。

セッションの作成¶

セッションは1つの会話です。 participantsはMongoDB-ObjectId文字列のリストで、通常はエンドユーザーです。

from datarobot.models.memory import Session

session = Session.create(
    memory_space_id=space.id,
    participants=["67500a000000000000000001"],
    description="Triage chat #42",
)
print(session.id) 

ソフト削除ライフサイクル戦略を指定しない場合、サーバーはデフォルトの戦略（180日間）を割り当てます。

メッセージの投稿¶

各メッセージはイベントです。 bodyは自由形式のJSONです。emitterは送信者を識別します。

event = session.post_event(
    body={"content": "Hello, my deployment is failing"},
    emitter={"type": "user", "id": "67500a000000000000000001"},
    event_type="message",
)
print(event.sequence_id)  # 0 

バッチ追加（最大200イベント、単一トランザクション）：

session.post_events([
    {
        "body": {"content": "Looking at it now."},
        "emitter": {"type": "agent", "id": "67500a000000000000000002"},
        "event_type": "message",
    },
    {
        "body": {"content": "Found the issue - rolling back."},
        "emitter": {"type": "agent", "id": "67500a000000000000000002"},
        "event_type": "message",
    },
]) 

イベントの読み取りと編集¶

# Newest 20 events:
recent = session.events(last_n=20)
for e in recent:
    print(e.sequence_id, e.emitter_type, e.body)

# Edit message #1:
session.update_event(
    sequence_id=1,
    body={"content": "Looking at it now (ETA 5min)."},
) 

update_eventは、楽観的並行性のためにオプションのcreated_atを受け付けます。そのタイムスタンプ以降にイベントが変更されている場合、サーバーは更新を拒否し、呼び出し元は再読み込みして再試行する必要があります。

標準のmem0クライアントを使用したメモリーの抽出¶

このサービスは、メモリー空間ごとにmem0互換のサブルートを公開します。 標準のmem0ai.MemoryClientがそのルートを参照するようにすれば、通常のmem0クライアントは変更なしで動作します（add()、get()、search()、get_all()、delete()）。

from mem0 import MemoryClient

endpoint = f"https://app.datarobot.com/api/v2/memory/{space.id}"
memory = MemoryClient(host=endpoint, api_key="<YOUR_DATAROBOT_API_TOKEN>")

memory.add(
    [{"role": "user", "content": "I deploy on Fridays using ArgoCD"}],
    user_id="alice",
    agent_id="support-bot",
)

hits = memory.search(
    "when do we deploy",
    filters={"user_id": "alice", "agent_id": "support-bot"},
) 

api_keyはDataRobot APIトークンです。 メモリー空間のスコープは完全にURLパス内にあり、追加のヘッダーは不要です。

共有とアクセス制御¶

メモリー空間では、APIやレジストリへのアクセスにユーザーレベルの機能フラグを使用するほか、エージェントメモリーサービスで適用される空間ごとの共有ロールも使用します。

エージェントメモリーAPIへのアクセスを有効にする¶

ユーザーがエージェントメモリーサービスを呼び出したり、レジストリ > メモリー空間を開いたりするには、組織またはシステム管理者が、そのユーザーのプロファイルでエージェントメモリーAPIへのアクセスを有効にする機能フラグを有効にする必要があります。 このフラグを設定しないと、メモリーAPIおよび「メモリー空間」ページは利用できません。

1. 管理者設定を開き、ユーザー管理に移動します。
2. ユーザーを選択し、ユーザープロファイルを表示をクリックします。
3. ユーザー設定で、エージェントメモリーAPIへのアクセスを有効にするを有効にします。

このレイヤーでのアクセスは「すべて許可」または「すべて拒否」の二者択一となります。このフラグでは、メモリーAPIにおける読み取りと書き込みの権限を個別に定義することはできません。 有効にすると、ユーザーは空間ごとの共有設定（後述）に従ってメモリーサービスを利用できるようになります。

メモリー空間ごとの共有ロール¶

アクセスできる各メモリー空間は、自分が所有しているもの、あるいは別のユーザーから共有されたものです。 リストへの表示と可視性は共有（設定）に従います。機能フラグだけでは、組織内のすべてのメモリー空間が公開されるわけではありません。

メモリー空間を作成または取得する際、APIの応答には以下の内容が含まれます。

• rbacResourceId — 共有を適用するために使用されるプラットフォーム識別子（存在する場合）。 通常のエージェントメモリーAPIワークフローでは、このフィールドは必要ありません。
• permissions — その空間で実行可能な操作（CAN_VIEW、CAN_UPDATE、CAN_DELETE、CAN_SHARE）であり、リクエストごとにメモリーサービスによって適用されます。

オーナーおよび共有権限を持つユーザーは、レジストリの共有ダイアログを通じて、他のユーザー、グループ、または組織にコンシューマー、エディター、またはオーナーのロールを付与することができます。 3つのロールはすべて、ロールのドロップダウンから選択できます。 メモリー空間のロールおよびメモリー空間の共有を参照してください。

permissionsの範囲外の操作を行うと、権限不足のエラーが発生します。 スキーマの詳細については、エージェントメモリーサービスのREST API（MemorySpaceResponse.permissionsおよびMemorySpaceResponse.rbacResourceId）を参照してください。

共有空間でメモリーを取り込んだり、イベントを投稿したり、セッションを作成したりするには、その空間のエディターまたはオーナーの権限を持っている必要があります（コンシューマーのみではできません）。

ユーザーのアクセス権を取り消すと、すべての権限が直ちに削除されます。

レジストリでの共有の管理¶

アクセス権の付与、変更、または取り消しは、レジストリ > メモリー空間から、各メモリー空間の共有ダイアログを使用して行います。 これが、コラボレーターの管理においてサポートされているワークフローです。共有は、エージェントメモリーサービスのAPIやPython SDKを通じて提供されていません。

手順の詳細については、メモリー空間の共有を参照してください。

セッションのライフサイクルと保持期間¶

すべてのセッションには、時間の経過に伴う挙動を制御する1つ以上のライフサイクル戦略が割り当てられています。 各戦略は、アクション（soft_delete（セッションとそのイベントを非表示にする）またはextract_memories（会話を長期記憶へ移行する））と、そのアクションがいつ実行されるかを決定するトリガーを組み合わせたものです。 作成時に戦略を指定しない場合、サーバーはデフォルトのsoft_delete戦略（TTL 180日）を適用します。

使用可能なトリガーは以下のとおりです。

session = Session.create(
    memory_space_id=space.id,
    participants=["67500a000000000000000001"],
    description="Triage chat #42",
    lifecycle_strategies=[{"type": "soft_delete", "trigger": {"ttl": 604800}}],
) 

有効期限のないセッション¶

neverトリガーを指定すると、セッションはライフサイクルの自動実行から完全に除外されます。つまり、セッションとそのイベントは、明示的なセッション削除（または管理者による恒久的な削除）によって削除されるまで保持されます。

session = Session.create(
    memory_space_id=space.id,
    participants=["67500a000000000000000001"],
    description="Application settings store",
    lifecycle_strategies=[{"type": "soft_delete", "trigger": {"never": True}}],
) 

neverトリガーは以下の場合に使用します。

• アプリケーションシステムのデータ：セッションメタデータに保存されるユーザープロファイル、設定、ワークスペースなどのレコードで、有効期限が切れると古いデータがクリーンアップされるどころか、アプリケーションが機能しなくなってしまう場合です。 休止状態のインストール環境は、キープアライブトラフィックがなくても、いかなる保持期間でも存続します。
• 終了日未定の保持期間：現時点で具体的な期間を特定できない場合でも、データを一定期間保持する必要がある場合は、neverを使用します。 2年を超えるものの、期間が有限である義務については、インストール環境のセッションTTLの上限を引き上げ、ttlトリガーを維持することをお勧めします。 これにより、期間が終了した時点で、ライフサイクルワーカーがセッションを回収できるようになります。 適用される保持期間については、コンプライアンス担当者にご確認ください。

通常の会話履歴にはneverトリガーの使用を避けてください。有効期限のないセッションを自動的に収集する仕組みはないため、それらの削除はアプリケーション側の責任となります。 自然な有効期限があるデータについては、ttlまたはidleを優先して使用してください。

既存のセッションの保持期間を更新する¶

保持期間の決定が行われる前に作成されたセッションは、そのライフサイクル戦略を置き換えることで、別のスケジュール（有効になっている場合はneverトリガーも含む）に移行させることができます。

session.update(
    lifecycle_strategies=[{"type": "soft_delete", "trigger": {"never": True}}],
) 

REST APIによる同様の更新：

curl -X PATCH "https://app.datarobot.com/api/v2/memory/MEMORY_SPACE_ID/sessions/SESSION_ID/" \
  -H "Authorization: Bearer <YOUR_DATAROBOT_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"lifecycleStrategies": [{"type": "soft_delete", "trigger": {"never": true}}]}' 

渡す戦略はリスト全体を置き換えるため、変更する戦略だけでなく、セッションに保持すべきすべての戦略を送信してください。 他のフィールドを更新する際に戦略を変更しない場合は、引数を省略してください。 このリクエストの検証は、作成時とまったく同じ方式で行われます。つまり、戦略は1つから5つまで、戦略タイプの重複は不可、またLLMが設定されていない場合のスペースに関するルールも同様です。 戦略をクリアすることはできません。Session.updateはlifecycle_strategies=Noneの場合にValueErrorを発生させ、REST APIは空のリストやnullを422レスポンスで拒否します。

その他に知っておくべきセマンティクス：

• 更新処理によりセッションのversionが引き上げられ、他のセッション更新と同様にIf-Match事前条件ヘッダーが尊重されます。 Session.updateは、最後に読み取ったバージョンを自動的に送信します。このチェックを無効にするにはif_match=Noneを指定し、上書きするには整数を指定してください。 REST経由の場合は、最後に読み取ったバージョンをIf-Matchヘッダーとして指定してください。
• セッションに対してすでに実行されたことのある戦略タイプは、再設定できません。ライフサイクル実行エンジンは同一のタイプを二度実行しないため、適用できない変更は、黙って保存されるのではなく、そのタイプ名を明記した409レスポンスで拒否されます。 設定を変更せずにそのようなタイプを再送信することは受け入れられるため、他のフィールドに対する「読み取り-変更-書き込み」形式の更新は引き続き機能します。
• neverトリガーが有効になっていない場合、まだneverトリガーを持たない戦略タイプにこれを追加しようとすると、422レスポンスで拒否されます。 すでにneverトリガーを保持しているセッションはこれを再送信できるため、「読み取り-変更-書き込み」形式の更新は引き続き機能します。 セッションをneverからttlまたはidleに移行することは、常に許可されています。