ストアおよびスキーマ

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

ストアAPI

クラス oracleagentmemory.core.OracleMemoryStore

ベース: IMemoryStore

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

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

メソッド add

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

• パラメータ:
  • contents list[str | None]– 永続化するペイロードを記録します。テキスト値は、index_textsまたはembeddingsが指定されていないかぎり、埋込みにも使用されます。テキスト値がNoneの場合、実装はmetadata["content"]にフォールバックする可能性があります。明示的な空の文字列は保持されます。
  • record_type str– 作成する論理レコード・タイプ(たとえば、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"または"agent_profile")。
  • index_texts list[str]– 埋込み/索引付けにのみ使用されるオプションの代替ペイロード。指定する場合は、テキスト入力と一致する必要があります。
  • 埋込み list[list[float]] | list[ndarray]– テキスト入力に合せたオプションの事前計算埋込みベクトル。指定した場合、ストアは埋込み機能を呼び出すのではなく、これらのベクトルを直接使用する必要があります。指定しない場合、ストアには埋込みがアタッチされている必要があります。そうしないと、エラーが発生します。
  • 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]– レコードとともに保持されるオプションのイベントタイムスタンプ。スカラー値は、整列されたテキスト入力間でブロードキャストできます。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None– オプションのコール元提供のメタデータ・ディクショナリ。明示的に""に設定するのではなく、テキスト値を省略した場合、メタデータにはフォールバック・ソースとして"content"を含めることができます。
  • **store_kwargs (Any)– 具象ストアに転送される実装固有の書き込みオプション。
• 戻り型: list[str]

ノート:

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

• 戻り値:入力と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: List[str]
• パラメータ:
  • コンテンツ list[str | None]
  • record_type str
  • index_texts list[str]
  • 埋込み list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_agent (抽象)

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

• パラメータ:
  • agent_id str– エージェントプロファイルの安定した識別子。
  • information str– エージェントを説明する自由形式のテキスト。
• 戻り値:作成されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

method add_async (非同期)

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

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

• パラメータ:
  • コンテンツ list[str | None]
  • record_type str
  • index_texts list[str]
  • 埋込み list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• 戻り型: list[str]

メソッド add_batches

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

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

例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_user (抽象)

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

• パラメータ:
  • user_id str– ユーザープロファイルの安定した識別子。
  • information str– ユーザーを説明する自由形式のテキスト。
• 戻り値:作成されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

method delete (抽象)

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

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

method delete_thread (抽象)

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

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

ノート:

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

method get (抽象)

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

• パラメータ:
  • record_type str– 取得するレコードの論理型。
  • record_id str– 取得するレコードの識別子。
• 戻り値:格納されたレコードが見つかった場合、それ以外の場合はNone。
• 戻りタイプ: レコード |なし

method list (抽象)

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

• パラメータ:
  • record_type str– 列挙する論理レコードタイプ。
  • limit int | None– 返される最新のレコードの最大数(オプション)。省略すると、実装はMAX_LIST_LIMITなどの安全な上限を適用できます。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • user_id str | None– 正確なユーザースコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、user_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • agent_id str | None– 正確なエージェントスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、agent_idがNoneのレコードのみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
• 戻り値:返されたウィンドウ内で最も古いものから新しいものの順に並べられたレコード。
• 戻りタイプ: List[Record]

method list_thread_messages (抽象)

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

• パラメータ:
  • thread_id str– メッセージが返されるスレッドの識別子。
  • last_n int | None– 含める最新のメッセージの数(オプション)。省略すると、スレッドの格納されているすべてのメッセージが返されます。
• 戻り値:返されるウィンドウ内で最も古いものから新しいものの順に並べられたメッセージ・レコード。
• 戻り型: List[MessageRecord]

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

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で受け入れられるオプションのレコードタイプフィルタと同じです。
• 戻り値:基礎となるsearchコールによって戻される(record, distance)ペア。
• 戻り型: List[tuple[Record、 float]]
• Raises: ValueError– kが1未満の場合。

method update (抽象)

保存されたレコード・コンテンツの更新、データの埋込みまたはメタデータの更新。

• パラメータ:
  • record_type str– 更新するレコードの論理型。
  • record_id str– 更新するレコードの識別子。
  • text str | None– オプションの置換コンテンツ。ストアがサポートする場合は、Noneを渡して、格納されたテキストを明示的にクリアします。ストアは、関連するセマンティク状態をクリアし、同じコールで競合するnull以外のindex_textまたはembedding更新を拒否することもできます。コンテンツを変更しないままにするには、引数を省略します。
  • index_text str | None– 永続テキストを変更せずに、格納されたベクトルを再計算するために使用されるオプションの埋込み専用ペイロード。
  • 埋込み list[float] | ndarray | None– オプションの事前計算済埋込みベクトル。指定した場合、これは直接使用され、埋込みコールは行われません。ストアがサポートする場合は、Noneを渡して、格納された埋込みを明示的にクリアします。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。ストアがサポートするときにメタデータをクリアするには、Noneを渡します。
• 戻り値:更新されたレコードの数(通常は0または1)。要求された論理識別子と一致する格納済レコードがない場合、0を返します。
• 戻り型: int
• Raises: ValueError– すべてのオプション・フィールドを省略したり、競合するセマンティック引数を指定したりするなど、更新ペイロードがストアに対して無効な場合。

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の場合、実装はmetadata["content"]にフォールバックする可能性があります。明示的な空の文字列は保持されます。
  • record_type str– 作成する論理レコード・タイプ(たとえば、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"または"agent_profile")。
  • index_texts list[str]– 埋込み/索引付けにのみ使用されるオプションの代替ペイロード。指定する場合は、テキスト入力と一致する必要があります。
  • 埋込み list[list[float]] | list[ndarray]– テキスト入力に合せたオプションの事前計算埋込みベクトル。指定した場合、ストアは埋込み機能を呼び出すのではなく、これらのベクトルを直接使用する必要があります。指定しない場合、ストアには埋込みがアタッチされている必要があります。そうしないと、エラーが発生します。
  • 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]– レコードとともに保持されるオプションのイベントタイムスタンプ。スカラー値は、整列されたテキスト入力間でブロードキャストできます。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None– オプションのコール元提供のメタデータ・ディクショナリ。明示的に""に設定するのではなく、テキスト値を省略した場合、メタデータにはフォールバック・ソースとして"content"を含めることができます。
  • **store_kwargs (Any)– 具象ストアに転送される実装固有の書き込みオプション。
• 戻り型: list[str]

ノート:

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

• 戻り値:入力と同じ論理的な順序で挿入されたレコードの識別子。
• 戻り型: List[str]
• パラメータ:
  • コンテンツ list[str | None]
  • record_type str
  • index_texts list[str]
  • 埋込み list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_async (非同期)

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

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

• パラメータ:
  • コンテンツ list[str | None]
  • record_type str
  • index_texts list[str]
  • 埋込み list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• 戻り型: list[str]

メソッド add_batches

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

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

例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_agent

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

• パラメータ:
  • agent_id str– エージェント識別子。
  • information str– エージェントに関するフリーフォーム情報。このテキストはプロファイル・コンテンツとして格納され、RECORD_CHUNKSにプロファイル埋込み行を作成するために使用されます。
• 戻り値:挿入されたエージェント・プロファイル・レコードの識別子。
• 戻り型: str

ノート:

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

例

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

メソッド add_user

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

• パラメータ:
  • user_id str– ユーザー識別子。
  • information str– ユーザーに関する自由形式の情報。このテキストはプロファイル・コンテンツとして格納され、RECORD_CHUNKSにプロファイル埋込み行を作成するために使用されます。
• 戻り値:挿入されたユーザー・プロファイル・レコードの識別子。
• 戻り型: str

ノート:

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

例

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

メソッド delete

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

• パラメータ:
  • record_type str– 削除するレコードタイプラベル。サポートされているタイプには、"thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"および"agent_profile"があります。
  • 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

メソッド delete_thread

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

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

ノート:

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

例

store.delete_thread("c1")
0

メソッド get

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

• パラメータ:
  • record_type str– 管理対象行に解決されるレコード・タイプ・ラベル("message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile"など)。
  • 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"、"user_profile"、または "agent_profile")。
  • limit int | None– 返されるレコードの最大数(オプション)。省略すると、ストアはデフォルトのリスト上限を使用します。Noneを渡して、その上限を無効にし、一致するすべてのレコードを返します。
  • thread_id str | None– 正確なスレッドスコープフィルタ。省略した場合、フィルタリングは適用されません。Noneに設定すると、thread_idがSQL NULLの行のみが返されます。スコープなしレコードの種類では、このフィルターは無視されます。
  • 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に設定した場合、格納されるメタデータには、要求されたすべての鍵と値が含まれている必要があります。ネストされたディクショナリは再帰的に照合されます。リスト値は、再帰的なサブセットの一致ではなく、正確な等価性によって照合されるため、リストの順序と長さも一致する必要があります。
• 戻り値:挿入順序で並べられたレコード。
• 戻りタイプ: list[レコード]

ノート:

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

例

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

メソッド list_thread_messages

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

• パラメータ:
  • 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– 含める検索可能なレコードタイプのオプションセット。省略すると、DB検索ではメッセージ、メモリー表の行およびアクター・プロファイルが対象になります。Actorプロファイルはinformationペイロードを寄与しますが、メッセージ行とメモリー行はcontentペイロードを寄与します。検索中、プロファイル・レコード・タイプは適用可能なスコープ・ディメンションのアクター識別子を使用し、残りのスコープ・ディメンションは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

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で受け入れられるオプションのレコードタイプフィルタと同じです。
• 戻り値:基礎となる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– 更新する格納された行の識別子。
  • 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オブジェクトを作成または変更しないでください。

空の作成

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

必要であれば作成

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

再作成する

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