エージェント・メモリー

このページでは、Oracle AI Agentの具体的なメモリー実装について説明します。

Oracle Agentメモリー

ノート: OracleAgentMemory.delete_thread()は、スレッド・スコープのカスケード・クリーンアップでサポートされるパスです。スレッドは、関連するメッセージ、永続メモリーおよび管理対象取得データとともに削除されます。これは、RAWメッセージ行のみを削除するOracleThread.delete_message()よりも大きくなります。スレッドを削除する前に、そのスレッドについてこのクライアントにすでに認識されている、以前に受け入れられたバックグラウンド抽出を待機します。削除の進行中は、同じスレッドに対するすべての同時操作をシリアライズしません。

クラス oracleagentmemory.core.OracleAgentMemory

ベース: IAgentMemory

Oracle DBまたはコール元提供のストアによってバックアップされるエージェント・メモリー・クライアント。

メモリー・クライアントを作成します。

警告: SchemaPolicy.CREATE_IF_NECESSARYは、初期化が成功する前に管理対象スキーマDDLおよびベストエフォート・データ・リライトを適用する可能性があるため、通常のクライアント起動よりもコストがかかることがあります。古い管理対象スキーマの最初のオープンを移行またはメンテナンス操作として計画します(そのスキーマに多数の行が含まれている可能性がある場合)。

スキーマ設定で管理対象の期限切れレコード・パージ・ジョブを作成する必要があるが、データベース・ユーザーにスケジューラ・ジョブ権限がない場合、初期化は警告して続行します。期限切れのメッセージおよびメモリーは読取りおよび検索から非表示のままですが、ジョブがCREATE JOBまたは同等のスケジューラ権限を持つユーザーによって作成されるまでは物理的にパージされません。

SchemaPolicy.CREATE_IF_NECESSARYが最初に既存のスキーマに対して管理対象ハイブリッド索引を作成する場合、Oracleは格納された検索テキストをスキャンし、構成済のデータベース内モデルから管理対象ハイブリッド索引状態を構築します。クライアントの起動は、そのDDLが終了するまで待機するため、大規模なスキーマの移行またはメンテナンス操作として最初のハイブリッド・アップグレードを計画します。SearchIndexSyncModeは、索引が存在した後の継続的なメンテナンスを制御します。最初の索引ビルドを非同期にすることはありません。

例

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

Oracleハイブリッド索引検索を利用するには、DB内埋込みモデルを使用します。

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

メソッド add_agent

ストアにエージェント・プロファイル・レコードを追加します。

ノート:

エージェント・プロファイル・レコードは、クライアント・レベルのストアに格納され、意図的にスコープ設定されていません。返されるレコード識別子は、アプリケーションがagent_idとして使用するパブリック識別子と同じです。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

メソッド add_memory

指定されたユーザー、エージェント、およびスレッドに起因するメモリーシステムをメモリーシステムに追加します。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

method add_memory_async (非同期)

メモリーレコードをクライアントに非同期に追加します。

メソッド add_user

ストアにユーザー・プロファイル・レコードを追加します。

ノート:

ユーザー・プロファイル・レコードは、クライアント・レベルのストアに格納され、意図的にスコープ設定されません。返されるレコード識別子は、アプリケーションがuser_idとして使用するパブリック識別子と同じです。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

メソッド close

エージェント・メモリー・コンポーネントをクローズします。

クローズは、新しいバックグラウンド抽出作業の受入れを停止し、構成されたタイムアウトまで保留中のバックグラウンド・メモリー抽出が終了するまで待機します。そのタイムアウトが期限切れになると、close()は、バックグラウンド抽出作業がまだ完了していない場合でも戻ります。このメソッドはべき等です。

例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

method close_async (非同期)

エージェント・メモリー・コンポーネントを非同期でクローズします。

このメソッドは、close()と同じ停止動作に従います。タイムアウトが期限切れになると、バックグラウンド抽出作業がまだ実行されている間に戻ってきます。

例

await client.close_async()

メソッド create_thread

スレッドを作成して登録する。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

メソッド delete_agent

識別子によるエージェント・プロファイル・レコードの削除。

ノート:

カスケード削除は、バッキング・ストア内で計画および実行されるため、1つのストア操作でプロファイルの削除およびすべてのスコープ指定子削除が発生します。カスケード削除が実行される前に、このメソッドは、このエージェント・メモリー・コンポーネントを介してその時点で認識されている所有スレッドに対して、以前のバックグラウンド抽出がすでに受け入れられているのを待機します。待機の開始後、または別のエージェント・メモリー・コンポーネントまたはプロセスによって開始された作業が受け入れられるまで待機しません。削除の進行中にアクターを有効範囲にした同時使用はサポートされていません。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

メソッド delete_memory

メモリーに似たレコード(メモリー、ファクト、プリファレンス、ガイドラインなど)を識別子で削除します。

例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

method delete_memory_async (非同期)

メモリーに似たレコード(メモリー、ファクト、プリファレンス、ガイドラインなど)を識別子で非同期に削除します。

メソッド delete_thread

スレッド識別子に関連付けられているすべてのレコードを削除します。

ノート:

この操作は、スレッドの保存期間を完全に削除する必要がある場合に使用します。バッキング・ストアは、スレッド・スコープの関連付けられたメッセージ、永続メモリーおよび管理対象取得データとともにスレッドを削除します。これは、RAWメッセージ・レコードのみを削除し、そのメッセージから作成された派生メモリーにカスケードしないOracleThread.delete_message()とは異なります。スレッドを削除する前に、このメソッドは、このエージェント・メモリー・コンポーネントを介してそのスレッドに対してすでに受け入れられている以前のバックグラウンド抽出を待機します。待機の開始後、または別のエージェント・メモリー・コンポーネントまたはプロセスによって開始された作業の後、バックグラウンド作業が受け入れられるまで待機しません。削除の進行中に同じスレッドを同時に使用することはサポートされていません。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

メソッド delete_user

識別子によるユーザー・プロファイル・レコードの削除。

ノート:

カスケード削除は、バッキング・ストア内で計画および実行されるため、1つのストア操作でプロファイルの削除およびすべてのスコープ指定子削除が発生します。カスケード削除が実行される前に、このメソッドは、このエージェント・メモリー・コンポーネントを介してその時点で認識されている所有スレッドに対して、以前のバックグラウンド抽出がすでに受け入れられているのを待機します。待機の開始後、または別のエージェント・メモリー・コンポーネントまたはプロセスによって開始された作業が受け入れられるまで待機しません。削除の進行中にアクターを有効範囲にした同時使用はサポートされていません。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

メソッド get_thread

以前に作成したスレッドを取得します。

ノート:

明示的なコールごとのオーバーライドが優先されます。実行時オーバーライドを省略すると、再オープンされたスレッドは、SDKのデフォルトにフォールバックする前に、使用可能な場合、永続化された実行時構成を使用します。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'

クエリーに関連するレコードを同期的に検索します。

ノート:

明示的なNoneスコープ値は、解決された完全一致ルールに従います。つまり、exact_*_match=Falseはそのディメンションを制約なしのままにし、exact_*_match=Trueはそのディメンションでスコープ指定されていないレコードのみに一致します。

method search_async (非同期)

クエリーに関連するレコードを非同期で検索します。

ノート:

明示的なNoneスコープ値は、解決された完全一致ルールに従います。つまり、exact_*_match=Falseはそのディメンションを制約なしのままにし、exact_*_match=Trueはそのディメンションでスコープ指定されていないレコードのみに一致します。

メソッド update_memory

格納されているメモリーに似たレコードを識別子で更新します。

ノート:

省略されたフィールドは、格納されたレコードから保持されます。ストアド・スコープは変更されません。メタデータの置換はオブジェクト全体の置換であり、再帰的なJSONマージではありません。

method update_memory_async (非同期)

格納されているメモリーに似たレコードを識別子で非同期に更新します。

ノート:

省略されたフィールドは変更されません。スコープの更新は、このAPIではサポートされていません。メタデータの置換はオブジェクト全体の置換であり、再帰的なJSONマージではありません。

メソッド update_thread

スレッド・メタデータおよび永続ランタイム構成の更新を保持します。

ノート:

ランタイム構成は、格納された会話スレッドと、このコールに渡された明示的なオーバーライドから解決され、結果を永続化する前にget_threadセマンティクスと一致します。省略されたメタデータおよび実行時構成の更新は、以前にロードされたOracleThreadインスタンスからではなく、格納されたデータから解決され、明示的に指定されたメタデータ更新または永続ランタイム構成オーバーライドのみがライトバックされます。メタデータの置換はオブジェクト全体の置換であり、再帰的なJSONマージではありません。スレッド所有権は、このAPIを介して変更できないため、user_idおよびagent_idは変更されません。抽出カウンタなどの可変の実行時状態は変更されません。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

メソッド wait_for_memory_extraction

このクライアントによって開始された以前のバックグラウンドメモリーの抽出を待ちます。

このメソッドは、このエージェント・メモリー・コンポーネントが所有するすべてのスレッドにわたって、このOracleAgentMemoryインスタンスを介してすでに開始されたバックグラウンド抽出を待機します。この待機の開始後、別のエージェント・メモリー・コンポーネントによって開始された抽出、または別のプロセスで実行された抽出の開始後、抽出が開始されるまで待機しません。この待機の終了時に抽出の失敗がカウントされます。

例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (非同期)

以前のバックグラウンド・メモリー抽出を非同期に待機します。

このメソッドは、wait_for_memory_extraction()と同じ動作に従います。

例

await client.wait_for_memory_extraction_async(timeout=10)

メモリー抽出

クラス oracleagentmemory.core.MemoryExtractionConfig

ベース: object

自動メモリー抽出のグループ化された設定。

このオブジェクトをOracleAgentMemory、create_thread、get_threadまたはupdate_threadに渡して、自動抽出を構成します。省略されたフィールドは、次の広い設定から継承されます。たとえば、memory_extraction_frequencyなしで作成されたスレッドでは、エージェント・メモリー・コンポーネントのデフォルトが使用され、コンポーネントのデフォルトはSDKのデフォルトに戻ります。

例

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

クラス oracleagentmemory.core.MemoryExtractionMode

ベース: str、Enum

自動メモリー抽出作業が実行されるタイミングを制御します。

INLINEは、書込みメソッドが返される前に自動抽出を実行します。BACKGROUNDは、RAW書込みが成功し、原因抽出作業がバックグラウンドで試行された後で戻されます。バックグラウンド抽出はベスト・エフォートです。導出されたメモリーは後で表示されるか、バックグラウンド作業を完了できない場合には決して書き込まれない可能性があります。

背景 = '背景'

RAWメッセージの永続化後に戻り、バックグラウンド作業でベストエフォート抽出を実行します。

インライン = 'インライン'

writeメソッドが返される前に抽出を実行します。

クラス oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

ベース: str、Enum

バックグラウンド抽出が時間内にキューに入れられない場合の動作を制御します。

= 'DROP'を削除します

警告を記録し、キュー容量が使用不可になったらすぐに続行します。

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

構成されたタイムアウトまでのキュー容量を待ってから、警告を記録して続行します。

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

構成されたタイムアウトまでのキュー容量を待機してから、TimeoutErrorを呼び出します。