繫線數目

此頁面顯示具體 Oracle 執行緒處理與開發人員專用訊息協助程式類型。

Oracle 執行緒

類別 `oracleagentmemory.core.OracleThread`

基本：IThread

由 Oracle 商店支援的執行緒。

此實作會內嵌並儲存執行緒訊息與手動新增的記憶，然後支援所有儲存記錄的相似性搜尋。

注意事項

訊息儲存為個別記錄 (每則訊息一筆記錄)。
您可以將搜尋限制在目前的執行緒，或是允許從任何執行緒 (由用戶端控制) 傳回結果。

建立新 OracleThread 執行處理。

參數：
- store OracleMemoryStore – 用來保存內嵌記錄的共用存放區後端。
- thread_id str – 繫線 ID。若未提供，則會產生 UUID。
- user_id str – 與執行緒關聯的使用者識別碼。如果省略，則會產生 UUID。
- agent_id str – 與繫線關聯的代理程式 ID。如果省略，則會產生 UUID。
- 中繼資料 dict[str, Any] | None – 與執行緒相關聯的選擇性類似 JSON 的中繼資料。
- persist_messages_in_config bool – _to_config 是否應包含最近的原始訊息快照。針對使用資料庫存放區的繫線自動設為 False，以避免透過繫線組態匯出訊息表格內容。
- LLM ILlm | None – 選用的 LLM 轉接器，用於記憶體擷取與環境定義摘要更新。提供時，add_messages 會從每個新增的訊息擷取相關記憶體，並將它們儲存為輸入的記憶體記錄 ("memory"、"guideline"、"fact" 或 "preference")。
- memory_extraction_config MemoryExtractionConfig – 選擇性執行緒層次記憶體擷取組態。您可以使用它來控制自動擷取設定值，例如擷取模式、摘要行為、擷取限制，以及是否完全啟用自動擷取。傳送此群組組態或不再使用的內嵌擷取參數，但不能同時傳送兩者。省略時，獨立的 OracleThread() 會在擷取欄位中使用 SDK 預設值，並保持啟用相關資訊環境摘要。
- memory_extraction_window int –
  
  擷取期間要作為 LLM 內容的最新訊息數目 (包括新新增的訊息)。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。預設為 -1。
  
  不再使用
  
  自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- context_summary_update_frequency int –
  
  應更新擷取相關資訊環境摘要的訊息數目。設為 -1，即可使用整批新增的訊息，針對每一 add_messages 呼叫彙總一次。預設為 -1。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- memory_extraction_frequency int –
  
  觸發記憶體擷取的訊息數目。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- memory_extraction_token_limit int –
  
  用於記憶體擷取和執行摘要更新的 LLM 提示大小上限 (記號)。較長的提示會被截斷。若為負數或 0，則會停用提示截斷。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- context_card_token_limit int – LLM 提示的最大輸入記號預算，用於建立內容卡中所含的摘要和主題清單。預設值為 100_000；小於或等於 0 的值會停用提示截斷。
- context_card_type_search_concurrency int – 使用 min_relevant_results_by_type 建立內容卡時，要同時執行的記憶體式記錄搜尋次數上限。預設為 5。
- max_message_token_length int – LLM 備份記憶體擷取和相關資訊環境摘要更新期間所使用之每個訊息的提示時間複本大小上限 (記號)。儲存的訊息內容維持不變。若為負數或 0，則不會執行提示時間縮短。如果提供 LLM，則會彙總過大小的提示複本，而非截斷。
- message_shortening_input_token_limit int – 縮短過大提示複本時，傳送給 LLM 之訊息摘錄的最大大小 (記號)。預設為 30_000 記號。如果為負數或 0，則在 LLM 型縮短期間不會套用輸出界限。
- enable_context_summary bool –
  
  是否要將執行緒的摘要保持在緊密的執行中。如果啟用且提供 llm，就會根據 context_summary_update_frequency 更新摘要。擷取記憶時，目前摘要會提供為內容。獨立 OracleThread() 的預設值為 True。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- memory_extraction_custom_instructionsstr | None –
  
  此執行緒附加至自動記憶體擷取系統提示的選擇性自訂指示。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- memory_extraction_inherit_message_metadata bool | Sequence[str] –
  
  自動擷取的記憶體是否繼承來源訊息的描述資料。傳送 True 以繼承所有訊息描述資料、非字串的最上層訊息描述資料索引鍵順序，僅繼承這些索引鍵，或傳送 False 以停用繼承。預設為 True。如果一個擷取傳送使用多個來源訊息，則選取的描述資料必須符合這些訊息。
  
  資訊：自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。
- 用戶端 OracleAgentMemory | None

範例

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

方法 `add_memory`

新增手動記憶體項目並為其編製索引。

參數：
- content str – 要儲存為記憶體的文字內容。
- memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 要儲存的記憶體類別。支援的值為 "memory"、"fact"、"guideline" 和 "preference"。省略時，內容會儲存為一般 "memory"。
- user_id str – 選擇性的使用者 ID 覆寫。
- agent_id str – 選擇性代理程式 ID 覆寫。
- thread_id str – 選擇性繫線 ID 覆寫。
- memory_id str – 此記憶體資料列的選擇性呼叫程式提供穩定 ID。
- 中繼資料 dict[str, Any] | None – 可選中繼資料以保留儲存的記憶體。
- timestamp str | None – 為此記憶體儲存的選擇性時戳。它代表記憶體建立的時間。省略或 None 時，存放區會使用目前的時間。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，請提供具體的 ISO-8601 時戳值。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- ttl_days int | None – 選擇性存留時間持續時間 (天)。省略此引數以使用綱要預設存留時間持續時間。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. 超過 MemoryRetentionConfig.max_ttl_days 的值會固定至該上限，但有警告。
- ttl_anchor TimeToLiveAnchor – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為資料庫建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為記憶體時戳。時間戳記錨定過期需要此記憶體的具體 ISO-8601 時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
傳回：插入之記憶體記錄的 ID。
傳回類型： str

範例

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

方法 `add_memory_async` (非同步)

以非同步方式新增記憶體。

參數：
- content str – 要儲存的記憶體內容。
- memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 要儲存的記憶體類別。支援的值為 "memory"、"fact"、"guideline" 和 "preference"。省略時，內容會儲存為一般 "memory"。
- user_id str – 選擇性使用者範圍覆寫。
- agent_id str – 選擇性代理程式範圍覆寫。
- thread_id str – 選擇性執行緒範圍置換。
- memory_id str – 選擇性呼叫程式提供的記憶體 ID。省略時，商店會產生 ID。
- 中繼資料 dict[str, Any] | None – 可選中繼資料以保留儲存的記憶體。
- timestamp str | None – 為此記憶體儲存的選擇性時戳。它代表記憶體建立的時間。省略或 None 時，存放區會使用目前的時間。
- ttl_days int | None – 選擇性存留時間持續時間 (天)。省略此引數以使用綱要預設存留時間持續時間，或針對未過期的記憶體傳送 None。
- ttl_anchor TimeToLiveAnchor – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 或 TimeToLiveAnchor.TIMESTAMP。
- **store_kwargs ( 任一 ) – 轉送至備份存放區的實行特定寫入選項。
傳回類型： str

方法 `add_messages`

新增訊息到討論串並建立它們索引。

在背景擷取模式中，此方法會在原始訊息插入後傳回，並在背景嘗試到期背景擷取。

參數：
- messages list[Message | MessageT] – 要附加的訊息清單。訊息可以是 Message 物件或含有 role 和 content 的字典 (以及選擇性的 id)。
- 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性共用或每個訊息中繼資料以供保存。省略時，會使用內嵌於每個訊息中的描述資料。
- ttl_days int | None | list[int | None] – 附加訊息的選擇性存留時間持續時間 (天)。省略此引數以使用綱要預設存留時間持續時間。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to create non-expiring messages when it does not. 超過 MemoryRetentionConfig.max_ttl_days 的值會固定至該上限，但有警告。定量值會套用至完整批次。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為資料庫建立時間，或為每個訊息時戳使用 TimeToLiveAnchor.TIMESTAMP。時間戳記錨定到期需要每個受影響訊息的具體 ISO-8601 時間戳記。省略時，相對於 TimeToLiveAnchor.CREATED_AT 的訊息就會過期。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
傳回：插入之訊息記錄的識別碼。在背景擷取模式中，當傳回這些識別碼時，自動擷取工作可能仍在執行中。
傳回類型： list[str]

注意事項

在 MemoryExtractionMode.BACKGROUND 中，原始訊息會在儲存擷取的記憶體之前保留。如果背景擷取沒有佇列，或者如果設定的佇列容量等待達到其逾時，則插入的原始訊息會維持儲存狀態，且呼叫會繼續而沒有擷取的記憶體，或發出 TimeoutError (視 background_extraction_queue_full_behavior 而定)。

範例

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

方法 `add_messages_async` (非同步)

非同步地新增信件到串列中，並為其建立索引。

在背景擷取模式中，此方法會在原始訊息插入後傳回，並在背景嘗試到期背景擷取。

參數：
- 訊息 list[Message | MessageT]
- 中繼資料 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]

方法 `delete_memory`

依 ID 從這個完全相同的繫線刪除類似記憶體的記錄 (例如記憶體、事實、偏好設定或準則)。

參數： memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會被刪除。
傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
傳回類型：整數

範例

thread.delete_memory("456")
0

方法 `delete_message`

依識別碼從此精確執行緒刪除訊息記錄。

參數： message_id str – 訊息 ID。只會刪除儲存的 thread_id 完全符合此討論串的訊息。
傳回數：刪除的訊息記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
傳回類型：整數

注意事項

刪除訊息只會移除原始訊息記錄。衍生的記憶體並不會被刪除，因為我們尚未追蹤哪個擷取的記憶體來自哪個訊息，所以它們仍然可以搜尋或仍會影響相關資訊環境卡輸出。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。

範例

thread.delete_message("123")
0

方法 `get_context_card`

傳回繫線的相關資訊環境卡物件。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_context_card_async。

參數：
- fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。省略時，會解析為 5。
- max_relevant_results int – 要包含的已擷取長期記錄數上限。省略時，除非提供 min_relevant_results_by_type，否則會解析為 5；在此情況下，它會解析為 5 的較大值，以及要求之每一類型下限的總和。
- max_recent_messages int – 要內嵌動詞的尾端原始訊息數目上限。省略時，會解析為 5。
- min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 為相關資訊環境卡中包含的相關類似記憶體記錄，選擇性的每種類型下限。系統會先搜尋要求的類型，然後從所有支援的類似記憶體的記錄類型中填入剩餘的 max_relevant_results 插槽。支援的金鑰為 "memory"、"fact"、"guideline" 及 "preference"。
- **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
傳回：包含以最新訊息為基礎之繫線相關資訊環境摘要的相關資訊環境卡物件。使用 OracleContextCard.content 來存取轉譯的類似 XML 文字。
傳回類型：OracleContextCard

注意事項

這會使用繫線的預設搜尋範圍與 exact_thread_match=False，因此可以包含來自相同使用者 / 代理程式之其他繫線的相關記憶體。

範例

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

方法 `get_context_card_async` (非同步)

非同步傳回執行緒的環境定義卡物件。

參數：
- fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。省略時，會解析為 5。
- max_relevant_results int – 要包含的已擷取長期記錄數上限。省略時，除非提供 min_relevant_results_by_type，否則會解析為 5；在此情況下，它會解析為 5 的較大值，以及要求之每一類型下限的總和。
- max_recent_messages int – 要內嵌動詞的尾端原始訊息數目上限。省略時，會解析為 5。
- min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 為相關資訊環境卡中包含的相關類似記憶體記錄，選擇性的每種類型下限。系統會先搜尋要求的類型，然後從所有支援的類似記憶體的記錄類型中填入剩餘的 max_relevant_results 插槽。支援的金鑰為 "memory"、"fact"、"guideline" 及 "preference"。
- **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
傳回：繫線的相關資訊環境卡物件。
傳回類型：OracleContextCard

範例

card = await thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
)
len(card.relevant_results or []) <= 5
True

方法 `get_messages`

回傳此討論串的已儲存訊息。

參數：
- start int | None – 開始索引 (0-based)。與 end 一起省略時，會傳回最近連結的視窗。
- end int | None – 結束索引 (不含)。省略時，會傳回最近訊息的連結視窗。傳送 None 或 -1 以明確向 start 要求所有訊息。
傳回：依時間順序排列的訊息。
傳回類型： list[ 訊息 ]

範例

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

方法 `get_messages_async` (非同步)

以非同步方式傳回原始執行緒訊息。

參數：
- start int | None – 選擇性的開始索引。
- end int | None – 選擇性結束索引。
傳回： 原始訊息物件。
傳回類型： list[ 訊息 ]

方法 `get_summary`

傳回執行緒的最佳投入力摘要。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_summary_async。

參數：
- except_last int – 要從摘要排除的最近訊息數目。
- token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過 _estimate_tokens() 預估的預算時，正值才會截斷；傳回的文字會設成 int(token_budget * 3.5) 個字元。非正值會停用輸出界限。
- **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
傳回：包含合成繫線摘要文字的摘要物件。
傳回類型：OracleSummary

範例

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

方法 `get_summary_async` (非同步)

非同步傳回執行緒的最佳投入力摘要。

參數：
- except_last int – 要從摘要排除的最近訊息數目。
- token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過 _estimate_tokens() 預估的預算時，正值才會截斷；傳回的文字會設成 int(token_budget * 3.5) 個字元。非正值會停用輸出界限。
- **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
傳回：包含合成繫線摘要文字的摘要物件。
傳回類型：OracleSummary

方法 `search`

同步搜尋與查詢相關的記錄。

參數：
- query str – 自然語言查詢字串。
- user_id str | None – 選擇性使用者範圍覆寫。省略的值會繼承繫線的預設使用者範圍。
- agent_id str | None – 選擇性代理程式範圍覆寫。省略的值會繼承繫線的預設代理程式範圍。
- thread_id str | None – 選擇性執行緒範圍置換。省略的值會繼承繫線目前的繫線 ID。
- exact_user_match bool – 是否應嚴格比對使用者。
- exact_agent_match bool – 是否應嚴格比對代理程式。
- exact_thread_match bool – 是否應嚴格比對執行緒。
- max_results int – 可選擇傳回的最大結果數。若有提供，至少必須為 1。省略此引數使用預設值 10。當有較少的非到期配對記錄存在時，呼叫可能會傳回少於 max_results。
- record_types list[str] – 要包含的選擇性記錄類型清單，例如 "memory" 或 "message"。
- metadata_filter dict[str, Any] | None –
  
  作為範圍與記錄類型篩選後之其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：
```
metadata_filter={
    "source": "chat",
    "travel": {"need": "transit"},
    "tags": ["trip", "urgent"],
}
```
  若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：
```
metadata_filter={
    "source": "chat",
    "tags": {
        "$array_contains": "trip",
        "$not": {"$array_contains": "archived"},
    },
}
```
- scope SearchScope – 選擇性的預建搜尋範圍。提供 scope 或明確的 ID 和完全相符的引數，不能同時提供兩者。
退貨：依遞減核發排序的搜尋結果。
傳回類型： list[SearchResult]
增加：ValueError – 如果 scope 與明確的 ID 或完全相符引數結合，如果 max_results 小於 1，或者 metadata_filter 既不是說明也不是 None，

注意事項

省略的範圍欄位會繼承此繫線的預設搜尋範圍：完全符合的使用者和代理程式，加上此繫線的目前 user_id、agent_id 和 thread_id。預設執行緒會故意留下 exact_thread_match=False，因此可能會從相同使用者 / 代理程式的其他執行緒傳回相關記錄。傳送 exact_thread_match=True 以將結果限制為目前的繫線。明確的 None 範圍值仍然遵循解析的完全相符規則：exact_*_match=False 會讓該維度維持不限制，而 exact_*_match=True 則只比對儲存的 None 值。

明確的 max_results 值必須至少為 1；省略引數會使用預設值 10。此為上限：當篩選條件的限制性太大、相符的記錄較少或因為實作特定的搜尋行為而導致呼叫傳回的結果可能少於 max_results。

方法 `search_async` (非同步)

以非同步方式搜尋與查詢相關的記錄。

參數：
- query str – 自然語言查詢字串。
- user_id str | None – 選擇性使用者範圍覆寫。省略的值會繼承繫線的預設使用者範圍。
- agent_id str | None – 選擇性代理程式範圍覆寫。省略的值會繼承繫線的預設代理程式範圍。
- thread_id str | None – 選擇性執行緒範圍置換。省略的值會繼承繫線目前的繫線 ID。
- exact_user_match bool – 是否應嚴格比對使用者。
- exact_agent_match bool – 是否應嚴格比對代理程式。
- exact_thread_match bool – 是否應嚴格比對執行緒。
- max_results int – 可選擇傳回的最大結果數。若有提供，至少必須為 1。省略此引數使用預設值 10。
- record_types list[str] – 要包含的選擇性記錄類型清單，例如 "memory" 或 "message"。
- metadata_filter dict[str, Any] | None –
  
  作為範圍與記錄類型篩選後之其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：
```
metadata_filter={
    "source": "chat",
    "travel": {"need": "transit"},
    "tags": ["trip", "urgent"],
}
```
  若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：
```
metadata_filter={
    "source": "chat",
    "tags": {
        "$array_contains": "trip",
        "$not": {"$array_contains": "archived"},
    },
}
```
- scope SearchScope – 選擇性的預建搜尋範圍。提供 scope 或明確的 ID 和完全相符的引數，不能同時提供兩者。
退貨：依遞減核發排序的搜尋結果。
傳回類型： list[SearchResult]
增加：ValueError – 如果 scope 與明確的 ID 或完全相符引數結合，如果 max_results 小於 1，或者 metadata_filter 既不是說明也不是 None，

注意事項

方法 `update_memory`

更新此確切執行緒所擁有的類似記憶體記錄。

參數：
- memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會更新。
- content str – 可選替代內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。不支援傳送 None；請省略 content 以保留目前的值，或使用 delete_memory() 來移除記錄。
- 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
- timestamp str | None – 此記憶體的選擇性新時戳。它代表記憶體建立的時間。省略時，會保留儲存的時間戳記。傳送 None 以清除儲存的時間戳記，並使用在商店中建立記錄的時間。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，取代時戳必須是 ISO-8601 字串。沒有時區的 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 的值會固定至該上限，但有警告。過期的記憶體無法供此繫線 API 使用，因此無法重新整理。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為記憶體建立時間，使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。進行重新整理時省略 ttl_anchor 時，繫線會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要相同呼叫中的替代 ISO-8601 時間戳記，或該格式的現有儲存事件時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
傳回：更新之類似記憶體記錄的 ID。
傳回類型： str

方法 `update_memory_async` (非同步)

以非同步方式更新類似記憶體的記錄。

參數：
- memory_id str – 要更新之類似記憶體記錄的 ID。
- content str – 可選替代內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。不支援傳送 None；請省略 content 以保留目前的值，或使用 delete_memory() 來移除記錄。
- 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
- timestamp str | None – 此記憶體的選擇性新時戳。它代表記憶體建立的時間。省略時，會保留儲存的時間戳記。傳送 None 以清除儲存的時間戳記，並使用在商店中建立記錄的時間。
- ttl_days int | None – 選擇性到期重新整理 (天)。將此引數與 ttl_anchor 一起省略，以保留目前的到期時戳。傳送 None 以清除過期。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。
- **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
傳回：更新之類似記憶體記錄的 ID。
傳回類型： str

範例

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

方法 `update_message`

更新此確切執行緒所擁有的原始訊息記錄。

參數：
- message_id str – 訊息 ID。只會更新其儲存的 thread_id 完全符合此討論串的訊息。
- content str – 可選替代訊息內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。不支援傳遞 None。
- 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
- 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 的值會固定至該上限，但有警告。此繫線 API 無法使用過期的訊息，因此無法重新整理。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。針對訊息建立時間使用 TimeToLiveAnchor.CREATED_AT，或針對儲存的事件時戳使用 TimeToLiveAnchor.TIMESTAMP。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。進行重新整理時省略 ttl_anchor 時，繫線會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要現有的儲存 ISO-8601 訊息時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
傳回：已更新訊息記錄的識別碼。
傳回類型： str

注意事項

省略的欄位會從儲存的記錄中保留。儲存的角色和時戳維持不變。編輯內容會更新原始訊息歷史記錄，若啟用自動擷取功能，可能會讓 SDK 從已編輯訊息和較早的歷史記錄中重新擷取記憶體。在 INLINE 模式中，擷取會在此方法傳回之前完成。在 BACKGROUND 模式中，此方法會在原始訊息更新成功且嘗試背景擷取之後傳回。此後續追蹤工作不會影響後續 add_messages() 呼叫所使用的一般擷取頻率。新增從編輯內容擷取的記憶時，現有擷取的記憶會保留在原位。因為原始訊息更新和之後擷取的任何記憶體寫入都不會異常地發生，所以如果背景工作未排入佇列、設定的佇列容量等待達到其逾時，或稍後擷取工作失敗，則擷取的記憶體仍可反映先前的訊息內容。另請注意，當來源訊息的 TTL 變更時，現有擷取的記憶體會保留其原始到期時間。

範例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

方法 `update_message_async` (非同步)

以非同步方式更新此確切執行緒所擁有的原始訊息記錄。

參數：
- message_id str – 訊息 ID。只會更新其儲存的 thread_id 完全符合此討論串的訊息。
- content str – 可選替代訊息內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。不支援傳遞 None。
- 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
- 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 的值會固定至該上限，但有警告。此繫線 API 無法使用過期的訊息，因此無法重新整理。
- ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。針對訊息建立時間使用 TimeToLiveAnchor.CREATED_AT，或針對儲存的事件時戳使用 TimeToLiveAnchor.TIMESTAMP。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。時間戳記錨定重新整理需要現有的儲存 ISO-8601 訊息時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
- **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
傳回：已更新訊息記錄的識別碼。
傳回類型： str

注意事項

範例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
run_async_in_sync(
    partial(thread.update_message_async, message_id, content="Edited message")
) == message_id
True

方法 `wait_for_memory_extraction`

等待此執行緒的較早背景記憶體擷取。

此方法會等待先前 add_messages()、add_messages_async()、update_message() 或 update_message_async() 透過相同代理程式記憶體元件對此繫線進行的背景擷取。如果其中一個呼叫已經完成，此方法會包含它在等待之前開始的擷取。

此方法不會等待此等待開始後開始擷取、由其他代理程式記憶體元件啟動擷取，或是在其他處理作業中執行的擷取。此等待的擷取失敗計數為已完成。

參數：timeout float | None – 選擇性的等待秒數上限。預設為 300。傳送 None，等待此繫線的待處理擷取完成。
發出：TimeoutError – 在先前的背景擷取完成之前逾時即觸發。
傳回類型：無

範例

thread.wait_for_memory_extraction(timeout=10)

方法 `wait_for_memory_extraction_async` (非同步)

非同步等待更早的背景記憶體擷取。

此方法遵循與 wait_for_memory_extraction() 相同的行為。

參數：timeout float | None – 選擇性的等待秒數上限。預設為 300。傳遞 None 以無限期等待。
發出：TimeoutError – 在先前的背景擷取完成之前逾時即觸發。
傳回類型：無

範例

await thread.wait_for_memory_extraction_async(timeout=10)

注意：delete_message() 只會刪除原始訊息資料列。衍生的記憶卡仍可搜尋或出現在內容卡中。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。從屬端層次繫線刪除會等待該繫線已知的較早接受背景擷取，但該繫線在刪除進行時，並不是相同繫線上其他作業的全域並行屏障。

訊息

類別 `oracleagentmemory.apis.thread.Message`

基礎：object

參數：
- 角色 str
- 內容 str
- 時間戳記 str | None
- 中繼資料 dict[str, Any] | None
- ID str | None

內容卡

類別 `oracleagentmemory.apis.contextcard.ContextCard`

基本：ABC

繫線 API 傳回的抽象相關資訊環境卡物件。

property `content` (摘要)

傳回類型： str
描述：傳回轉譯的內容卡文字。

類別 `oracleagentmemory.core.contextcard.OracleContextCard`

基本：ContextCard

Oracle 執行緒傳回的內容卡。

參數：
- summary str – 卡片中內嵌的摘要文字。
- 主題 Sequence[str] | None – 與執行緒關聯的選擇性擷取主題。
- relevant_results Sequence[SearchResult] | None – 卡片中包含的選擇性擷取持久記錄。
- recent_messages Sequence[Message] | None – 可選擇將最近的原始訊息轉譯到卡片中。
- message_format str – 呈現 recent_messages 時使用的內部範本。

特性 `content`

傳回類型： str
描述：傳回轉譯的內容卡文字。
傳回：類似 XML 的轉譯相關資訊環境卡文字，適用於提示組合。
傳回類型： str

範例

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

特性 `formatted_content`

傳回類型： str
描述：傳回用於提示建立流程的已轉譯內容卡文字。
傳回： 類似 XML 的轉譯內容卡文字。
傳回類型： str

範例

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

摘要

類別 `oracleagentmemory.apis.summary.Summary`

基本：ABC

繫線 API 傳回的抽象繫線摘要物件。

property `content` (摘要)

傳回類型： str
描述：傳回合成摘要文字。

類別 `oracleagentmemory.core.summary.OracleSummary`

基本：Summary

Oracle 執行緒傳回的摘要。

參數： content str – 從繫線記錄合成的摘要文字。

範例

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

特性 `content`

傳回類型： str
描述：傳回合成摘要文字。
傳回：執行緒的摘要文字。
傳回類型： str

範例

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

特性 `formatted_content`

傳回類型： str
描述：傳回用於提示建立流程的轉譯摘要文字。
傳回：呈現的摘要文字。
傳回類型： str

範例

OracleSummary(content="Thread recap").formatted_content
'Thread recap'

繫線數目

Oracle 執行緒

類別 oracleagentmemory.core.OracleThread

不再使用

方法 add_memory

方法 add_memory_async (非同步)

方法 add_messages

方法 add_messages_async (非同步)

方法 delete_memory

方法 delete_message

方法 get_context_card

方法 get_context_card_async (非同步)

方法 get_messages

方法 get_messages_async (非同步)

方法 get_summary

方法 get_summary_async (非同步)

方法 search

方法 search_async (非同步)

方法 update_memory

方法 update_memory_async (非同步)

方法 update_message

方法 update_message_async (非同步)

方法 wait_for_memory_extraction

方法 wait_for_memory_extraction_async (非同步)

訊息

類別 oracleagentmemory.apis.thread.Message

內容卡

類別 oracleagentmemory.apis.contextcard.ContextCard

property content (摘要)

類別 oracleagentmemory.core.contextcard.OracleContextCard

特性 content

特性 formatted_content

摘要

類別 oracleagentmemory.apis.summary.Summary

property content (摘要)

類別 oracleagentmemory.core.summary.OracleSummary

特性 content

特性 formatted_content

類別 `oracleagentmemory.core.OracleThread`

方法 `add_memory`

方法 `add_memory_async` (非同步)

方法 `add_messages`

方法 `add_messages_async` (非同步)

方法 `delete_memory`

方法 `delete_message`

方法 `get_context_card`

方法 `get_context_card_async` (非同步)

方法 `get_messages`

方法 `get_messages_async` (非同步)

方法 `get_summary`

方法 `get_summary_async` (非同步)

方法 `search`

方法 `search_async` (非同步)

方法 `update_memory`

方法 `update_memory_async` (非同步)

方法 `update_message`

方法 `update_message_async` (非同步)

方法 `wait_for_memory_extraction`

方法 `wait_for_memory_extraction_async` (非同步)

類別 `oracleagentmemory.apis.thread.Message`

類別 `oracleagentmemory.apis.contextcard.ContextCard`

property `content` (摘要)

類別 `oracleagentmemory.core.contextcard.OracleContextCard`

特性 `content`

特性 `formatted_content`

類別 `oracleagentmemory.apis.summary.Summary`

property `content` (摘要)

類別 `oracleagentmemory.core.summary.OracleSummary`

特性 `content`

特性 `formatted_content`