エージェント・メモリーの開始

この記事では、エージェント・メモリーのインストールと、ユーザー・コンテキストの格納および取得などの基本的なメモリー操作の実行について説明します。

前提条件

次のものがあることを確認します。

Oracle AI Databaseの機能要件

Oracle Agent MemoryのDBバック・ストアには、Oracle AI Database 23ai以上(データベース・バージョン23.4以上)が必要です。Oracle AI Vector Searchの場合、データベースのCOMPATIBLE初期化パラメータを23.4.0以上に設定します。

選択した検索戦略には、次の追加要件があります。

マネージド・スキーマの初期化中、Oracle Agent Memoryは、DDLを実行する前に接続データベース・バージョンを検証し、選択した検索戦略が使用できない場合にアップグレード・アクションを報告します。

管理対象データベースの設定

スキーマ所有者がメモリー・ストアを作成または再作成すると、Oracle Agent Memory Pythonパッケージによって、必要な管理対象データベース・オブジェクトが準備されます。所有者は、Oracle CREATE TABLEおよびCREATE PROCEDUREシステム権限を必要とします。

スキーマ設定のスキーマ所有者として接続します。schema_ownerを使用するアプリケーション接続は、既存のストアにアクセスし、SchemaPolicy.REQUIRE_EXISTINGを使用する必要があります。これは、所有者の管理対象データベース・オブジェクトを作成または更新しません。

SDKのインストール

oracleagentmemoryのすべてのバージョンおよびサポートされているプラットフォームは、ソフトウェアのダウンロード・ページにあります。

エージェント・メモリーをインストールするには、次を実行します。

pip install "oracleagentmemory==26.8.0"

pipを使用してインストールすると、サポートされているプラットフォームで事前構築済のバイナリ・ホイールがプルされます。

ロギングおよび診断

Oracle AI Agent Memoryは、oracleagentmemoryで始まるロガー名で、標準のPythonロギングを介して診断メッセージを出力します。SDKでは、ハンドラまたはログ・レベルは構成されません。アプリケーションは、これらのログを既存のコンソール、ファイルまたは可観測性パイプラインにルーティングできます。一部のログ・レコードでは、構造化ロギング・ハンドラによって取得できる安全な構造化診断にPythonロギングのextraフィールドが使用されます。

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

制御された環境でトラブルシューティングを行うには、DEBUGログを有効にします:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

本番デプロイメントは、DEBUG以外のレベルで維持します。DEBUGログは開発およびサポート診断を目的としており、ログ・メッセージ・テキストは安定したパブリックAPIとして扱わないでください。

Time-to-Liveおよび期限切れ- レコード・パージ

Oracle DBにバックアップされたメッセージおよびメモリーは、スキーマ・レベルの保存デフォルトと、書込みおよび更新APIのレコードごとのttl_days/ttl_anchor値の組合せによって自動的に期限切れになる場合があります。

Oracle Agent Memoryは、管理対象スキーマを作成またはアップグレードするときに、有効なソース行が存在しなくなった期限切れ行、その取得チャンクおよび孤立取得チャンクを物理的に削除する日次DBMS_SCHEDULERパージ・ジョブも作成します。スキーマ設定でそのジョブを作成する必要があるが、データベース・ユーザーにCREATE JOBがない場合、設定が警告で完了します。失効した行は読取りおよび検索から除外されますが、失効した孤立したチャンクは、権限のあるユーザーがジョブを作成するまで物理的にパージされません。SchemaPolicy.REQUIRE_EXISTINGでは、欠落しているパージ・ジョブは許容され、DEBUGレベルで記録されます。

リンク・メモリー・スキーマは、パージ・ジョブが期限切れのメモリーを削除し、Oracleがそのリンクをカスケードする場合など、リンクの削除後に存続するメモリーを再検証するトリガーも作成します。スキーマ所有者は、スキーマの作成時またはアップグレード時にCREATE TRIGGERを必要とします。通常のランタイム・ユーザーは、その権限を必要としません。

完全な保存モデル、MemoryRetentionConfig設定、パージ・ジョブ検証問合せ、手動DBAジョブ作成およびTimeToLiveAnchorを使用したPythonの例については、メッセージおよびメモリーの存続時間の使用を参照してください。

リンクメモリースキーマのアクセス権

リンク・メモリー・スキーマには、Oracle SQLプロパティ・グラフと、リンクの削除時にライフサイクル状態を正しく維持するデータベース・トリガーが含まれています。

memory_store_idを設定すると、管理対象グラフ名に表と同じ接頭辞が付けられます。たとえば、memory_store_id="SALES"はSALES_MEMORY_GRAPHを作成します。

APP_SCHEMAおよびAPP_USER値はプレースホルダです。データベース・ユーザー名に置き換えます。引用符で囲まれていないOracle識別子は大文字で格納されるため、例では大文字を使用します。

  1. スキーマの設定時に、スキーマ所有者にCREATE PROPERTY GRAPHおよびCREATE TRIGGERを付与します。これらは、管理対象グラフまたはリンク削除トリガーを作成する必要があるたびに、SchemaPolicy.CREATE_IF_NECESSARYまたはSchemaPolicy.RECREATEで必要です。 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    アップグレードで管理対象グラフまたはリンク削除トリガーを作成または再作成する必要がある場合は、後からSDKをアップグレードする前に再度付与します。

  2. 通常のアプリケーション実行時に、Oracleに接続するユーザーを決定します。
    • ランタイム・ユーザーがAPP_SCHEMAの場合、追加のグラフ付与は必要ありません。グラフ所有者は、独自のグラフにアクセスできます。
    • ランタイム・ユーザーが異なる場合は、スキーマの設定後にAPP_SCHEMAとして次を実行します。デフォルトのグラフ名はMEMORY_GRAPHで、memory_store_idが設定されている場合は接頭辞付きの名前を使用します。 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      ランタイム・ユーザーには、Oracle Agent Memoryデプロイメントのリストアに必要な通常のデータベース・アクセスも必要です。

SchemaPolicy.REQUIRE_EXISTINGは、グラフおよびトリガーがすでに存在することを想定しているため、最初のステップをスキップします。別のランタイム・ユーザーは、引き続き管理対象プロパティ・グラフにアクセスする必要があります。

メモリー・インスタンスの初期化

埋込み、LLMおよびデータベース接続を構成して、OracleAgentMemoryインスタンスを作成します。

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

ノート:デフォルトでは、管理対象Oracle AI Databaseスキーマはメッセージおよびメモリーの保存期間を設定しません。別の保存期間を使用するように、MemoryRetentionConfigまたはレコードごとの存続時間設定を構成します。詳細は、「メッセージおよびメモリーの存続時間の使用」を参照してください。

メモリー・エントリの格納

スレッドを作成し、メッセージを追加し、ユーザーのメモリー・エントリを格納することから始めます。

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

メモリー・エントリの取得

ユーザー・スコープ問合せを使用してメモリーを検索します。

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

出力:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

ノート:示されている出力は図です。将来のバージョンでは、追加の結果タイプ、フィールド、または順序付けが返される場合があります。

モデル互換性

次の大規模言語モデル(LLM)および埋込みモデルは、oracleagentmemoryと互換性があります。

LLM

次の大規模言語モデル(LLM)が互換性があることが確認されました。

OCIでホストされるモデル

OpenAI

自己ホストLLM

Anthropic

Gemini

埋込み

次の埋込みモデルが互換性があることが確認されました。

OCIでホストされるモデル

OpenAI

自己ホストLLM

Gemini