商店與綱要

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

儲存 API

商店寫入語意

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

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

update() 中 add() 和 content 中的 contents 控制 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`	此清單會被視為呼叫者擁有的區塊。每個非空白字串都會寫入為一個擷取列，且商店不會再次分區。	此清單會被視為呼叫者擁有的區塊。每個非空白字串都會寫入為一個擷取列，且商店不會再次分區。
`None` `index_texts` 項目或 `index_text=None`	外部 `index_texts` 清單中的 `None` 表示「使用此記錄的預存內容」。	除非同時提供 `content`，否則 `index_text=None` 會在未變更儲存的內容時清除擷取資料列。
空白字串或空白區塊清單	儲存記錄內容，且不提供該記錄的擷取文字。	在提供 `content` 時更新記錄內容，並清除該記錄的擷取文字。

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

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

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

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

某些組合被拒絕，因此儲存的文字、擷取文字和向量不會偏差。傳送 content=None 會清除儲存的內容和擷取資料列，因此無法與非空值的 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] – 記錄有效負載 (Payload) 的唯讀順序。訊息項目可能包含排序的 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] – 僅用於語意索引的選擇性替代有效負載。如果提供，外部清單必須與文字輸入對齊。每個項目可以是字串，商店可能會在內部分區，或是非空白字串的清單，商店會將其視為來電者擁有的區塊，且不得再次分割。
- 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 項目會儲存 NULL 事件時戳；讀取會使用記錄建立時間作為有效時戳。
- 中繼資料 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] – 支援到期之記錄的選擇性存留時間持續時間 (天)。省略此引數以使用存放區預設值。針對不應到期的記錄，傳送 None。定量值可以跨對齊的文字輸入廣播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 將相對於儲存的建立時間到期，或相對於每個記錄的事件時間戳記，使用 TimeToLiveAnchor.TIMESTAMP 將到期。省略時，實作會使用 TimeToLiveAnchor.CREATED_AT。
- 狀態 RecordStatus | list[RecordStatus] – 記錄的選擇性生命週期狀態或狀態。省略此項目以儲存 RecordStatus.VALID。
- **store_kwargs ( 任一 ) – 轉送至具體存放區的實行特定寫入選項。
傳回類型： list[str]

備註

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

傳回：插入之記錄的識別碼，其邏輯順序與輸入相同。
傳回類型： List[str]
參數：
- 內容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | 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]
- 狀態 RecordStatus | list[RecordStatus]
- store_kwargs Any

方法 `add_agent` (摘要)

新增專員資料檔記錄。

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

方法 `add_agent_async` (非同步)

非同步新增專員資料檔記錄。

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

方法 `add_async` (非同步)

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

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

參數：
- 內容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | 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]
- 狀態 RecordStatus | list[RecordStatus]
- store_kwargs Any
傳回類型： list[str]

方法 `add_batches`

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

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

範例

store.add_batches(
    [
        PendingRecordBatch(
            contents=["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_relations` (摘要)

儲存一或多個導向關係。

定量值會跨來源記錄批次廣播。清單值的長度必須相同。一個端點組只能儲存一個方向。使用 opposite_relation_types 來描述反向檢視，而不是新增第二個反向關係。實作可能會限制它們保存的端點記錄類型和關係標籤。

參數：
- source_record_ids str | list[str] – 每個導向關係之來源端的記錄識別碼或識別碼。
- source_record_types str | list[str] – source_record_ids 的記錄類型或類型。請為所有來源提供一個值，或為每個關係提供一個值。
- target_record_ids str | list[str] – 每個導向關係之目標端的記錄識別碼或識別碼。
- target_record_types str | list[str] – target_record_ids 的記錄類型或類型。請為所有目標提供一個值，或為每個關係提供一個值。
- relation_types str | list[str] – 直接關係標籤或標籤。為所有關係提供一個值，或為每個關係提供一個值。
- opposite_relation_types str | list[str] – 反向檢視每個關係的選擇性標籤或標籤。若為內建記憶體關係類型，省略會使用預先定義的反向標籤。對於自訂關係類型，省略會在兩個方向使用相同的標籤。
- relation_ids str | None | list[str | None] – 選擇性的穩定識別碼或識別碼。省略此項目，讓商店產生識別碼。
- 時間戳記 str | None | list[str | None] – 儲存在關係上的選擇性時間戳記或時間戳記。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 儲存在關係上的選擇性中繼資料物件。
退貨：輸入順序中的關係識別碼。
傳回類型： list[str]

範例

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

方法 `add_relations_async` (非同步)

非同步儲存一或多個導向關係。

定量值會跨來源記錄批次廣播。清單值的長度必須相同。一個端點組只能儲存一個方向。使用 opposite_relation_types 來描述反向檢視，而不是新增第二個反向關係。

參數：
- source_record_ids str | list[str] – 每個導向關係之來源端的記錄識別碼或識別碼。
- source_record_types str | list[str] – source_record_ids 的記錄類型或類型。請為所有來源提供一個值，或為每個關係提供一個值。
- target_record_ids str | list[str] – 每個導向關係之目標端的記錄識別碼或識別碼。
- target_record_types str | list[str] – target_record_ids 的記錄類型或類型。請為所有目標提供一個值，或為每個關係提供一個值。
- relation_types str | list[str] – 直接關係標籤或標籤。為所有關係提供一個值，或為每個關係提供一個值。
- opposite_relation_types str | list[str] – 反向檢視每個關係的選擇性標籤或標籤。若為內建記憶體關係類型，省略會使用預先定義的反向標籤。對於自訂關係類型，省略會在兩個方向使用相同的標籤。
- relation_ids str | None | list[str | None] – 選擇性的穩定識別碼或識別碼。省略此項目，讓商店產生識別碼。
- 時間戳記 str | None | list[str | None] – 儲存在關係上的選擇性時間戳記或時間戳記。
- 中繼資料 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 – 使用者設定檔的穩定識別碼。省略資料庫備份的實行時，可能會從附加的一般使用者安全相關資訊環境推斷這個值。
- 資訊 str – 描述使用者的必要任意格式文字。
- 中繼資料 dict[str, Any] | None – 儲存在使用者設定檔資料列上的選擇性中繼資料對應。
傳回：所建立使用者資料檔記錄的識別碼。
傳回類型： str

方法 `add_user_async` (非同步)

非同步新增使用者資料檔記錄。

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

方法 `delete` (摘要)

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

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

方法 `delete_async` (非同步)

以非同步方式依識別碼刪除一筆儲存的記錄。

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

方法 `delete_relations` (摘要)

依識別碼刪除關係。

生命週期狀態會從剩餘的關係重新計算。

參數： relation_ids str | list[str] – 要刪除之關係的 ID 或 ID。
傳回：刪除的關係數目。
傳回類型：整數

範例

store.delete_relations("relation-id")
1

方法 `delete_relations_async` (非同步)

依 ID 非同步刪除關係。

生命週期狀態會從剩餘的關係重新計算。

參數： relation_ids str | list[str] – 要刪除之關係的 ID 或 ID。
傳回：刪除的關係數目。
傳回類型：整數

範例

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

方法 `delete_thread` (摘要)

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

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

備註

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

方法 `delete_thread_async` (非同步)

非同步刪除執行緒及其相關聯的預存資料。

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

備註

方法 `get` (摘要)

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

參數：
- record_type str – 要擷取之記錄的邏輯類型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- record_id str – 要擷取之記錄的識別碼。
- include_bytes bool – 是否要載入儲存的影像位元組。對於訊息記錄，這會控制附加的影像是否包含其位元組。對於影像記錄，它會控制是否載入獨立影像位元組。此選項不會影響其他記錄類型。
傳回：找到儲存的記錄，否則為 None。"thread" 查尋會傳回 ThreadRecord，其中包含繫線描述資料、程式實際執行組態、程式實際執行狀態，以及在存放區支援持續性繫線時填入的建立時戳。
傳回類型： 記錄 | 無

方法 `get_async` (非同步)

以非同步方式依類型與識別碼擷取一筆儲存的記錄。

參數：
- 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` (摘要)

在儲存的來源至目標方向傳回一個關係。

僅提供 relation_id，或提供一個完整的來源至目標端點元組。

參數：
- 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(...)

方法 `get_relation_async` (非同步)

依 ID 或端點元組以非同步方式擷取一個關係。

僅提供 relation_id，或提供一個完整的來源至目標端點元組。

參數：
- 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"、"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 的記錄。設定為字典時，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"],
}
```
- include_bytes bool – 附加至訊息記錄的影像記錄或影像是否包含其儲存的位元組。省略或 False 時，會傳回影像描述和描述資料，而不會載入位元組。若為直接影像清單，請只使用完全相同的 record_id 和至少一個完全相符的使用者、代理程式或繫線範圍篩選，將此設為 True。此選項不會影響其他記錄類型。
- record_id str – 精確記錄識別碼篩選。省略時，會傳回任何 ID 的記錄。範圍和描述資料篩選會維持其他限制條件。
傳回：在傳回視窗中從最舊到最新排序的記錄。
傳回類型： List[ 記錄 ]

方法 `list_async` (非同步)

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

參數：
- 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 的記錄。設定為字典時，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"],
}
```
- include_bytes bool – 附加至訊息記錄的影像記錄或影像是否包含其儲存的位元組。省略或 False 時，會傳回影像描述和描述資料，而不會載入位元組。若為直接影像清單，請只使用完全相同的 record_id 和至少一個完全相符的使用者、代理程式或繫線範圍篩選，將此設為 True。此選項不會影響其他記錄類型。
- record_id str – 精確記錄識別碼篩選。省略時，會傳回任何 ID 的記錄。範圍和描述資料篩選會維持其他限制條件。
傳回：在傳回視窗中從最舊到最新排序的記錄。
傳回類型： List[ 記錄 ]

方法 `list_relations` (摘要)

以其來源至目標方向列出已儲存的關係。

參數：
- relation_type str – 要比對的選擇性導向關係標籤，例如 "supports" 或 "supersedes"。省略以包含每個關係類型。
- source_record_id str – 要比對的選擇性來源記錄識別碼。
- source_record_type str – 要比對的選擇性來源記錄類型。
- target_record_id str – 要比對的選擇性目標記錄 ID。
- target_record_type str – 要比對的選擇性目標記錄類型。
- limit int | None – 選擇性要傳回之最早建立關係的數目上限。省略時，實作可能會套用安全的上限，例如 MAX_LIST_LIMIT。傳送 None 以傳回每個相符的已儲存關係。
- metadata_filter dict[str, Any] | None – 描述資料篩選。省略時，不會套用任何篩選。設為 None 時，只會傳回中繼資料為 None 的關係。設定為字典時，項目會與 AND 語意結合。巢狀字典使用遞迴完全相符的方式。純量和清單值需要完全相等；請使用 {"tags": {"$array_contains": "prod"}} 來比對陣列成員身分，使用 "$array_contains_any" 來比對任何列出的值，或使用 "$not" 來否定另一個欄位表示式。
- relation_id str – 精確的關係識別碼篩選。省略時，會傳回任何 ID 的關係。其他篩選條件仍會維持其他限制。
傳回：依建立時間和 ID 排序的關係。
傳回類型： list[ RecordRelation ]

範例

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

方法 `list_relations_async` (非同步)

以非同步方式列出來源至目標方向的關係。

參數：
- relation_type str – 要比對的選擇性導向關係標籤，例如 "supports" 或 "supersedes"。省略以包含每個關係類型。
- source_record_id str – 要比對的選擇性來源記錄識別碼。
- source_record_type str – 要比對的選擇性來源記錄類型。
- target_record_id str – 要比對的選擇性目標記錄 ID。
- target_record_type str – 要比對的選擇性目標記錄類型。
- limit int | None – 選擇性要傳回之最早建立關係的數目上限。省略時，實作可能會套用安全的上限，例如 MAX_LIST_LIMIT。傳送 None 以傳回每個相符的已儲存關係。
- metadata_filter dict[str, Any] | None – 描述資料篩選。省略時，不會套用任何篩選。設為 None 時，只會傳回中繼資料為 None 的關係。設定為字典時，項目會與 AND 語意結合。巢狀字典使用遞迴完全相符的方式。純量和清單值需要完全相等；請使用 {"tags": {"$array_contains": "prod"}} 來比對陣列成員身分，使用 "$array_contains_any" 來比對任何列出的值，或使用 "$not" 來否定另一個欄位表示式。
- relation_id str – 直接比對的選擇性關係 ID。
傳回：依建立時間和 ID 排序的關係。
傳回類型： list[ RecordRelation ]

範例

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

方法 `list_thread_messages` (摘要)

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

參數：
- thread_id str – 應傳回其訊息之繫線的 ID。
- 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 ]

方法 `list_thread_messages_async` (非同步)

非同步列出一個執行緒所儲存的訊息歷史記錄。

參數：
- thread_id str – 應傳回其訊息之繫線的 ID。
- 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` (摘要)

依相似性搜尋記錄。

參數：
- 查詢 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" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。
- include_invalid_results bool – 結果是否包含無效狀態的類似記憶體記錄。預設為 True。傳送 False 以排除它們。
- num_hops int – 每個直接記憶體結果中要遵循的記憶體連結邊緣數目。支援從 0 到 5 的值；0 會停用圖表擴充。
- max_linked_results int – 連附至每個直接結果之所有躍點的連結記憶體上限。0 會保留沒有連結相關資訊環境的直接結果。預設為 100。
傳回：以增加距離排序的 (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-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

方法 `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"}} 等組合條件。
- include_invalid_results bool – search 接受的相同生命週期狀態結果選項。
- num_hops int – search 接受的圖形擴充深度相同。
- max_linked_results int – search 接受的每一直接結果 link-memory 限制相同。
傳回：基礎 search 呼叫傳回的 (record, distance) 組。
傳回類型： List[tuple[ 記錄，浮點數 ]]
發出：ValueError – 如果 k 小於 1。

方法 `update` (摘要)

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

參數：
- record_type str – 要更新之記錄的邏輯類型。
- record_id str – 要更新之記錄的識別碼。
- 內容 str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – 正規取代內容。對於 message 記錄，傳送字串或依序排列的文字和影像內容部分；使用 "" 將訊息取代為空白文字。對於類似記憶體的記錄，商店可以接受 None 來清除儲存的文字和關聯的語意狀態。忽略引數讓內容維持不變。請勿同時提供 text。
- index_text str | list[str] | None – 可選替代語意有效負載 (Payload)，用於重新計算或取代儲存的搜尋狀態，而不變更保存的文字。字串可以由商店內部分區。將非空白字串清單視為來電者擁有的區塊，且不得再次分割。有些實作也可以將此分別保存為混合搜尋文字。對於 image 記錄，此欄位會取代保存的影像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None – 可選的預先計算嵌入向量或區塊嵌入向量清單。提供時，會直接使用，不會呼叫內嵌程式。多個向量需要相符的 index_text 區塊清單或現有的儲存區塊文字資料列。傳送 None，在商店支援時明確清除儲存的內嵌。具有文字感知索引的商店也可以允許沒有內嵌或明確內嵌的語意更新。
- 中繼資料 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 作為記錄建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用存放區或綱要預設存留時間持續時間。在重新整理期間省略 ttl_anchor 時，實行會使用 TimeToLiveAnchor.CREATED_AT。
- 狀態 RecordStatus – 記錄的選擇性取代生命週期狀態。
- 文字 str | None –
  
  content 的別名已不再使用。傳遞 None 以在存放區支援時明確清除儲存的文字。請勿同時提供 content。
  
  已棄用
  
  自 26.8.0 版起已不再使用：此參數在 26.8.0 已不再使用，將會在 27.1 中移除。請改用 content。
傳回數：更新的記錄數 (0 或 1)。0 的傳回值表示未更新任何記錄。
傳回類型：整數
發出：ValueError - 如果存放區的更新有效負載無效，例如省略每個選擇性欄位或提供衝突的語意引數。

方法 `update_async` (非同步)

以非同步方式更新儲存的記錄內容、嵌入資料、中繼資料、時間戳記或到期。

參數：
- record_type str – 要更新之記錄的邏輯類型。
- record_id str – 要更新之記錄的識別碼。
- 內容 str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – 正規取代內容。對於 message 記錄，傳送字串或依序排列的文字和影像內容部分；使用 "" 將訊息取代為空白文字。對於類似記憶體的記錄，商店可以接受 None 來清除儲存的文字和關聯的語意狀態。忽略引數讓內容維持不變。請勿同時提供 text。
- index_text str | list[str] | None – 可選替代語意有效負載 (Payload)，用於重新計算或取代儲存的搜尋狀態，而不變更保存的文字。字串可以由商店內部分區。將非空白字串清單視為來電者擁有的區塊，且不得再次分割。有些實作也可以將此分別保存為混合搜尋文字。對於 image 記錄，此欄位會取代保存的影像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None – 可選的預先計算嵌入向量或區塊嵌入向量清單。提供時，會直接使用，不會呼叫內嵌程式。多個向量需要相符的 index_text 區塊清單或現有的儲存區塊文字資料列。傳送 None，在商店支援時明確清除儲存的內嵌。具有文字感知索引的商店也可以允許沒有內嵌或明確內嵌的語意更新。
- 中繼資料 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 作為記錄建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用存放區或綱要預設存留時間持續時間。在重新整理期間省略 ttl_anchor 時，實行會使用 TimeToLiveAnchor.CREATED_AT。
- 狀態 RecordStatus – 記錄的選擇性取代生命週期狀態。省略以保留目前的狀態。
- 文字 str | None –
  
  content 的別名已不再使用。傳遞 None 以在存放區支援時明確清除儲存的文字。請勿同時提供 content。
  
  已棄用
  
  自 26.8.0 版起已不再使用：此參數在 26.8.0 已不再使用，將會在 27.1 中移除。請改用 content。
傳回數：更新的記錄數 (0 或 1)。0 的傳回值表示未更新任何記錄。
傳回類型：整數
發出：ValueError - 如果存放區的更新有效負載無效，例如省略每個選擇性欄位或提供衝突的語意引數。

方法 `update_relations` (摘要)

更新預存關係上的可變值。

省略的欄位會維持不變，但變更為內建記憶體關係類型會將其反向標籤取代為固定反向。資料庫備份的記憶體存放區也會在關係類型變更之後重新計算端點生命週期狀態。

參數：
- relation_ids str | list[str] – 要更新之關係的識別碼或識別碼。
- relation_types str | list[str] – 選擇性的取代導向關係標籤或標籤。省略此項目以保留儲存的標籤。
- opposite_relation_types str | list[str] – 選擇性的取代反向關係標籤或標籤。傳送要取代的標籤，或省略此引數以保留標籤。
- 時間戳記 str | None | list[str | None] – 選擇性取代時間戳記或時間戳記。傳送 None 以清除儲存的時間戳記。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性取代中繼資料物件。提供的描述資料會取代儲存的物件，不會合併。
傳回：已更新關係的識別碼。
傳回類型： list[str]

範例

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

方法 `update_relations_async` (非同步)

在儲存的關係上以非同步方式更新可變值。

參數：
- relation_ids str | list[str] – 要更新之關係的識別碼或識別碼。
- relation_types str | list[str] – 選擇性的取代導向關係標籤或標籤。省略此項目以保留儲存的標籤。
- opposite_relation_types str | list[str] – 選擇性的取代反向關係標籤或標籤。傳送要取代的標籤，或省略此引數以保留標籤。
- 時間戳記 str | None | list[str | None] – 選擇性取代時間戳記或時間戳記。傳送 None 以清除儲存的時間戳記。
- 中繼資料 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 連線或集區。傳送原始連線可啟用此商店實例的單一階段作業模式：並行商店呼叫會在本機進行序列化，以保留寫入作業所使用的資料列鎖定與交易假設。針對並行要求使用連線集區。
- 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。兩種模式都不會讓存放區變成唯讀：一般記憶體讀取和寫入都使用連線使用者的有效資料庫授權。對於 Deep Data Security 執行階段存取，請使用 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 – 受管理資料庫記憶體存放區的穩定 ID。重複使用相同的 ID 來重新開啟相同的受管理商店。ID 會以底線結合至受管理資料庫物件名稱，因此必須以字母為開頭、僅包含字母、數字及底線，且最多 16 個字元。傳送此項目或 table_name_prefix，但不可同時傳送兩者。如果省略，當同時省略 table_name_prefix 時，存放區會使用 table_name_prefix 或前綴的預設值。在連線使用者綱要中建立、修復或重新建立存放區時，該綱要中必須要有相容的 DBMS_AGENT_MEMORY_STORE 套裝程式。
- schema_owner str – 現有受管理記憶體存放區的選擇性綱要擁有者。省略此選項即可使用連線使用者的綱要。pool 引數可以是原始資料庫連線或連線集區；當它屬於具有其他使用者所擁有之表格授權的應用程式資料庫使用者時，請使用此選項。此選項僅適用於已建立之受管理記憶體存放區的程式實際執行存取。使用 SchemaPolicy.REQUIRE_EXISTING 進行一般跨綱要存取，或使用 SchemaPolicy.NO_CHECK 搭配使用中的一般使用者安全相關資訊環境進行深層資料安全保護存放區。以綱要擁有者身分連線時，建立、升級或重新建立受管理記憶體存放區，並省略此選項。傳送未加引號的 ID；小寫輸入已標準化為大寫，但不支援引號括住的綱要擁有者。將 CREATE SESSION 和必要的物件權限授與應用程式資料庫使用者；請參閱疑難排解指南的 Database Users and Privileges 小節，瞭解確切的授權。另一種方法是，在程式實際執行綱要中顯示相同名稱的受管理物件檢視，並省略 schema_owner；只有 SchemaPolicy.REQUIRE_EXISTING 支援此檢視。
- search_strategy SearchStrategy – 選取 search() 後端的 SearchStrategy 值。使用 SearchStrategy.VECTOR (預設) 進行僅限向量擷取，使用 SearchStrategy.HYBRID 在預存搜尋文字上查詢受管理的 Oracle 混合向量索引，或使用 SearchStrategy.KEYWORD 在預存搜尋文字上依關鍵字 / 文字比對進行排名 (不含向量融合)。KEYWORD 不需要內嵌程式。HYBRID 需要 embedder 作為 OracleDBEmbedder，因此受管理的混合索引使用與主要儲存庫內嵌程式相同的資料庫內模型。如果關鍵字從屬端開啟現有的混合綱要，則存放區可以使用該混合索引的文字分支。現有綱要使用不相容的策略時，啟動會失敗，因為該綱要可能未包含策略所需的預存搜尋狀態。省略 schema_policy=SchemaPolicy.REQUIRE_EXISTING 和此引數時，存放區最佳效果會從受管理描述資料偵測綱要的預存搜尋模式，並在可用時使用該模式。
- 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)，再比較或儲存綱要描述資料。根據儲存在記錄中的預期資訊、應用程式保留的原因，以及任何應用程式或管制保留承諾來選擇此組態。
發出：RuntimeError – 如果一般使用者安全相關資訊環境在 SchemaPolicy.NO_CHECK 以外的綱要原則上為作用中，或者如果在沒有作用中一般使用者安全相關資訊環境的情況下開啟或使用 NO_CHECK 程式實際執行存放區。

警告：SchemaPolicy.CREATE_IF_NECESSARY 可能比一般存放區啟動更為昂貴，因為在初始化成功之前，它可能會修復受管理的綱要物件。當綱要可能包含許多資料列時，將修復工作計畫為維護作業。舊版綱要上的存放區需要先升級套裝程式綱要，再進行初始化。

如果綱要設定必須建立受管理過期記錄永久清除工作，但資料庫使用者缺乏 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 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None] – 記錄有效負載 (Payload) 的唯讀順序。訊息項目可能包含已排序的 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] – 作為搜尋文字的選擇性替代有效負載。您可以使用此選項來控制資料庫備份的關鍵字或混合搜尋索引。每個外部清單項目都會與一筆記錄對齊。字串項目可以由商店分區。清單項目會被視為呼叫者擁有的區塊，並依原樣寫入 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] – 與插入的記錄相關聯的選擇性使用者識別碼。定量值可以跨對齊的輸入廣播。在 SchemaPolicy.NO_CHECK 程式實際執行存放區中省略時，存放區會使用作用中一般使用者安全相關資訊環境的使用者名稱。明確地傳送 None 以保留未作用領域的使用者 ID。
- 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" 作為後援來源。影像寫入需要具有 "image/png"、"image/jpeg" 或 "image/webp" 的 "image_mime_type"。商店會使用此欄位來儲存影像，但不會將其傳回為記錄中繼資料的一部分。
- ttl_days int | None | list[int | None] – Optional time-to-live duration in days for message and memory-like records. Omit this argument to use MemoryRetentionConfig.default_ttl_days from the managed schema. 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. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Scalar values may be broadcast across aligned inputs.
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 將相對於資料庫建立時間的到期，或相對於提供的事件時戳，使用 TimeToLiveAnchor.TIMESTAMP 將到期。省略時，到期會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定過期對每個插入的記錄都需要具體的 ISO-8601 時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- 狀態 RecordStatus | list[RecordStatus] – 支援該狀態之記錄的選擇性生命週期狀態。提供一個 RecordStatus 值，以將它套用至每個輸入記錄，或與 contents 一致的狀態清單。省略此引數以使用 RecordStatus.VALID。
- **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_agent_async` (非同步)

非同步新增專員資料檔記錄。

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

方法 `add_async` (非同步)

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

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

參數：
- 內容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | 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]
- 狀態 RecordStatus | list[RecordStatus]
- store_kwargs Any
傳回類型： list[str]

方法 `add_batches`

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

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

範例

store.add_batches(
    [
        PendingRecordBatch(
            contents=["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_relations`

以原子方式儲存一或多個記憶體對記憶體關係。

定量值會跨來源 ID 批次廣播；清單必須對齊。一個端點組只能儲存一個關係方向。內建記憶體連結標籤會收到固定的反向標籤，而生命週期標籤會更新相同交易中的端點狀態。

參數：
- source_record_ids str | list[str] – 來源記憶體 ID，作為純量或對齊的清單。
- source_record_types str | list[str] – 來源記錄的類似記憶體類型。
- target_record_ids str | list[str] – 目標記憶體 ID，作為純量或對齊的清單。
- target_record_types str | list[str] – 目標記錄的類似記憶體類型。
- relation_types str | list[str] – 直接關係標籤。
- opposite_relation_types str | list[str] – 自訂關係類型的選擇性反向標籤。這描述已儲存關係的反向視圖；它不會在反向方向建立第二個關係。
- relation_ids str | None | list[str | None] – 選擇性的穩定關係識別碼。省略以產生識別碼。
- 時間戳記 str | None | list[str | None] – 隨關係儲存的選擇性時間戳記。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 與關係一起儲存的選擇性中繼資料。
傳回：以輸入順序建立關係識別碼。
傳回類型： list[str]

範例

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

方法 `add_relations_async` (非同步)

非同步儲存一或多個導向關係。

參數：
- source_record_ids str | list[str] – 每個導向關係之來源端的記錄識別碼或識別碼。
- source_record_types str | list[str] – source_record_ids 的記錄類型或類型。請為所有來源提供一個值，或為每個關係提供一個值。
- target_record_ids str | list[str] – 每個導向關係之目標端的記錄識別碼或識別碼。
- target_record_types str | list[str] – target_record_ids 的記錄類型或類型。請為所有目標提供一個值，或為每個關係提供一個值。
- relation_types str | list[str] – 直接關係標籤或標籤。為所有關係提供一個值，或為每個關係提供一個值。
- opposite_relation_types str | list[str] – 反向檢視每個關係的選擇性標籤或標籤。若為內建記憶體關係類型，省略會使用預先定義的反向標籤。對於自訂關係類型，省略會在兩個方向使用相同的標籤。
- relation_ids str | None | list[str | None] – 選擇性的穩定識別碼或識別碼。省略此項目，讓商店產生識別碼。
- 時間戳記 str | None | list[str | None] – 儲存在關係上的選擇性時間戳記或時間戳記。
- 中繼資料 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 – 使用者 ID。在 SchemaPolicy.NO_CHECK 程式實際執行存放區中省略時，存放區會使用作用中一般使用者安全相關資訊環境的使用者名稱。否則，請明確提供此引數。
- 資訊 str – 使用者的必要任意格式資訊。此文字會儲存為基本資料內容，並用於建立基本資料的可搜尋表示法。
- 中繼資料 dict[str, Any] | None – 儲存在使用者設定檔資料列上的選擇性中繼資料對應。
傳回：插入之使用者設定檔記錄的識別碼。
傳回類型： str

備註

使用者資料檔記錄未作用領域。插入的公用記錄 ID 是明確或推斷的 user_id。

範例

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

方法 `add_user_async` (非同步)

非同步新增使用者資料檔記錄。

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

方法 `delete`

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

參數：
- record_type str – 要刪除的記錄類型標籤。支援的類型包括 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 和 "agent_profile"，以及 "thread_summary"。
- 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_async` (非同步)

以非同步方式依識別碼刪除一筆儲存的記錄。

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

方法 `delete_relations`

依 ID 刪除關係並重新計算生命週期狀態。

參數： relation_ids str | list[str] – 要刪除之關係的 ID 或 ID。
傳回：刪除的關係數目。
傳回類型：整數

範例

store.delete_relations("relation-id")
1

方法 `delete_relations_async` (非同步)

依 ID 非同步刪除關係。

生命週期狀態會從剩餘的關係重新計算。

參數： relation_ids str | list[str] – 要刪除之關係的 ID 或 ID。
傳回：刪除的關係數目。
傳回類型：整數

範例

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

方法 `delete_thread`

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

參數： thread_id str – 應移除其資料列的繫線 ID，包括繫線資料列、相依子項資料列，以及明確的區塊資料列清除。
傳回：已刪除的繫線資料列數目 (0 或 1)。
傳回類型：整數

備註

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

範例

store.delete_thread("c1")
0

方法 `delete_thread_async` (非同步)

非同步刪除執行緒及其相關聯的預存資料。

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

備註

方法 `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'

方法 `get_async` (非同步)

以非同步方式依類型與識別碼擷取一筆儲存的記錄。

參數：
- 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 識別的一個關係或完整的端點元組。

僅提供 relation_id，或提供一個完整的來源至目標端點元組。

參數：
- 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(...)

方法 `get_relation_async` (非同步)

依 ID 或端點元組以非同步方式擷取一個關係。

僅提供 relation_id，或提供一個完整的來源至目標端點元組。

參數：
- 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 時，只會傳回沒有儲存中繼資料的記錄。設定為字典時，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"],
}
```
- include_bytes bool – 附加至訊息記錄的影像記錄或影像是否包含其儲存的位元組。預設為 False。直接映像檔清單需要 record_id 和至少一個完全相符的使用者、代理程式或繫線範圍篩選 (若為 True)。
- record_id str – 精確記錄識別碼篩選。省略時，會傳回任何 ID 的記錄。範圍和描述資料篩選會維持其他限制條件。
退貨：依插入順序排序的記錄。
傳回類型： list[ 記錄 ]

備註

"user_profile" 與 "agent_profile" 為非作用領域記錄類型。對於這些記錄類型，會忽略 thread_id、user_id 和 agent_id，動作者識別會保留在 record.id 中。"thread" 記錄會將繫線 ID 顯示為 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

方法 `list_async` (非同步)

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

參數：
- 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 的記錄。設定為字典時，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"],
}
```
- include_bytes bool – 附加至訊息記錄的影像記錄或影像是否包含其儲存的位元組。省略或 False 時，會傳回影像描述和描述資料，而不會載入位元組。若為直接影像清單，請只使用完全相同的 record_id 和至少一個完全相符的使用者、代理程式或繫線範圍篩選，將此設為 True。此選項不會影響其他記錄類型。
- record_id str – 精確記錄識別碼篩選。省略時，會傳回任何 ID 的記錄。範圍和描述資料篩選會維持其他限制條件。
傳回：在傳回視窗中從最舊到最新排序的記錄。
傳回類型： List[ 記錄 ]

方法 `list_relations`

以其來源至目標方向列出關係。

參數：
- relation_type str – 要比對的選擇性導向關係標籤，例如 "supports" 或 "supersedes"。省略以包含每個關係類型。
- source_record_id str – 要比對的選擇性來源記錄識別碼。
- source_record_type str – 要比對的選擇性來源記錄類型。
- target_record_id str – 要比對的選擇性目標記錄 ID。
- target_record_type str – 要比對的選擇性目標記錄類型。
- limit int | None – 選擇性要傳回之最早建立關係的數目上限。省略時，存放區會使用 MAX_LIST_LIMIT。傳送 None 以傳回每個相符的已儲存關係。
- metadata_filter dict[str, Any] | None – 描述資料篩選。省略時，不會套用任何篩選。設為 None 時，只會傳回中繼資料為 None 的關係。設定為字典時，項目會與 AND 語意結合。巢狀字典使用遞迴完全相符的方式。純量和清單值需要完全相等；請使用 {"tags": {"$array_contains": "prod"}} 來比對陣列成員身分，使用 "$array_contains_any" 來比對任何列出的值，或使用 "$not" 來否定另一個欄位表示式。
- relation_id str – 精確的關係識別碼篩選。省略時，會傳回任何 ID 的關係。其他篩選條件仍會維持其他限制。
傳回：依建立時間和 ID 排序的關係。
傳回類型： list[ RecordRelation ]

範例

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

方法 `list_relations_async` (非同步)

以非同步方式列出來源至目標方向的關係。

參數：
- relation_type str – 要比對的選擇性導向關係標籤，例如 "supports" 或 "supersedes"。省略以包含每個關係類型。
- source_record_id str – 要比對的選擇性來源記錄識別碼。
- source_record_type str – 要比對的選擇性來源記錄類型。
- target_record_id str – 要比對的選擇性目標記錄 ID。
- target_record_type str – 要比對的選擇性目標記錄類型。
- limit int | None – 選擇性要傳回之最早建立關係的數目上限。省略時，實作可能會套用安全的上限，例如 MAX_LIST_LIMIT。傳送 None 以傳回每個相符的已儲存關係。
- metadata_filter dict[str, Any] | None – 描述資料篩選。省略時，不會套用任何篩選。設為 None 時，只會傳回中繼資料為 None 的關係。設定為字典時，項目會與 AND 語意結合。巢狀字典使用遞迴完全相符的方式。純量和清單值需要完全相等；請使用 {"tags": {"$array_contains": "prod"}} 來比對陣列成員身分，使用 "$array_contains_any" 來比對任何列出的值，或使用 "$not" 來否定另一個欄位表示式。
- relation_id str – 直接比對的選擇性關係 ID。
傳回：依建立時間和 ID 排序的關係。
傳回類型： list[ RecordRelation ]

範例

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

方法 `list_thread_messages`

傳回繫線的持續訊息。

參數：
- thread_id str – 應傳回其訊息的繫線 ID。
- 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")
[]

方法 `list_thread_messages_async` (非同步)

非同步列出一個執行緒所儲存的訊息歷史記錄。

參數：
- thread_id str – 應傳回其訊息之繫線的 ID。
- 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 時，請至少提供一個非空格字元。向量搜尋會內嵌此文字；關鍵字搜尋會與預存搜尋文字相符；混合搜尋會使用它來擷取文字和向量。當文字超過設定的區塊大小時，商店會個別搜尋每個查詢區塊，並將排名的結果與相對的排名融合合併。
- 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" 可否定相同欄位的其他欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符。
- include_invalid_results bool – 結果是否包含無效狀態的類似記憶體記錄。預設為 True。傳送 False 以排除它們。
- num_hops int – 每個直接記憶體結果中要遵循的記憶體連結邊緣數目。支援從 0 到 5 的值；0 會停用圖表擴充。擴張將跟隨兩個方向的連結。連結的記錄會繼續遵守要求的範圍、中繼資料、記錄類型及到期篩選。直接訊息、文件及設定檔結果會保留在結果集中，但不會展開圖表。
- max_linked_results int – 連附至每個直接結果之所有躍點的連結記憶體上限。0 會保留沒有連結相關資訊環境的直接結果。預設為 100。
傳回：以增加距離排序的 (record, distance) 組。清單可能包含少於 k 個項目。對於分塊查詢，距離衍生自互惠排名融合分數。
傳回類型： list[tuple[ 記錄，浮動 ]]
發生：
- 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

方法 `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"}} 等組合條件。
- include_invalid_results bool – search 接受的相同生命週期狀態結果選項。
- num_hops int – search 接受的圖形擴充深度相同。
- max_linked_results int – search 接受的每一直接結果 link-memory 限制相同。
傳回：基礎 search 呼叫傳回的 (record, distance) 組。
傳回類型： List[tuple[ 記錄，浮點數 ]]
發出：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 – 選擇性僅限語意有效負載 (Payload)。省略時，會使用 content 來編製語意索引。在支援混合功能的綱要上，這也會變成 Oracle 文字元件所使用的預存搜尋文字。字串值可由商店分區；清單值會被視為呼叫者擁有的區塊，並依原樣寫入至 RECORD_CHUNKS。僅提供 embedding 時，會重複使用現有的搜尋文字。
- 嵌入 list[float] | ndarray | list[list[float] | ndarray] | None –
  
  可選的預先計算嵌入向量或區塊嵌入向量列表。設定本機向量儲存時，會直接使用，不會進行內嵌程式呼叫。傳送 None 以清除儲存的內嵌。提供 content 時，單一向量代表整個取代文字，即使已設定的區塊會分割該文字。除非 index_text 是區塊清單，否則取代文字時會拒絕多個區塊向量。只提供 embedding 時，內嵌計數必須符合記錄的現有區塊資料列。
  
  在 SearchStrategy.VECTOR 中，向量搜尋會依據儲存的內嵌進行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，資料庫備份搜尋會跨預存搜尋文字和 Oracle 管理的文字或混合索引狀態排名，因此更新階段內嵌只會影響任何已設定的本機向量儲存，而不會影響該作用中搜尋策略。如果此儲存設定沒有本機向量儲存，請提供 index_text 而非 embedding 以更新這些文字感知索引的可見文字。僅文字語意更新可能會在這些模式下完全省略 embedding。
- 中繼資料 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 – Optional expiration refresh in days. Omit this argument together with ttl_anchor to preserve the current expiration timestamp. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Refreshing expiration can make an expired record visible again if it has not been purged yet.
- 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。
- 狀態 RecordStatus – 記錄的選擇性取代生命週期狀態。省略以保留目前的狀態。
- 文字 str | None –
  
  content 的別名已不再使用。請傳送 None 以清除儲存的文字，並清除儲存的內嵌。請勿同時提供 content。
  
  已棄用
  
  自 26.8.0 版起已不再使用：此參數在 26.8.0 已不再使用，將會在 27.1 中移除。請改用 content。
傳回數：更新的記錄數 (0 或 1)。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", content="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

方法 `update_async` (非同步)

以非同步方式更新儲存的記錄內容、嵌入資料、中繼資料、時間戳記或到期。

參數：
- record_type str – 要更新之記錄的邏輯類型。
- record_id str – 要更新之記錄的識別碼。
- 內容 str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – 正規取代內容。對於 message 記錄，傳送字串或依序排列的文字和影像內容部分；使用 "" 將訊息取代為空白文字。對於類似記憶體的記錄，商店可以接受 None 來清除儲存的文字和關聯的語意狀態。忽略引數讓內容維持不變。請勿同時提供 text。
- index_text str | list[str] | None – 可選替代語意有效負載 (Payload)，用於重新計算或取代儲存的搜尋狀態，而不變更保存的文字。字串可以由商店內部分區。將非空白字串清單視為來電者擁有的區塊，且不得再次分割。有些實作也可以將此分別保存為混合搜尋文字。對於 image 記錄，此欄位會取代保存的影像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None – 可選的預先計算嵌入向量或區塊嵌入向量清單。提供時，會直接使用，不會呼叫內嵌程式。多個向量需要相符的 index_text 區塊清單或現有的儲存區塊文字資料列。傳送 None，在商店支援時明確清除儲存的內嵌。具有文字感知索引的商店也可以允許沒有內嵌或明確內嵌的語意更新。
- 中繼資料 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 作為記錄建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用存放區或綱要預設存留時間持續時間。在重新整理期間省略 ttl_anchor 時，實行會使用 TimeToLiveAnchor.CREATED_AT。
- 狀態 RecordStatus – 記錄的選擇性取代生命週期狀態。省略以保留目前的狀態。
- 文字 str | None –
  
  content 的別名已不再使用。傳遞 None 以在存放區支援時明確清除儲存的文字。請勿同時提供 content。
  
  已棄用
  
  自 26.8.0 版起已不再使用：此參數在 26.8.0 已不再使用，將會在 27.1 中移除。請改用 content。
傳回數：更新的記錄數 (0 或 1)。0 的傳回值表示未更新任何記錄。
傳回類型：整數
發出：ValueError - 如果存放區的更新有效負載無效，例如省略每個選擇性欄位或提供衝突的語意引數。

方法 `update_relations`

更新可變關係欄位並重新計算端點生命週期狀態。

省略的欄位則維持不變。內建記憶體連結標籤一律會保留其衍生的反向標籤。

參數：
- relation_ids str | list[str] – 要更新之關係的識別碼或識別碼。
- relation_types str | list[str] – 選擇性的取代導向關係標籤或標籤。
- opposite_relation_types str | list[str] – 自訂類型的選擇性取代反向標籤或標籤。
- 時間戳記 str | None | list[str | None] – 選擇性取代時間戳記。傳送 None 以清除。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性取代中繼資料。它會取代現有的描述資料。
傳回：已更新關係的識別碼。
傳回類型： list[str]

範例

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

方法 `update_relations_async` (非同步)

在儲存的關係上以非同步方式更新可變值。

參數：
- relation_ids str | list[str] – 要更新之關係的識別碼或識別碼。
- relation_types str | list[str] – 選擇性的取代導向關係標籤或標籤。省略此項目以保留儲存的標籤。
- opposite_relation_types str | list[str] – 選擇性的取代反向關係標籤或標籤。傳送要取代的標籤，或省略此引數以保留標籤。
- 時間戳記 str | None | list[str | None] – 選擇性取代時間戳記或時間戳記。傳送 None 以清除儲存的時間戳記。
- 中繼資料 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()。

若要擷取一個關係，請自行提供 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

描述兩筆記錄之間的已儲存直接關係。

參數：
- id str – 關係的穩定 ID。
- source_record_id str – 關係之儲存來源的記錄識別碼。
- source_record_type str – 來源記錄的邏輯類型。
- target_record_id str – 關係之儲存目標的記錄 ID。
- target_record_type str – 目標記錄的邏輯類型。
- relation_type str – 其意義遵循已儲存的來源至目標方向的標籤。
- opposite_relation_type str – 遍歷從目標移至來源時使用的標籤。
- timestamp str | None – 與關係關聯的選擇性呼叫程式時戳。
- 中繼資料 dict[str, Any] | None – 隨關係儲存的選用類似 JSON 的中繼資料。
- created_at str – 關係的資料庫建立時戳。

搜尋策略

類別 `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)

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

重新建立

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

不勾選 (_R)

略過受管理綱要驗證並建立。作用中的一般使用者安全相關資訊環境時，對現有的深層資料安全保護存放區使用此原則。在一般使用者相關資訊環境下開啟的存放區需要每個後續資料庫作業的作用中相關資訊環境。其他綱要原則會拒絕一般使用者相關資訊環境，因為綱要週期工作必須透過管理資料庫識別執行。

商店與綱要

儲存 API

商店寫入語意

儲存層次擷取有效負載

類別 oracleagentmemory.core.OracleMemoryStore

方法 add

方法 add_agent (摘要)

方法 add_agent_async (非同步)

方法 add_async (非同步)

方法 add_batches

方法 add_batches_async (非同步)

方法 add_relations (摘要)

方法 add_relations_async (非同步)

方法 add_user (摘要)

方法 add_user_async (非同步)

方法 delete (摘要)

方法 delete_async (非同步)

方法 delete_relations (摘要)

方法 delete_relations_async (非同步)

方法 delete_thread (摘要)

方法 delete_thread_async (非同步)

方法 get (摘要)

方法 get_async (非同步)

方法 get_relation (摘要)

方法 get_relation_async (非同步)

方法 list (摘要)

方法 list_async (非同步)

方法 list_relations (摘要)

方法 list_relations_async (非同步)

方法 list_thread_messages (摘要)

方法 list_thread_messages_async (非同步)

方法 search (摘要)

方法 search_async (非同步)

方法 update (摘要)

已棄用

方法 update_async (非同步)

已棄用

方法 update_relations (摘要)

方法 update_relations_async (非同步)

Oracle DB 商店

類別 oracleagentmemory.core.OracleDBMemoryStore

已棄用

方法 add

方法 add_agent

方法 add_agent_async (非同步)

方法 add_async (非同步)

方法 add_batches

方法 add_batches_async (非同步)

方法 add_relations

方法 add_relations_async (非同步)

方法 add_user

方法 add_user_async (非同步)

方法 delete

方法 delete_async (非同步)

方法 delete_relations

方法 delete_relations_async (非同步)

方法 delete_thread

方法 delete_thread_async (非同步)

方法 get

方法 get_async (非同步)

方法 get_relation

方法 get_relation_async (非同步)

方法 list

方法 list_async (非同步)

方法 list_relations

方法 list_relations_async (非同步)

方法 list_thread_messages

方法 list_thread_messages_async (非同步)

方法 search

方法 search_async (非同步)

方法 update

已棄用

方法 update_async (非同步)

已棄用

方法 update_relations

方法 update_relations_async (非同步)

關係

類別 oracleagentmemory.apis.relations.RecordRelation

搜尋策略

類別 oracleagentmemory.core.dbsearch.SearchStrategy

類別 `oracleagentmemory.core.OracleMemoryStore`

方法 `add`

方法 `add_agent` (摘要)

方法 `add_agent_async` (非同步)

方法 `add_async` (非同步)

方法 `add_batches`

方法 `add_batches_async` (非同步)

方法 `add_relations` (摘要)

方法 `add_relations_async` (非同步)

方法 `add_user` (摘要)

方法 `add_user_async` (非同步)

方法 `delete` (摘要)

方法 `delete_async` (非同步)

方法 `delete_relations` (摘要)

方法 `delete_relations_async` (非同步)

方法 `delete_thread` (摘要)

方法 `delete_thread_async` (非同步)

方法 `get` (摘要)

方法 `get_async` (非同步)

方法 `get_relation` (摘要)

方法 `get_relation_async` (非同步)

方法 `list` (摘要)

方法 `list_async` (非同步)

方法 `list_relations` (摘要)

方法 `list_relations_async` (非同步)

方法 `list_thread_messages` (摘要)

方法 `list_thread_messages_async` (非同步)

方法 `search` (摘要)

方法 `search_async` (非同步)

方法 `update` (摘要)

方法 `update_async` (非同步)

方法 `update_relations` (摘要)

方法 `update_relations_async` (非同步)

類別 `oracleagentmemory.core.OracleDBMemoryStore`

方法 `add`

方法 `add_agent`

方法 `add_agent_async` (非同步)

方法 `add_async` (非同步)

方法 `add_batches`

方法 `add_batches_async` (非同步)

方法 `add_relations`

方法 `add_relations_async` (非同步)

方法 `add_user`

方法 `add_user_async` (非同步)

方法 `delete`

方法 `delete_async` (非同步)

方法 `delete_relations`

方法 `delete_relations_async` (非同步)

方法 `delete_thread`

方法 `delete_thread_async` (非同步)

方法 `get`

方法 `get_async` (非同步)

方法 `get_relation`

方法 `get_relation_async` (非同步)

方法 `list`

方法 `list_async` (非同步)

方法 `list_relations`

方法 `list_relations_async` (非同步)

方法 `list_thread_messages`

方法 `list_thread_messages_async` (非同步)

方法 `search`

方法 `search_async` (非同步)

方法 `update`

方法 `update_async` (非同步)

方法 `update_relations`

方法 `update_relations_async` (非同步)

類別 `oracleagentmemory.apis.relations.RecordRelation`

類別 `oracleagentmemory.core.dbsearch.SearchStrategy`

類別 `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

類別 `oracleagentmemory.core.retention.MemoryRetentionConfig`

類別 `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

類別 `oracleagentmemory.core.SchemaPolicy`