エージェント・メモリー

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

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は、索引が存在した後の継続的なメンテナンスを制御します。最初の索引ビルドを非同期にすることはありません。

例

別のデータベース・ユーザーが作成したスキーマにアクセスするには、アプリケーションDBユーザーのmemory_rw_poolを構成し、memory_schema_ownerを所有ユーザーの引用符で囲まれていないデータベース名に設定します。

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),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

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,
    memory_store_id=memory_store_id,
)

メソッド 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'

method add_agent_async (非同期)

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

ノート

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

例

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

メソッド add_image

クライアントにイメージ・レコードを追加します。

例

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

method add_image_async (非同期)

構成済ストアを介して1つのスタンドアロン・イメージを保持します。

descriptionを省略するか、Noneを指定すると、構成されたLLMによってキャプションが生成されます。

メソッド 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 (非同期)

メモリー・システムに非同期的にメモリーを追加します。

例

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

メソッド 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'

method add_user_async (非同期)

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

ノート

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

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async(
    "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()と同じ停止動作に従います。タイムアウトが期限切れになると、バックグラウンド・ワークがまだ実行されている間に戻ってきます。

例

import asyncio
asyncio.run(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'

method create_thread_async (非同期)

スレッドを作成して非同期に登録します。

例

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

メソッド delete_agent

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

ノート

プロファイルを削除する前に、このメソッドは、このエージェント・メモリー・コンポーネントを介して認識される所有スレッドに対して、以前のバックグラウンド抽出がすでに受け入れられるまで、最大300秒待機します。この待機は、カスケード・クリーンアップが有効かどうかに適用されます。カスケード・クリーンアップは、バッキング・ストア内で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

method delete_agent_async (非同期)

エージェント・プロファイル・レコードを識別子で非同期に削除します。

ノート

このメソッドは、delete_agent()で説明されているバックグラウンド抽出待機および同時実行性の動作に従います。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

メソッド delete_image

イメージ・レコードを識別子で削除します。

method delete_image_async (非同期)

構成済ストアを介して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_memory()で記述されたターゲットとなるバックグラウンド抽出待機および同時実行性の動作に従います。

例

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

識別子または完全なエンドポイント・タプルによるリレーションの削除。

relation_idが指定されていない場合は、格納されているソースからターゲットへの方向ですべてのソース、ターゲット、型およびリレーション・ラベル引数を指定します。

例

client.delete_record_link(relation_id="relation-id")
1

リレーションをIDまたは完全なエンドポイント・タプルで非同期に削除します。

メソッド 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

method delete_thread_async (非同期)

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

ノート

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

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

メソッド delete_user

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

ノート

プロファイルを削除する前に、このメソッドは、このエージェント・メモリー・コンポーネントを介して認識される所有スレッドに対して、以前のバックグラウンド抽出がすでに受け入れられるまで、最大300秒待機します。この待機は、カスケード・クリーンアップが有効かどうかに適用されます。カスケード・クリーンアップは、バッキング・ストア内で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

method delete_user_async (非同期)

識別子によるユーザー・プロファイル・レコードを非同期的に削除します。

ノート

このメソッドは、delete_user()で説明されているバックグラウンド抽出待機および同時実行性の動作に従います。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("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="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

method get_thread_async (非同期)

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

ノート

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

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

格納された2つのレコード間の有向リレーションを作成します。

現在、両方のエンドポイントはメモリーに似たレコード("memory"、"fact"、"guideline"または"preference")である必要があります。組込みのリレーション型は、"supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by")および"duplicates"です。"contradicts"と"duplicates"は、同じラベルを逆に使用します。

1つのエンドポイント・ペアに対して格納できる方向は1つのみです。opposite_relation_typeは、ターゲットからソースへのトラバース時にリレーションを指定します。たとえば、new "supersedes" oldの場合、逆走はold "is_superseded_by" newです。

例

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

格納されたレコード間の型付きリレーションを非同期的に作成します。

現在、両方のエンドポイントはメモリーに似たレコード("memory"、"fact"、"guideline"または"preference")である必要があります。組込みのリレーション型は、"supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by")および"duplicates"です。"contradicts"と"duplicates"は、同じラベルを逆に使用します。

メソッド list_agents

永続エージェント・プロファイル・レコードをリストします。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

method list_agents_async (非同期)

永続化されたエージェント・プロファイル・レコードを非同期的にリストします。

例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

メソッド list_images

永続スタンドアロン・イメージ・レコードをリストします。

例

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

method list_images_async (非同期)

永続化されたスタンドアロン・イメージ・レコードを非同期的にリストします。

例

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

メソッド list_memories

永続メモリーのようなレコードをリストします。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

method list_memories_async (非同期)

永続メモリーに似たレコードを非同期的にリストします。

例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

メソッド list_messages

永続チャット・メッセージ・レコードをリストします。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

method list_messages_async (非同期)

永続化されたチャット・メッセージ・レコードを非同期的にリストします。

例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

メソッド list_threads

永続化された会話スレッドをリストします。

例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

method list_threads_async (非同期)

永続化された会話スレッドを非同期的にリストします。

例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

メソッド list_users

永続ユーザー・プロファイル・レコードをリストします。

例

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'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

method list_users_async (非同期)

永続ユーザー・プロファイル・レコードを非同期的にリストします。

例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

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

ノート

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

method search_async (非同期)

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

ノート

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

メソッド update_image

格納されたイメージ・レコードを識別子で更新します。

ノート

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

method update_image_async (非同期)

構成済ストアを介して1つのスタンドアロン・イメージを更新します。

既存のバイトを保持するには、imageを省略します。imageを指定する場合は、mime_typeを指定する必要があります。既存の説明を保持するには、descriptionを省略します。Noneを渡して、構成されたLLMで新しい説明を生成します。nullでない説明によって、その説明が直接置き換えられます。メタデータ、タイムスタンプおよび有効期限の設定は、指定すると更新されます。

メソッド update_memory

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

ノート

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

method update_memory_async (非同期)

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

ノート

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

例

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

格納されている1つのリレーションの可変フィールドを更新します。

省略された値は保持されます。relation_typeが組込みメモリー・リレーション型に変更されると、その固定逆ラベルがopposite_relation_typeに置換されます。timestampにNoneを渡すか、metadataを渡してその値をクリアします。

例

client.update_record_link("relation-id", relation_type="supports")
1

1つのストアド・リレーションを非同期的に更新します。

メソッド 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

method update_thread_async (非同期)

更新されたスレッド・メタデータと永続的なランタイム構成を非同期に保持します。

メソッド 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()と同じ動作に従います。

例

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

イメージ入力制限

クラス oracleagentmemory.core.ImageInputLimitConfig

ベース: object

RAWイメージおよびLLMイメージ・リクエスト制限を構成します。

省略されたフィールドは、次の広範な構成スコープから継承されます。クライアント・フィールドはSDKのデフォルトを継承しますが、スレッドごとのフィールドはクライアント構成を継承します。検証を無効にできず、解決された値はSDKの絶対maximaを超えることはできません。

例

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

メモリー抽出

クラス oracleagentmemory.core.MemoryExtractionImageContext

ベース: str、Enum

イメージが自動メモリー抽出にどのように関与するかを選択します。

DISABLEDは、抽出プロンプトからイメージおよびイメージの説明を省略します。イメージは、元のイメージ・パーツを送信します。CAPTIONはイメージの説明をテキストとして送信し、選択したすべてのイメージに空白でない説明が必要です。

キャプション = 'CAPTION'

説明をテキストとして含め、選択したイメージごとに1つ必要です。

DISABLED = 'DISABLED'

抽出プロンプトにイメージまたはイメージの説明を含めないでください。

イメージ = 'IMAGE'

元のイメージ・パーツを抽出プロンプトに含めます。

MEMORY = 'MEMORY'

イメージ固有のメモリー抽出は現在サポートされていません。

クラス oracleagentmemory.core.MemoryExtractionConfig

ベース: object

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

このオブジェクトをOracleAgentMemory、create_thread、get_threadまたはupdate_threadに渡して、自動抽出を構成します。extraction_modeおよびバックグラウンド・キューの設定により、イメージ説明の自動生成も制御されます。各フィールドは独立して変換されます。操作に指定された値が優先され、その後に保存されたスレッド値、クライアント値およびSDKデフォルトが続きます。新規およびスタンドアロン・スレッドには、スレッド値が保存されていません。

例

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

抽出またはイメージの説明がすぐにキューに入れられない場合の処理。

省略された値はDROPに解決されます。

キュー容量を待機モードで待機するバックグラウンド作業の最大秒数。

省略された値は300.0秒に解決されます。

自動リフレッシュ前の、最新の有効なサマリー後のメッセージ。

0以下の値は、チェックごとにリフレッシュされます。

OAMがスレッド読取りおよび抽出プロンプトのコンテキスト・サマリーを保持するかどうか。

抽出とイメージの説明をインラインで実行するか、バックグラウンドで実行するか。

省略された値はBACKGROUNDに解決されます。

抽出実行間のメッセージ。0未満の値は、追加するたびに抽出されます。

イメージ表現。省略はスレッド、クライアント、DISABLEDに解決されます。

ソース・メッセージ・メタデータが抽出されたメモリーにコピーされました。

プロンプトの入力トークン予算。1未満の値は制限を無効にします。

抽出プロンプトに使用される最近のメッセージ・ウィンドウ。-1では、新しいメッセージのみが使用されます。

自動リンク解決プロンプトに追加されるオプションのコール元命令。

抽出された記憶に対する自動リンクの解決方法。

省略された値はPOST_EXTRACTIONに解決されます。

POST_EXTRACTIONリンク解決の入力トークン予算合計。

1未満の値は、制限を無効にします。

クラス oracleagentmemory.core.MemoryExtractionMode

ベース: str、Enum

自動抽出およびイメージの説明を実行するタイミングを制御します。

INLINEは、書込みメソッドが返される前に導出された作業を完了します。BACKGROUNDは、RAW書込みが成功した後、その動作をキューに入れようとします。バックグラウンド・ワークはベスト・エフォートです。生成された説明と導出された記憶は後で表示されるか、完了できない場合は決して書き込まれない可能性があります。

背景 = '背景'

raw書き込みおよびバックグラウンドでの派生作業の実行後に戻ります。

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

書込みが戻される前に、完全な抽出およびイメージの説明。

クラス oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

ベース: str、Enum

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

抽出固有の名前にもかかわらず、この設定はバックグラウンド・モードでのイメージ説明の自動生成にも適用されます。

= 'DROP'を削除します

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

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

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

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

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