よくある質問(FAQ)とトラブルシューティング

このページでは、Oracle AI Agent Memoryの一般的なインストール、データベース要件、データベース・アクセスおよびパッケージ互換性の質問について説明します。

このページのスニペットのPythonスクリプト/ノートブック。

インストールおよびアップグレード

インストール中に「一致するディストリビューションが見つかりません」と表示されるのはなぜですか。

Oracle AI Agent Memoryは、Python 3.10から3.14をサポートしています。Python 3.9を使用してインストールした場合、pipは、次のような汎用エラーを報告することがあります:

ERROR: Could not find a version that satisfies the requirement oracleagentmemory==26.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.0

pythonとpipの両方に同じPythonインタプリタが使用されていることを確認します。

python --version
python -m pip --version
python -m pip install oracleagentmemory

バージョンが Python 3.10より前の場合は、Python 3.10、3.11、3.12、3.13、または3.14を使用して新しい環境を作成し、再度インストールします。

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install oracleagentmemory

データベースの要件

サポートされているOracle AI Databaseのバージョンと検索戦略を教えてください。

Oracle Agent Memoryは、DBバック・ストアにOracle AI Database 23ai (23.4)以上を必要とします。SearchStrategy.HYBRIDには、リリース更新23.6以降も必要です。Oracle AI Vector Searchに必要なCOMPATIBLE設定など、完全な戦略要件については、Oracle AI Databaseの機能要件を参照してください。

データベースをベクトル検索用にどのように構成しますか。

Oracle AI Agent Memoryでは、ベクトル検索またはベクトル索引でバックアップされたスキーマを使用する前に、Oracle Databaseでベクトル・メモリーを構成する必要があります。ベクトル・メモリー領域が構成されていないか、小さすぎる場合、データベース操作は次のエラーで失敗する可能性があります。

ORA-51962: The vector memory area is out of space for the current container.

ORA-51962のOracle AI Databaseエラー・ヘルプを参照してください。

DBAまたは特権管理者に、ルート・コンテナとターゲット・プラガブル・データベースの両方のベクトル・メモリーのサイズを尋ねます。正確な値は、データベースおよびワークロードによって異なります。この例では、ルートで512M、PDBで256Mを構成します。

ALTER SESSION SET CONTAINER = CDB$ROOT;
ALTER SYSTEM SET vector_memory_size = 512M SCOPE=SPFILE SID='*';
SHUTDOWN IMMEDIATE;
STARTUP;
ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;
ALTER SESSION SET CONTAINER = <PDB_NAME>;
ALTER SYSTEM SET vector_memory_size = 256M SCOPE=BOTH;
SELECT value FROM v$parameter WHERE name = 'vector_memory_size';

管理対象スキーマの設定がORA-00054で失敗した場合はどうなりますか?

管理対象スキーマの設定では、ベクトル、Oracle Textまたはハイブリッド検索索引を作成できます。これらのDDL操作はロックの影響を受けるため、ビジー状態のデータベースでは次のようなエラーが発生することがあります。

RuntimeError: Managed schema DDL failed (ORA-00054). Check that the database user has the
required schema privileges and quota to create, alter, and drop the SDK managed tables and
indexes. If those look correct, check for existing object-name conflicts or transient DDL
locks, then retry.

Oracle AI Agent Memoryは、マネージド・ベクトル索引、キーワード・テキスト索引およびハイブリッド索引の作成時に、一時的なORA-00054障害をすでに再試行しています。エラーが依然として環境に存在する場合は、スキーマ設定を実行する接続にセッションDDL_LOCK_TIMEOUTを増やすことが適切かどうかをDBAまたは特権管理者に問い合せてください。この設定は、Oracle AI Agent Memoryだけでなく、データベース・セッション全体を待機するDDLに影響します。

データベース・ユーザーおよび権限

あるDBユーザーがメモリー・スキーマを作成し、別のDBユーザーがそれを使用することはできますか。

特権所有者アカウントを使用して管理対象スキーマを作成し、各アプリケーションDBユーザーに必要な権限のみを付与します。通常のアプリケーションの起動では、SchemaPolicy.REQUIRE_EXISTINGを使用して、DBオブジェクトを作成または変更せずにスキーマを検証する必要があります。

ここで、ownerは、管理対象表および索引を所有するOracle AI Databaseユーザーを意味します。メモリー・レコードに関連付けられているアプリケーション・レベルのユーザーまたはエージェントとは無関係です。ランタイム・クライアントは、このデータベース・ユーザーをschema_ownerと呼びます。

1つの接続またはプールをスキーマ所有者用に、もう1つの接続またはプールをアプリケーションDBユーザー用に構成します。

import os

from oracleagentmemory.core.embedders import Embedder
from oracleagentmemory.core.llms import Llm
import oracledb

DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
OWNER_DB_USER = os.environ.get("ORACLE_MEMORY_OWNER_DB_USER", "memory_owner")
RUNTIME_DB_USER = os.environ.get("ORACLE_MEMORY_RUNTIME_DB_USER", "memory_r")
MEMORY_STORE_ID = "APP_MEMORY"

owner_pool = oracledb.SessionPool(
    user=OWNER_DB_USER,
    password=os.environ["ORACLE_MEMORY_OWNER_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)
runtime_pool = oracledb.SessionPool(
    user=RUNTIME_DB_USER,
    password=os.environ["ORACLE_MEMORY_RUNTIME_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)

次の例では、embedderおよびllmがアプリケーションにすでに構成されていることを前提としています。また、APP_MEMORY_オブジェクト名の接頭辞を使用するmemory_store_id="APP_MEMORY"も設定します。共有AGENT_MEMORY_STORES表には接頭辞がありません。アプリケーション・ユーザーは、ストアに保存された構成を読み取るためにSELECTが必要です。この所有者スキーマ内のすべてのストアの行が含まれるため、権限によってこれらのレジストリ行の読取りも許可されます。可視性の影響については、下のビューのセクションの警告を参照してください。

スキーマを所有者としてブートストラップします。

from oracleagentmemory.core import (
    OracleAgentMemory,
    SchemaPolicy,
)

owner_memory = OracleAgentMemory(
    connection=owner_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_EMPTY,
    memory_store_id=MEMORY_STORE_ID,
)

この初期化は、スキーマ所有者として接続中に実行されます。必要に応じて、Oracle Agent Memoryがそのスキーマで使用するデータベース表および内部データベース・コード(PL/SQLパッケージ)を作成します。アプリケーション・クライアントがschema_ownerに接続する前に実行します。

既存のデータベース・テーブルまたは内部データベース・コードがインストールされたPythonパッケージと一致しない場合、通常の起動で置き換えられません。スキーマ所有者として接続し、名前付きストアの置換が可能な場合にのみSchemaPolicy.RECREATEを使用します。それ以外の場合は、アプリケーション・クライアントが再接続する前に、データベース管理者に所有者スキーマの更新を依頼してください。

古い管理対象スキーマに対して、所有者アカウントがサポートされる非破壊アップグレードを意図的に適用する場合は、かわりにSchemaPolicy.CREATE_IF_NECESSARYを使用します。これを調整メンテナンス操作として処理します。1つのスキーマ所有者接続を実行し、管理対象表に書き込むアプリケーション・インスタンスを停止し、複数のクライアントによるアップグレードの同時実行を許可しません。アップグレードが正常に完了したら、SchemaPolicy.REQUIRE_EXISTINGを使用してアプリケーション・インスタンスを再起動します。この制限は重要です。管理対象アップグレードではデータ・バックフィルが実行され、Oracle AI DatabaseではDDL文が暗黙的にコミットされるため、アップグレードによって中間表シェイプが一時的に公開される可能性があります。

アップグレードが中断された場合は、報告されたデータベースの問題を解決し、同じスキーマ所有者操作を再実行します。サポートされているアップグレード・ステップは、文書化された中間状態を認識し、開始せずに再開できます。

スキーマ・ライフサイクル操作(作成、修復、アップグレード、再作成および削除)を調整メンテナンス作業として処理します。特定のメモリー・ストアに対して、1つのスキーマ所有者接続から一度に1つのライフサイクル操作のみを実行します。Oracle Agent Memory Pythonパッケージ管理を同じストアの手動データベース管理と組み合せず、ライフサイクル操作の進行中に管理対象データベース表または内部データベース・コードを変更しないでください。通常のアプリケーション・クライアントは、SchemaPolicy.REQUIRE_EXISTINGを使用する必要があります。

メモリー・ストアを作成する前に所有者側のスキーマ設定が失敗するのはなぜですか。

同じスキーマ・ストアを作成またはオープンする前に、Oracle Agent Memory Pythonパッケージで、スキーマ所有者のアカウントで使用するデータベース表および内部データベース・コードの作成が必要になる場合があります。所有者は、選択したストア機能に必要な権限とともに、CREATE TABLEおよびCREATE PROCEDUREを必要とします。たとえば、リンク・メモリーにはCREATE TRIGGERおよびCREATE PROPERTY GRAPHが必要です。機能固有の権限については、エージェント・メモリーのスタート・ガイドを参照してください。

schema_ownerを使用するアプリケーション接続では、所有者のデータベース表または内部データベース・コードを準備または変更できません。スキーマ・ライフサイクル操作を実行するために所有者として接続し、SchemaPolicy.REQUIRE_EXISTINGを使用してアプリケーション・クライアントを再接続します。

読取り専用ランタイム・ユーザーにどのような権限を付与する必要がありますか。

DBAまたは特権管理者に、接続に必要な通常のデータベース権限(CREATE SESSIONなど)をアプリケーションDBユーザーに付与するよう依頼します。次に、スキーマ所有者から管理対象オブジェクトにSELECTを付与します。これにより、ユーザーはメッセージ、メモリ、スレッド、またはプロファイルを記述せずに、既存のメモリを検索できます。

これをDBAまたは特権管理者として実行します。

GRANT CREATE SESSION TO memory_r;

次に、これらの権限をmemory_ownerとして実行します。オブジェクト名には、前述のPythonの例で使用されるAPP_MEMORY_接頭辞が含まれます。

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_r;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_THREAD TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MESSAGE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MEMORY TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_r;

読取り/書込みランタイム・ユーザーにどのような権限を付与する必要がありますか。

スレッドの作成、メッセージの追加、メモリーの追加、レコードの更新または削除を行うアプリケーションDBユーザーの場合、管理対象スキーマを所有するデータベース・ユーザーを使用して、データベースに必要な接続権限を付与します。

これをDBAまたは特権管理者として実行します。

GRANT CREATE SESSION TO memory_rw;

次に、次の権限付与をmemory_ownerとして実行します。

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_rw;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_THREAD TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MESSAGE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MEMORY TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_rw;

データベース内埋込みモデルへのアクセス権をアプリケーションDBユーザーに付与するにはどうすればよいですか。

OracleDBEmbedderをデフォルトのprovider="database"とともに使用すると、SDKは接続データベース・ユーザーとしてVECTOR_EMBEDDINGを実行します。エージェント・メモリー表に対するユーザーの権限では、埋込みモデルへのアクセス権は付与されません。埋込みSQLを実行するアカウントも、そのモデルを適用できる必要があります。

データベース・ユーザーがモデルを所有している場合、追加の付与は必要ありません。別のスキーマがモデルを所有している場合、モデル所有者またはDBAは、モデルを使用するためのランタイム・ユーザー権限を付与する必要があります。

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

ランタイム接続ではmemory_rwが使用されるため、埋込みに完全なモデル名を指定します。

from oracleagentmemory.core.embedders import OracleDBEmbedder

db_embedder = OracleDBEmbedder(
    connection=runtime_pool,
    model="MEMORY_OWNER.DOC_MODEL",
    embedding_dimension=384,
)

SELECT ANY MINING MODELは、多くのスキーマでモデルを使用する必要があるアプリケーションに対して、より広範なオプションです。既知のモデルの場合は、前述の特定の権限を使用します。モデル権限の詳細は、OracleのDBMS_DATA_MININGセキュリティ・モデルを参照してください。

`schema_owner`のかわりにビューを使用できますか。

はい。ただし、これはセカンダリ・デプロイメント・オプションです。アプリケーションDBユーザーが所有者スキーマのオブジェクトに対する権限付与を受信できる場合は、schema_ownerを優先します。ビューは、メンテナンス要件と別のレイヤーをデータベース設定に追加します。ビューを使用する場合は、所有者スキーマが存在し、アプリケーションDBユーザーに必要な直接オブジェクト権限が付与された後に、アプリケーションDBユーザーのスキーマに同じ名前を持つビューを作成します。完全な管理対象オブジェクトを公開する単純なビューを使用します。これらのビューは、レコードの書込みが必要なアプリケーションDBユーザーに対して更新可能である必要があります。アプリケーションDBユーザーとして、または必要なビュー作成権限を持つDBAを介して、次を実行します。

この例では、前にmemory_store_id="APP_MEMORY"から導出されたAPP_MEMORY_接頭辞を使用し、別のIDを使用する場合は独自の接頭辞に置き換えます。

CREATE VIEW AGENT_MEMORY_STORES AS
   SELECT * FROM memory_owner.AGENT_MEMORY_STORES;
CREATE VIEW APP_MEMORY_THREAD AS
   SELECT * FROM memory_owner.APP_MEMORY_THREAD;
CREATE VIEW APP_MEMORY_ACTOR_PROFILE AS
   SELECT * FROM memory_owner.APP_MEMORY_ACTOR_PROFILE;
CREATE VIEW APP_MEMORY_MESSAGE AS
   SELECT * FROM memory_owner.APP_MEMORY_MESSAGE;
CREATE VIEW APP_MEMORY_MEMORY AS
   SELECT * FROM memory_owner.APP_MEMORY_MEMORY;
CREATE VIEW APP_MEMORY_RECORD_CHUNKS AS
   SELECT * FROM memory_owner.APP_MEMORY_RECORD_CHUNKS;

これらのビューを使用する場合は、schema_ownerを省略し、SchemaPolicy.REQUIRE_EXISTINGを使用してクライアントを開きます。SDKは、ビューを既存の管理対象スキーマとして検証し、索引およびその他のスキーマ所有オブジェクトを所有者スキーマに残します。この回避策は、ベクトル・モード・スキーマでのみサポートされ、キーワード検索またはハイブリッド検索にはschema_ownerを使用します。アプリケーションDBユーザーは、管理対象スキーマとビューの整合性を維持します。新しいOAMバージョンが管理対象表を追加したり、必要な列を変更したりする場合は、そのスキーマに対してクライアントを開く前に、対応するビューを作成または更新します。

警告:この設定では、アプリケーション・ユーザーが相互に分離されることはありません。memory_owner.AGENT_MEMORY_STORESには、memory_ownerが所有するすべてのストアの行があります。ビューでは、これらのすべての行が公開されます。たとえば、所有者にSALESストアとSUPPORTストアがある場合、このビューを問い合せることができるアプリケーション・ユーザーは、両方のストアのレジストリ詳細を読み取ることができます。

OWNER_IDはmemory_ownerのままであり、アプリケーション・ユーザーのIDにはなりません。schema_ownerを使用する場合も同様です。SELECTアクセス権を持つアプリケーション・ユーザーは、レジストリを開くストアのみでなく、レジストリ全体を読み取ることができます。分離のために、異なるデータベース・スキーマにストアを配置し、別々にアクセス権を付与します。

権限付与後にランタイム・ユーザーと接続するにはどうすればよいですか。

実行時に、管理対象スキーマを所有するデータベース・ユーザーを使用して、SchemaPolicy.REQUIRE_EXISTINGでクライアントを構築します。

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
    #Schema owner of the tables; this avoids ALTER SESSION
    #SET CURRENT_SCHEMA for the runtime connection.
    schema_owner=OWNER_DB_USER,
)

読取り専用ユーザーは、既存のレコードに対して検索APIをコールできます。create_thread()、add_messages()、add_memory()、update()、delete()などの書込みAPIは、対応するDML権限も受け取らないかぎり使用できません。

読取り/書込みアプリケーションDBユーザーは、同じ接続パターンを使用し、通常の書込みおよび検索APIをコールできます。

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    "concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

パッケージの互換性

パッケージ依存関係の競合を解決するにはどうすればよいですか。

Oracle AI Agent Memoryは、モデル・プロバイダの統合のためにLiteLLMに依存しています。古いOracle AI Agent Memoryリリース(26.4.0を含む)では、より厳密なLiteLLM上限が使用され、新しいopenaiまたはpython-dotenvバージョンが必要な場合に他のエージェント・フレームワークまたは統合パッケージと競合する可能性があります。

Oracle AI Agent Memory 26.8.0では、litellm>=1.84.0,<2を使用して、より新しい互換性のあるopenaiおよびpython-dotenvバージョンを使用できます。リゾルバが競合を報告する場合:

利用可能な最新のOracle AI Agent Memoryリリースにアップグレードします。
互換性のないLiteLLM範囲を同じ環境に固定するほかのパッケージはインストールしないでください。たとえば、CrewAIのLiteLLM追加で互換性のないLiteLLMバージョンが選択された場合、crewai[litellm]のかわりにcrewaiをインストールします。
インストール後にpython -m pip checkを実行して、最終的な環境の一貫性を確認します。
別のフレームワークが互換性のないLiteLLM、OpenAI、または python-dotenvの範囲をピン留めする場合は、依存関係の範囲を整列できるまで、別の環境またはサービスで Oracle AI Agent Memoryを分離します。