商店與綱要

此頁面顯示 Oracle 代理程式記憶體 SDK 使用的核心存放區摘要和綱要控制項。

儲存 API

商店寫入語意

儲存庫寫入會在應用程式儲存的文字與儲存用於擷取的有效負載之間保留明確的分隔。大多數應用程式都可以使用記憶體層級和執行緒層級的 API，並讓存放區準備進行向量、關鍵字或混合擷取所需的搜尋資料列。低階存放區 API 會顯示 index_texts、index_text、embeddings 和 embedding，以供已知道應使用哪些文字或向量進行擷取的進階整合使用。

將每一個部份寫成兩個相關部份：

add() 中的 contents 和 update() 中的 text 控制 get()、list() 和搜尋結果所傳回的預存記錄文字。
add() 中的 index_texts 和 update() 中的 index_text 控制寫入存放區擷取資料列的文字。搜尋會使用這些資料列，然後傳回原始邏輯記錄。

如果未提供搜尋置換或明確內嵌，則存放區會使用解析的儲存文字作為擷取文字。設定分區時，商店會分區非空白文字。空白文字會儲存記錄文字，但不會提供擷取文字。

下表說明在考慮明確向量有效負載之前，如何選擇擷取文字。

儲存層次擷取有效負載

輸入項	add()	個更新()
省略 `index_texts` 或 `index_text`	每筆記錄都會使用解析的 `contents` 值進行擷取。	取代的 `text` 值會用於擷取。如果也省略 `text`，則僅內嵌更新會重複使用記錄的現有擷取文字資料列。
字串 `index_texts` 項目或字串 `index_text`	此字串會取代該記錄的擷取文字。寫入擷取列之前，商店可以將其分塊。	此字串會取代該記錄的擷取文字。寫入擷取列之前，商店可以將其分塊。
`list[str]` `index_texts` 項目或 `list[str]` `index_text`	此清單會被視為呼叫者擁有的區塊。每個非空白字串都會寫入為一個擷取列，且商店不會再次分區。	此清單會被視為呼叫者擁有的區塊。每個非空白字串都會寫入為一個擷取列，且商店不會再次分區。
`None` `index_texts` 項目或 `index_text=None`	外部 `index_texts` 清單中的 `None` 表示「使用此記錄的預存內容」。	除非同時提供 `text`，否則 `index_text=None` 會在未變更儲存文字時清除擷取資料列。
空白字串或空白區塊清單	儲存記錄文字，且不提供該記錄的擷取文字。	在提供 `text` 時更新記錄文字，並清除該記錄的擷取文字。

明確內嵌是選擇性的。省略時，當設定本機向量儲存時，存放區會從擷取文字衍生本機向量；關鍵字或混合存放區也可以使用純文字擷取資料列。提供明確的 embeddings 或 embedding 值時，存放區會直接寫入這些向量，而不會為這些向量呼叫其內嵌器。

在 add() 中，embeddings=None 的行為類似於省略 embeddings。在 update() 中，embedding=None 是明確的：存放區會根據 text 和 index_text 保留或重寫擷取文字，但會儲存沒有本機向量的資料列。如果同時省略 text 和 index_text，就會清除現有擷取列中的向量。

向量形狀告訴商店，來電者所採取的區塊所有權是多少：

一個向量表示整個檢索文字的一個向量。商店不會分割該明確向量的文字。如果該檢索文字是空的，則可以在沒有伴隨區塊文字的情況下儲存向量。
多個向量是每個呼叫者擁有的區塊一個向量。提供相符的 index_texts 或 index_text 區塊清單，或使用僅內嵌的 update() 來重複使用記錄的現有擷取文字資料列。
向量計數必須與區塊計數相符，且一個 add() 呼叫中的所有明確向量必須具有相同維度。
只有在沒有擷取文字資料列與其對齊時，才允許空白的每個記錄向量有效負載。

某些組合被拒絕，因此儲存的文字、擷取文字和向量不會偏差。傳送 text=None 會清除儲存的文字和擷取資料列，因此無法與非空值的 index_text 或 embedding 值合併；動作者設定檔記錄不支援 text=None。在 update() 中傳送 index_text=None 表示「清除擷取資料列」，因此在相同的呼叫中不允許非空白的明確內嵌。多個明確的向量需要明確的區塊文字，除非更新是僅內嵌的，且現有的擷取列已提供區塊文字。

類別 `oracleagentmemory.core.OracleMemoryStore`

基本：IMemoryStore

OracleAgentMemory 使用的通用儲存介面。

商店實施負責保存文字記錄，並對其執行相似性搜尋。同時定義了同步和非同步進入點，因此高階 API 可以公開相符的同步 / 非同步曲面，而不需要複製儲存特定邏輯。

方法 `add`

新增記錄至商店。

參數：
- contents list[str | None] – 記錄要保存的有效負載 (Payload)。除非提供 index_texts 或 embeddings，否則文字值也用於語意索引。當文字值為 None 時，實作可能會轉為 metadata["content"]。系統會保留明確的空白字串。
- record_type str – 要建立的邏輯記錄類型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"。
- index_texts list[str | list[str] | None] – 僅用於語意索引的選擇性替代有效負載。如果提供，外部清單必須與文字輸入對齊。每個項目可以是字串，商店可能會在內部分區，或是非空白字串的清單，商店會將其視為來電者擁有的區塊，且不得再次分割。
- embeddings 金紗夢婚禮 list[list[float] | ndarray | list[list[float] | ndarray]] – 可選預先計算與文字輸入對齊的嵌入向量。每個記錄項目可以是該記錄的一個嵌入向量或區塊嵌入向量的清單。如果提供，商店必須直接使用這些向量，而不是叫用其嵌入器。一筆記錄的多個向量需要相符的 index_texts 區塊清單，因此文字和向量區塊界限是明確的。如果未提供，存放區通常會從設定的內嵌程式衍生語意狀態，但實作特定的文字感知索引模式也可能允許只寫入文字，而不需要寫入文字。
- 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] – 選擇性訊息角色，例如 "user" 或 "assistant"。定量值可以跨對齊的文字輸入廣播。僅在 record_type 為 "message" 時使用。
- 時間戳記 str | None | list[str | None] – 隨記錄一起儲存的選擇性時間戳記。每個時戳代表記錄的建立時間。定量值可以跨對齊的文字輸入廣播。省略或 None 項目使用目前的時間。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性呼叫程式提供的中繼資料字典。當省略文字值而非明確設定為 "" 時，描述資料可以包含 "content" 作為後援來源。
- ttl_days int | None | list[int | None] – 支援到期之記錄的選擇性存留時間持續時間 (天)。省略此引數以使用存放區預設值。針對不應到期的記錄，傳送 None。定量值可以跨對齊的文字輸入廣播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 將相對於儲存的建立時間到期，或相對於每個記錄的事件時間戳記，使用 TimeToLiveAnchor.TIMESTAMP 將到期。省略時，實作會使用 TimeToLiveAnchor.CREATED_AT。
- **store_kwargs ( 任一 ) – 轉送至具體存放區的實行特定寫入選項。
傳回類型： list[str]

注意事項

當呼叫程式已經有一或多個 PendingRecordBatch 物件時，請使用 add_batches()。

傳回：插入之記錄的識別碼，其邏輯順序與輸入相同。
傳回類型： List[str]
參數：
- 內容 list[str | None]
- 記錄類型 str
- 索引相關資訊環境 list[str | list[str] | None]
- 婚禮 list[list[float] | ndarray | list[list[float] | ndarray]]
- 記錄 ID str | None | list[str | None]
- thread_ids str | None | list[str | None]
- user_idsstr | None | list[str | None]
- 代理程式 ID 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]
- store_kwargs Any

方法 `add_agent` (摘要)

新增專員資料檔記錄。

參數：
- agent_id str – 代理程式設定檔的穩定 ID。
- 資訊 str – 描述代理程式的任意格式文字。
- 中繼資料 dict[str, Any] | None – 儲存在代理程式設定檔資料列上的選擇性中繼資料對應。
傳回：所建立專員資料檔記錄的識別碼。
傳回類型： str

方法 `add_async` (非同步)

以非同步方式將資料列導向的記錄新增至商店。

接受相同的引數，並傳回與 add() 相同的識別碼。

參數：
- 內容 list[str | None]
- 記錄類型 str
- 索引相關資訊環境 list[str | list[str] | None]
- 婚禮 list[list[float] | ndarray | list[list[float] | ndarray]]
- 記錄 ID str | None | list[str | None]
- thread_ids str | None | list[str | None]
- user_idsstr | None | list[str | None]
- 代理程式 ID 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]
- store_kwargs Any
傳回類型： list[str]

方法 `add_batches`

新增來電者準備的邏輯批次至商店。

參數：
- 批次 list[PendingRecordBatch] – 要保存的完整已準備邏輯批次。每個批次都應有自己的每個記錄欄位，例如 record_type、範圍值、角色、時間戳記和中繼資料。
- **store_kwargs ( 任一 ) – 轉送至具體存放區的實行特定寫入選項。
傳回：插入之記錄的識別碼，與輸入批次和資料列的邏輯順序相同。
傳回類型： List[str]

範例

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

方法 `add_batches_async` (非同步)

以非同步方式將呼叫器準備的邏輯批次新增至存放區。

接受相同的引數，並傳回與 add_batches() 相同的識別碼。

參數：
- 批次 list[PendingRecordBatch]
- store_kwargs Any
傳回類型： list[str]

方法 `add_user` (摘要)

新增使用者基本資料記錄。

參數：
- user_id str – 使用者設定檔的穩定識別碼。
- 資訊 str – 描述使用者的任意格式文字。
- 中繼資料 dict[str, Any] | None – 儲存在使用者設定檔資料列上的選擇性中繼資料對應。
傳回：所建立使用者資料檔記錄的識別碼。
傳回類型： str

方法 `delete` (摘要)

依識別碼刪除一筆儲存的記錄。

參數：
- record_type str – 要移除之記錄的邏輯類型。
- record_id str – 要移除之記錄的識別碼。
- cascade bool – 若為 True，請在相同刪除作業中對要求的最上層目標套用任何儲存支援的層疊刪除行為。這主要用於目標，例如擁有額外範圍記錄的動作者設定檔。例如，使用者設定檔或代理程式設定檔連鎖可能會刪除擁有的繫線本身、繫線作用領域的訊息和類似記憶體的記錄，以及任何剩餘的直接作用者作用領域記錄 (例如訊息、記憶體、準則、事實或偏好設定)。針對動作者設定檔刪除，當缺少相符的資料檔資料列時，仍會執行此作用領域清除。
傳回：刪除的要求最上層記錄數目，通常為 0 或 1。串連的子項資料列不會個別計算，因此當遺漏的動作者設定檔觸發範圍清除時，這仍可能是 0。
傳回類型：整數

方法 `delete_thread` (摘要)

刪除執行緒及其關聯的預存資料。

參數： thread_id str – 要移除之繫線的 ID。
傳回：已刪除的繫線記錄數目，通常是 0 或 1。
傳回類型：整數

注意事項

這是儲存層次作業，用於移除商店所管理的執行緒與執行緒作用領域記錄。保留需求呼叫刪除來源訊息和衍生繫線作用領域記憶體資料時，偏好刪除繫線，因為訊息層次刪除並不表示會移除個別保存的衍生記錄。

方法 `get` (摘要)

依類型與識別碼擷取一筆儲存的記錄。

參數：
- record_type str – 要擷取之記錄的邏輯類型。
- record_id str – 要擷取之記錄的識別碼。
傳回：找到儲存的記錄，否則為 None。
傳回類型： 記錄 | 無

方法 `list` (摘要)

列出一個記錄類型的已儲存記錄。

參數：
- 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 的記錄。未限制範圍的記錄類型會忽略此篩選。
- metadata_filter dict[str, Any] | None –
  
  中繼資料篩選。省略時，不會套用任何篩選。設為 None 時，只會傳回中繼資料為 None 的記錄。設定為字典時，metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的描述資料中。巢狀字典會遞迴比對。定量與清單值會完全符合；清單順序與長度也必須相符。若要測試陣列成員身分，請使用欄位層級運算子字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的清單運算元表示必須要有所有列出的值；"$array_contains_any" 表示必須至少有一個列出的值。使用 "$not" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。範例包括純量欄位的 metadata_filter={"source": "slack"}、巢狀欄位的 metadata_filter={"review": {"status": "open"}}，以及完全相符的清單 metadata_filter={"tags": ["prod", "urgent"]}。結合條件以要求所有條件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
傳回：在傳回視窗中從最舊到最新排序的記錄。
傳回類型： List[ 記錄 ]

方法 `list_thread_messages` (摘要)

列出一個執行緒中儲存的訊息歷史記錄。

參數：
- thread_id str – 應傳回其訊息之繫線的 ID。
- last_n int | None – 要包含之最新訊息的選擇性數目。省略時，會傳回執行緒所有儲存的訊息。
傳回：在傳回視窗中從最舊到最新排序的訊息記錄。
傳回類型： List[ MessageRecord ]

方法 `search` (摘要)

依相似性搜尋記錄。

參數：
- 查詢 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" 表示必須至少有一個列出的值。使用 "$not" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。
傳回：以增加距離排序的 (record, distance) 組。清單可能包含少於 k 個項目。
傳回類型： list[tuple[ 記錄，浮動 ]]
發出：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

描述資料陣列包含值時進行篩選：

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

方法 `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 – search 接受的選擇性描述資料篩選相同，包括純量、巢狀、精確清單、陣列成員身分，以及 {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]} 和 {"tags": {"$array_contains": "prod"}} 等組合條件。
傳回：基礎 search 呼叫傳回的 (record, distance) 組。
傳回類型： List[tuple[ 記錄，浮點數 ]]
發出：ValueError – 如果 k 小於 1。

方法 `update` (摘要)

更新儲存的記錄內容、嵌入資料、中繼資料、時間戳記或到期。

參數：
- record_type str – 要更新之記錄的邏輯類型。
- record_id str – 要更新之記錄的識別碼。
- 文字 str | None – 選擇性取代內容。傳遞 None 以在存放區支援時明確清除儲存的文字。商店也可以清除關聯的語意狀態，並拒絕相同呼叫中發生衝突的非空值 index_text 或 embedding 更新。忽略引數讓內容維持不變。
- index_text str | list[str] | None – 可選替代語意有效負載 (Payload)，用於重新計算或取代儲存的搜尋狀態，而不變更保存的文字。字串可以由商店內部分區。將非空白字串清單視為來電者擁有的區塊，且不得再次分割。有些實作也可以將此分別保存為混合搜尋文字。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None – 可選的預先計算嵌入向量或區塊嵌入向量清單。提供時，會直接使用，不會呼叫內嵌程式。多個向量需要相符的 index_text 區塊清單或現有的儲存區塊文字資料列。傳送 None，在商店支援時明確清除儲存的內嵌。具有文字感知索引的商店也可以允許沒有內嵌或明確內嵌的語意更新。
- 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。傳送 None 以在存放區支援時清除描述資料。
- timestamp str | None – 隨記錄一起儲存的選擇性新時戳。它代表記錄的建立時間。忽略此引數，讓儲存的時間戳記維持不變。傳送 None 以清除儲存的時間戳記，並使用商店支援時將記錄新增至商店的時間。
- ttl_days int | None – 選擇性到期重新整理 (天)。將此引數與 ttl_anchor 一起省略，以保留目前的到期時戳。傳送 None 以清除過期。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為記錄建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用存放區或綱要預設存留時間持續時間。在重新整理期間省略 ttl_anchor 時，實行會使用 TimeToLiveAnchor.CREATED_AT。
傳回數：更新的記錄數，通常是 0 或 1。當沒有儲存的記錄符合要求的邏輯識別碼時，傳回 0。
傳回類型：整數
發出：ValueError - 如果存放區的更新有效負載無效，例如省略每個選擇性欄位或提供衝突的語意引數。

Oracle DB 商店

類別 `oracleagentmemory.core.OracleDBMemoryStore`

基本：OracleMemoryStore

訊息、記憶體和動作者設定檔的資料庫備份保存。

建立 Oracle DB 存放區。

參數：
- embedder IEmbedder | None – 商店需要內嵌本機向量時使用的內嵌程式。當呼叫程式一律提供預先計算的向量，或當關鍵字搜尋與純文字寫入及文字查詢搭配使用時，可以是 None。SearchStrategy.HYBRID 在此需要 OracleDBEmbedder，因此受管理的混合索引可以使用此內嵌器的資料庫內模型。
- pool Any – Oracle DB 連線或集區。傳送原始連線可啟用此商店實例的單一階段作業模式：並行商店呼叫會在本機進行序列化，以保留寫入作業所使用的資料列鎖定與交易假設。針對並行要求使用連線集區。
- schema_policy SchemaPolicy | str – 綱要設定模式。預設為需要現有且最新的受管理綱要，且不執行 DDL 變更。使用 SchemaPolicy.CREATE_IF_NECESSARY 來填入遺漏的物件，或使用 SchemaPolicy.RECREATE 來刪除及重新建立受管理物件。SchemaPolicy.CREATE_IF_NECESSARY 可以套用支援的受管理綱要版本升級、可以透過新增文字索引來升級向量綱要以進行關鍵字搜尋，或透過新增受管理搜尋結構和混合索引來進行混合搜尋。
- vector_dim int | None – 本機向量儲存的選擇性內嵌維度。傳送正整數以建立受管理的內嵌資料欄和向量索引，並根據該維度驗證現有的綱要描述資料。如果此存放區不需要本機向量儲存，請傳送 None 或省略引數。關鍵字與混合搜尋可以從已儲存的搜尋文字進行作業，而不需要本機內嵌資料欄。向量搜尋需要本機向量儲存。
- table_name_prefix str –
  
  新增至受管理表格 / 索引名稱的選擇性前置碼。傳送此項目或 memory_store_id，但不可同時傳送兩者。
  
  注意：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_store_id。
- memory_store_id str – 受管理資料庫記憶體存放區的穩定 ID。重複使用相同的 ID 來重新開啟相同的受管理商店。ID 會以底線結合至受管理資料庫物件名稱，因此必須以字母為開頭、僅包含字母、數字及底線，且最多 16 個字元。傳送此項目或 table_name_prefix，但不可同時傳送兩者。如果省略，當同時省略 table_name_prefix 時，存放區會使用 table_name_prefix 或前綴的預設值。
- search_strategy SearchStrategy – 選取 search() 後端的 SearchStrategy 值。使用 SearchStrategy.VECTOR (預設) 進行僅限向量擷取，使用 SearchStrategy.HYBRID 在預存搜尋文字上查詢受管理的 Oracle 混合向量索引，或使用 SearchStrategy.KEYWORD 在預存搜尋文字上依關鍵字 / 文字比對進行排名 (不含向量融合)。KEYWORD 不需要內嵌程式。HYBRID 需要 embedder 作為 OracleDBEmbedder，因此受管理的混合索引使用與主要儲存庫內嵌程式相同的資料庫內模型。如果關鍵字從屬端開啟現有的混合綱要，則存放區可以使用該混合索引的文字分支。現有綱要使用不相容的策略時，啟動會失敗，因為該綱要可能未包含策略所需的預存搜尋狀態。
- search_index_sync SearchIndexSyncMode – SearchIndexSyncMode 值，可選取 SearchStrategy.HYBRID 和 SearchStrategy.KEYWORD 的受管理搜尋索引重新整理行為。SearchIndexSyncMode.ON_COMMIT 是預設值，可在寫入交易確認後立即搜尋記錄。SearchIndexSyncMode.MANUAL 會將重新整理留給明確的資料庫端同步作業。SearchIndexSyncMode.AUTO 可讓 Oracle 以非同步方式重新整理受管理混合索引，且僅支援 SearchStrategy.HYBRID；關鍵字搜尋拒絕 AUTO。
- memory_retention_config MemoryRetentionConfig – 資料庫備份訊息和記憶體的選擇性記憶體保留組態。當新的寫入省略 ttl_days 時，會使用 MemoryRetentionConfig.default_ttl_days。MemoryRetentionConfig.max_ttl_days 會將明確的每筆記錄持續時間固定在設定的最大值上方，並加上警告。設定時，ttl_days=None 會使用該最大值，而不是建立非到期的資料列。使用 SchemaPolicy.CREATE_IF_NECESSARY 時，明確的組態會重新整理現有最新受管理綱要上儲存的中繼資料，但不會更新現有的到期日；省略時會保留現有的設定。如果明確組態在 NOT_SET_MARKER 留下 default_ttl_days 或 max_ttl_days，則 SDK 會先將該屬性解析為其預設值 (None)，再比較或儲存綱要描述資料。根據儲存在記錄中的預期資訊、應用程式保留的原因，以及任何應用程式或管制保留承諾來選擇此組態。

警告：SchemaPolicy.CREATE_IF_NECESSARY 可能比一般存放區啟動更為昂貴，因為在初始化成功之前，它可能會套用受管理的綱要 DDL 和最佳效果資料重寫。當該綱要可能包含許多資料列時，計畫第一個開啟的舊受管理綱要作為移轉或維護作業。

如果綱要設定必須建立受管理過期記錄永久清除工作，但資料庫使用者缺乏 Scheduler-job 權限，初始化會警告並繼續。已過期的訊息和記憶體會保持隱藏，無法讀取和搜尋，但要等到工作由具備 CREATE JOB 或同等排程器權限的使用者建立後，才會實際將它們整個清除。

SchemaPolicy.CREATE_IF_NECESSARY 先透過現有綱要建立受管理的混合索引時，Oracle 會掃描儲存的搜尋文字，並從設定的資料庫內模型建立受管理的混合索引狀態。儲存初始化等待該 DDL 完成，因此計畫第一個混合式升級作為大型綱要的移轉或維護作業。SearchIndexSyncMode 控制索引存在之後的進行中維護；它不會使第一個索引建立成為非同步。

建立該受管理的混合索引也會建立由受管理綱要命名的 DBMS_VECTOR_CHAIN 向量設定程式偏好設定。此偏好設定會儲存已設定 OracleDBEmbedder 模型的輕量型向量化程式組態中繼資料。可以使用 Oracle Text 偏好設定檢視 (例如 CTX_USER_PREFERENCES 和 CTX_USER_PREFERENCE_VALUES) 進行檢查。

方法 `add`

新增記錄至 Oracle DB 商店。

參數：
- contents list[str | None] – 記錄要保存的有效負載 (Payload)。除非提供 index_texts，否則文字值也會用於搜尋文字。當文字值為 None 時，商店可能會轉為 metadata["content"]。系統會保留明確的空白字串。
- record_type str – 要建立的邏輯記錄類型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"。
- index_texts list[str | list[str] | None] – 作為搜尋文字的選擇性替代有效負載。您可以使用此選項來控制資料庫備份的關鍵字或混合搜尋索引。每個外部清單項目都會與一筆記錄對齊。字串項目可以由商店分區。清單項目會被視為呼叫者擁有的區塊，並依原樣寫入 RECORD_CHUNKS.chunk_text。同時提供 embeddings 時，清單項目每一區塊只需要一個向量；字串項目只接受該記錄的單一向量。
- 婚禮 list[list[float] | ndarray | list[list[float] | ndarray]] –
  
  可選的預先計算嵌入向量與 contents 對齊。每個記錄項目可以是一個向量或分區向量清單。設定本機向量儲存時，這些向量會直接儲存為記錄的向量表示法，而不是呼叫商店的嵌入器來建立寫入的本機向量。單一向量表示整個語意文字，即使已設定的區塊會分割它。多個區塊向量需要相符的 index_texts 區塊清單。
  
  在 SearchStrategy.VECTOR 中，向量搜尋會對照儲存的向量進行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，資料庫備份搜尋會透過預存搜尋文字和 Oracle 管理的文字或混合索引狀態排名，因此附加時間內嵌只會影響任何已設定的本機向量儲存，而不會影響該作用中搜尋策略。如果此儲存設定沒有本機向量儲存，請提供 index_texts 而非 embeddings 以覆寫那些文字感知索引可見的文字。
- record_ids str | None | list[str | None] – 可選的呼叫者顯示識別碼。單一字串可用於單一記錄插入，而清單必須與 contents 一致。省略此欄位時會傳回產生的識別碼。
- 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] – 選擇性訊息角色，例如 "user" 或 "assistant"。僅在 record_type 為 "message" 時使用。
- 時間戳記 str | None | list[str | None] – 隨記錄一起儲存的選擇性時間戳記。每個時戳代表記錄的建立時間。定量值可以跨對齊的輸入廣播。省略或 None 項目會取消設定事件時戳。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，每個受影響的記錄都必須有具體的 ISO-8601 時間戳記值。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性中繼資料字典。當省略文字值而非設為 "" 時，描述資料可以包含 "content" 作為後援來源。
- ttl_days int | None | list[int | None] – 選用訊息和類似記憶體之記錄的存留時間持續時間 (天)。省略此引數以使用受管理綱要中的 MemoryRetentionConfig.default_ttl_days。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to create a non-expiring record when it does not. 超過 MemoryRetentionConfig.max_ttl_days 的值會固定至該上限，但有警告。定量值可以跨對齊的輸入廣播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 將相對於資料庫建立時間的到期，或相對於提供的事件時戳，使用 TimeToLiveAnchor.TIMESTAMP 將到期。省略時，到期會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定過期對每個插入的記錄都需要具體的 ISO-8601 時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **store_kwargs ( 任一 ) – 資料庫寫入選項。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 – 代理程式 ID。
- 資訊 str – 代理程式的任意格式資訊。此文字會儲存為基本資料內容，並用於建立基本資料的可搜尋表示法。
- 中繼資料 dict[str, Any] | None – 儲存在代理程式設定檔資料列上的選擇性中繼資料對應。
傳回：插入的專員資料檔記錄的識別碼。
傳回類型： str

注意事項

專員資料檔記錄未作用領域。插入的公用記錄 ID 與傳送為 agent_id 的值相同。

範例

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

方法 `add_async` (非同步)

以非同步方式將資料列導向的記錄新增至商店。

接受相同的引數，並傳回與 add() 相同的識別碼。

參數：
- 內容 list[str | None]
- 記錄類型 str
- 索引相關資訊環境 list[str | list[str] | None]
- 婚禮 list[list[float] | ndarray | list[list[float] | ndarray]]
- 記錄 ID str | None | list[str | None]
- thread_ids str | None | list[str | None]
- user_idsstr | None | list[str | None]
- 代理程式 ID 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]
- store_kwargs Any
傳回類型： list[str]

方法 `add_batches`

新增來電者準備的邏輯批次至商店。

參數：
- 批次 list[PendingRecordBatch] – 要保存的完整已準備邏輯批次。每個批次都應有自己的每個記錄欄位，例如 record_type、範圍值、角色、時間戳記和中繼資料。
- **store_kwargs ( 任一 ) – 轉送至具體存放區的實行特定寫入選項。
傳回：插入之記錄的識別碼，與輸入批次和資料列的邏輯順序相同。
傳回類型： List[str]

範例

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

方法 `add_batches_async` (非同步)

以非同步方式將呼叫器準備的邏輯批次新增至存放區。

接受相同的引數，並傳回與 add_batches() 相同的識別碼。

參數：
- 批次 list[PendingRecordBatch]
- store_kwargs Any
傳回類型： list[str]

方法 `add_user`

新增使用者基本資料記錄。

參數：
- user_id str – 使用者 ID。
- 資訊 str – 使用者的任意格式資訊。此文字會儲存為基本資料內容，並用於建立基本資料的可搜尋表示法。
- 中繼資料 dict[str, Any] | None – 儲存在使用者設定檔資料列上的選擇性中繼資料對應。
傳回：插入之使用者設定檔記錄的識別碼。
傳回類型： str

注意事項

使用者資料檔記錄未作用領域。插入的公用記錄 ID 與傳送為 user_id 的值相同。

範例

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

方法 `delete`

依 ID 刪除一個受管理資料列及其區塊資料列。

參數：
- record_type str – 要刪除的記錄類型標籤。支援的類型包括 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 和 "agent_profile"。
- record_id str – 要刪除的識別碼。
- cascade bool – 當 True 時，將支援的最上層目標 (例如動作者設定檔) 展開至相同交易內的作用領域子項資料列。對於使用者設定檔或代理程式設定檔目標，這會先刪除擁有的繫線資料列，移除其繫線作用領域訊息和記憶體表格資料列，然後刪除其餘的直接作用領域訊息和類似記憶體的資料列 (memory、guideline、fact、preference)。當相符的基本資料列已不存在時，此作用領域清除仍會執行。
傳回：已移除要求的最上層目標數目，通常為 0 或 1。串連的子項資料列不會個別計算，因此當遺漏的動作者設定檔觸發範圍清除時，這仍可能是 0。
傳回類型：整數

注意事項

此作業會在一個交易內執行。當支援的最上層目標啟用 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 – 應移除其資料列的繫線 ID，包括繫線資料列、相依子項資料列，以及明確的區塊資料列清除。
傳回：已刪除的繫線資料列數目 (0 或 1)。
傳回類型：整數

注意事項

當您需要執行緒作用領域的連鎖清除時，請使用此作業。在資料庫備份存放區中，刪除繫線會移除受管理繫線資料列以及相關聯的訊息和記憶體資料列，以及保留供擷取的搜尋資料。這比訊息階層刪除大，僅會移除原始訊息列。執行緒刪除會移除在相同交易中的相依訊息與記憶體資料列及其相關聯的擷取資料。

範例

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 時，只會傳回沒有儲存中繼資料的記錄。設定為字典時，metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的描述資料中。巢狀字典會遞迴比對。定量與清單值會完全符合；清單順序與長度也必須相符。若要測試陣列成員身分，請使用欄位層級運算子字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的清單運算元表示必須要有所有列出的值；"$array_contains_any" 表示必須至少有一個列出的值。使用 "$not" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。範例包括純量欄位的 metadata_filter={"source": "slack"}、巢狀欄位的 metadata_filter={"review": {"status": "open"}}，以及完全相符的清單 metadata_filter={"tags": ["prod", "urgent"]}。結合條件以要求所有條件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
退貨：依插入順序排序的記錄。
傳回類型： 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 – 應傳回其訊息的繫線 ID。
- last_n int | None – 要傳回之最近訊息的選擇性數目。
傳回：依插入順序排列的訊息記錄。
傳回類型： list[ MessageRecord ]

範例

store.list_thread_messages("c1")
[]

方法 `search`

依相似性搜尋記錄。

作用中的搜尋後端取決於存放區設定的 SearchStrategy。SearchStrategy.VECTOR 會將查詢向量與儲存的記錄向量進行排名。SearchStrategy.HYBRID 會透過預存搜尋文字及其受管理索引狀態查詢 Oracle 的受管理混合索引。SearchStrategy.KEYWORD 只會以符合已儲存搜尋文字的文字來排名。

參數：
- query str | None – 可選的自然語言文字，用於尋找相符或相似的記錄。省略 query_vector 時，請至少提供一個非空格字元。向量搜尋會內嵌此文字；關鍵字搜尋會與預存搜尋文字相符；混合搜尋會使用它來擷取文字和向量。
- query_vector list[float] | None – 選用的預先計算查詢內嵌。只能提供 query 和 query_vector 其中之一。在向量搜尋中，這會與儲存的記錄向量進行比較。在混合式搜尋中，會將它當作查詢端向量輸入傳送至 Oracle 的受管理混合索引，而且不會讓資料庫存放區直接與新增時間或更新時間儲存的向量進行比較。關鍵字搜尋不接受 query_vector。向量必須為非空白、一維，且僅包含有限數值。在混合搜尋中，其維度必須符合設定的 OracleDBEmbedder 模型。
- k int – 要傳回的結果數目上限。明確值必須至少為 1。此為上限：當篩選條件的限制性太大、有較少的非過期相符記錄存在，或因為實作特定的搜尋行為而導致呼叫傳回的結果可能少於 k。
- thread_id str | None – 選擇性繫線範圍 ID。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 – 要包含的可搜尋記錄類型集合 (選擇性)。省略時，資料庫搜尋會涵蓋訊息、記憶體表格資料列以及動作者設定檔。動作者設定檔會貢獻其 information 有效負載，而訊息和記憶體資料列則構成其 content 有效負載。在搜尋期間，資料檔記錄類型會針對適用的範圍維度使用其動作者識別碼，而其餘範圍維度則行為 None。
- metadata_filter dict[str, Any] | None – 選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的描述資料中。巢狀字典會遞迴比對。定量與清單值會完全符合；清單順序與長度也必須相符。若要測試陣列成員身分，請使用欄位層級運算子字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的清單運算元表示必須要有所有列出的值；"$array_contains_any" 表示必須至少有一個列出的值。使用 "$not" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。
傳回：以增加距離排序的 (record, distance) 組。清單可能包含少於 k 個項目。
傳回類型： list[tuple[ 記錄，浮動 ]]
發出：ValueError – 如果 k 小於 1，如果同時提供或不提供 query 和 query_vector，如果 query 空白，則當向量模式無法解析內嵌查詢、如果 query_vector 無效，或 metadata_filter 無效時。

範例

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

方法 `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 – search 接受的選擇性描述資料篩選相同，包括純量、巢狀、精確清單、陣列成員身分，以及 {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]} 和 {"tags": {"$array_contains": "prod"}} 等組合條件。
傳回：基礎 search 呼叫傳回的 (record, distance) 組。
傳回類型： List[tuple[ 記錄，浮點數 ]]
發出：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 | list[str] | None – 選擇性僅限語意有效負載 (Payload)。省略時，會使用 text 來編製語意索引。在支援混合功能的綱要上，這也會變成 Oracle 文字元件所使用的預存搜尋文字。字串值可由商店分區；清單值會被視為呼叫者擁有的區塊，並依原樣寫入至 RECORD_CHUNKS。僅提供 embedding 時，會重複使用現有的搜尋文字。
- 嵌入 list[float] | ndarray | list[list[float] | ndarray] | None –
  
  可選的預先計算嵌入向量或區塊嵌入向量列表。設定本機向量儲存時，會直接使用，不會進行內嵌程式呼叫。傳送 None 以清除儲存的內嵌。提供 text 時，單一向量代表整個取代文字，即使已設定的區塊會分割該文字。除非 index_text 是區塊清單，否則取代文字時會拒絕多個區塊向量。只提供 embedding 時，內嵌計數必須符合記錄的現有區塊資料列。
  
  在 SearchStrategy.VECTOR 中，向量搜尋會依據儲存的內嵌進行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，資料庫備份搜尋會跨預存搜尋文字和 Oracle 管理的文字或混合索引狀態排名，因此更新階段內嵌只會影響任何已設定的本機向量儲存，而不會影響該作用中搜尋策略。如果此儲存設定沒有本機向量儲存，請提供 index_text 而非 embedding 以更新這些文字感知索引的可見文字。僅文字語意更新可能會在這些模式下完全省略 embedding。
- 中繼資料 dict[str, Any] | None – 序列化至 JSON 並儲存在 metadata 中的選擇性中繼資料對應。
- timestamp str | None – 隨記錄一起儲存的選擇性新時戳。它代表記錄的建立時間。省略時，會保留現有的時間戳記。傳送 None 以清除儲存的時間戳記，並使用資料庫建立時間進行未來的 TimeToLiveAnchor.CREATED_AT 到期重新整理。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，不含時區的 ISO-8601 時戳會被視為 UTC。
- ttl_days int | None – 選擇性到期重新整理 (天)。將此引數與 ttl_anchor 一起省略，以保留目前的到期時戳。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. 超過 MemoryRetentionConfig.max_ttl_days 的值會固定至該上限，但有警告。若尚未清除過期記錄，則重新整理過期記錄可再次顯示。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 來計算儲存的建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 來計算相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。使用綱要的 MemoryRetentionConfig.default_ttl_days，提供不含 ttl_days 的 ttl_anchor 會重新整理過期。重新整理期間省略 ttl_anchor 時，存放區會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要相同呼叫中的替代 ISO-8601 時間戳記，或該格式的現有儲存事件時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
傳回：更新的資料列數目 (0 或 1)。當沒有符合 record_type 和 record_id 的邏輯記錄時，傳回 0。
傳回類型：整數
發出：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.dbsearch.SearchStrategy`

基本：Enum

Oracle DB 商店的搜尋行為。

資料庫存放區初始化使用選取的策略來選擇受管理綱要搜尋功能。VECTOR 搜尋會儲存本機內嵌項目。KEYWORD 搜尋會儲存可搜尋的文字和文字索引。HYBRID 搜尋會儲存可搜尋的文字加上 Oracle 管理的混合向量索引狀態。資料庫存放區會在啟動時驗證此綱要功能，因此不相容的策略不會無訊息地傳回不完整的結果。

VECTOR: 僅依向量相似性搜尋。商店會內嵌具有已設定之內嵌器的查詢，或使用呼叫者提供的 query_vector，並依與已儲存向量的距離排列記錄的等級。搭配針對向量搜尋設定的資料庫綱要使用。
HYBRID: 使用 Oracle 管理的混合索引進行搜尋。Oracle 將已儲存搜尋文字的文字比對與資料庫內混合索引的向量排名結合。當使用者可以依自然語言以及精確的識別碼、別名或產品名稱進行搜尋時，請使用此選項。此策略要求存放區的主要內嵌程式必須是 OracleDBEmbedder，因此受管理索引和儲存共用一個資料庫內模型。
KEYWORD: 僅透過與預存搜尋文字相符的關鍵字 / 文字進行搜尋。此模式不會建立本機查詢內嵌，不需要 Oracle DB 內嵌程式。在針對現有混合綱要開啟時，它可以使用該混合索引的文字分支，而不需要建立新的混合索引。當精確的識別碼、別名、產品名稱或短詞應該在沒有向量融合的情況下驅動擷取時，請使用此選項。

HYBRID = 'HYBRID'

關鍵字 = 'KEYWORD'

VECTOR = 'VECTOR'

搜尋索引同步模式

類別 `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

基本：Enum

受管理資料庫搜尋索引的重新整理行為。

此設定控制 Oracle 何時對資料庫備份文字感知搜尋顯示新的或變更的搜尋文字。SearchStrategy.HYBRID 使用 Oracle 管理的混合向量索引。SearchStrategy.KEYWORD 使用 Oracle Text 索引。SearchStrategy.VECTOR 不使用此設定。

ON_COMMIT: 當寫入交易確認時重新整理索引。這是大多數應用程式的預設和最簡單選項，因為記錄在成功寫入後可立即搜尋。它可以新增寫入交易的工作，因為索引會立即保持在最新狀態。
MANUAL: 不要自動重新整理索引。在您自行執行資料庫端索引同步作業之前，新的或更新的記錄可能不會出現在關鍵字或混合搜尋中。這對於您要在其中控制重新整理工作執行時的大量載入或維護時段非常有用。
AUTO: 讓 Oracle 以非同步方式重新整理受管理的混合索引。寫入可以避免立即重新整理成本，但搜尋結果可能會落後最近的寫入，直到 Oracle 完成背景重新整理為止。只有 SearchStrategy.HYBRID 才支援此模式。

警告：此設定控制受管理搜尋索引存在之後的進行中維護。它不會使第一個索引建置成為非同步。透過現有預存搜尋文字建立受管理的混合索引可能會長時間執行，因為 Oracle 會從該文字建立受管理的混合索引狀態。

自動 = 'AUTO'

手動 = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

存留時間

類別 `oracleagentmemory.core.retention.MemoryRetentionConfig`

基礎：object

Oracle DB 備份記錄的綱要層次保留設定值。

參數：
- default_ttl_days int | None – 預設存留時間持續時間 (天)。保留為 NOT_SET_MARKER 以使用預設值 None (無最大值)。
- max_ttl_days int | None – 選擇性的最長存留時間 (天)。保留為 NOT_SET_MARKER 以使用預設值 None。傳遞 None 為無最大值。設定時，此為強制上限：嘗試使用較大 ttl_days 值的寫入會被限制為此上限並出現警告，而寫入通過 ttl_days=None 的 API 則會使用此上限，而不是建立非到期的記錄。

類別 `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

基本：Enum

用來從存留期間計算到期時間戳記的錨點。

CREATED_AT: 從記錄的資料庫建立時戳計算到期時間。這是呼叫者省略 ttl_anchor 時的預設值。
TIMESTAMP: 從記錄的預存事件時戳計算到期時間。當訊息或記憶體代表較舊的事件，且應該相對於該事件時間而非插入時間到期時，使用此選項。

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'TIMESTAMP'

綱要原則

類別 `oracleagentmemory.core.SchemaPolicy`

基礎：str、Enum

Oracle DB 存放區的綱要建立原則。

需求 _ 現有

驗證完整受管理綱要已經存在且為最新狀態。請勿建立或修改資料庫物件。

空白建立 (_I)

如果沒有受管理物件，啟動安裝綱要。如果物件已經存在，則需要完整且最新的受管理綱要。

需要建立 (_I)

建立遺漏的受管理物件並套用支援的受管理綱要升級。

重新建立

刪除並重新建立所有受管理綱要物件。這是破壞性的。

商店與綱要

儲存 API

商店寫入語意

類別 oracleagentmemory.core.OracleMemoryStore

方法 add

方法 add_agent (摘要)

方法 add_async (非同步)

方法 add_batches

方法 add_batches_async (非同步)

方法 add_user (摘要)

方法 delete (摘要)

方法 delete_thread (摘要)

方法 get (摘要)

方法 list (摘要)

方法 list_thread_messages (摘要)

方法 search (摘要)

方法 search_async (非同步)

方法 update (摘要)

Oracle DB 商店

類別 oracleagentmemory.core.OracleDBMemoryStore

方法 add

方法 add_agent

方法 add_async (非同步)

方法 add_batches

方法 add_batches_async (非同步)

方法 add_user

方法 delete

方法 delete_thread

方法 get

方法 list

方法 list_thread_messages

方法 search

方法 search_async (非同步)

方法 update

搜尋策略

類別 oracleagentmemory.core.dbsearch.SearchStrategy

HYBRID = 'HYBRID'

關鍵字 = 'KEYWORD'

VECTOR = 'VECTOR'

搜尋索引同步模式

類別 oracleagentmemory.core.dbsearch.SearchIndexSyncMode

自動 = 'AUTO'

手動 = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

存留時間

類別 oracleagentmemory.core.retention.MemoryRetentionConfig

類別 oracleagentmemory.apis.ttl.TimeToLiveAnchor

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'TIMESTAMP'

綱要原則

類別 oracleagentmemory.core.SchemaPolicy

需求 _ 現有

空白建立 (_I)

需要建立 (_I)

重新建立

類別 `oracleagentmemory.core.OracleMemoryStore`

方法 `add`

方法 `add_agent` (摘要)

方法 `add_async` (非同步)

方法 `add_batches`

方法 `add_batches_async` (非同步)

方法 `add_user` (摘要)

方法 `delete` (摘要)

方法 `delete_thread` (摘要)

方法 `get` (摘要)

方法 `list` (摘要)

方法 `list_thread_messages` (摘要)

方法 `search` (摘要)

方法 `search_async` (非同步)

方法 `update` (摘要)

類別 `oracleagentmemory.core.OracleDBMemoryStore`

方法 `add`

方法 `add_agent`

方法 `add_async` (非同步)

方法 `add_batches`

方法 `add_batches_async` (非同步)

方法 `add_user`

方法 `delete`

方法 `delete_thread`

方法 `get`

方法 `list`

方法 `list_thread_messages`

方法 `search`

方法 `search_async` (非同步)

方法 `update`

類別 `oracleagentmemory.core.dbsearch.SearchStrategy`

類別 `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

類別 `oracleagentmemory.core.retention.MemoryRetentionConfig`

類別 `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

類別 `oracleagentmemory.core.SchemaPolicy`