ストアおよびスキーマ

このページには、Oracle Agent Memory SDKで使用されるコア・ストアの抽象化およびスキーマ・コントロールが表示されます。

ストアAPI

ストア書込みセマンティクス

ストア書込みでは、アプリケーションが格納するテキストと、ストアが取得に使用するペイロードが明確に分離されます。ほとんどのアプリケーションでは、メモリー・レベルおよびスレッド・レベルのAPIを使用し、ベクトル、キーワードまたはハイブリッド取得に必要な検索行をストアで準備できます。下位レベルのストアAPIでは、index_texts、index_text、embeddingsおよびembeddingが公開され、取得にどのテキストまたはベクトルを使用する必要があるかをすでに認識している高度な統合に使用されます。

各書込みは、次の2つの関連部分と考えてください。

検索オーバーライドまたは明示的な埋込みが指定されていない場合、ストアは解決された格納済テキストを取得テキストとして使用します。チャンク化が構成されている場合、空でないテキストはストアによってチャンク化されます。空のテキストはレコード・テキストを格納しますが、検索テキストは提供しません。

次の表は、明示的なベクトル・ペイロードが考慮される前に取得テキストを選択する方法を示しています。

ストア・レベルの取得ペイロード

入力 add() update()
index_textsまたはindex_textを省略 各レコードは、その解決されたcontents値を取得に使用します。 置換text値が取得に使用されます。textも省略した場合、埋込みのみの更新では、レコードの既存の取得テキスト行が再利用されます。
文字列index_textsエントリまたは文字列index_text この文字列は、そのレコードの検索テキストを置換します。ストアは、取得行を書き込む前にチャンク化することがあります。 この文字列は、そのレコードの検索テキストを置換します。ストアは、取得行を書き込む前にチャンク化することがあります。
list[str] index_textsエントリまたはlist[str] index_text リストは、呼び出し元が所有するチャンクとして扱われます。空でない各文字列は1つの取得行として書き込まれ、ストアは再度チャンク化しません。 リストは、呼び出し元が所有するチャンクとして扱われます。空でない各文字列は1つの取得行として書き込まれ、ストアは再度チャンク化しません。
None index_textsエントリまたはindex_text=None 外部index_textsリストのNoneは、「このレコード用に格納されたコンテンツを使用」を意味します。 index_text=Noneは、textも指定されていないかぎり、格納されたテキストを変更せずに取得行をクリアします。
空の文字列または空のチャンク・リスト レコード・テキストを格納し、そのレコードの取得テキストは提供しません。 textが指定されるとレコード・テキストが更新され、そのレコードの取得テキストがクリアされます。

明示的な埋込みはオプションです。これらを省略すると、ストアは、ローカル・ベクトル・ストレージの構成時に取得テキストからローカル・ベクトルを導出します。キーワード・ストアまたはハイブリッド・ストアでは、テキストのみの取得行を使用することもできます。明示的なembeddingsまたはembedding値が指定されている場合、ストアはそれらのベクトルを直接書き込み、それらのベクトルの埋込みをコールしません。

add()では、embeddings=Noneはembeddingsを省略する場合と同様に動作します。update()では、embedding=Noneは明示的です。ストアは、取得テキストをtextおよびindex_textに従って保持またはリライトしますが、これらの行はローカル・ベクトルなしで格納します。textとindex_textの両方を省略すると、既存の取得行からベクトルがクリアされます。

ベクトル・シェイプは、コール元がどのくらいのチャンク所有権を取得しているかを示します。

一部の組合せは拒否されるため、格納されたテキスト、検索テキストおよびベクトルは離れて移動しません。text=Noneを渡すと、格納されたテキスト行と取得行がクリアされるため、null以外のindex_textまたはembedding値と組み合せることはできません。アクター・プロファイル・レコードはtext=Noneをサポートしていません。update()にindex_text=Noneを渡すことは、取得行のクリアを意味するため、空でない明示的な埋込みは同じコールでは許可されません。複数の明示的なベクトルでは、更新が埋込み専用であり、既存の取得行ですでにチャンク・テキストが提供されていないかぎり、明示的なチャンク・テキストが必要です。

クラス oracleagentmemory.core.OracleMemoryStore

ベース: IMemoryStore

OracleAgentMemoryで使用される共通ストア・インタフェース。

ストア実装は、テキスト・レコードの永続化と類似性検索の実行を担当します。同期エントリ・ポイントと非同期エントリ・ポイントの両方が定義されているため、上位レベルのAPIは、ストア固有のロジックを複製せずに、一致する同期/非同期サーフェスを公開できます。

メソッド add

レコードをストアに追加します。

ノート:

add_batches()は、コール元にすでに1つ以上のPendingRecordBatchオブジェクトがある場合に使用します。

method add_agent (抽象)

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

method add_async (非同期)

行指向レコードをストアに非同期的に追加します。

同じ引数を受け入れ、add()と同じ識別子を返します。

メソッド add_batches

コール元準備の論理バッチをストアに追加します。

例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (非同期)

コール元準備の論理バッチをストアに非同期で追加します。

同じ引数を受け入れ、add_batches()と同じ識別子を返します。

method add_user (抽象)

ユーザープロファイルレコードを追加します。

method delete (抽象)

1つの格納済レコードを識別子で削除します。

method delete_thread (抽象)

スレッドとそれに関連付けられた格納データを削除します。

ノート:

これは、ストアによって管理されるスレッドおよびスレッド・スコープのレコードを削除するためのストア・レベルの操作です。保存要件でソース・メッセージと導出されたスレッド・スコープのメモリー・データの両方を削除する場合に、スレッドの削除を優先します。メッセージ・レベルの削除は、個別に永続化された導出レコードが削除されることを意味しないためです。

method get (抽象)

格納されているレコードをタイプおよび識別子別に取得します。

method list (抽象)

1つのレコードタイプの格納済みレコードをリストします。

method list_thread_messages (抽象)

1つのスレッドについて格納されているメッセージ履歴を一覧表示します。

method search (抽象)

類似性でレコードを検索します。

例

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

スカラー・メタデータ値をフィルタします。

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

ネストされたメタデータに対するフィルタ:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

次の順序を含むリスト値を完全に一致させます。

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

メタデータ配列に値が含まれている場合にフィルタします。

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

複数のメタデータ条件を結合します。レコードはすべてのキーを満たす必要があります。

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method search_async (非同期)

セマンティックの類似性によってレコードを非同期で検索します。

method update (抽象)

格納されたレコード・コンテンツの更新、データ、メタデータ、タイムスタンプまたは有効期限の埋込み。

Oracle DBストア

クラス oracleagentmemory.core.OracleDBMemoryStore

ベース: OracleMemoryStore

メッセージ、メモリーおよびアクター・プロファイルのデータベース・バックアップの永続性。

Oracle DBストアを作成します。

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

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

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

その管理対象ハイブリッド索引を作成すると、管理対象スキーマによって名前が付けられたDBMS_VECTOR_CHAINベクトル化プリファレンスも作成されます。このプリファレンスには、構成されたOracleDBEmbedderモデルからの軽量ベクトル化構成メタデータが格納されます。これは、CTX_USER_PREFERENCESやCTX_USER_PREFERENCE_VALUESなどのOracle Textプリファレンス・ビューで検査できます。

メソッド add

Oracle DBストアにレコードを追加します。

例

store.add(
    ["Index this stored text"],
    record_type="memory",
    record_ids="mem-db-add-docs",
)
['mem-db-add-docs']
store.add(
    ["Stored text"],
    record_type="memory",
    index_texts=["Search this text"],
    record_ids="mem-db-index-text-docs",
)
['mem-db-index-text-docs']
store.add(
    ["Short-lived event"],
    record_type="memory",
    record_ids="mem-db-ttl-docs",
    timestamps="2026-01-01T12:00:00+00:00",
    ttl_days=7,
    ttl_anchor=TimeToLiveAnchor.TIMESTAMP,
)
['mem-db-ttl-docs']

メソッド add_agent

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

ノート:

エージェント・プロファイル・レコードのスコープは設定されていません。挿入されたパブリック・レコード識別子は、agent_idとして渡される値と同じです。

例

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

method add_async (非同期)

行指向レコードをストアに非同期的に追加します。

同じ引数を受け入れ、add()と同じ識別子を返します。

メソッド add_batches

コール元準備の論理バッチをストアに追加します。

例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (非同期)

コール元準備の論理バッチをストアに非同期で追加します。

同じ引数を受け入れ、add_batches()と同じ識別子を返します。

メソッド add_user

ユーザープロファイルレコードを追加します。

ノート:

ユーザー・プロファイル・レコードのスコープは設定されていません。挿入されたパブリック・レコード識別子は、user_idとして渡される値と同じです。

例

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

メソッド delete

1つの管理対象行とそのチャンク行を識別子で削除します。

ノート:

この操作は、1つのトランザクション内で実行されます。サポートされている最上位ターゲットに対してcascadeが有効な場合、プロファイル削除およびスコープ指定子の削除はすべてコミットまたはロールバックされます。

例

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

メソッド delete_thread

スレッドとそれに関連付けられた格納された行を削除します。

ノート:

この操作は、スレッド・スコープのカスケード・クリーン・アップが必要な場合に使用します。DBバック・ストアでは、スレッドを削除すると、管理対象スレッドの行と、関連するメッセージ行およびメモリー行、および取得用に保持されている検索データが削除されます。これは、RAWメッセージ行のみを削除するメッセージ・レベルの削除よりも広範囲です。スレッド削除では、依存メッセージ行とメモリー行が、同じトランザクション内の関連する取得データとともに削除されます。

例

store.delete_thread("c1")
0

メソッド get

識別子によって格納されたレコードを取得します。

例

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

メソッド list

レコードタイプの永続レコードを列挙します。

ノート:

"user_profile"および"agent_profile"は、スコープ指定されていないレコード・タイプです。これらのレコード・タイプの場合、thread_id、user_idおよびagent_idは無視され、アクター・アイデンティティはrecord.idに残ります。

例

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

メソッド list_thread_messages

スレッドの永続メッセージを返します。

例

store.list_thread_messages("c1")
[]

類似性でレコードを検索します。

アクティブな検索バックエンドは、ストアの構成済SearchStrategyによって異なります。SearchStrategy.VECTORは、格納されたレコード・ベクトルに対して問合せベクトルをランク付けします。SearchStrategy.HYBRIDは、格納された検索テキストおよびその管理対象索引の状態に対して、Oracleの管理対象ハイブリッド索引を問い合せます。SearchStrategy.KEYWORDは、格納された検索テキストに一致するテキストでのみランク付けします。

例

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

スカラー・メタデータ値をフィルタします。

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

ネストされたメタデータに対するフィルタ:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

次の順序を含むリスト値を完全に一致させます。

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

メタデータ配列に値が含まれている場合にフィルタします。

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

複数のメタデータ条件を結合します。レコードはすべてのキーを満たす必要があります。

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method search_async (非同期)

セマンティックの類似性によってレコードを非同期で検索します。

メソッド update

格納されたレコード・コンテンツ、検索状態、メタデータおよびタイムスタンプ値を更新します。

例

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

検索戦略

クラス oracleagentmemory.core.dbsearch.SearchStrategy

ベース: Enum

Oracle DBストアの検索動作。

DBストアの初期化では、選択した戦略を使用して、管理対象スキーマ検索機能を選択します。VECTOR検索では、ローカル埋込みが格納されます。KEYWORD検索では、検索可能なテキストとテキスト索引が格納されます。HYBRID検索では、検索可能なテキストとOracle管理のハイブリッド・ベクトル索引の状態が格納されます。DBストアは起動時にこのスキーマ機能を検証するため、互換性のない戦略では不完全な結果が暗黙のうちに返されません。

VECTOR
ベクトル類似性のみで検索します。ストアは、構成された埋込み子で問合せを埋め込むか、コール元提供のquery_vectorを使用して、格納されたベクトルからの距離でレコードをランク付けします。ベクトル検索用に構成されたDBスキーマで使用します。
HYBRID
Oracleのマネージド・ハイブリッド索引を検索します。Oracleは、格納された検索テキストに対するテキスト一致と、データベース内ハイブリッド索引からのベクトル・ランキングを組み合せます。これは、ユーザーが自然言語や正確な識別子、別名、製品名で検索できる場合に使用します。この方法では、管理対象索引およびストアが1つのデータベース内モデルを共有するように、ストアのメイン・埋込みをOracleDBEmbedderにする必要があります。
KEYWORD
格納された検索テキストに一致するキーワード/テキストでのみ検索します。このモードでは、ローカル問合せ埋込みは作成されず、Oracle DB埋込みは必要ありません。既存のハイブリッド・スキーマに対してオープンすると、新しいハイブリッド索引を作成せずにそのハイブリッド索引のテキスト・ブランチを使用できます。これは、ベクトル・フュージョンなしで正確な識別子、別名、製品名または短いフレーズで取得を実行する必要がある場合に使用します。

HYBRID = 'HYBRID'

KEYWORD = 'KEYWORD'

VECTOR = 'VECTOR'

検索インデックス同期モード

クラス oracleagentmemory.core.dbsearch.SearchIndexSyncMode

ベース: Enum

管理対象DB検索索引のリフレッシュ動作。

この設定は、Oracleが新規または変更した検索テキストをDBバック・テキスト対応検索で表示するタイミングを制御します。SearchStrategy.HYBRIDは、Oracleの管理対象ハイブリッド・ベクトル索引を使用します。SearchStrategy.KEYWORDは、Oracle Text索引を使用します。SearchStrategy.VECTORでは、この設定は使用されません。

ON_COMMIT
書込みトランザクションのコミット時に索引をリフレッシュします。レコードは書込みの成功直後に検索可能であるため、これはほとんどのアプリケーションでデフォルトであり、最も簡単な選択です。索引がすぐに最新の状態に保たれるため、トランザクションを記述する作業を追加できます。
MANUAL
索引は自動的にリフレッシュしないでください。新規または更新されたレコードは、データベース側の索引同期操作を自分で実行するまで、キーワード検索またはハイブリッド検索に表示されない場合があります。これは、作業のリフレッシュの実行時に制御するバルク・ロードまたはメンテナンス・ウィンドウに便利です。
AUTO
Oracleが管理対象ハイブリッド索引を非同期的にリフレッシュできるようにします。書込みは即時リフレッシュ・コストを回避できますが、Oracleがバックグラウンド・リフレッシュを完了するまで、検索結果は最近の書込みより遅れる可能性があります。このモードは、SearchStrategy.HYBRIDでのみサポートされています。

警告:この設定は、管理対象検索索引が存在した後の継続的なメンテナンスを制御します。最初の索引ビルドを非同期にすることはありません。既存のストアド・サーチ・テキストに対するマネージド・ハイブリッド索引の作成は、Oracleがそのテキストからマネージド・ハイブリッド索引の状態を構築するため、長時間実行される可能性があります。

AUTO = 'AUTO'

手動 = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

存続時間

クラス oracleagentmemory.core.retention.MemoryRetentionConfig

ベース: object

Oracle DBバックアップ・レコードのスキーマ・レベルの保存設定。

クラス oracleagentmemory.apis.ttl.TimeToLiveAnchor

ベース: Enum

存続時間からの失効タイムスタンプの計算に使用されるアンカー。

CREATED_AT
レコードのデータベース作成タイムスタンプからの有効期限を計算します。これは、呼出し側がttl_anchorを省略した場合のデフォルトです。
TIMESTAMP
レコードの格納済イベント・タイムスタンプからの有効期限を計算します。これは、メッセージまたはメモリーが古いイベントを表し、挿入時間ではなくそのイベント時間に対して相対的に期限切れになる場合に使用します。

CREATED_AT = 'CREATED_AT'

タイムスタンプ = 'TIMESTAMP'

スキーマ・ポリシー

クラス oracleagentmemory.core.SchemaPolicy

ベース: str、Enum

Oracle DBストアのスキーマ作成ポリシー。

存在が必要

フルマネージド・スキーマがすでに存在し、最新であることを確認します。DBオブジェクトを作成または変更しないでください。

空の作成

管理対象オブジェクトが存在しない場合は、スキーマをブートストラップします。オブジェクトがすでに存在する場合は、完全で最新の管理対象スキーマが必要です。

必要であれば作成

欠落している管理対象オブジェクトを作成し、サポートされている管理対象スキーマのアップグレードを適用します。

再作成する

すべての管理対象スキーマ・オブジェクトを削除して再作成します。これは破壊的です。