ストアおよびスキーマ

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

ストアAPI

クラス oracleagentmemory.core.OracleMemoryStore

ベース: IMemoryStore

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

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

method add (抽象)

テキスト・レコードの埋込みと永続化。

• パラメータ:
  • contents list[str | None]– 格納するテキスト・ペイロード。これらの値は、index_textsが指定されていない場合の埋込みペイロードとしても使用されます。項目を省略(None)すると、使用可能な場合にメタデータ・キー"content"から解決を格納し、それ以外の場合は空のコンテンツが保持されます。
  • record_type str– 格納されたレコードのレコードタイプラベル("message"や "memory"など)。
  • index_texts list[str]– contentsに合せたオプションの埋込み専用ペイロード。
  • 埋込み list[list[float]] | list[ndarray]– contentsに合せたオプションの事前計算済埋込みベクトル。指定した場合、ストアはこれらのベクトルを直接使用し、埋込みをコールしません。
  • record_ids str | None | list[str] | list[None]– オプションの呼び出し元で表示されるレコードID。完全に指定するか(テキストごとに1つ)、すべてのテキストに対して省略する必要があります。返されたIDは、指定された場合、これらの値と一致します。
  • thread_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • user_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • agent_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • roles str | None | list[str | None]– メッセージ・レコードのチャット・ロール(オプション)。
  • timestamps str | None | list[str | None]– オプションのタイムスタンプまたはレコードごとのタイムスタンプ。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None– オプションのメタデータマッピングまたはレコードごとのメタデータマッピング。メタデータには、省略されたテキスト値のフォールバック・ソースとして"content"を含めることができます。
  • **store_kwargs (Any)– 上位レベルのAPIによって転送される、ストア固有の書き込みオプション。
• 戻り値:入力コンテンツ・アイテムごとに識別子を挿入します。これらは、指定された場合はrecord_idsに一致し、それ以外の場合は生成識別子を格納します。
• 戻り型: list[str]

例

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

method search (抽象)

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

• パラメータ:
  • query str | None– 自然言語問合せ。query_vectorを省略する場合は、指定する必要があります。
  • query_vector list[float] | None– オプションの事前計算済問合せ埋込み。queryおよびquery_vectorのいずれかを指定する必要があります。
  • k int– 戻す結果の最大数。明示的な値は、1以上である必要があります。
  • thread_id str | None– オプションのスレッドスコープ。
  • user_id str | None– オプションのユーザーおよびエージェントのスコープフィルタ。
  • agent_id str | None– オプションのユーザーおよびエージェントのスコープフィルタ。
  • exact_user_match bool– 指定された各スコープ識別子を正確に一致させる必要があるかどうか。
  • exact_agent_match bool– 指定された各スコープ識別子を正確に一致させる必要があるかどうか。
  • exact_thread_match bool– 指定された各スコープ識別子を正確に一致させる必要があるかどうか。
  • record_types set[str] | None– 含めるレコード・タイプのオプション・セット。
  • metadata_filter dict[str, Any] | None– オプションの部分メタデータマッピング。レコードが一致するのは、格納されているメタデータにリクエストされたすべてのキーと値が含まれている場合のみです。ネストされたディクショナリは再帰的に照合されます。リスト値は、再帰的なサブセットの一致ではなく、正確な等価性によって照合されるため、リストの順序と長さも一致する必要があります。
• 戻り値:距離の増加でソートされた(record, distance)ペア。
• 戻り型: list[tuple[Record、 float]]
• Raises: ValueError– kが1未満の場合。

例

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

Oracle DBストア

クラス oracleagentmemory.core.OracleDBMemoryStore

ベース: OracleMemoryStore

メッセージおよび型付きメモリー・レコードに対するデータベース・バックアップの永続性。

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

• パラメータ:
  • embedder IEmbedder | None– ベクトル化されたレコード・タイプに使用される埋込み。呼出し側が常にadd、updateおよびsearchに事前計算されたベクトルを提供する場合、Noneになります。
  • pool Any– Oracle DB接続またはプール。RAW接続を渡すと、このストア・インスタンスに対してシングル・セッション・モードが有効になります。コンカレント・ストア・コールは、書込み操作で使用される行ロックおよびトランザクションの仮定を保持するためにローカルにシリアライズされます。コンカレント要求には接続プールを使用します。
  • schema_policy SchemaPolicy | str– スキーマ設定モード。デフォルトでは、既存の最新の管理対象スキーマが必要であり、DDLの変更は実行されません。欠落しているオブジェクトを埋めるにはSchemaPolicy.CREATE_IF_NECESSARYを使用し、管理対象オブジェクトを削除して再作成するにはSchemaPolicy.RECREATEを使用します。
  • vector_dim int–VECTOR列の作成時にスキーマを作成するためのディメンションを埋め込みます。
  • table_name_prefix str– 管理対象テーブル/インデックス名に追加されるオプションの接頭辞。

メソッド add

メモリー・ストアにレコードを追加します。

• パラメータ:
  • contents list[str | None]– 格納するテキスト・ペイロード。これらの値は、index_textsまたはembeddingsが指定されていないかぎり、埋込みの計算にも使用されます。項目を省略(None)すると、使用可能な場合にメタデータ・キー"content"から解決を格納し、それ以外の場合は空のコンテンツが保持されます。
  • record_type str– 格納されたレコードのレコードタイプラベル(たとえば、"message"、"memory"、guideline、fact、または preference)。
  • index_texts list[str]– 埋込み/索引付けにのみ使用されるオプションの代替ペイロード。指定する場合は、contentsと同じ長さにする必要があります。
  • 埋込み list[list[float]] | list[ndarray]– contentsに合せたオプションの事前計算済埋込みベクトル。指定した場合、ストアはこれらのベクトルを直接使用する必要があり、埋込みを起動できません。省略すると、ストアは空でない索引付けペイロードに対してのみ埋込みを使用します。明示的な空の文字列はチャンク埋込みなしで格納されます。
  • record_ids str | None | list[str] | list[None]– オプションの呼び出し元で表示されるレコードID。完全に指定するか(テキストごとに1つ)、すべてのテキストに対して省略する必要があります。返されたIDは、指定された場合、これらの値と一致します。省略すると、ストアはクライアント側のIDを生成します。
  • thread_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • user_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • agent_ids str | None | list[str | None]– レコードとともに格納されるオプションのスコープ識別子。
  • roles str | None | list[str | None]– メッセージ・レコードのチャット・ロール(オプション)。
  • timestamps str | None | list[str | None]– オプションのコール元提供のイベントタイムスタンプ。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None– オプションのコール元提供のメタデータ・ディクショナリ。メタデータには、省略されたテキスト値のフォールバック・ソースとして"content"を含めることができます。
  • **store_kwargs (Any)– ストア固有の書き込みオプション。現在サポートされているキーには、Oracle executemanyバッチ処理用のbatch_sizeが含まれています。
• 戻り値:入力コンテンツ・アイテムごとに識別子を挿入します。これらは、指定された場合はrecord_idsと一致し、それ以外の場合は、生成された戻りIDが格納されます。
• 戻り型: list[str]

例

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

メソッド add_agent

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

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

例

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

メソッド add_user

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

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

例

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

メソッド delete

管理対象ベクトルレコード行とそのチャンク行を識別子で削除します。

• パラメータ:
  • record_type str– "message"、"memory"、"guideline"、"fact"、"preference"など、管理対象表のターゲット指定が必要なレコードタイプラベル
  • record_id str - 削除する行の識別子。
• 戻り値:削除された行数(識別子が見つからなかった場合は0)。
• 戻り型: int

例

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

メソッド delete_thread

スレッドおよびそれに関連付けられたベクトル・レコードおよびチャンク行を削除します。

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

例

store.delete_thread("c1")
0

メソッド get

格納されたメッセージまたはメモリーを識別子で取得します。

• パラメータ:
  • record_type str– "message"、"memory"、"guideline"、"fact"、"preference"などの管理対象ベクトルレコード行に解決されるレコードタイプラベル。
  • record_id str– 検索する識別子。
• 戻り値:検出時にデコードされたメタデータを含むレコードが移入されます。それ以外の場合はNoneです。
• 戻りタイプ: レコード |なし

例

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

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

• パラメータ:
  • record_type str– レコード型のラベル(例: "message"、"memory"、"guideline"、"fact"、または "preference")。
  • limit int– 戻すレコードの最大数。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、スレッド・ディメンションでスコープ指定されていないレコードのみが返されます。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、ユーザー・ディメンションでスコープ指定されていないレコードのみが返されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、エージェント・ディメンションでスコープ指定されていないレコードのみが返されます。
  • metadata_filter dict[str, Any] | None– メタデータフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータが格納されていないレコードのみが返されます。dictに設定した場合、格納されるメタデータには、要求されたすべての鍵と値が含まれている必要があります。ネストされたディクショナリは再帰的に照合されます。リスト値は、再帰的なサブセットの一致ではなく、正確な等価性によって照合されるため、リストの順序と長さも一致する必要があります。
• 戻り値:挿入順序で並べられたレコード。
• 戻りタイプ: list[レコード]

例

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']

メソッド list_thread_messages

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

• パラメータ:
  • thread_id str– メッセージを返すスレッド識別子。
  • last_n int | None– 返される最新のメッセージの数(オプション)。
• 戻り値:挿入順序で並べられたメッセージ・レコード。
• 戻り型: list[MessageRecord]

例

store.list_thread_messages("c1")
[]

メソッド search

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

• パラメータ:
  • query str | None– 自然言語問合せ。query_vectorを省略する場合は、指定する必要があります。
  • query_vector list[float] | None– オプションの事前計算済問合せ埋込み。queryおよびquery_vectorのいずれかを指定する必要があります。
  • k int– 返す結果の最大数。明示的な値は、1以上である必要があります。
  • thread_id str | None– オプションのスレッドスコープ識別子。exact_thread_match=Falseは、スレッドディメンションを制約なしのままにします。exact_thread_match=Trueは、指定された thread_idと完全に一致します。thread_id=Noneの場合、スレッド・ディメンションでスコープ指定されていないレコードのみが一致します。
  • user_id str | None– オプションのユーザーおよびエージェントのスコープ識別子。対応するexact_*_match=Falseフラグは、そのディメンションを制約なしのままにします。exact_*_match=Trueは、指定されたIDと正確に一致します。IDがNoneの場合、そのディメンションでスコープ指定されていないレコードのみが一致します。
  • agent_id str | None– オプションのユーザーおよびエージェントのスコープ識別子。対応するexact_*_match=Falseフラグは、そのディメンションを制約なしのままにします。exact_*_match=Trueは、指定されたIDと正確に一致します。IDがNoneの場合、そのディメンションでスコープ指定されていないレコードのみが一致します。
  • exact_user_match bool– 各スコープ識別子を正確に一致させる必要があるかどうか。Falseは、そのディメンションを制約なしのままにします。Trueは、指定された値と正確に一致します。その値がNoneの場合、そのディメンションのスコープなしレコードのみに一致します。
  • exact_agent_match bool– 各スコープ識別子を正確に一致させる必要があるかどうか。Falseは、そのディメンションを制約なしのままにします。Trueは、指定された値と正確に一致します。その値がNoneの場合、そのディメンションのスコープなしレコードのみに一致します。
  • exact_thread_match bool– 各スコープ識別子を正確に一致させる必要があるかどうか。Falseは、そのディメンションを制約なしのままにします。Trueは、指定された値と正確に一致します。その値がNoneの場合、そのディメンションのスコープなしレコードのみに一致します。
  • record_types set[str] | None– 含めるレコード・タイプのオプション・セット。省略すると、検索対象は任意のレコードタイプになります。
  • metadata_filter dict[str, Any] | None– オプションの部分メタデータマッピング。レコードが一致するのは、格納されているメタデータにリクエストされたすべてのキーと値が含まれている場合のみです。ネストされたディクショナリは再帰的に照合されます。リスト値は、再帰的なサブセットの一致ではなく、正確な等価性によって照合されるため、リストの順序と長さも一致する必要があります。
• 戻り値:距離の増加でソートされた(record, distance)ペア。
• 戻り型: list[tuple[Record、 float]]
• Raises: ValueError– kが1未満の場合。

例

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

メソッド update

格納されたレコード・コンテンツ、チャンク埋込みおよびメタデータ値を更新します。

• パラメータ:
  • record_type str– 変更される行のレコードタイプラベル("message"、"memory"、guideline、fact、または preferenceなど)
  • record_id str– 更新するメッセージまたはメモリー行の識別子。
  • text str | None– content列に保持されるオプションの置換テキスト。Noneを渡して、格納されているテキストをクリアし、格納されている埋込みをクリアします。Noneのみを渡すか、同じコールで省略されたセマンティック引数を渡します。""を渡すと、明示的な空のコンテンツが保持され、そのレコードのチャンク埋込みがクリアされます。省略すると、既存のコンテンツは変更されません。
  • index_text str | None– オプションの埋込み専用ペイロード。省略すると、textが埋め込まれます。
  • 埋込み list[float] | ndarray | None– オプションの事前計算済埋込みベクトル。指定した場合、これは直接使用され、埋込みコールは行われません。Noneを渡して、格納された埋込みをクリアします。
  • metadata dict[str, Any] | None– オプションのメタデータ・マッピングは、JSONにシリアライズされ、metadataに格納されます。
• 戻り値:更新された行の数(0または1)。record_typeおよびrecord_idに一致する論理レコードがない場合、0を返します。
• 戻り型: int
• Raises: ValueError– record_typeがサポートされていない場合、更新ペイロードが指定されていない場合、またはセマンティク更新引数に互換性がない場合。

例

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.SchemaPolicy

ベース: str、Enum

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

存在が必要

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

空の作成

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

必要であれば作成

欠落している管理対象オブジェクト(メタデータを含む)のみを作成します。

再作成する

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