ストアおよびスキーマ

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

ストアAPI

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

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

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

• add()のcontentsおよびupdate()のcontentは、get()、list()および検索結果によって返される格納済レコード・コンテンツを制御します。
• add()のindex_textsおよびupdate()のindex_textは、ストアの取得行に書き込まれるテキストを制御します。検索ではこれらの行が使用され、元の論理レコードが返されます。

update()は、非推奨の互換性パラメータとしてtextも受け入れます。新しいコードでcontentを使用します。textを指定すると、非推奨警告が発行されます。

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

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

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

入力	add()	update()
index_textsまたはindex_textを省略	各レコードは、その解決されたcontents値を取得に使用します。	置換content値が取得に使用されます。contentも省略した場合、埋込みのみの更新では、レコードの既存の取得テキスト行が再利用されます。
文字列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は、contentも指定されていないかぎり、格納されたコンテンツを変更せずに取得行をクリアします。
空の文字列または空のチャンク・リスト	レコード・コンテンツが格納され、そのレコードの取得テキストは提供されません。	contentが指定されるとレコード・コンテンツが更新され、そのレコードの取得テキストがクリアされます。

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

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

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

• 1つのベクトルは、取得テキスト全体に対して1つのベクトルを意味します。ストアは、明示的なベクトルのテキストを分割しません。その検索テキストが空の場合、ベクトルはコンパニオン・チャンク・テキストなしで格納できます。
• 複数のベクトルは、呼び出し元が所有するチャンクごとに1つのベクトルを意味します。一致するindex_textsまたはindex_textチャンク・リストを指定するか、レコードの既存の取得テキスト行を再利用する埋込み専用のupdate()を使用します。
• ベクトル数はチャンク数と一致する必要があり、1つのadd()コールのすべての明示的なベクトルは同じディメンションである必要があります。
• 空のレコードごとのベクトル・ペイロードは、それと一致する取得テキスト行がない場合にのみ許可されます。

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

クラス oracleagentmemory.core.OracleMemoryStore

ベース: IMemoryStore

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

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

メソッド add

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

• パラメータ:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]– レコード・ペイロードの読取り専用シーケンス。メッセージ・エントリには順序付けられたMessageContent部分が含まれる場合がありますが、スレッド・サマリー・エントリはマッピングである場合があります。テキスト値は、index_textsまたはembeddingsが指定されていないかぎり、セマンティク索引付けにも使用されます。テキスト値がNoneの場合、実装はmetadata["content"]にフォールバックする可能性があります。明示的な空の文字列は保持されます。
  • record_type str– 作成する論理レコード・タイプ(たとえば、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"または"thread_summary")。
  • index_texts list[str | list[str] | None]– セマンティック索引付けにのみ使用されるオプションの代替ペイロード。指定した場合、外部リストはテキスト入力と一致する必要があります。各エントリは、ストアが内部的にチャンク化できる文字列、またはストアがコール元所有のチャンクとして処理し、再度分割できない空でない文字列のリストです。
  • 埋込み list[list[float] | ndarray | list[list[float] | ndarray]]– テキスト入力に合せたオプションの事前計算埋込みベクトル。各レコード・エントリは、1つの埋込みベクトルまたはそのレコードのチャンク埋込みベクトルのリストのいずれかです。指定した場合、ストアは埋込み機能を呼び出すのではなく、これらのベクトルを直接使用する必要があります。1つのレコードの複数のベクトルでは、テキストおよびベクトル・チャンクの境界が明示されるように、一致するindex_textsチャンク・リストが必要です。指定しない場合、ストアは通常、構成された埋込みからセマンティク状態を導出しますが、実装固有のテキスト対応索引付けモードでは、テキストのみの書込みを1つなしで許可することもできます。
  • record_ids str | None | list[str | None]– オプションの呼び出し元表示識別子。1つの文字列を1レコード挿入に使用できますが、リストはテキスト入力と一致している必要があります。このフィールドを省略すると、生成された識別子が返されます。
  • 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]– オプションのメッセージ・ロール("user"や"assistant"など)。スカラー値は、整列されたテキスト入力間でブロードキャストできます。record_typeが"message"の場合にのみ使用されます。
  • timestamps str | None | list[str | None]– レコードとともに保存するオプションのタイムスタンプ。各タイムスタンプは、レコードに関連付けられたイベントを表します。スカラー値は、整列されたテキスト入力間でブロードキャストできます。省略されたエントリまたはNoneエントリは、NULLイベント・タイムスタンプを格納します。読取りでは、レコード作成時間を有効タイムスタンプとして使用します。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションのコール元提供のメタデータ・ディクショナリ。明示的に""に設定するのではなく、テキスト値を省略した場合、メタデータにはフォールバック・ソースとして"content"を含めることができます。record_type="image"の場合、各イメージ書込みには、"image/png"、"image/jpeg"または"image/webp"のいずれかを含む"image_mime_type"が必要です。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • ttl_days int | None | list[int | None]– 有効期限をサポートするレコードのオプションの存続期間(日数)。store defaultを使用するには、この引数を省略します。期限切れにならないレコードに対してNoneを渡します。スカラー値は、整列されたテキスト入力間でブロードキャストできます。
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]– オプションの稼働時間アンカー。TimeToLiveAnchor.CREATED_ATを使用して、格納された作成時間を基準にして期限切れにするか、TimeToLiveAnchor.TIMESTAMPを使用して各レコードのイベント・タイムスタンプを基準にして期限切れにします。省略すると、実装はTimeToLiveAnchor.CREATED_ATを使用します。
  • statuses RecordStatus | list[RecordStatus]– オプションのライフサイクルステータスまたはレコードのステータス。RecordStatus.VALIDを格納する場合は、これを省略します。
  • **store_kwargs (Any)– 具象ストアに転送される実装固有の書き込みオプション。
• 戻り型: list[str]

ノート

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

• 戻り値:入力と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: List[str]
• パラメータ:
  • コンテンツ Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • 埋込み list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • ロール str | None | list[str | None]
  • タイムスタンプ str | None | list[str | None]
  • メタデータ dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • ステータス RecordStatus | list[RecordStatus]
  • store_kwargs Any

method add_agent (抽象)

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

• パラメータ:
  • agent_id str– エージェントプロファイルの安定した識別子。
  • information str– エージェントを説明する自由形式のテキスト。
  • metadata dict[str, Any] | None– エージェント・プロファイル行に格納されているオプションのメタデータ・マッピング。
• 戻り値:作成されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

method add_agent_async (非同期)

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

• パラメータ:
  • agent_id str– エージェントプロファイルの安定した識別子。
  • information str– エージェントを説明する自由形式のテキスト。
  • metadata dict[str, Any] | None– エージェント・プロファイル行に格納されているオプションのメタデータ・マッピング。
• 戻り値:作成されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

method add_async (非同期)

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

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

• パラメータ:
  • コンテンツ Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • 埋込み list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • ロール str | None | list[str | None]
  • タイムスタンプ str | None | list[str | None]
  • メタデータ dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • ステータス RecordStatus | list[RecordStatus]
  • store_kwargs Any
• 戻り型: list[str]

メソッド add_batches

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

• パラメータ:
  • batches list[PendingRecordBatch]– 永続化する完全に準備された論理バッチ。各バッチには、record_type、スコープ値、ロール、タイムスタンプ、メタデータなどのレコードごとに独自のフィールドが必要です。
  • **store_kwargs (Any)– 具象ストアに転送される実装固有の書き込みオプション。
• 戻り値:入力バッチおよび行と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: List[str]

例

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

method add_batches_async (非同期)

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

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

• パラメータ:
  • バッチ list[PendingRecordBatch]
  • store_kwargs Any
• 戻り型: list[str]

method add_relations (抽象)

1つ以上の指示された関係を格納します。

スカラー値は、ソース・レコード・バッチ全体でブロードキャストされます。リスト値は同じ長さである必要があります。1つのエンドポイント・ペアに対して格納できる方向は1つのみです。opposite_relation_typesを使用して、2番目の逆リレーションを追加するのではなく、逆ビューを記述します。実装では、保持するエンドポイント・レコード・タイプおよびリレーション・ラベルを制限できます。

• パラメータ:
  • source_record_ids str | list[str]– 各指示付きリレーションのソース端にあるレコードの識別子または識別子。
  • source_record_types str | list[str]– source_record_idsのレコード・タイプまたはタイプ。すべてのソースに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • target_record_ids str | list[str]– 各指示付きリレーションのターゲット端にあるレコードの識別子または識別子。
  • target_record_types str | list[str]– target_record_idsのレコードタイプまたはタイプ。すべてのターゲットに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • relation_types str | list[str]– 指示付きリレーション・ラベル。すべてのリレーションに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • opposite_relation_types str | list[str]– 各リレーションの逆ビューに対するオプションのラベルまたはラベル。組み込みのメモリーリレーションタイプの場合、省略は事前定義された逆ラベルを使用します。カスタムリレーションタイプの場合、省略は両方向に同じラベルを使用します。
  • relation_ids str | None | list[str | None]– オプションの安定した識別子または識別子。ストアで識別子を生成するには、これを省略します。
  • timestamps str | None | list[str | None]– リレーションに格納するオプションのタイムスタンプまたはタイムスタンプ。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– リレーションに格納するオプションのメタデータ・オブジェクト。
• 戻り値:入力順のリレーション識別子。
• 戻り型: list[str]

例

store.add_relations(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method add_relations_async (非同期)

非同期に1つ以上の指示付きリレーションを格納します。

スカラー値は、ソース・レコード・バッチ全体でブロードキャストされます。リスト値は同じ長さである必要があります。1つのエンドポイント・ペアに対して格納できる方向は1つのみです。opposite_relation_typesを使用して、2番目の逆リレーションを追加するのではなく、逆ビューを記述します。

• パラメータ:
  • source_record_ids str | list[str]– 各指示付きリレーションのソース端にあるレコードの識別子または識別子。
  • source_record_types str | list[str]– source_record_idsのレコード・タイプまたはタイプ。すべてのソースに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • target_record_ids str | list[str]– 各指示付きリレーションのターゲット端にあるレコードの識別子または識別子。
  • target_record_types str | list[str]– target_record_idsのレコードタイプまたはタイプ。すべてのターゲットに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • relation_types str | list[str]– 指示付きリレーション・ラベル。すべてのリレーションに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • opposite_relation_types str | list[str]– 各リレーションの逆ビューに対するオプションのラベルまたはラベル。組み込みのメモリーリレーションタイプの場合、省略は事前定義された逆ラベルを使用します。カスタムリレーションタイプの場合、省略は両方向に同じラベルを使用します。
  • relation_ids str | None | list[str | None]– オプションの安定した識別子または識別子。ストアで識別子を生成するには、これを省略します。
  • timestamps str | None | list[str | None]– リレーションに格納するオプションのタイムスタンプまたはタイムスタンプ。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– リレーションに格納するオプションのメタデータ・オブジェクト。
• 戻り値:入力順のリレーション識別子。
• 戻り型: list[str]

例

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method add_user (抽象)

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

• パラメータ:
  • user_id str– ユーザープロファイルの安定した識別子。DBバック実装では、この値を省略すると、アタッチされたエンド・ユーザー・セキュリティ・コンテキストからこの値が推測される場合があります。
  • information str– ユーザーを記述するために必要な自由形式テキスト。
  • metadata dict[str, Any] | None– ユーザープロファイル行に格納されているオプションのメタデータマッピング。
• 戻り値:作成されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

method add_user_async (非同期)

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

• パラメータ:
  • user_id str– ユーザープロファイルの安定した識別子。
  • information str– ユーザーを説明する自由形式のテキスト。
  • metadata dict[str, Any] | None– ユーザープロファイル行に格納されているオプションのメタデータマッピング。
• 戻り値:作成されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

method delete (抽象)

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

• パラメータ:
  • record_type str– 削除するレコードの論理型。
  • record_id str– 削除するレコードの識別子。
  • カスケード bool– Trueの場合、同じ削除操作内でリクエストされたトップレベル・ターゲットに対して、ストアでサポートされているカスケード削除動作を適用します。これは主に、追加のスコープ付きレコードを所有するアクター・プロファイルなどのターゲットに使用されます。たとえば、ユーザー・プロファイル・カスケードまたはエージェント・プロファイル・カスケードでは、所有されているスレッド自体、スレッド・スコープのメッセージおよびそれらのスレッドで削除されたメモリーのようなレコード、およびメッセージ、メモリー、ガイドライン、ファクト、プリファレンスなどのアクター・スコープの残りの直接レコードを削除できます。アクタープロファイル削除の場合、一致するプロファイル行がすでに存在していなくても、このスコープ指定クリーンアップが実行される場合があります。
• 戻り値:削除されたリクエストされたトップレベル・レコードの数(通常は0または1)。カスケードされた子行は個別にカウントされないため、欠落しているアクター・プロファイルによってスコープ指定クリーン・アップがトリガーされた場合でも、これは0になることがあります。
• 戻り型: int

method delete_async (非同期)

1つのストアド・レコードを識別子で非同期に削除します。

• パラメータ:
  • record_type str– 削除するレコードの論理型。
  • record_id str– 削除するレコードの識別子。
  • カスケード bool– Trueの場合、同じ削除操作内でリクエストされたトップレベル・ターゲットに対して、ストアでサポートされているカスケード削除動作を適用します。これは主に、追加のスコープ付きレコードを所有するアクター・プロファイルなどのターゲットに使用されます。たとえば、ユーザー・プロファイル・カスケードまたはエージェント・プロファイル・カスケードでは、所有されているスレッド自体、スレッド・スコープのメッセージおよびそれらのスレッドで削除されたメモリーのようなレコード、およびメッセージ、メモリー、ガイドライン、ファクト、プリファレンスなどのアクター・スコープの残りの直接レコードを削除できます。アクタープロファイル削除の場合、一致するプロファイル行がすでに存在していなくても、このスコープ指定クリーンアップが実行される場合があります。
• 戻り値:削除されたリクエストされたトップレベル・レコードの数(通常は0または1)。カスケードされた子行は個別にカウントされないため、欠落しているアクター・プロファイルによってスコープ指定クリーン・アップがトリガーされた場合でも、これは0になることがあります。
• 戻り型: int

method delete_relations (抽象)

識別子による関係の削除

ライフサイクル状態は、残っているリレーションから再計算されます。

• パラメータ: relation_ids str | list[str]– 削除する関係の識別子または識別子。
• 戻り値:削除されたリレーションの数。
• 戻り型: int

例

store.delete_relations("relation-id")
1

method delete_relations_async (非同期)

識別子で関係を非同期に削除します。

ライフサイクル状態は、残っているリレーションから再計算されます。

• パラメータ: relation_ids str | list[str]– 削除する関係の識別子または識別子。
• 戻り値:削除されたリレーションの数。
• 戻り型: int

例

await store.delete_relations_async("relation-id")
1

method delete_thread (抽象)

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

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

ノート

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

method delete_thread_async (非同期)

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

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

ノート

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

method get (抽象)

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

• パラメータ:
  • record_type str– 取得するレコードの論理型("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"image"など)。
  • record_id str– 取得するレコードの識別子。
  • include_bytes bool– 格納されたイメージバイトをロードするかどうか。メッセージ・レコードの場合、添付されたイメージにバイトを含めるかどうかを制御します。イメージ・レコードの場合、スタンドアロン・イメージのバイトをロードするかどうかを制御します。このオプションは、他のレコードタイプには影響しません。
• 戻り値:格納されたレコードが見つかった場合、それ以外の場合はNone。"thread"参照は、スレッド・メタデータ、ランタイム構成、ランタイム状態およびストアで永続スレッドがサポートされるときに移入された作成タイムスタンプを含むThreadRecordを返します。
• 戻りタイプ: レコード |なし

method get_async (非同期)

タイプおよび識別子によって、格納されている1つのレコードを非同期的に取得します。

• パラメータ:
  • record_type str– 取得するレコードの論理型("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"image"など)。
  • record_id str– 取得するレコードの識別子。
  • include_bytes bool– 格納されたイメージバイトをロードするかどうか。メッセージ・レコードの場合、添付されたイメージにバイトを含めるかどうかを制御します。イメージ・レコードの場合、スタンドアロン・イメージのバイトをロードするかどうかを制御します。このオプションは、他のレコードタイプには影響しません。
• 戻り値:格納されたレコードが見つかった場合、それ以外の場合はNone。"thread"参照は、スレッド・メタデータ、ランタイム構成、ランタイム状態およびストアで永続スレッドがサポートされるときに移入された作成タイムスタンプを含むThreadRecordを返します。
• 戻りタイプ: レコード |なし

method get_relation (抽象)

格納されているソースからターゲットへの方向で1つのリレーションを返します。

relation_idを単独で指定するか、ソースとターゲットの完全なエンドポイント・タプルを1つ指定します。

• パラメータ:
  • source_record_id str– ソースレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • source_record_type str– ソース・レコード・タイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_id str– ターゲットレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_type str– ターゲットレコードタイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_type str– 指示付きリレーション・ラベル。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_id str– 直接照合するリレーション識別子。この引数をエンドポイント・タプル・フィールドと組み合せるのではなく、単独で指定します。
• 戻り値:一致するリレーション(存在しない場合はNone)。
• 戻り型: RecordRelation |なし

例

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method get_relation_async (非同期)

IDまたはエンドポイント・タプルで1つのリレーションを非同期的に取得します。

relation_idを単独で指定するか、ソースとターゲットの完全なエンドポイント・タプルを1つ指定します。

• パラメータ:
  • source_record_id str– ソースレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • source_record_type str– ソース・レコード・タイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_id str– ターゲットレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_type str– ターゲットレコードタイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_type str– 指示付きリレーション・ラベル。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_id str– 直接照合するリレーション識別子。この引数をエンドポイント・タプル・フィールドと組み合せるのではなく、単独で指定します。
• 戻り値:一致するリレーション(存在しない場合はNone)。
• 戻り型: RecordRelation |なし

例

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

method list (抽象)

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

• パラメータ:
  • record_type str– "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"thread_summary"または"image"など、列挙する論理レコード・タイプ。
  • limit int | None– 返される最新のレコードの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。record_typeが"thread"の場合は、thread_idを設定しないでください。record_idを使用して、特定のスレッドを選択します。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、user_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、agent_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。

  • metadata_filter dict[str, Any] | None–

    メタデータ・フィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのレコードのみが返されます。dictに設定すると、metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "slack"}、ネストしたフィールドの場合はmetadata_filter={"review": {"status": "open"}}、完全リスト一致の場合はmetadata_filter={"tags": ["prod", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool– メッセージレコードに添付されたイメージレコードまたはイメージに、格納されたバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。ダイレクト・イメージ・リストの場合、これをTrueに設定するのは、正確なrecord_idおよび少なくとも1つの正確なユーザー、エージェントまたはスレッド・スコープ・フィルタを使用する場合のみです。このオプションは、他のレコードタイプには影響しません。
  • record_id str– 正確なレコード識別子フィルタ。省略すると、識別子を持つレコードが返されます。スコープおよびメタデータ・フィルタは、追加の制約のままです。
• 戻り値:返されたウィンドウ内で最も古いものから新しいものの順に並べられたレコード。
• 戻りタイプ: List[Record]

method list_async (非同期)

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

• パラメータ:
  • record_type str– 列挙する論理レコード・タイプ("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"image"など)。
  • limit int | None– 返される最新のレコードの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。record_typeが"thread"の場合は、thread_idを設定しないでください。record_idを使用して、特定のスレッドを選択します。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、user_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、agent_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。

  • metadata_filter dict[str, Any] | None–

    メタデータ・フィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのレコードのみが返されます。dictに設定すると、metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "slack"}、ネストしたフィールドの場合はmetadata_filter={"review": {"status": "open"}}、完全リスト一致の場合はmetadata_filter={"tags": ["prod", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool– メッセージレコードに添付されたイメージレコードまたはイメージに、格納されたバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。ダイレクト・イメージ・リストの場合、これをTrueに設定するのは、正確なrecord_idおよび少なくとも1つの正確なユーザー、エージェントまたはスレッド・スコープ・フィルタを使用する場合のみです。このオプションは、他のレコードタイプには影響しません。
  • record_id str– 正確なレコード識別子フィルタ。省略すると、識別子を持つレコードが返されます。スコープおよびメタデータ・フィルタは、追加の制約のままです。
• 戻り値:返されたウィンドウ内で最も古いものから新しいものの順に並べられたレコード。
• 戻りタイプ: List[Record]

method list_relations (抽象)

ストアド・リレーションをソースとターゲットの方向にリストします。

• パラメータ:
  • relation_type str– 照合するオプションの指示付きリレーション・ラベル("supports"や"supersedes"など)。すべてのリレーション・タイプを含める場合は省略します。
  • source_record_id str– 照合するオプションのソースレコード識別子。
  • source_record_type str– 照合するオプションのソースレコードタイプ。
  • target_record_id str– 一致するオプションのターゲットレコード識別子。
  • target_record_type str– 一致させるオプションのターゲットレコードタイプ。
  • limit int | None– 返されるもっとも早く作成されたリレーションの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、一致するすべてのストアド・リレーションを返します。
  • metadata_filter dict[str, Any] | None– メタデータフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのリレーションのみが返されます。dictに設定すると、エントリはANDセマンティクスと結合されます。ネストされたディクショナリでは、再帰的完全一致が使用されます。スカラー値およびリスト値には正確な等価性が必要です。配列メンバーシップを照合するには{"tags": {"$array_contains": "prod"}}を、リストされた値と一致させるには"$array_contains_any"を、別のフィールド式を否定するには"$not"を使用します。
  • relation_id str– 正確なリレーション識別子フィルタ。省略すると、任意の識別子との関係が返されます。その他のフィルタは追加の制約のままです。
• 戻り値:リレーションは、作成時間と識別子でソートされます。
• 戻り型: list[RecordRelation]

例

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method list_relations_async (非同期)

ソースからターゲットへのリレーションを非同期的にリストします。

• パラメータ:
  • relation_type str– 照合するオプションの指示付きリレーション・ラベル("supports"や"supersedes"など)。すべてのリレーション・タイプを含める場合は省略します。
  • source_record_id str– 照合するオプションのソースレコード識別子。
  • source_record_type str– 照合するオプションのソースレコードタイプ。
  • target_record_id str– 一致するオプションのターゲットレコード識別子。
  • target_record_type str– 一致させるオプションのターゲットレコードタイプ。
  • limit int | None– 返されるもっとも早く作成されたリレーションの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、一致するすべてのストアド・リレーションを返します。
  • metadata_filter dict[str, Any] | None– メタデータフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのリレーションのみが返されます。dictに設定すると、エントリはANDセマンティクスと結合されます。ネストされたディクショナリでは、再帰的完全一致が使用されます。スカラー値およびリスト値には正確な等価性が必要です。配列メンバーシップを照合するには{"tags": {"$array_contains": "prod"}}を、リストされた値と一致させるには"$array_contains_any"を、別のフィールド式を否定するには"$not"を使用します。
  • relation_id str– 直接照合するオプションのリレーション識別子。
• 戻り値:リレーションは、作成時間と識別子でソートされます。
• 戻り型: list[RecordRelation]

例

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

method list_thread_messages (抽象)

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

• パラメータ:
  • thread_id str– メッセージが返されるスレッドの識別子。
  • last_n int | None– 含める最新のメッセージの数(オプション)。省略すると、スレッドの格納されているすべてのメッセージが返されます。シーケンス範囲と組み合せると、その範囲内に制限が適用されます。
  • range_start_seq_no int | None– オプションの下限シーケンス境界。seq_noがこの値以上のメッセージのみが返されます。
  • range_end_seq_no int | None– オプションの排他的上限シーケンス境界。seq_noがこの値より小さいメッセージのみが返されます。
  • include_bytes bool– 返されるメッセージにアタッチされているイメージ部分に、格納されているバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。
• 戻り値:返されるウィンドウ内で最も古いものから新しいものの順に並べられたメッセージ・レコード。
• 戻り型: List[MessageRecord]

method list_thread_messages_async (非同期)

1つのスレッドについて格納されているメッセージ履歴を非同期的にリストします。

• パラメータ:
  • thread_id str– メッセージが返されるスレッドの識別子。
  • last_n int | None– 含める最新のメッセージの数(オプション)。省略すると、スレッドの格納されているすべてのメッセージが返されます。シーケンス範囲と組み合せると、その範囲内に制限が適用されます。
  • range_start_seq_no int | None– オプションの下限シーケンス境界。seq_noがこの値以上のメッセージのみが返されます。
  • range_end_seq_no int | None– オプションの排他的上限シーケンス境界。seq_noがこの値より小さいメッセージのみが返されます。
  • include_bytes bool– 返されるメッセージにアタッチされているイメージ部分に、格納されているバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。
• 戻り値:返されるウィンドウ内で最も古いものから新しいものの順に並べられたメッセージ・レコード。
• 戻り型: List[MessageRecord]

method search (抽象)

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

• パラメータ:
  • query str | None– 自然言語問合せ。query_vectorを省略する場合は、指定する必要があります。
  • query_vector list[float] | None– オプションの事前計算済問合せ埋込み。queryおよびquery_vectorのいずれかを指定する必要があります。
  • k int– 戻す結果の最大数。明示的な値は、1以上である必要があります。これは上限です。フィルタが制限しすぎている場合、有効期限が切れていない一致レコードが少ない場合、または実装固有の検索動作のために、コールで返される結果がkより少ない場合があります。
  • 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– オプションのメタデータフィルタマッピング。metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。
  • include_invalid_results bool– 結果に無効なステータスのメモリーに似たレコードが含まれるかどうか。デフォルトはTrueです。Falseを渡して除外します。
  • num_hops int– 各ダイレクトメモリー結果から従うメモリーリンクエッジの数。0から5までの値がサポートされ、0はグラフ展開を無効にします。
  • max_linked_results int– 各直接結果にアタッチされたすべてのホップ間でリンクされたメモリーの最大数。0は、リンクされたコンテキストなしで直接の結果を保持します。デフォルトは100です。
• 戻り値:距離の増加でソートされた(record, distance)ペア。リストに含まれるエントリ数はk未満です。
• 戻り型: 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-docs2",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs2']
any(
    record.id == "mem-search-meta-source-docs2"
    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-docs2",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs2']
any(
    record.id == "mem-search-meta-review-docs2"
    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-docs2",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs2']
any(
    record.id == "mem-search-meta-tags-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

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

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

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

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

method search_async (非同期)

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

• パラメータ:
  • query str | None– searchで受け入れられる問合せテキストと同じです。
  • k int– searchで受け入れられる同じ最大結果数。明示的な値は、1以上である必要があります。
  • query_vector list[float] | None– searchで受け入れられる、オプションの事前計算済みクエリー埋め込みと同じです。
  • thread_id str | None– searchで受け入れられるオプションのスコープフィルタと同じです。
  • user_id str | None– searchで受け入れられるオプションスコープフィルタと同じです。
  • agent_id str | None– searchで受け入れられるオプションのスコープフィルタと同じです。
  • exact_user_match bool– searchで受け入れられる完全一致フラグと同じです。
  • exact_agent_match bool– searchで受け入れられる完全一致フラグと同じです。
  • exact_thread_match bool– searchで受け入れられる完全一致フラグと同じです。
  • record_types set[str] | None– searchで受け入れられるオプションのレコードタイプフィルタと同じです。
  • metadata_filter dict[str, Any] | None– スカラー、ネスト、完全リスト、配列メンバーシップ、および {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]}、{"tags": {"$array_contains": "prod"}}などの結合条件を含む、searchで受け入れられる同じオプションのメタデータフィルタ。
  • include_invalid_results bool– searchで受け入れられるライフサイクルステータスの結果オプションが同じです。
  • num_hops int– searchで受け入れられるグラフ拡張の深さが同じです。
  • max_linked_results int– searchで受け入れられる直接結果ごとのリンクメモリー制限が同じです。
• 戻り値:基礎となるsearchコールによって戻される(record, distance)ペア。
• 戻り型: List[tuple[Record、 float]]
• Raises: ValueError– kが1未満の場合。

method update (抽象)

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

• パラメータ:
  • record_type str– 更新するレコードの論理型。
  • record_id str– 更新するレコードの識別子。
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None– 標準的な置換コンテンツ。messageレコードの場合は、文字列または順序付けられた一連のテキストおよびイメージ・コンテンツ・パートを渡します。""を使用して、メッセージを空のテキストに置き換えます。メモリーに似たレコードの場合、ストアはNoneを受け入れて、格納されたテキストおよび関連するセマンティック状態をクリアできます。コンテンツを変更しないままにするには、引数を省略します。これをtextとともに指定しないでください。
  • index_text str | list[str] | None– 永続テキストを変更せずに、格納された検索状態を再計算または置換するために使用されるオプションの代替セマンティックペイロード。文字列はストアによって内部的にチャンク化される場合があります。空でない文字列のリストは、呼び出し元が所有するチャンクとして扱われ、再度分割することはできません。一部の実装では、これをハイブリッド検索テキストとして個別に永続化することもできます。imageレコードの場合、このフィールドは永続イメージの説明を置換します。
  • 埋込み list[float] | ndarray | list[list[float] | ndarray] | None– オプションの事前計算済埋込みベクトルまたはチャンク埋込みベクトルのリスト。指定した場合、これは直接使用され、埋込みコールは行われません。複数のベクトルでは、一致するindex_textチャンク・リストまたは既存の格納済チャンク・テキスト行が必要です。ストアがサポートする場合は、Noneを渡して、格納された埋込みを明示的にクリアします。テキスト対応索引付けのストアでは、埋込みや明示的な埋込みなしでのセマンティック更新も許可されます。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。ストアがサポートするときにメタデータをクリアするには、Noneを渡します。イメージcontentを置換するには、このマッピングに"image_mime_type"が必要です。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • timestamp str | None– レコードとともに保存するオプションの新しいタイムスタンプ。これは、レコードが作成された時間を表します。この引数を省略すると、格納されているタイムスタンプは変更されません。Noneを渡して、保存されたタイムスタンプをクリアし、ストアがサポートしているときにレコードがストアに追加された時刻を使用します。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。現在の有効期限タイムスタンプを保持するには、ttl_anchorとともにこの引数を省略します。Noneを渡して有効期限をクリアします。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。レコード作成時間にはTimeToLiveAnchor.CREATED_ATを、同じ更新で指定された置換timestampにはTimeToLiveAnchor.TIMESTAMPを、timestampを省略した場合は格納されたイベント・タイムスタンプを使用します。ttl_daysを指定せずにttl_anchorを指定すると、ストアまたはスキーマのデフォルトの存続期間が使用されます。リフレッシュ中にttl_anchorを省略すると、実装ではTimeToLiveAnchor.CREATED_ATが使用されます。
  • status RecordStatus– レコードの置換ライフサイクル・ステータス(オプション)。

  • text str | None–

    contentの非推奨の別名。ストアがサポートする場合は、Noneを渡して、格納されたテキストを明示的にクリアします。これをcontentとともに指定しないでください。

    非推奨

    バージョン26.8.0以降非推奨: このパラメータは26.8.0で非推奨になり、27.1で削除されます。かわりにcontentを使用してください。

• 戻り値:更新されたレコードの数(0または1)。戻り値0は、レコードが更新されなかったことを意味します。
• 戻り型: int
• Raises: ValueError– すべてのオプション・フィールドを省略したり、競合するセマンティック引数を指定したりするなど、更新ペイロードがストアに対して無効な場合。

method update_async (非同期)

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

• パラメータ:
  • record_type str– 更新するレコードの論理型。
  • record_id str– 更新するレコードの識別子。
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None– 標準的な置換コンテンツ。messageレコードの場合は、文字列または順序付けられた一連のテキストおよびイメージ・コンテンツ・パートを渡します。""を使用して、メッセージを空のテキストに置き換えます。メモリーに似たレコードの場合、ストアはNoneを受け入れて、格納されたテキストおよび関連するセマンティック状態をクリアできます。コンテンツを変更しないままにするには、引数を省略します。これをtextとともに指定しないでください。
  • index_text str | list[str] | None– 永続テキストを変更せずに、格納された検索状態を再計算または置換するために使用されるオプションの代替セマンティックペイロード。文字列はストアによって内部的にチャンク化される場合があります。空でない文字列のリストは、呼び出し元が所有するチャンクとして扱われ、再度分割することはできません。一部の実装では、これをハイブリッド検索テキストとして個別に永続化することもできます。imageレコードの場合、このフィールドは永続イメージの説明を置換します。
  • 埋込み list[float] | ndarray | list[list[float] | ndarray] | None– オプションの事前計算済埋込みベクトルまたはチャンク埋込みベクトルのリスト。指定した場合、これは直接使用され、埋込みコールは行われません。複数のベクトルでは、一致するindex_textチャンク・リストまたは既存の格納済チャンク・テキスト行が必要です。ストアがサポートする場合は、Noneを渡して、格納された埋込みを明示的にクリアします。テキスト対応索引付けのストアでは、埋込みや明示的な埋込みなしでのセマンティック更新も許可されます。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。ストアがサポートするときにメタデータをクリアするには、Noneを渡します。イメージcontentを置換するには、このマッピングに"image_mime_type"が必要です。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • timestamp str | None– レコードとともに保存するオプションの新しいタイムスタンプ。これは、レコードが作成された時間を表します。この引数を省略すると、格納されているタイムスタンプは変更されません。Noneを渡して、保存されたタイムスタンプをクリアし、ストアがサポートしているときにレコードがストアに追加された時刻を使用します。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。現在の有効期限タイムスタンプを保持するには、ttl_anchorとともにこの引数を省略します。Noneを渡して有効期限をクリアします。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。レコード作成時間にはTimeToLiveAnchor.CREATED_ATを、同じ更新で指定された置換timestampにはTimeToLiveAnchor.TIMESTAMPを、timestampを省略した場合は格納されたイベント・タイムスタンプを使用します。ttl_daysを指定せずにttl_anchorを指定すると、ストアまたはスキーマのデフォルトの存続期間が使用されます。リフレッシュ中にttl_anchorを省略すると、実装ではTimeToLiveAnchor.CREATED_ATが使用されます。
  • status RecordStatus– レコードの置換ライフサイクル・ステータス(オプション)。現在のステータスを保持するには、これを省略します。

  • text str | None–

    contentの非推奨の別名。ストアがサポートする場合は、Noneを渡して、格納されたテキストを明示的にクリアします。これをcontentとともに指定しないでください。

    非推奨

    バージョン26.8.0以降非推奨: このパラメータは26.8.0で非推奨になり、27.1で削除されます。かわりにcontentを使用してください。

• 戻り値:更新されたレコードの数(0または1)。戻り値0は、レコードが更新されなかったことを意味します。
• 戻り型: int
• Raises: ValueError– すべてのオプション・フィールドを省略したり、競合するセマンティック引数を指定したりするなど、更新ペイロードがストアに対して無効な場合。

method update_relations (抽象)

ストアドリレーションの可変値を更新します。

省略されたフィールドは変更されませんが、ビルトイン・メモリー・リレーション・タイプに変更すると、その逆ラベルが固定逆に置換されます。DBバック・メモリー・ストアでは、リレーション・タイプの変更後にエンドポイントのライフサイクル状態も再計算されます。

• パラメータ:
  • relation_ids str | list[str]– 更新する関係の識別子または識別子。
  • relation_types str | list[str]– オプションの置換指示付きリレーション・ラベル。格納されているラベルを保持するには、これを省略します。
  • opposite_relation_types str | list[str]– オプションの置換逆リレーションのラベルまたはラベル。ラベルを渡して置換するか、この引数を省略して保存します。
  • timestamps str | None | list[str | None]– オプションの置換タイムスタンプまたはタイムスタンプ。格納されているタイムスタンプをクリアするには、Noneを渡します。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションの置換メタデータ・オブジェクト。指定されたメタデータは、格納されたオブジェクトを置き換えますが、マージされません。
• 戻り値:更新されたリレーションの識別子。
• 戻り型: list[str]

例

store.update_relations(
    "relation-id", relation_types="supports"
)
['relation-id']

method update_relations_async (非同期)

ストアドリレーションの可変値を非同期に更新します。

省略されたフィールドは変更されませんが、ビルトイン・メモリー・リレーション・タイプに変更すると、その逆ラベルが固定逆に置換されます。DBバック・メモリー・ストアでは、リレーション・タイプの変更後にエンドポイントのライフサイクル状態も再計算されます。

• パラメータ:
  • relation_ids str | list[str]– 更新する関係の識別子または識別子。
  • relation_types str | list[str]– オプションの置換指示付きリレーション・ラベル。格納されているラベルを保持するには、これを省略します。
  • opposite_relation_types str | list[str]– オプションの置換逆リレーションのラベルまたはラベル。ラベルを渡して置換するか、この引数を省略して保存します。
  • timestamps str | None | list[str | None]– オプションの置換タイムスタンプまたはタイムスタンプ。格納されているタイムスタンプをクリアするには、Noneを渡します。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションの置換メタデータ・オブジェクト。指定されたメタデータは、格納されたオブジェクトを置き換えますが、マージされません。
• 戻り値:更新されたリレーションの識別子。
• 戻り型: list[str]

例

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Oracle DBストア

クラス oracleagentmemory.core.OracleDBMemoryStore

ベース: OracleMemoryStore

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

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

• パラメータ:
  • embedder IEmbedder | None– ストアでローカル・ベクトル埋込みが必要な場合に使用される埋込み。呼出し側が常に事前計算されたベクトルを提供する場合、またはキーワード検索をテキストのみの書込みおよびテキスト問合せとともに使用する場合は、Noneになります。SearchStrategy.HYBRIDでは、管理対象ハイブリッド索引でこの埋込み者のデータベース内モデルを使用できるように、ここにOracleDBEmbedderが必要です。
  • pool Any– Oracle DB接続またはプール。RAW接続を渡すと、このストア・インスタンスに対してシングル・セッション・モードが有効になります。コンカレント・ストア・コールは、書込み操作で使用される行ロックおよびトランザクションの仮定を保持するためにローカルにシリアライズされます。コンカレント要求には接続プールを使用します。
  • schema_policy SchemaPolicy | str– 管理対象スキーマのオープンまたは準備方法を制御します。デフォルトでは、既存の最新のスキーマが必要であり、DDLの変更は行われません。memory_store_idで識別されるストアの場合、SchemaPolicy.CREATE_IF_NECESSARYは必要に応じてスキーマを作成または修復し、SchemaPolicy.RECREATEはスキーマを削除して再作成します。古いスキーマ・バージョンを修復するには、パッケージ・スキーマのアップグレードが必要です。schema_ownerが設定されている場合は、通常のクロススキーマ・アクセスにSchemaPolicy.REQUIRE_EXISTINGを使用し、ディープ・データ・セキュリティ・ランタイム・アクセスにSchemaPolicy.NO_CHECKを使用します。いずれも、スキーマの作成、修復、レクリエーション、および最初のハイブリッド索引作成を含む管理対象スキーマDDLを防止します。これらのアクションは、schema_ownerなしで所有データベース・ユーザーとして接続している間に実行します。いずれのモードでもストアは読取り専用になりません。通常のメモリーの読取りと書込みでは、接続ユーザーの有効なデータベース認可が使用されます。ディープ・データ・セキュリティのランタイム・アクセスの場合は、SchemaPolicy.NO_CHECKを使用して、OracleMemoryEndUserSecurityContextがアクティブなときにストアを作成します。結果のストアには、以降のデータベース操作ごとにアクティブなエンドユーザー・コンテキストが必要です。NO_CHECK以外のスキーマ・ポリシーは、アクティブなエンドユーザー・コンテキストを拒否するため、スキーマ・ライフサイクル作業を誤ってエンド・ユーザーとして実行することはできません。
  • vector_dim int | None– ローカル・ベクトル・ストレージの埋込みディメンション(オプション)。正の整数を渡して、管理対象埋込み列およびベクトル索引を作成し、そのディメンションに対して既存のスキーマ・メタデータを検証します。Noneを渡すか、このストアにローカル・ベクトル記憶域が必要ない場合は引数を省略します。キーワードおよびハイブリッド検索は、ローカル埋込み列なしで格納された検索テキストから操作できます。ベクトル検索にはローカル・ベクトル・ストレージが必要です。この引数を省略し、有効な検索バックエンドがベクトル検索の場合、埋込みが使用可能なときはストアはembedder.embedding_dimensionを使用します。

  • table_name_prefix str–

    管理対象表/索引名に追加されるオプションの接頭辞。これまたはmemory_store_idのいずれかを渡します。両方は渡しません。

    非推奨

    バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨になり、27.1で削除されます。かわりにmemory_store_idを使用してください。

  • memory_store_id str– 管理対象DBメモリー・ストアの安定したID。同じIDを再利用して、同じ管理対象ストアを再オープンします。IDはアンダースコアを使用して管理対象DBオブジェクト名に結合されるため、先頭は文字で、使用できるのは文字、数字およびアンダースコアのみで、最大16文字である必要があります。これまたはtable_name_prefixのいずれかを渡します。両方は渡しません。省略した場合、table_name_prefixも省略すると、ストアはtable_name_prefixまたは接頭辞なしのデフォルトを使用します。接続ユーザーのスキーマでストアを作成、修復または再作成するには、そのスキーマに互換性のあるDBMS_AGENT_MEMORY_STOREパッケージが必要です。
  • schema_owner str– 既存の管理対象メモリー・ストアのオプションのスキーマ所有者。接続ユーザーのスキーマを使用するには、このオプションを省略します。pool引数は、RAWデータベース接続または接続プールです。別のユーザーが所有する表に対する権限があるアプリケーションDBユーザーに属している場合は、このオプションを使用します。このオプションは、すでに作成されている管理対象メモリー・ストアへの実行時アクセス専用です。通常のクロススキーマ・アクセスにはSchemaPolicy.REQUIRE_EXISTINGを使用し、ディープ・データ・セキュリティで保護されたストアにはアクティブなエンドユーザー・セキュリティ・コンテキストを持つSchemaPolicy.NO_CHECKを使用します。スキーマ所有者として接続しているときに管理対象メモリー・ストアを作成、アップグレードまたは再作成し、このオプションを省略します。引用符で囲まれていない識別子を渡します。小文字の入力は大文字に正規化され、引用符で囲まれた大/小文字を区別するスキーマ所有者はサポートされません。CREATE SESSIONおよび必要なオブジェクト権限をアプリケーションDBユーザーに付与します。正確な付与については、トラブルシューティング・ガイドのDatabase Users and Privilegesの項を参照してください。別の方法として、ランタイム・スキーマで同じ名前の管理対象オブジェクト・ビューを公開し、schema_ownerを省略します。これは、SchemaPolicy.REQUIRE_EXISTINGでのみサポートされます。
  • search_strategy SearchStrategy– search()のバックエンドを選択するSearchStrategy値。ベクトルのみの取得にはSearchStrategy.VECTOR(デフォルト)、格納された検索テキストに対して管理されたOracleハイブリッド・ベクトル索引を問い合せるにはSearchStrategy.HYBRID、ベクトル・フュージョンのない格納された検索テキストに対してキーワード/テキスト一致でランク付けするにはSearchStrategy.KEYWORDを使用します。KEYWORDには埋込みは必要ありません。HYBRIDでは、管理対象ハイブリッド索引がメイン・ストア・埋込みと同じデータベース内モデルを使用するように、embedderをOracleDBEmbedderにする必要があります。キーワード・クライアントが既存のハイブリッド・スキーマを開く場合、ストアはそのハイブリッド索引のテキスト・ブランチを使用できます。既存のスキーマで互換性のない戦略が使用されている場合、そのスキーマには戦略に必要なストアド・サーチ状態が含まれていない可能性があるため、起動に失敗します。schema_policy=SchemaPolicy.REQUIRE_EXISTINGおよびこの引数を省略すると、ストア・ベストエフォートでは、管理対象メタデータからスキーマの格納済検索モードが検出され、使用可能な場合はそのモードが使用されます。
  • search_index_sync SearchIndexSyncMode– SearchStrategy.HYBRIDおよびSearchStrategy.KEYWORDの管理対象検索索引リフレッシュ動作を選択するSearchIndexSyncMode値。SearchIndexSyncMode.ON_COMMITがデフォルトであり、書込みトランザクションがコミットされるとすぐにレコードを検索可能にします。SearchIndexSyncMode.MANUALは、明示的なデータベース側の同期操作へのリフレッシュを残します。SearchIndexSyncMode.AUTOを使用すると、Oracleは管理対象ハイブリッド索引を非同期的にリフレッシュでき、SearchStrategy.HYBRIDでのみサポートされます。キーワード検索ではAUTOが拒否されます。
  • memory_retention_config MemoryRetentionConfig–DBでバックアップされたメッセージおよびメモリーのオプションのメモリー保持構成。MemoryRetentionConfig.default_ttl_daysは、新しい書込みがttl_daysを省略する場合に使用されます。MemoryRetentionConfig.max_ttl_daysは、構成済の最大値を上回る明示的なレコードごとの期間を警告付きでクランプし、設定されている場合、ttl_days=Noneは失効しない行を作成するかわりにその最大値を使用します。SchemaPolicy.CREATE_IF_NECESSARYを使用すると、明示的な構成では、既存の管理対象スキーマに格納されているメタデータがリフレッシュされますが、既存の有効期限は更新されず、省略すると既存の設定が維持されます。明示的な構成がNOT_SET_MARKERにdefault_ttl_daysまたはmax_ttl_daysを残す場合、SDKはスキーマ・メタデータを比較または格納する前に、その属性をデフォルト値(None)に解決します。この構成は、レコードに格納される予想情報、アプリケーションが保持する理由、およびアプリケーションまたは規制保持のコミットメントに基づいて選択します。
• Raises: RuntimeError– エンド・ユーザー・セキュリティ・コンテキストがSchemaPolicy.NO_CHECK以外のスキーマ・ポリシーでアクティブである場合、またはNO_CHECKランタイム・ストアがアクティブなエンドユーザー・セキュリティ・コンテキストなしでオープンまたは使用される場合。

警告: SchemaPolicy.CREATE_IF_NECESSARYは、初期化が成功する前に管理対象スキーマ・オブジェクトを修復する可能性があるため、通常のストアの起動よりもコストがかかることがあります。スキーマに多数の行が含まれている可能性がある場合は、メンテナンス操作として修復作業を計画します。古いスキーマ・バージョンのストアでは、初期化の前にパッケージ・スキーマのアップグレードが必要です。

スキーマ設定で管理対象の期限切れレコード・パージ・ジョブを作成する必要があるが、データベース・ユーザーにスケジューラ・ジョブ権限がない場合、初期化は警告して続行します。期限切れのメッセージおよびメモリーは読取りおよび検索から非表示のままですが、ジョブが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ストアにレコードを追加します。

• パラメータ:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]– レコード・ペイロードの読取り専用シーケンス。メッセージ・エントリには、順序付けられたMessageContent部分を含めることができます。スレッド・サマリー・エントリは、マッピング、{"text": value}オブジェクトになる文字列、またはJSON nullとして格納されるNoneです。テキスト値は、index_textsが指定されていないかぎり、検索にも使用されます。その他のレコード・タイプの場合、Noneはmetadata["content"]にフォールバックできます。明示的な空の文字列は保持されます。
  • record_type str– 作成する論理レコード・タイプ("message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"thread_summary"など)。
  • index_texts list[str | list[str] | None]– 検索テキストとして使用されるオプションの代替ペイロード。これを使用して、DBバックのキーワード索引またはハイブリッド検索索引を制御します。各外部リスト・エントリは、1つのレコードに揃っています。文字列エントリはストアによってチャンク化できます。リスト・エントリは、コール元が所有するチャンクとして扱われ、そのままRECORD_CHUNKS.chunk_textに書き込まれます。embeddingsも指定されている場合、リスト・エントリはチャンクごとに1つのベクトルのみを必要とします。文字列エントリは、そのレコードに対して1つのベクトルのみを受け入れます。

  • 埋込み list[list[float] | ndarray | list[list[float] | ndarray]]–

    contentsに整列されたオプションの事前計算済埋込みベクトル。各レコード・エントリは、1つのベクトルまたはチャンク・ベクトルのリストです。ローカル・ベクトル・ストレージが構成されている場合、これらのベクトルは、ストアの埋込みをコールして書込み用のローカル・ベクトルを作成するのではなく、レコードのベクトル表現として直接格納されます。単一のベクトルは、構成済のチャンカが分割する場合でも、セマンティック・テキスト全体を表します。複数のチャンク・ベクトルでは、一致するindex_textsチャンク・リストが必要です。

    SearchStrategy.VECTORでは、ベクトル検索は格納されたベクトルに対してランク付けされます。SearchStrategy.HYBRIDまたはSearchStrategy.KEYWORDでは、DBバック検索は、格納された検索テキストおよびOracle管理テキストまたはハイブリッド索引の状態をランク付けするため、アドタイム埋込みは、構成済のローカル・ベクトル・ストレージにのみ影響し、そのアクティブな検索戦略には影響しません。このストアがローカル・ベクトル・ストレージなしで構成されている場合は、embeddingsのかわりにindex_textsを指定して、これらのテキスト対応索引に表示されるテキストをオーバーライドします。

  • record_ids str | None | list[str | None]– オプションの呼び出し元表示識別子。1つの文字列を1つのレコード挿入に使用できますが、リストはcontentsと一致している必要があります。このフィールドを省略すると、生成された識別子が返されます。
  • thread_ids str | None | list[str | None]– 挿入されたレコードに関連付けられたオプションのスレッド識別子。スカラー値は、整列された入力間でブロードキャストできます。
  • user_ids str | None | list[str | None]– 挿入されたレコードに関連付けられたオプションのユーザー識別子。スカラー値は、整列された入力間でブロードキャストできます。SchemaPolicy.NO_CHECKランタイム・ストアで省略すると、ストアはアクティブなエンドユーザー・セキュリティ・コンテキストのユーザー名を使用します。スコープなしのユーザーIDを保持するには、Noneを明示的に渡します。
  • agent_ids str | None | list[str | None]– 挿入されたレコードに関連付けられたオプションのエージェント識別子。スカラー値は、整列された入力間でブロードキャストできます。
  • roles str | None | list[str | None]– オプションのメッセージ・ロール("user"や"assistant"など)。record_typeが"message"の場合にのみ使用されます。
  • timestamps str | None | list[str | None]– レコードとともに保存するオプションのタイムスタンプ。各タイムスタンプは、レコードが作成された時刻を表します。スカラー値は、整列された入力間でブロードキャストできます。省略されたエントリまたはNoneエントリは、イベントのタイムスタンプを設定しません。ttl_anchorがTimeToLiveAnchor.TIMESTAMPの場合、影響を受けるすべてのレコードには、具体的なISO-8601タイムスタンプ値が必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションのメタデータディクショナリ。テキスト値を""に設定するのではなく省略した場合、メタデータにはフォールバック・ソースとして"content"を含めることができます。イメージ書込みには、"image/png"、"image/jpeg"または"image/webp"を指定した"image_mime_type"が必要です。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • ttl_days int | None | list[int | None]– メッセージおよびメモリーに似たレコードに対するオプションの存続時間(日数)。管理対象スキーマのMemoryRetentionConfig.default_ttl_daysを使用するには、この引数を省略します。Noneを渡して、保存構成の設定時にMemoryRetentionConfig.max_ttl_daysを使用するか、失効しないレコードを作成します。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。スカラー値は、整列された入力間でブロードキャストできます。
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]– オプションの稼働時間アンカー。TimeToLiveAnchor.CREATED_ATを使用してデータベース作成時間を基準に期限切れにするか、TimeToLiveAnchor.TIMESTAMPを使用して指定されたイベント・タイムスタンプを基準に期限切れにします。省略すると、有効期限はTimeToLiveAnchor.CREATED_ATを使用します。Timestamp-anchored有効期限には、挿入されたレコードごとに具体的なISO-8601タイムスタンプが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • statuses RecordStatus | list[RecordStatus]– それをサポートするレコードのライフサイクル・ステータス(オプション)。1つのRecordStatus値を指定して、すべての入力レコード、またはcontentsに合せたステータスのリストに適用します。RecordStatus.VALIDを使用するには、この引数を省略します。
  • **store_kwargs (Any)–DB書き込みオプション。batch_sizeは、エグゼキュータのバッチサイズを制御し、デフォルトは 256です。
• 戻り値:入力と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: list[str]

例

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 str– エージェント識別子。
  • information str– エージェントに関するフリーフォーム情報。このテキストはプロファイル コンテンツとして保存され、プロファイルの検索可能な表現の作成に使用されます。
  • metadata dict[str, Any] | None– エージェント・プロファイル行に格納されているオプションのメタデータ・マッピング。
• 戻り値:挿入されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

ノート

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

例

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

method add_agent_async (非同期)

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

• パラメータ:
  • agent_id str– エージェントプロファイルの安定した識別子。
  • information str– エージェントを説明する自由形式のテキスト。
  • metadata dict[str, Any] | None– エージェント・プロファイル行に格納されているオプションのメタデータ・マッピング。
• 戻り値:作成されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

method add_async (非同期)

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

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

• パラメータ:
  • コンテンツ Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • 埋込み list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • ロール str | None | list[str | None]
  • タイムスタンプ str | None | list[str | None]
  • メタデータ dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • ステータス RecordStatus | list[RecordStatus]
  • store_kwargs Any
• 戻り型: list[str]

メソッド add_batches

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

• パラメータ:
  • batches list[PendingRecordBatch]– 永続化する完全に準備された論理バッチ。各バッチには、record_type、スコープ値、ロール、タイムスタンプ、メタデータなどのレコードごとに独自のフィールドが必要です。
  • **store_kwargs (Any)– 具象ストアに転送される実装固有の書き込みオプション。
• 戻り値:入力バッチおよび行と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: List[str]

例

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

method add_batches_async (非同期)

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

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

• パラメータ:
  • バッチ list[PendingRecordBatch]
  • store_kwargs Any
• 戻り型: list[str]

メソッド add_relations

メモリーとメモリーの関係を1つ以上原子的に格納します。

スカラー値は、ソースIDバッチ全体でブロードキャストされます。リストは整列している必要があります。1つのエンドポイント・ペアに対して格納できるリレーション方向は1つのみです。組込みのメモリー・リンク・ラベルは固定の逆ラベルを受け取り、ライフサイクル・ラベルは同じトランザクションのエンドポイント状態を更新します。

• パラメータ:
  • source_record_ids str | list[str]– スカラーまたは整列リストとしてのソースメモリー識別子。
  • source_record_types str | list[str]– ソース・レコードのメモリーに似た型。
  • target_record_ids str | list[str]– スカラーまたは整列リストとしてのターゲットメモリー識別子。
  • target_record_types str | list[str]– ターゲット・レコードのメモリーに似た型。
  • relation_types str | list[str]– 指示付きリレーション・ラベル。
  • opposite_relation_types str | list[str]– カスタム・リレーション・タイプのオプションの逆ラベル。これは、格納されたリレーションの逆ビューを表し、逆方向に2番目のリレーションは作成しません。
  • relation_ids str | None | list[str | None]– オプションの安定したリレーション識別子。識別子を生成するには省略します。
  • timestamps str | None | list[str | None]– リレーションとともに格納されるオプションのタイムスタンプ。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– リレーションとともに格納されるオプションのメタデータ。
• 戻り値:入力順序でリレーション識別子を作成しました。
• 戻り型: list[str]

例

store.add_relations(
    "new-memory", "memory", "old-memory", "memory", "supersedes"
)
['relation-id']

method add_relations_async (非同期)

非同期に1つ以上の指示付きリレーションを格納します。

スカラー値は、ソース・レコード・バッチ全体でブロードキャストされます。リスト値は同じ長さである必要があります。1つのエンドポイント・ペアに対して格納できる方向は1つのみです。opposite_relation_typesを使用して、2番目の逆リレーションを追加するのではなく、逆ビューを記述します。

• パラメータ:
  • source_record_ids str | list[str]– 各指示付きリレーションのソース端にあるレコードの識別子または識別子。
  • source_record_types str | list[str]– source_record_idsのレコード・タイプまたはタイプ。すべてのソースに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • target_record_ids str | list[str]– 各指示付きリレーションのターゲット端にあるレコードの識別子または識別子。
  • target_record_types str | list[str]– target_record_idsのレコードタイプまたはタイプ。すべてのターゲットに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • relation_types str | list[str]– 指示付きリレーション・ラベル。すべてのリレーションに1つの値を指定するか、リレーションごとに1つの値を指定します。
  • opposite_relation_types str | list[str]– 各リレーションの逆ビューに対するオプションのラベルまたはラベル。組み込みのメモリーリレーションタイプの場合、省略は事前定義された逆ラベルを使用します。カスタムリレーションタイプの場合、省略は両方向に同じラベルを使用します。
  • relation_ids str | None | list[str | None]– オプションの安定した識別子または識別子。ストアで識別子を生成するには、これを省略します。
  • timestamps str | None | list[str | None]– リレーションに格納するオプションのタイムスタンプまたはタイムスタンプ。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– リレーションに格納するオプションのメタデータ・オブジェクト。
• 戻り値:入力順のリレーション識別子。
• 戻り型: list[str]

例

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

メソッド add_user

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

• パラメータ:
  • user_id str– ユーザー識別子。SchemaPolicy.NO_CHECKランタイム・ストアで省略すると、ストアはアクティブなエンドユーザー・セキュリティ・コンテキストのユーザー名を使用します。それ以外の場合は、この引数を明示的に指定します。
  • information str– ユーザーに関する必要な自由形式情報。このテキストはプロファイル コンテンツとして保存され、プロファイルの検索可能な表現の作成に使用されます。
  • metadata dict[str, Any] | None– ユーザープロファイル行に格納されているオプションのメタデータマッピング。
• 戻り値:挿入されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

ノート

ユーザー・プロファイル・レコードのスコープは設定されていません。挿入されたパブリック・レコード識別子は、明示的または推測されたuser_idです。

例

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

method add_user_async (非同期)

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

• パラメータ:
  • user_id str– ユーザープロファイルの安定した識別子。
  • information str– ユーザーを説明する自由形式のテキスト。
  • metadata dict[str, Any] | None– ユーザープロファイル行に格納されているオプションのメタデータマッピング。
• 戻り値:作成されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

メソッド delete

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

• パラメータ:
  • record_type str– 削除するレコードタイプラベル。サポートされているタイプには、"thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"および"thread_summary"があります。
  • record_id str– 削除する識別子。
  • カスケード bool– Trueの場合、アクター・プロファイルなどのサポートされている最上位ターゲットを、同じトランザクション内のスコープ指定された子行に展開します。ユーザー・プロファイル・ターゲットまたはエージェント・プロファイル・ターゲットの場合、所有されているスレッド行が最初に削除され、そのスレッド・スコープのメッセージおよびメモリー表の行が削除されます。その後、アクター・スコープの残りの直接メッセージおよびメモリーに似た行(memory、guideline、fact、preference)が削除されます。このスコープ指定クリーンアップは、一致するプロファイル行がすでに存在する場合でも実行されます。
• 戻り値:削除されたリクエストされたトップレベル・ターゲットの数(通常は0または1)。カスケードされた子行は個別にカウントされないため、欠落しているアクター・プロファイルによってスコープ指定クリーン・アップがトリガーされた場合でも、これは0になることがあります。
• 戻り型: int

ノート

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

例

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

method delete_async (非同期)

1つのストアド・レコードを識別子で非同期に削除します。

• パラメータ:
  • record_type str– 削除するレコードの論理型。
  • record_id str– 削除するレコードの識別子。
  • カスケード bool– Trueの場合、同じ削除操作内でリクエストされたトップレベル・ターゲットに対して、ストアでサポートされているカスケード削除動作を適用します。これは主に、追加のスコープ付きレコードを所有するアクター・プロファイルなどのターゲットに使用されます。たとえば、ユーザー・プロファイル・カスケードまたはエージェント・プロファイル・カスケードでは、所有されているスレッド自体、スレッド・スコープのメッセージおよびそれらのスレッドで削除されたメモリーのようなレコード、およびメッセージ、メモリー、ガイドライン、ファクト、プリファレンスなどのアクター・スコープの残りの直接レコードを削除できます。アクタープロファイル削除の場合、一致するプロファイル行がすでに存在していなくても、このスコープ指定クリーンアップが実行される場合があります。
• 戻り値:削除されたリクエストされたトップレベル・レコードの数(通常は0または1)。カスケードされた子行は個別にカウントされないため、欠落しているアクター・プロファイルによってスコープ指定クリーン・アップがトリガーされた場合でも、これは0になることがあります。
• 戻り型: int

メソッド delete_relations

リレーションを識別子で削除し、ライフサイクル状態を再計算します。

• パラメータ: relation_ids str | list[str]– 削除する関係の識別子または識別子。
• 戻り値:削除されたリレーションの数。
• 戻り型: int

例

store.delete_relations("relation-id")
1

method delete_relations_async (非同期)

識別子で関係を非同期に削除します。

ライフサイクル状態は、残っているリレーションから再計算されます。

• パラメータ: relation_ids str | list[str]– 削除する関係の識別子または識別子。
• 戻り値:削除されたリレーションの数。
• 戻り型: int

例

await store.delete_relations_async("relation-id")
1

メソッド delete_thread

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

• パラメータ: thread_id str– スレッド行、依存する子行、明示的なチャンク行のクリーンアップなど、行を削除する必要があるスレッド識別子。
• 戻り値:削除されたスレッド行の数(0または1)。
• 戻り型: int

ノート

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

例

store.delete_thread("c1")
0

method delete_thread_async (非同期)

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

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

ノート

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

メソッド get

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

• パラメータ:
  • record_type str– "message"、"memory"、"guideline"、"fact"、"preference"、"thread"、"user_profile"、"agent_profile"、"thread_summary"などの管理対象行に解決されるレコード・タイプ・ラベル。
  • record_id str– 検索する識別子。
  • include_bytes bool– イメージレコードのイメージバイトをロードするか、メッセージレコードの添付イメージをロードするか。デフォルトはFalseです。
• 戻り値:検出時にデコードされたメタデータを含むレコードが移入されます。それ以外の場合は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'

method get_async (非同期)

タイプおよび識別子によって、格納されている1つのレコードを非同期的に取得します。

• パラメータ:
  • record_type str– 取得するレコードの論理型("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"image"など)。
  • record_id str– 取得するレコードの識別子。
  • include_bytes bool– 格納されたイメージバイトをロードするかどうか。メッセージ・レコードの場合、添付されたイメージにバイトを含めるかどうかを制御します。イメージ・レコードの場合、スタンドアロン・イメージのバイトをロードするかどうかを制御します。このオプションは、他のレコードタイプには影響しません。
• 戻り値:格納されたレコードが見つかった場合、それ以外の場合はNone。"thread"参照は、スレッド・メタデータ、ランタイム構成、ランタイム状態およびストアで永続スレッドがサポートされるときに移入された作成タイムスタンプを含むThreadRecordを返します。
• 戻りタイプ: レコード |なし

メソッド get_relation

IDまたは完全なエンドポイント・タプルで識別される1つのリレーションを返します。

relation_idを単独で指定するか、ソースとターゲットの完全なエンドポイント・タプルを1つ指定します。

• パラメータ:
  • source_record_id str– ソースレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • source_record_type str– ソース・レコード・タイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_id str– ターゲットレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_type str– ターゲットレコードタイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_type str– 指示付きリレーション・ラベル。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_id str– 直接照合するリレーション識別子。この引数をエンドポイント・タプル・フィールドと組み合せるのではなく、単独で指定します。
• 戻り値:一致するストアド・リレーション、または存在しない場合はNone。
• 戻り型: RecordRelation |なし

例

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method get_relation_async (非同期)

IDまたはエンドポイント・タプルで1つのリレーションを非同期的に取得します。

relation_idを単独で指定するか、ソースとターゲットの完全なエンドポイント・タプルを1つ指定します。

• パラメータ:
  • source_record_id str– ソースレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • source_record_type str– ソース・レコード・タイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_id str– ターゲットレコード識別子。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • target_record_type str– ターゲットレコードタイプ。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_type str– 指示付きリレーション・ラベル。relation_idが省略されている場合は、他のエンドポイント・タプル・フィールドで必須です。
  • relation_id str– 直接照合するリレーション識別子。この引数をエンドポイント・タプル・フィールドと組み合せるのではなく、単独で指定します。
• 戻り値:一致するリレーション(存在しない場合はNone)。
• 戻り型: RecordRelation |なし

例

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

メソッド list

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

• パラメータ:
  • record_type str– レコード・タイプ・ラベル("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"thread"、"user_profile"または"agent_profile"など)。
  • limit int | None– 返されるレコードの最大数(オプション)。省略すると、ストアはデフォルトのリスト上限を使用します。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがSQL NULLの行のみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。record_typeが"thread"の場合は、thread_idを設定しないでください。record_idを使用して、特定のスレッドを選択します。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、user_idがSQL NULLの行のみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、agent_idがSQL NULLの行のみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。

  • metadata_filter dict[str, Any] | None–

    メタデータ・フィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータが格納されていないレコードのみが返されます。dictに設定すると、metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "slack"}、ネストしたフィールドの場合はmetadata_filter={"review": {"status": "open"}}、完全リスト一致の場合はmetadata_filter={"tags": ["prod", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool– メッセージレコードに添付されたイメージレコードまたはイメージに、格納されたバイトが含まれているかどうか。デフォルトはFalseです。直接イメージ・リストでは、Trueの場合、record_idおよび1つ以上の正確なユーザー、エージェントまたはスレッド・スコープ・フィルタが必要です。
  • record_id str– 正確なレコード識別子フィルタ。省略すると、識別子を持つレコードが返されます。スコープおよびメタデータ・フィルタは、追加の制約のままです。
• 戻り値:挿入順序で並べられたレコード。
• 戻りタイプ: list[レコード]

ノート

"user_profile"および"agent_profile"は、スコープ指定されていないレコード・タイプです。これらのレコード・タイプの場合、thread_id、user_idおよびagent_idは無視され、アクター・アイデンティティはrecord.idに残ります。"thread"レコードは、スレッド識別子をrecord.idおよびrecord.thread_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

method list_async (非同期)

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

• パラメータ:
  • record_type str– 列挙する論理レコード・タイプ("thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"、"image"など)。
  • limit int | None– 返される最新のレコードの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。record_typeが"thread"の場合は、thread_idを設定しないでください。record_idを使用して、特定のスレッドを選択します。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、user_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、agent_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。

  • metadata_filter dict[str, Any] | None–

    メタデータ・フィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのレコードのみが返されます。dictに設定すると、metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "slack"}、ネストしたフィールドの場合はmetadata_filter={"review": {"status": "open"}}、完全リスト一致の場合はmetadata_filter={"tags": ["prod", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool– メッセージレコードに添付されたイメージレコードまたはイメージに、格納されたバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。ダイレクト・イメージ・リストの場合、これをTrueに設定するのは、正確なrecord_idおよび少なくとも1つの正確なユーザー、エージェントまたはスレッド・スコープ・フィルタを使用する場合のみです。このオプションは、他のレコードタイプには影響しません。
  • record_id str– 正確なレコード識別子フィルタ。省略すると、識別子を持つレコードが返されます。スコープおよびメタデータ・フィルタは、追加の制約のままです。
• 戻り値:返されたウィンドウ内で最も古いものから新しいものの順に並べられたレコード。
• 戻りタイプ: List[Record]

メソッド list_relations

リレーションをソースとターゲットの方向にリストします。

• パラメータ:
  • relation_type str– 照合するオプションの指示付きリレーション・ラベル("supports"や"supersedes"など)。すべてのリレーション・タイプを含める場合は省略します。
  • source_record_id str– 照合するオプションのソースレコード識別子。
  • source_record_type str– 照合するオプションのソースレコードタイプ。
  • target_record_id str– 一致するオプションのターゲットレコード識別子。
  • target_record_type str– 一致させるオプションのターゲットレコードタイプ。
  • limit int | None– 返されるもっとも早く作成されたリレーションの最大数(オプション)。省略すると、ストアはMAX_LIST_LIMITを使用します。Noneを渡して、一致するすべてのストアド・リレーションを返します。
  • metadata_filter dict[str, Any] | None– メタデータフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのリレーションのみが返されます。dictに設定すると、エントリはANDセマンティクスと結合されます。ネストされたディクショナリでは、再帰的完全一致が使用されます。スカラー値およびリスト値には正確な等価性が必要です。配列メンバーシップを照合するには{"tags": {"$array_contains": "prod"}}を、リストされた値と一致させるには"$array_contains_any"を、別のフィールド式を否定するには"$not"を使用します。
  • relation_id str– 正確なリレーション識別子フィルタ。省略すると、任意の識別子との関係が返されます。その他のフィルタは追加の制約のままです。
• 戻り値:リレーションは、作成時間と識別子でソートされます。
• 戻り型: list[RecordRelation]

例

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method list_relations_async (非同期)

ソースからターゲットへのリレーションを非同期的にリストします。

• パラメータ:
  • relation_type str– 照合するオプションの指示付きリレーション・ラベル("supports"や"supersedes"など)。すべてのリレーション・タイプを含める場合は省略します。
  • source_record_id str– 照合するオプションのソースレコード識別子。
  • source_record_type str– 照合するオプションのソースレコードタイプ。
  • target_record_id str– 一致するオプションのターゲットレコード識別子。
  • target_record_type str– 一致させるオプションのターゲットレコードタイプ。
  • limit int | None– 返されるもっとも早く作成されたリレーションの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、一致するすべてのストアド・リレーションを返します。
  • metadata_filter dict[str, Any] | None– メタデータフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、メタデータがNoneのリレーションのみが返されます。dictに設定すると、エントリはANDセマンティクスと結合されます。ネストされたディクショナリでは、再帰的完全一致が使用されます。スカラー値およびリスト値には正確な等価性が必要です。配列メンバーシップを照合するには{"tags": {"$array_contains": "prod"}}を、リストされた値と一致させるには"$array_contains_any"を、別のフィールド式を否定するには"$not"を使用します。
  • relation_id str– 直接照合するオプションのリレーション識別子。
• 戻り値:リレーションは、作成時間と識別子でソートされます。
• 戻り型: list[RecordRelation]

例

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

メソッド list_thread_messages

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

• パラメータ:
  • thread_id str– メッセージを返すスレッド識別子。
  • last_n int | None– 返される最新のメッセージの数(オプション)。
  • range_start_seq_no int | None– オプションの下限シーケンス境界。
  • range_end_seq_no int | None– オプションの排他的上限シーケンス境界。
  • include_bytes bool– 返されるメッセージにアタッチされているイメージ部分に、格納されているバイトが含まれているかどうか。デフォルトはFalseです。
• 戻り値:挿入順序で並べられたメッセージ・レコード。
• 戻り型: list[MessageRecord]

例

store.list_thread_messages("c1")
[]

method list_thread_messages_async (非同期)

1つのスレッドについて格納されているメッセージ履歴を非同期的にリストします。

• パラメータ:
  • thread_id str– メッセージが返されるスレッドの識別子。
  • last_n int | None– 含める最新のメッセージの数(オプション)。省略すると、スレッドの格納されているすべてのメッセージが返されます。シーケンス範囲と組み合せると、その範囲内に制限が適用されます。
  • range_start_seq_no int | None– オプションの下限シーケンス境界。seq_noがこの値以上のメッセージのみが返されます。
  • range_end_seq_no int | None– オプションの排他的上限シーケンス境界。seq_noがこの値より小さいメッセージのみが返されます。
  • include_bytes bool– 返されるメッセージにアタッチされているイメージ部分に、格納されているバイトが含まれているかどうか。省略またはFalseを指定すると、バイトをロードせずにイメージの説明およびメタデータが返されます。
• 戻り値:返されるウィンドウ内で最も古いものから新しいものの順に並べられたメッセージ・レコード。
• 戻り型: List[MessageRecord]

メソッド search

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

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

• パラメータ:
  • query str | None– 一致するレコードまたは類似レコードの検索に使用されるオプションの自然言語テキスト。query_vectorを省略する場合は、空白以外の文字を少なくとも1つ指定します。ベクトル検索では、このテキストが埋め込まれます。キーワード検索では、格納された検索テキストと照合されます。ハイブリッド検索では、テキスト検索とベクトル検索の両方に使用されます。テキストが構成済チャンク・サイズを超えると、ストアは各問合せチャンクを個別に検索し、ランク付けされた結果を相互ランク・フュージョンとマージします。
  • query_vector list[float] | None– オプションの事前計算済問合せ埋込み。queryおよびquery_vectorのいずれかを指定する必要があります。ベクトル検索では、これは格納されたレコード・ベクトルと比較されます。ハイブリッド検索では、問合せ側のベクトル入力としてOracleのマネージド・ハイブリッド索引に送信され、DBストアがアドタイム・ストアド・ベクトルまたは更新時ストアド・ベクトルと直接比較されることはありません。キーワード検索ではquery_vectorを使用できません。ベクトルは空でない1次元で、有限数値のみを含む必要があります。ハイブリッド検索では、そのディメンションが構成済のOracleDBEmbedderモデルと一致する必要があります。
  • k int– 返す結果の最大数。明示的な値は、1以上である必要があります。これは上限です。フィルタが制限しすぎている場合、有効期限が切れていない一致レコードが少ない場合、または実装固有の検索動作のために、コールで返される結果がkより少ない場合があります。
  • 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– 含める検索可能なレコードタイプのオプションセット。DB検索を省略すると、メッセージ、イメージなどのドキュメント、メモリー表の行およびアクター・プロファイルが対象になります。イメージ・レコードはその説明、アクター・プロファイルはinformationペイロードを寄与し、メッセージ行とメモリー行はcontentペイロードを寄与します。検索中、プロファイル・レコード・タイプは適用可能なスコープ・ディメンションのアクター識別子を使用し、残りのスコープ・ディメンションはNoneとして動作します。
  • metadata_filter dict[str, Any] | None– オプションのメタデータフィルタマッピング。metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリではないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは格納されたメタデータに存在する必要があります。ネストされたディクショナリは再帰的に照合されます。スカラー値とリスト値は完全一致で照合され、リストの順序と長さも一致する必要があります。配列メンバーシップをテストするには、{"tags": {"$array_contains": "prod"}}などのフィールド・レベルの演算子ディクショナリを使用します。"$array_contains"のリスト・オペランドは、リストされたすべての値が存在する必要があることを意味します。"$array_contains_any"は、リストされた値が少なくとも1つ存在する必要があることを意味します。"$not"を使用して、演算子ディクショナリやRAWの完全一致値など、同じフィールドの別のフィールド・レベル式を否定します。負の式は、欠落しているフィールドを含め、正の式が失敗すると一致します。負の配列メンバーシップも非配列フィールドと一致します。
  • include_invalid_results bool– 結果に無効なステータスのメモリーに似たレコードが含まれるかどうか。デフォルトはTrueです。Falseを渡して除外します。
  • num_hops int– 各ダイレクトメモリー結果から従うメモリーリンクエッジの数。0から5までの値がサポートされ、0はグラフ展開を無効にします。拡張は、両方向のリンクに従います。リンクされたレコードは、引き続き、リクエストされたスコープ、メタデータ、レコード・タイプおよび有効期限のフィルタに従います。ダイレクト・メッセージ、ドキュメントおよびプロファイルの結果は結果セットに残りますが、グラフは展開されません。
  • max_linked_results int– 各直接結果にアタッチされたすべてのホップ間でリンクされたメモリーの最大数。0は、リンクされたコンテキストなしで直接の結果を保持します。デフォルトは100です。
• 戻り値:距離の増加でソートされた(record, distance)ペア。リストに含まれるエントリ数はk未満です。チャンク化された問合せの場合、距離は相互ランク融合スコアから導出されます。
• 戻り型: list[tuple[Record、 float]]
• 引き上げ:
  • ValueError– kが1より小さい場合、queryとquery_vectorの両方またはどちらも指定されていない場合、queryが空白の場合、ベクトル・モードが問合せ埋込みを解決できない場合、query_vectorが無効の場合、またはmetadata_filterが無効の場合。
  • TimeoutError– グラフ展開に許容される最大時間を超える時間がかかる場合。

例

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 (非同期)

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

• パラメータ:
  • query str | None– searchで受け入れられる問合せテキストと同じです。
  • k int– searchで受け入れられる同じ最大結果数。明示的な値は、1以上である必要があります。
  • query_vector list[float] | None– searchで受け入れられる、オプションの事前計算済みクエリー埋め込みと同じです。
  • thread_id str | None– searchで受け入れられるオプションのスコープフィルタと同じです。
  • user_id str | None– searchで受け入れられるオプションスコープフィルタと同じです。
  • agent_id str | None– searchで受け入れられるオプションのスコープフィルタと同じです。
  • exact_user_match bool– searchで受け入れられる完全一致フラグと同じです。
  • exact_agent_match bool– searchで受け入れられる完全一致フラグと同じです。
  • exact_thread_match bool– searchで受け入れられる完全一致フラグと同じです。
  • record_types set[str] | None– searchで受け入れられるオプションのレコードタイプフィルタと同じです。
  • metadata_filter dict[str, Any] | None– スカラー、ネスト、完全リスト、配列メンバーシップ、および {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]}、{"tags": {"$array_contains": "prod"}}などの結合条件を含む、searchで受け入れられる同じオプションのメタデータフィルタ。
  • include_invalid_results bool– searchで受け入れられるライフサイクルステータスの結果オプションが同じです。
  • num_hops int– searchで受け入れられるグラフ拡張の深さが同じです。
  • max_linked_results int– searchで受け入れられる直接結果ごとのリンクメモリー制限が同じです。
• 戻り値:基礎となるsearchコールによって戻される(record, distance)ペア。
• 戻り型: List[tuple[Record、 float]]
• Raises: ValueError– kが1未満の場合。

メソッド update

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

• パラメータ:
  • record_type str– 変更される行のレコードタイプラベル("message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、または "agent_profile"など)
  • record_id str– 更新する格納された行の識別子。
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None– 正規の置換コンテンツがcontent列に保持されます。メッセージ・レコードの場合は、""を渡して、格納されたベクトル表現のクリア中にコンテンツをクリアします。明示的なNoneは拒否されます。メモリーに似たレコードの場合は、Noneを渡して格納されたテキストをクリアし、埋込みを行い、同じコールでNoneまたは省略されたセマンティック引数のみを渡します。省略すると、既存のコンテンツは変更されません。これをtextとともに指定しないでください。
  • index_text str | list[str] | None– オプションのセマンティック専用ペイロード。省略すると、contentがセマンティク索引付けに使用されます。ハイブリッド対応スキーマでは、これはOracleのテキスト・コンポーネントで使用されるストアド検索テキストにもなります。文字列値は、ストアによってチャンク化できます。リスト値は、コール元が所有するチャンクとして扱われ、そのままRECORD_CHUNKSに書き込まれます。embeddingのみを指定すると、既存の検索テキストが再利用されます。

  • 埋込み list[float] | ndarray | list[list[float] | ndarray] | None–

    オプションの事前計算済埋込みベクトルまたはチャンク埋込みベクトルのリスト。ローカル・ベクトル・ストレージが構成されている場合、これは直接使用され、埋込みコールは行われません。Noneを渡して、格納された埋込みをクリアします。contentが指定されている場合、構成済のチャンカがそのテキストを分割する場合でも、単一のベクトルは置換テキスト全体を表します。index_textがチャンク・リストでないかぎり、テキストの置換時に複数のチャンク・ベクトルが拒否されます。embeddingのみを指定する場合、埋込み数はレコードの既存のチャンク行と一致する必要があります。

    SearchStrategy.VECTORでは、ベクトル検索は格納された埋込みに対してランク付けされます。SearchStrategy.HYBRIDまたはSearchStrategy.KEYWORDでは、DBバック検索は、格納された検索テキストおよびOracle管理のテキストまたはハイブリッド索引の状態をランク付けするため、更新時の埋込みは、構成済のローカル・ベクトル・ストレージにのみ影響し、そのアクティブな検索戦略には影響しません。このストアがローカル・ベクトル・ストレージなしで構成されている場合は、embeddingのかわりにindex_textを指定して、テキスト対応索引に表示されるテキストを更新します。テキストのみのセマンティク更新では、これらのモードでembeddingを完全に省略できます。

  • metadata dict[str, Any] | None– オプションのメタデータ・マッピングは、JSONにシリアライズされ、metadataに格納されます。イメージcontentを置換するには、"image_mime_type"を"image/png"、"image/jpeg"または"image/webp"にする必要があります。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • timestamp str | None– レコードとともに保存するオプションの新しいタイムスタンプ。これは、レコードが作成された時間を表します。省略すると、既存のタイムスタンプが保持されます。Noneを渡して、保存されたタイムスタンプをクリアし、将来のTimeToLiveAnchor.CREATED_AT失効リフレッシュにデータベース作成時間を使用します。ttl_anchorがTimeToLiveAnchor.TIMESTAMPの場合、タイムゾーンなしのISO-8601タイムスタンプはUTCとして扱われます。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。現在の有効期限タイムスタンプを保持するには、ttl_anchorとともにこの引数を省略します。Noneを渡して、保存構成が1つ設定されているときにMemoryRetentionConfig.max_ttl_daysを使用するか、そうでない場合は有効期限をクリアします。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。失効を更新すると、失効したレコードがまだパージされていない場合に再度表示されることがあります。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。TimeToLiveAnchor.CREATED_ATを使用して、格納された作成時間からカウントするか、TimeToLiveAnchor.TIMESTAMPを使用して同じ更新で指定された置換timestampからカウントするか、またはtimestampが省略された格納されたイベント・タイムスタンプからカウントします。ttl_daysを指定しないでttl_anchorを指定すると、スキーマのMemoryRetentionConfig.default_ttl_daysを使用して有効期限がリフレッシュされます。リフレッシュ中にttl_anchorを省略すると、ストアはTimeToLiveAnchor.CREATED_ATを使用します。タイムスタンプ・アンカー・リフレッシュでは、同じコールの置換ISO-8601タイムスタンプ、またはその形式の既存の格納済イベント・タイムスタンプのいずれかが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • status RecordStatus– レコードの置換ライフサイクル・ステータス(オプション)。現在のステータスを保持するには、これを省略します。

  • text str | None–

    contentの非推奨の別名。Noneを渡して、格納されているテキストをクリアし、格納されている埋込みをクリアします。これをcontentとともに指定しないでください。

    非推奨

    バージョン26.8.0以降非推奨: このパラメータは26.8.0で非推奨になり、27.1で削除されます。かわりにcontentを使用してください。

• 戻り値:更新されたレコードの数(0または1)。戻り値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", content="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

method update_async (非同期)

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

• パラメータ:
  • record_type str– 更新するレコードの論理型。
  • record_id str– 更新するレコードの識別子。
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None– 標準的な置換コンテンツ。messageレコードの場合は、文字列または順序付けられた一連のテキストおよびイメージ・コンテンツ・パートを渡します。""を使用して、メッセージを空のテキストに置き換えます。メモリーに似たレコードの場合、ストアはNoneを受け入れて、格納されたテキストおよび関連するセマンティック状態をクリアできます。コンテンツを変更しないままにするには、引数を省略します。これをtextとともに指定しないでください。
  • index_text str | list[str] | None– 永続テキストを変更せずに、格納された検索状態を再計算または置換するために使用されるオプションの代替セマンティックペイロード。文字列はストアによって内部的にチャンク化される場合があります。空でない文字列のリストは、呼び出し元が所有するチャンクとして扱われ、再度分割することはできません。一部の実装では、これをハイブリッド検索テキストとして個別に永続化することもできます。imageレコードの場合、このフィールドは永続イメージの説明を置換します。
  • 埋込み list[float] | ndarray | list[list[float] | ndarray] | None– オプションの事前計算済埋込みベクトルまたはチャンク埋込みベクトルのリスト。指定した場合、これは直接使用され、埋込みコールは行われません。複数のベクトルでは、一致するindex_textチャンク・リストまたは既存の格納済チャンク・テキスト行が必要です。ストアがサポートする場合は、Noneを渡して、格納された埋込みを明示的にクリアします。テキスト対応索引付けのストアでは、埋込みや明示的な埋込みなしでのセマンティック更新も許可されます。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。ストアがサポートするときにメタデータをクリアするには、Noneを渡します。イメージcontentを置換するには、このマッピングに"image_mime_type"が必要です。ストアでは、このフィールドを使用してイメージが保存されますが、レコードのメタデータの一部として返されません。
  • timestamp str | None– レコードとともに保存するオプションの新しいタイムスタンプ。これは、レコードが作成された時期を表します。この引数を省略すると、格納されているタイムスタンプは変更されません。Noneを渡して、保存されたタイムスタンプをクリアし、ストアがサポートしているときにレコードがストアに追加された時刻を使用します。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。現在の有効期限タイムスタンプを保持するには、ttl_anchorとともにこの引数を省略します。Noneを渡して有効期限をクリアします。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。レコード作成時間にはTimeToLiveAnchor.CREATED_ATを、同じ更新で指定された置換timestampにはTimeToLiveAnchor.TIMESTAMPを、timestampを省略した場合は格納されたイベント・タイムスタンプを使用します。ttl_daysを指定せずにttl_anchorを指定すると、ストアまたはスキーマのデフォルトの存続期間が使用されます。リフレッシュ中にttl_anchorを省略すると、実装ではTimeToLiveAnchor.CREATED_ATが使用されます。
  • status RecordStatus– レコードの置換ライフサイクル・ステータス(オプション)。現在のステータスを保持するには、これを省略します。

  • text str | None–

    contentの非推奨の別名。ストアがサポートする場合は、Noneを渡して、格納されたテキストを明示的にクリアします。これをcontentとともに指定しないでください。

    非推奨

    バージョン26.8.0以降非推奨: このパラメータは26.8.0で非推奨になり、27.1で削除されます。かわりにcontentを使用してください。

• 戻り値:更新されたレコードの数(0または1)。戻り値0は、レコードが更新されなかったことを意味します。
• 戻り型: int
• Raises: ValueError– すべてのオプション・フィールドを省略したり、競合するセマンティック引数を指定したりするなど、更新ペイロードがストアに対して無効な場合。

メソッド update_relations

変更可能なリレーション・フィールドを更新し、エンドポイントのライフサイクル状態を再計算します。

省略されたフィールドは変更されません。組み込みのメモリーリンクラベルは、常に派生した逆ラベルを保持します。

• パラメータ:
  • relation_ids str | list[str]– 更新する関係の識別子または識別子。
  • relation_types str | list[str]– オプションの置換指示付きリレーション・ラベル。
  • opposite_relation_types str | list[str]– カスタム・タイプの代替リバース・ラベルまたはラベル(オプション)。
  • timestamps str | None | list[str | None]– オプションの置換タイムスタンプ。Noneを渡してクリアします。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションの置換メタデータ。既存のメタデータを置き換えます。
• 戻り値:更新されたリレーションの識別子。
• 戻り型: list[str]

例

store.update_relations("relation-id", relation_types="supports")
['relation-id']

method update_relations_async (非同期)

ストアドリレーションの可変値を非同期に更新します。

省略されたフィールドは変更されませんが、ビルトイン・メモリー・リレーション・タイプに変更すると、その逆ラベルが固定逆に置換されます。DBバック・メモリー・ストアでは、リレーション・タイプの変更後にエンドポイントのライフサイクル状態も再計算されます。

• パラメータ:
  • relation_ids str | list[str]– 更新する関係の識別子または識別子。
  • relation_types str | list[str]– オプションの置換指示付きリレーション・ラベル。格納されているラベルを保持するには、これを省略します。
  • opposite_relation_types str | list[str]– オプションの置換逆リレーションのラベルまたはラベル。ラベルを渡して置換するか、この引数を省略して保存します。
  • timestamps str | None | list[str | None]– オプションの置換タイムスタンプまたはタイムスタンプ。格納されているタイムスタンプをクリアするには、Noneを渡します。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– オプションの置換メタデータ・オブジェクト。指定されたメタデータは、格納されたオブジェクトを置き換えますが、マージされません。
• 戻り値:更新されたリレーションの識別子。
• 戻り型: list[str]

例

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

関係

OracleDBMemoryStoreは、メモリーに似たレコード(memory、fact、guidelineおよびpreference)間の有向リレーションを格納できます。統合で下位レベルのリレーションAPIが必要な場合は、add_relations()、get_relation()、list_relations()、update_relations()およびdelete_relations()を使用します。クライアントおよびスレッドAPIは、サポートされているメモリー・リレーション・タイプに対してlink_records()、update_record_link()およびdelete_record_link()を提供します。

1つのリレーションを取得するには、単独でrelation_idを指定するか、ソース・レコードIDとタイプ、ターゲット・レコードIDとタイプ、およびリレーション・タイプの完全なストアド・エンドポイント・タプルを指定します。部分タプルおよび任意のタプル・フィールドと組み合せたリレーションIDは、どちらも要求されたリレーションを明確に識別しないため無効です。

list_relations()を使用して、作成順序でリレーションを列挙します。ソースまたはターゲットのレコードIDおよびタイプ、または指示付きリレーション・ラベルでフィルタします。limit=Noneを渡さないかぎり、ストアの通常のセーフ・リスト制限が使用されます。そのmetadata_filterは、list()と同じ完全一致、ネストされたオブジェクト、配列メンバーシップおよび否定セマンティクスを使用します。metadata_filter=Noneを渡して、メタデータを持たないリレーションのみを返します。

ライフサイクル・リレーション・タイプ(supersedes、refinesおよびduplicates)は、リンクが存在する間、ターゲット・メモリーに無効なマークを付けます。最後のリンクを削除または変更すると、ターゲットが有効なステータスに復元されます。検索APIでは、include_invalid_results=Falseを使用して無効なレコードを除外できます。

クラス oracleagentmemory.apis.relations.RecordRelation

ベース: object

2つのレコード間の1つの格納および指示された関係の説明。

• パラメータ:
  • id str– リレーションの安定した識別子。
  • source_record_id str– リレーションの格納されたソースにあるレコードの識別子。
  • source_record_type str– ソース・レコードの論理型。
  • target_record_id str– リレーションの格納されたターゲットにあるレコードの識別子。
  • target_record_type str– ターゲット・レコードの論理型。
  • relation_type str– 格納されたソースからターゲットへの方向に続く意味を持つラベル。
  • opposite_relation_type str– トラバーサルがターゲットからソースに移動するときに使用されるラベル。
  • timestamp str | None– リレーションに関連付けられたオプションの呼び出し元タイムスタンプ。
  • metadata dict[str, Any] | None– リレーションとともに格納されるオプションのJSONに似たメタデータ。
  • created_at str– リレーションのデータベース作成タイムスタンプ。

検索戦略

クラス 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バックアップ・レコードのスキーマ・レベルの保存設定。

• パラメータ:
  • default_ttl_days int | None– デフォルトの存続時間(日数)。デフォルトのNone (最大値なし)を使用する場合は、NOT_SET_MARKERのままにします。
  • max_ttl_days int | None– オプションの最大存続時間(日数)。デフォルトのNoneを使用する場合は、NOT_SET_MARKERのままにします。最大値なしでNoneを渡します。設定されている場合、これはハード・キャップです。大きいttl_days値を使用しようとする書込みは、警告とともにこの最大値に固定され、ttl_days=Noneを渡す書込みAPIは、期限切れでないレコードを作成するのではなく、この最大値を使用します。

クラス oracleagentmemory.apis.ttl.TimeToLiveAnchor

ベース: Enum

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

CREATED_AT

レコードのデータベース作成タイムスタンプからの有効期限を計算します。これは、呼出し側がttl_anchorを省略した場合のデフォルトです。

TIMESTAMP

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

CREATED_AT = 'CREATED_AT'

タイムスタンプ = 'TIMESTAMP'

スキーマ・ポリシー

クラス oracleagentmemory.core.SchemaPolicy

ベース: str、Enum

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

存在が必要

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

空の作成

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

必要であれば作成

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

再作成する

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

チェックしない(_C)

管理対象スキーマの検証および作成をスキップします。このポリシーは、エンド・ユーザー・セキュリティ・コンテキストがアクティブなときに、既存のディープ・データ・セキュリティ保護されたストアに使用します。エンド・ユーザー・コンテキストで開かれたストアには、後続の各データベース操作に対してアクティブなコンテキストが必要です。スキーマ・ライフサイクルの作業は管理データベース・アイデンティティを介して実行する必要があるため、他のスキーマ・ポリシーはエンドユーザー・コンテキストを拒否します。