エージェント・メモリー

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

Oracle Agentメモリー

ノート: OracleAgentMemory.delete_thread()は、スレッド・スコープのカスケード・クリーンアップでサポートされるパスです。スレッドは、関連するメッセージ、永続メモリーおよび管理対象ベクトルまたはチャンク・データとともに削除されます。これは、RAWメッセージ行のみを削除するOracleThread.delete_message()よりも大きくなります。

クラス oracleagentmemory.core.OracleAgentMemory

ベース: IAgentMemory

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

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

• パラメータ:
  • store OracleMemoryStore– オプションの事前構成済みストアインスタンス。指定した場合、クライアントは独自のストアをインスタンス化するのではなく、このストアを直接使用します。これは、呼出し側が、OracleAgentMemoryによって公開されるコンストラクタ・オプション以外のストア構成を必要とする場合に便利です。
  • connection object– オプションの Oracle DB接続/プール。指定すると、DBストアが使用されます。RAW接続を渡すと、このクライアント・インスタンスに対してシングルセッション・モードが有効になるため、コンカレント要求ではかわりに接続プールを使用する必要があります。省略した場合、呼出し側は明示的なstoreを渡す必要があります。
  • embedder IEmbedder | str–Embedder実装インスタンスまたはLiteLLM埋込みモデル識別子。省略した場合、埋込みはアタッチされず、呼出し側は下位レベルのストアAPIを介して事前計算されたベクトルを提供する必要があります。
  • LLM ILlm– メモリー抽出またはコンテキスト要約、あるいはその両方のためにスレッドによって使用されるオプションのLLMアダプタ。デフォルトでは、このクライアントから作成またはロードされたスレッドにはLLMが必要であるため、最新のメッセージを永続メモリー用にマイニングできます。ここでllmを渡すか、後でcreate_threadに指定するか、extract_memories=Falseでオプト・アウトします。
  • extract_memories bool– Trueの場合、このクライアントによって作成またはロードされるスレッドはLLMを必要とし、自動メモリー抽出は有効なままになります。自動メモリー抽出を無効にし、これらのスレッドをLLMなしで操作できるようにするには、Falseに設定します。デフォルトではTrueであるため、抽出LLMの欠落は高速で失敗します。
  • schema_policy SchemaPolicy | str– connectionからDBストアを構築する場合にのみ使用されるDBスキーマ設定ポリシー。デフォルトはSchemaPolicy.REQUIRE_EXISTINGです。
  • table_name_prefix str– connectionからDBストアを構築する場合にのみ使用されるオプションのDB表/索引接頭辞。
• Raises: ValueError– 競合するストア構成(storeと connectionの両方を渡す、DB接続のないDB固有のオプション、storeと connectionの両方を省略するなど)が指定されている場合。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

メソッド add_agent

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

• パラメータ:
  • agent_id str– エージェント識別子。
  • information str– エージェントに関するフリーフォーム情報。
• 戻り値:ストアド・エージェント・プロファイルの識別子。
• 戻り型: str

ノート:

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

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

メソッド add_memory

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

• パラメータ:
  • content str– 永続化するメモリー・コンテンツ。
  • user_id str– 格納されたメモリーに関連付けられたオプションのスコープ識別子。
  • agent_id str– 格納されたメモリーに関連付けられたオプションのスコープ識別子。
  • thread_id str– 格納されたメモリーに関連付けられたオプションのスコープ識別子。
  • memory_id str– このメモリー行の呼び出し元提供の安定した識別子(オプション)。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメモリー・レコードの識別子。
• 戻り型: str

例

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'

メソッド add_user

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

• パラメータ:
  • user_id str– ユーザー識別子。
  • information str– ユーザーに関する自由形式の情報。
• 戻り値:格納されたユーザー・プロファイルの識別子。
• 戻り型: str

ノート:

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

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

メソッド create_thread

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

• パラメータ:
  • thread_id str– スレッド識別子。省略すると、新しいものが生成されます。
  • user_id str– このスレッドレコードに添付されたユーザー識別子。省略すると、新しいものが生成されます。
  • agent_id str– このスレッドレコードに添付されたエージェント識別子。省略すると、新しいものが生成されます。
  • metadata dict[str, Any] | None– スレッド行に保持されるオプションのJSONのようなメタデータ。
  • LLM ILlm– このスレッドのオプションのLLMオーバーライド。省略すると、構築時に構成されたクライアントレベルのLLMが使用されます。デフォルトでは、自動メモリー抽出を実行できるように、クライアントまたはスレッドのいずれかがLLMを提供する必要があります。この要件からオプトアウトするには、extract_memories=Falseをここまたはクライアントに設定します。
  • extract_memories bool– 自動メモリー抽出のためのオプションのスレッドごとのオーバーライド。Trueの場合、自動抽出を実行できるように、このスレッドにはLLMが必要です。このスレッドの自動抽出を無効にし、LLMのない操作を許可するには、Falseに設定します。省略すると、クライアント・レベルのextract_memories設定が使用されます。
  • max_message_token_length int– メモリーの抽出およびコンテキストサマリーの更新中に、切り捨てまたはサマリーを実行するまでのプロンプト時間の最大メッセージサイズ。格納されたメッセージ・コンテンツは変更されません。省略すると、デフォルトで15_000トークンになります。
  • message_shortening_input_token_limit int– オーバーサイズのプロンプトタイムメッセージコピーを短縮するときにLLMに送信されたメッセージ抜粋の最大サイズ(トークン単位)。省略すると、デフォルトで30_000トークンになります。
  • memory_extraction_window int– メモリーの抽出中に含める最新のメッセージの数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1つの抽出が実行されます。省略した場合、デフォルトは-1です。
  • context_summary_update_frequency int– コンテキストサマリーのリフレッシュの頻度。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1つのサマリー更新が実行されます。省略した場合、デフォルトは-1です。
  • memory_extraction_frequency int– メモリー抽出更新の頻度。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1つの抽出が実行されます。省略した場合、デフォルトは-1です。
  • memory_extraction_token_limit int– メモリーの抽出およびサマリー更新の実行に使用されるLLMプロンプトの最大サイズ(トークン単位)。省略した場合、デフォルトは100_000です。
  • context_card_token_limit int– コンテキストカードのサマリーに使用されるLLMプロンプトの最大サイズ(トークン単位)。省略した場合、デフォルトは100_000です。
  • enable_context_summary bool– このスレッドの実行中のコンテキストサマリーを保持するかどうか。
  • **kwargs (Any)– 追加の実装固有のスレッドオプション。
• 戻り値: OracleThread。
• 戻りタイプ: OracleThread
• Raises: ValueError– 自動メモリー抽出に使用できるLLMがなく、スレッドおよびクライアントがextract_memories=Falseで構成されていない場合。

例

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

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

• パラメータ:
  • agent_id str– プロファイルを削除するエージェント識別子。
  • cascade bool– True (デフォルト)の場合は、このエージェントにスコープ指定されたレコードも削除します。これには、所有スレッド自体の削除、それらのスレッドで削除されたメッセージおよびメモリーに似たレコードの削除、およびメッセージ、メモリー、ガイドライン、ファクト、プリファレンスなどのエージェント・スコープの残りの直接レコードが含まれます。このスコープ指定クリーンアップは、一致するエージェント・プロファイル行がすでにない場合でも実行されます。プロファイル・レコードのみを削除するには、Falseに設定します。
• 戻り値:削除されたエージェント・プロファイル行の数(0または1)。これは、カスケード・クリーンアップ中にスコープ指定された行が削除された場合でも0になることがあります。
• 戻り型: int

ノート:

カスケード削除は、バッキング・ストア内で計画および実行されるため、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

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

• パラメータ: memory_id str– メモリー識別子。識別子は、格納されているmemory、guideline、factまたはpreferenceレコードを参照できます。
• 戻り値:削除されたメモリーに似た行の数(0または1)。
• 戻り型: int

例

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

メソッド delete_thread

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

• パラメータ: thread_id str– 削除するスレッド識別子。
• 戻り値:削除されたスレッド行の数(0または1)。
• 戻り型: int

ノート:

この操作は、スレッドの保存期間を完全に削除する必要がある場合に使用します。バッキング・ストアでは、スレッドがスレッド・スコープの関連付けられたメッセージ、永続メモリーおよび管理対象ベクトル行またはチャンク行とともに削除されます。これは、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

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

• パラメータ:
  • user_id str– プロファイルを削除するユーザー識別子。
  • cascade bool– True (デフォルト)の場合は、このユーザーにスコープ指定されたレコードも削除します。これには、所有されているスレッド自体の削除、それらのスレッドで削除されたメッセージやメモリーに似たレコードの削除、およびメッセージ、メモリー、ガイドライン、ファクト、プリファレンスなどの残りの直接ユーザー・スコープのレコードが含まれます。このスコープ指定クリーンアップは、一致するユーザー・プロファイル行がすでにない場合でも実行されます。プロファイル・レコードのみを削除するには、Falseに設定します。
• 戻り値:削除されたユーザー・プロファイル行の数(0または1)。これは、カスケード・クリーンアップ中にスコープ指定された行が削除された場合でも0になることがあります。
• 戻り型: int

ノート:

カスケード削除は、バッキング・ストア内で計画および実行されるため、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

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

• パラメータ:
  • thread_id str– スレッドの作成時に使用される識別子。
  • LLM ILlm– 再オープンされたスレッドのオプションのLLMオーバーライド。省略すると、構築時に構成されたクライアントレベルのLLMが使用されます。
  • extract_memories bool– 再オープンされたスレッドでの自動メモリー抽出のオプションのオーバーライド。省略すると、クライアント・レベルのextract_memories設定が使用されます。
  • max_message_token_length int– メモリー抽出時およびコンテキストサマリー更新時の切り捨てまたはサマリーの前に、プロンプト時の最大メッセージサイズをオプションでオーバーライドします。格納されたメッセージ・コンテンツは変更されません。
  • message_shortening_input_token_limit int– オーバーサイズのプロンプトタイムメッセージコピーを短縮するときにLLMに送信されたメッセージ抜粋の最大サイズ(トークン単位)をオーバーライドします(オプション)。
  • memory_extraction_window int– メモリーの抽出中に使用された最近のメッセージ数のオーバーライド(オプション)。
  • context_summary_update_frequency int– コンテキスト・サマリー・リフレッシュの頻度に対するオプションのオーバーライド。
  • memory_extraction_frequency int– メモリー抽出更新の頻度に対するオプションのオーバーライド。
  • memory_extraction_token_limit int– メモリーの抽出およびサマリー更新の実行に使用されるLLMプロンプトの最大サイズ(トークン単位)に対するオプションのオーバーライド。
  • context_card_token_limit int– コンテキストカードのサマリーに使用されるLLMプロンプトの最大サイズ(トークン単位)に対するオプションのオーバーライド。
  • enable_context_summary bool– 再オープンされたスレッドが実行中のコンテキストサマリーを保持するかどうかのオプションのオーバーライド。
• 戻り値:ストア・メタデータから再構築されたスレッド・ハンドル。
• 戻りタイプ: OracleThread
• 昇給:
  • KeyError– このクライアントインスタンスに対してスレッドIDが不明な場合。
  • ValueError– 自動メモリー抽出に使用できるLLMがなく、クライアントが extract_memories=Falseを使用して構成されていない場合。

ノート:

明示的なコールごとのオーバーライドが優先されます。実行時オーバーライドを省略すると、再オープンされたスレッドは、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'