エージェント・メモリー

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

Oracle Agentメモリー

クラス 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

ノート:

エージェント・プロファイル・レコードは、クライアント・レベルのストアに格納されます。

例

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

ノート:

ユーザー・プロファイル・レコードは、クライアント・レベルのストアに格納されます(特定のスレッドには関連付けられません)。

例

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– このスレッドレコードに添付されたエージェント識別子。省略すると、新しいものが生成されます。
  • 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つのサマリー更新が実行されます。add_messages中にリフレッシュされたスレッド要約メタデータにも同じ頻度が再利用されます。省略した場合、デフォルトは4です。
  • memory_extraction_frequency int– メモリー抽出更新の頻度。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1つの抽出が実行されます。省略した場合、デフォルトは-1です。
  • memory_extraction_token_limit int– トークンの最大抽出プロンプトサイズ。省略した場合、デフォルトは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_memory

識別子によるメモリー・レコードの削除。

• パラメータ: memory_id str– メモリー識別子。
• 戻り値:削除されたメモリー行の数(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– 削除するスレッド識別子。
  • allow_non_existing bool– Trueの場合、欠落しているスレッドの削除はno-opとして扱われます。
• 戻り値:削除されたスレッド行の数(0または1)。
• 戻り型: int

例

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

メソッド 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– トークンの最大抽出プロンプトサイズに対するオプションのオーバーライド。
  • 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'