セキュリティーに関する考慮事項

スコープ: このドキュメントでは、Oracle AI Agent Memory Python SDKに関連するセキュリティ上の考慮事項について説明します。これは、SDKのアクティブ・メモリー機能またはストア・レイヤーのいずれかを使用するアプリケーションにのみ適用されます。

重要である理由: Oracle AI Agent Memoryは、スレッド・コンテンツおよびメモリー・レコードをOracle Databaseに永続化し、LLMにバックアップされた機能が有効になっている場合は、サマリー、メモリー抽出または埋込み用に構成済のモデル・エンドポイントにコンテンツを送信します。したがって、セキュアなデプロイメントは、アプリケーション・データの慎重な処理、取得範囲、データベース・アクセス、外部モデル・エンドポイントおよび保存ポリシーに依存します。

LLMでバックアップされたメモリー処理に関する考慮事項

Oracle AI Agent Memoryは、スレッド要約や自動メモリー抽出などのアクティブメモリー機能をサポートしています。これらの機能を有効にすると、SDKは、構成済のLLMまたは埋込みエンドポイントに、最近のメッセージ、スレッド・サマリー、取得済メモリーまたは検索テキストを送信できます。

重要:構成されたモデル・エンドポイントおよびデプロイメント・ポリシーに適したコンテンツのみをOracle AI Agent Memoryに送信します。シークレット、資格証明または不要な機密データが含まれるように見えるデータに対してアクティブ・メモリーが有効になっている場合は、メッセージがメモリー・パイプラインに入る前にそのコンテンツを最小化またはリダクションします。抽出された記憶、要約、コンテキスト・カードおよびその他のモデル派生テキストを信頼できない出力として処理します。この出力は、統合アプリケーションによって安全にレビューおよび処理する必要があります。

警告:モデル派生テキストが永続メモリー状態になる可能性があります。自動抽出、要約またはコンテキスト・カード機能を有効にすると、アプリケーションがその特定の中間値をレビューする前に、SDKによってサマリー、抽出されたメモリーまたは取得されたレコードが、メモリー抽出、要約、コンテキスト・カードまたはエージェント・プロンプトなどの後のプロンプトに挿入されます。これを通常の信頼できないLLMデータ・フローとして扱います。アプリケーションが消費する出力を確認して検証し、メモリー由来のコンテンツが特権アクションまたはバイパス・ポリシーを認可しないようにします。

アクティブ・メモリー機能を使用する場合は、次の推奨事項に従います。

• アプリケーション・データの検証および最小化: アプリケーションがSDKに送信するメッセージ、メタデータおよびIDを確認します。メモリー・ワークフローが必要とするより多くのデータを渡さないでください。
• 信頼できるモデル・エンドポイントの使用: LLMを構成し、トランスポート・セキュリティ、データ・レジデンシ、保持および運用モニタリングの要件を満たすエンドポイントを埋め込みます。
• 生成されたメモリーをアプリケーション・データおよび信頼できない出力として処理: 抽出されたメモリー、サマリーおよびコンテキスト・カードは導出された出力です。特権アクション、外部ツール・コールまたは顧客に見える決定に影響を与える前に、アプリケーションがそれらを使用する方法を確認します。
• 遅延導出書込みが許容される場合のみ非同期抽出を選択: バックグラウンド・モードでは、導出メモリー、サマリーまたは関連するランタイム状態が書き込まれる前に、RAWメッセージの書込みを完了できます。モデル派生状態が永続的になる前に、ワークフローでレビューまたはより厳密なコミット境界が必要な場合は、インライン抽出を使用するか、そのワークフローの自動抽出を無効にします。
• 永続的プロンプト・インジェクションのアカウント: メモリーに格納されたコール元提供、取得またはモデル派生テキストを、後で要約、抽出、コンテキスト・カードまたはエージェント・プロンプトにリプレイできます。プロンプト・デリミタ、エスケープおよび抽出命令は、モデル入力の構成に役立ちますが、セキュリティ境界ではありません。抽出された記憶、要約、コンテキスト・カード、およびその他の永続的またはプロンプトバウンドの中間テキストを確認してから、それらに依存します。モデル派生テキストが将来の抽出またはコンテキスト構成に影響を与える前にワークフローでレビューが必要な場合は、自動抽出を無効にし、明示的なメモリー書込みまたは別のアプリケーション制御レビュー・ゲートを使用します。
• 宛先の派生テキストをサニタイズまたはエスケープ: 抽出されたメモリー、サマリー、コンテキスト・カードまたはその他のモデル派生テキストがHTML、Markdown、テンプレート、ログまたはその他の出力サーフェスにレンダリングされる場合は、コンテキストに適したエスケープまたはサニタイズを適用します。派生テキストをダウンストリーム・プロンプト、ツール入力、コマンドまたはその他のインタプリタのようなコンテキストで再利用する前に、同じ注意を払ってください。
• 適切なオペレーティング・モードの選択: モデル派生テキストが後で抽出またはコンテキスト構成に影響を与える前にアプリケーションを確認する必要がある場合は、自動抽出を実行しないワークフローに明示的なメモリー書込み、ストア専用統合またはmemory_extraction_config=MemoryExtractionConfig(extract_memories=False)を使用することを検討してください。

永続性およびデータの最小化に関する考慮事項

Oracle AI Agent Memoryは、DBバック・ストアが使用されたときに、メッセージ、メモリー、メタデータおよび埋込みをOracle Databaseに永続化するように設計されています。これにより、恒久的な取得およびクロスセッション・メモリーが可能になりますが、保持に適したデータをアプリケーションが計画する必要があることも意味します。

次のガイダンスは、セキュアなデータ処理プラクティスに従ってデプロイメントを維持するのに役立ちます。

• ストアのみの使用の場合、必要なもののみを保持: 役立つビジネスに適したコンテンツのみがメモリー・ストアに書き込まれるようにアプリケーションを設計します。
• アクティブ・メモリー機能が有効になっている場合、導出されたレコードの計画: メッセージやメタデータなどのコール元提供のコンテンツに加えて、抽出されたメモリー、サマリーまたは埋込みもワークフローによって保持される場合があります。
• 信頼できるものとして書込み可能なメモリー・パスを処理: メッセージ、サマリー、メモリー、メタデータ、埋込みまたはスレッド・ランタイム状態を記述できるデータベース資格証明およびバックエンド・コード・パスは、今後のプロンプトおよび取得結果に影響する可能性があります。アクティブ・メモリー機能は意図的にモデル派生状態を維持します。ワークフローに適さない場合は、自動抽出を無効にするか、より狭いアプリケーション・コントロールとのストア専用/手動書込み統合を使用します。
• 保存作業の正しい削除スコープの選択: delete_message()は、RAWメッセージ・レコードのみを削除します。導出されたメモリーまたはそのメッセージから作成されたその他のダウンストリーム・スレッド・スコープのアーティファクトは、抽出されたメモリーがメッセージごとの来歴を現在保持していないため、検索可能なままにできます。関連付けられたメモリーおよび管理対象取得データも削除するスレッド・スコープのクリーンアップが必要な場合は、OracleAgentMemory.delete_thread()を使用します。
• バックグラウンド作業のための削除および停止境界を中心に計画します: delete_thread()、delete_user(cascade=True)およびdelete_agent(cascade=True)は、待機の開始時に、そのクライアントにすでに認識されている、以前に受け入れられたバックグラウンド抽出のみを待機します。他のハンドル、コンポーネントまたはプロセスにわたるグローバルな同時実行性の障壁ではなく、削除中の同時書込みはサポートされていません。保存境界または停止境界が、現在のクライアントからすでに受け入れられているバックグラウンド抽出を最初に終了する必要がある場合は、プロセスの停止または関連する管理操作の前にwait_for_memory_extraction()をコールします。
• 保持および削除ポリシーを事前に定義: アプリケーションで削除または保持のコミットメントが提供されている場合は、ワークフローによって作成されたRAWメッセージ、抽出されたメモリー、メタデータおよびその他の関連レコードをカバーしていることを確認してください。レコードごとのttl_days値およびスキーマのmemory_retention_configは、各レコードの予想される情報のタイプ、アプリケーションでその情報を保持する必要がある理由および適用可能な保存コミットメントに基づいて選択します。レコードを経過時間でパージする必要がある場合は、自動失効を使用し、特にスキーマ設定ユーザーにスケジューラ・ジョブ権限がない場合に、管理対象Oracleパージ・ジョブがDBバック・デプロイメントに存在することを確認します。
• パージ・ジョブ・データベース・ロードの計画: 管理対象Oracleパージ・ジョブはスケジュールで実行され、1つの大きな削除ではなく、SDK管理表から期限切れの行がバッチで削除されます。パージ・アクティビティがレイテンシの影響を受けやすいデータベース・ワークロードと重複する可能性がある場合、書込み率が高い環境、REDO/UNDO生成、スキップ実行履歴および行ボリュームを監視し、保持設定または操作ロールアウト計画を調整します。管理対象ジョブは1日schedule_limitを設定するため、遅延時間が長すぎる実行は、任意に遅延して開始するかわりにスキップできます。
• 記憶を信頼できる情報源として利用しない: 格納された記憶は、コンテキストと検索を改善することを目的としています。アプリケーションは、重要な決定のために信頼できるシステムに依存し続ける必要があります。

取得スコープおよびアクセス制御に関する考慮事項

Oracle AI Agent Memoryは、コール元提供のuser_id、agent_idおよびthread_id値を使用して、取得の範囲を指定します。これは強力なフィルタリング・モデルですが、取得したコンテンツの使用方法または表示方法を決定する際にアプリケーションが依存する唯一の制御ではありません。

デフォルトでは、スレッド・スコープ取得では、user_idとagent_idの完全一致とthread_idのより広い一致が使用されるため、関連する結果は、同じユーザー・エージェント・ペアの過去のスレッドにまたがることができます。最上位のOracleAgentMemory.search()およびsearch_async()コールでは、明示的なユーザー・スコープ指定と正確なユーザー一致も必要です。パブリック・クライアントAPIが誤って複数のユーザーを検索しないように、省略されたユーザー・スコープおよびexact_user_match=Falseを拒否します。user_id=Noneの受渡しは、ユーザー完全一致でのみ許可され、スコープなしレコードのみをターゲットとします。

取得を設計する際には、次の演習を使用します。

• アプリケーション・ルールをメモリー・スコープにマップ: アプリケーションがSDKに渡すスコープが、テナント、ユーザーおよびデータ共有ルールと一致していることを確認します。
• すべてのクライアント検索で明示的なユーザー・スコープを渡す: リクエストJSONまたはその他のコール元制御入力からではなく、認証されたリクエスト・コンテキストからuser_idを導出し、各トップレベルのOracleAgentMemory.search()またはsearch_async()コールで指定します。user_id=Noneは、スコープなしレコードに意図的に制限されたワークフローに対してのみ使用します。
• ユース・ケースを満たす最も狭いスコープの優先: より機密性の高いデータを処理するワークフローには、完全一致フィルタと厳密なフィルタを使用します。
• クロススレッド取得を意図的に確認する: より広範な取得により、セッション間の継続性が向上しますが、アプリケーションでは、その動作が適切な場合にのみ有効にする必要があります。
• 検索結果を最終決定ではなく、取得したコンテンツとして処理: 返された記憶は関連性がある可能性がありますが、アプリケーションはそれらを表示または処理するかどうか、およびその方法を決定する責任を負います。
• 取得したテキストを統合境界で安全に処理: 取得したレコードには、コール元提供のテキストまたはモデル派生テキストを含めることができます。取得したメモリーまたはその他の返されたテキストがHTML、Markdown、テンプレート、ログまたはその他の出力サーフェスにレンダリングされる場合、コンテキストに適したエスケープまたはサニタイゼーションを適用してから、それを表示、変換、またはダウンストリーム・システムに渡します。

アプリケーション統合および呼出し側の信頼に関する考慮事項

Oracle AI Agent Memoryは、エンド・ユーザーが直接ではなく、統合アプリケーションまたはその他の信頼できるバックエンド・コードによってコールされることを想定しています。エンド・ユーザー向けのセキュリティ境界ではなく、エンド・ユーザーによる認証または認可を単独で実行しません。パッケージは、コール元を信頼して、各操作に対して正しいuser_id、agent_id、thread_idおよび取得スコープを提供します。

重要:統合アプリケーションは、Oracle AI Agent Memory APIをコールする前に、エンド・ユーザーの認証、アクセスの認可、および正しいuser_idとスコープの導出を担当します。コール元が提供するuser_idは、アイデンティティの証明ではなく、範囲指定値です。

SDKをエージェント・アプリケーションに統合する場合は、次の演習を使用します。

• セキュリティに依存するアプリケーション入力としてuser_idを処理: 統合アプリケーションが、認証されたコンテキストではなく、リクエストJSONまたはその他のコール元制御入力からuser_idを導出する場合、クロスユーザー・メモリー・アクセスを許可できます。エンド・ユーザーが任意の値を選択できるようにするのではなく、認証済アプリケーション・コンテキストからuser_idを導出します。
• すべてのメモリー・コールの前にアプリケーション認可を適用: 統合アプリケーションは、現在のリクエストに対して有効なuser_id、agent_id、thread_idおよび検索スコープ値を決定し、意図したテナントおよびユーザー境界内で読取りおよび書込みを保持する必要があります。
• RAWメモリーAPIをエンド・ユーザーに公開しない: add_memoryや検索ヘルパーなどのパッケージAPIは、コール元を検証し、ポリシーを適用し、書込みまたは返すことができるデータを制御するアプリケーション・ロジックにラップする必要があります。
• ユーザーID検出および列挙特権の保持: パッケージがuser_id値のリストまたは列挙のためのヘルパーを追加する場合は、管理機能としてのみ処理し、統合アプリケーションを介してエンド・ユーザーに公開することはありません。
• スコープ・オーバーライドの慎重な確認: スレッド・スコープを広げ、完全一致を無効化したり、下位レベルのストアAPIにドロップするワークフローは、信頼できるコンポーネントに制限され、クロスユーザー効果またはクロステナント効果についてレビューする必要があります。

ロギングおよび診断に関する考慮事項

Oracle AI Agent Memoryは、標準のPythonロギングを使用し、統合アプリケーションのアプリケーション・ログ・ハンドラまたはログ・レベルを構成しません。アプリケーションは、oracleagentmemoryロガーを有効にし、既存のロギング構成を介してSDKログをルーティングできます。

SDKログを使用する場合は、次の演習を使用します。

• 本番デプロイメントを非DEBUGレベルで保持: DEBUGロギングは、制御された開発またはサポート診断のみを目的としており、本番ログの収集には適していません。
• 診断ログへのアクセスの制限: 適切なアクセス制御、保持および共有ポリシーを使用して、保護されたシンクにログを格納します。オペレーティング環境外でログを送信する前に、サポート・バンドルを確認します。
• アプリケーション・ロギング・ラッパーに機密コンテキストを追加しない: プロンプト、メモリー・コンテンツ、資格証明、RAWメタデータ、データベース行値またはコール元制御識別子を使用してSDKログ・レコードをエンリッチしないでください。
• ログ・テキストを監査インタフェースではなく診断出力として処理: ログ・メッセージはSDKの動作のトラブルシューティングに役立ちますが、アプリケーションはセキュリティおよびコンプライアンス・ワークフローに対して独自の明示的な監査イベントを使用する必要があります。

データベース・アクセス、スキーマ管理およびシークレットに関する考慮事項

Oracle AI Agent Memoryは、コール元提供のOracle Database接続またはプールを使用します。パッケージは、データベース資格証明自体を作成または管理しません。また、コール元にかわってデータベース・ネットワーク暗号化を作成、ネゴシエートまたはアップグレードしません。

重要:本番コードは、TLS対応のOracle Database接続またはプールをOracle AI Agent Memoryに渡す必要があります。SDKは、コール元提供の接続またはプールをそのまま使用し、プレーン・テキストDSNをアップグレードしません。信頼できないネットワーク、共有ネットワークまたは外部ネットワーク間でプレーン・テキストのデータベース接続を使用しないでください。python-oracledbを使用する場合は、公式のOracle Databaseへのネットワーク・トラフィックのセキュアな暗号化の項に従い、接続またはプールの作成の一環としてTLSまたは別の承認済暗号化トランスポートを構成します。

重要: APIキー、パスワードまたはその他のシークレットをアプリケーション・コード、チェックイン構成またはエクスポートされたアーティファクトに直接埋め込まないでください。セキュア・インジェクション・メカニズムを常に使用し、資格証明アクセスの最小権限の原則に従います。

次のデプロイメント・プラクティスをお薦めします。

• 必要な権限のみを持つデータベース・ユーザーの使用: 選択したデプロイメント・モデルおよびスキーマ・ポリシーに必要なもののみを付与します。
• 実際の場合、削除ワークフローに別のデータベース・ユーザーを使用します: アプリケーションでレコードを削除する必要がある場合は、それらのパスの専用の接続またはプールを優先し、管理対象Oracle AI Agentメモリー表のDELETEをそのデータベース・ユーザーにのみ付与します。メインのランタイム接続は、通常の操作に必要な削除以外の権限に限定しておき、偶発的または不要な削除のブラスト半径が狭くなるようにします。DELETE権限のない接続を介してコール元がdelete()を呼び出すと、Oracle Databaseはその文を拒否します。
• 暗号化されたデータベース接続およびプールの作成: 本番コードは、TLS対応のOracle Database接続またはプールをSDKに渡す必要があります。Oracle AI Agent Memoryは、指定されたとおりにコール元提供の接続またはプールを使用するため、python-oracledbでは、protocol="tcps"や同等のTCPS DSNなどのTLS対応接続を優先し、必要なウォレットまたはCA資料を構成し、サーバー証明書の検証を有効のままにします。
• DDL変更を明示的に必要でないかぎり、デフォルトのスキーマ・ポリシーを保持します: SchemaPolicy.REQUIRE_EXISTINGがデフォルトであり、通常のアプリケーションの起動時にスキーマ・オブジェクトの作成、変更または削除が回避されます。
• 破壊的設定モードの制限: SchemaPolicy.RECREATEは、設定、テストまたは管理ワークフローを目的としており、通常の本番パスでは使用しないでください。
• アプリケーション・コード内の動的SQLアセンブリではなく、パッケージ管理SQLパスに依存: 管理対象DBパスでは、レコード値および検索フィルタがバインド変数とともに送信され、管理対象オブジェクト名は検証済接頭辞から導出されます。
• 接続およびプロバイダの資格証明の保護: データベース、LLMを格納し、OCI Vaultなどのシークレット・マネージャに資格証明を埋め込み、定期的にローテーションします。
• ThinモードとThickモードの両方で検証されたTLSを優先: 公式のpython-oracledbドキュメントでは、ThinモードとThickモードの両方がTLSをサポートし、ThickモードでもOracle Native Network Encryptionを使用できることに注意してください(これが承認された標準です)。
• データベースへのセキュア・トランスポートの使用: データベース・ネットワーク・セキュリティ、TLS構成および認証方法は、コール元提供の接続によって決定され、組織の標準に従う必要があります。

ネットワーク通信および外部エンドポイントに関する考慮事項

Oracle AI Agent Memoryは、デプロイメントがリモートLLMまたは埋込みプロバイダを構成するときに、外部サービスと通信できます。SDKは、構成されたクライアント・パスを介してプロンプトおよびリクエスト・パラメータを転送しますが、周囲のアプリケーションおよびデプロイメントは引き続きこれらの接続を保護します。

次をお薦めします:

• モデル・エンドポイントにHTTPSを使用し、使用可能な場合はプライベートまたは制限付きネットワーク・パスを優先します。
• 予期しない宛先、異常なリクエスト・ボリュームまたは異常なトークン消費のアウトバウンド・トラフィックおよびプロバイダの使用状況を監視します。
• 規制ワークフローまたは機密ワークフローでアクティブ・メモリー機能を有効にする前に、コンプライアンスおよびレジデンシーのニーズに一致するプロバイダを選択します。

リソース疲労ベクトルに関する考慮事項

メモリー・ワークフローは、データベースの使用率を高め、トラフィックを埋め込み、LLMトークンを経時的に消費できます。これは、悪意のある過剰使用と、サイズの超過メッセージや過剰な検索パターンなどの無実の実装ミスの両方に当てはまります。

本番の強化の一環として、次のコントロールを使用します。

• 実用的なプロンプトおよびメッセージ境界の設定: ワークロードおよびプロバイダの制限にあわせて、max_message_token_lengthやmemory_extraction_token_limitなどの値を構成します。max_message_token_lengthは、抽出ワークフローで使用されるプロンプト時コピーを制限します。格納されたメッセージは変更されません。
• バインドされた取得サイズ: アプリケーション検索に適切なmax_results値およびレコード・タイプ・フィルタを使用します。
• SDK外部のインフラストラクチャ制限の適用: データベース割当て、接続制限、ネットワーク制御、エンドポイント・タイムアウトおよび周囲のデプロイメントのレート制限を使用します。
• 時間の経過に伴う増加の監視: 格納されたメッセージ量、永続メモリーの増加、プロバイダの使用量および問合せレイテンシを追跡して、信頼性に影響が及ぶ前に保持またはチューニングの変更を行えるようにします。