代理程式記憶體

此頁面顯示具體 Oracle AI 代理程式記憶體實行。

Oracle 代理程式記憶體

注意：OracleAgentMemory.delete_thread() 是執行緒作用領域重疊清除的支援路徑。它會將執行緒與相關聯的訊息、持久記憶體及受管理的擷取資料一起移除。大於 OracleThread.delete_message()，只刪除原始訊息資料列。在刪除執行緒之前，它會等待此從屬端已知該執行緒的較早接受背景擷取。進行刪除時，它不會序列化相同執行緒的每個並行作業。

類別 oracleagentmemory.core.OracleAgentMemory

基本：IAgentMemory

由 Oracle DB 或來電者提供的存放區所支援的代理程式記憶體從屬端。

建立記憶體從屬端。

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

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

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

範例

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

使用資料庫內內嵌模型來利用 Oracle 混合索引搜尋：

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

方法 add_agent

新增專員資料檔記錄至商店。

注意事項

客服員資料檔記錄會儲存在客戶層級商店中，故意不受範圍限制。傳回的記錄識別碼與應用程式用作 agent_id 的公用識別碼相同。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

方法 add_memory

在記憶體系統中新增屬於指示之使用者、代理程式以及繫線的記憶體。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

方法 add_memory_async (非同步)

非同步新增記憶體記錄至用戶端。

方法 add_user

新增使用者資料檔記錄至商店。

注意事項

使用者基本資料記錄儲存在用戶端層級儲存區中，故意不受範圍限制。傳回的記錄識別碼與應用程式用作 user_id 的公用識別碼相同。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

方法 close

關閉代理程式記憶體元件。

關閉會停止接受新的背景擷取工作，並等待擱置中背景記憶體擷取完成到設定的逾時。如果逾時到期，即使部分背景擷取工作仍未完成，close() 仍會傳回。方法為冪等。

範例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

方法 close_async (非同步)

非同步關閉代理程式記憶體元件。

此方法遵循與 close() 相同的關閉行為。如果逾時到期，則可以在背景擷取工作仍在執行中時傳回。

範例

await client.close_async()

方法 create_thread

建立與註冊執行緒。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

方法 delete_agent

依識別碼刪除專員資料檔記錄。

注意事項

階層式刪除是在後備儲存中進行計畫與執行，因此設定檔刪除與所有範圍的下階刪除都會在一個商店作業中進行。執行重疊刪除之前，此方法會等待此代理程式記憶體元件當時已知之擁有繫線的先前背景擷取。它不會等到等待開始後才接受工作，也不會等到其他代理程式記憶體元件或處理作業啟動工作。不支援在進行刪除時使用並行動作者作用領域。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

方法 delete_memory

依識別碼刪除類似記憶體的記錄 (例如，記憶體、事實、偏好或準則)。

範例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

方法 delete_memory_async (非同步)

以非同步方式依識別碼刪除類似記憶體的記錄 (例如記憶體、事實、偏好或準則)。

方法 delete_thread

刪除所有與執行緒識別碼相關聯的記錄。

注意事項

當您需要完全移除執行緒的保留時，請使用此作業。備份存放區會將繫線連同相關的繫線作用領域訊息、持久的記憶體，以及受管理的擷取資料一起刪除。這與 OracleThread.delete_message() 不同，它只會移除原始訊息記錄，不會串聯至從該訊息建立的衍生記憶體。刪除繫線之前，此方法會等待先前已透過此代理程式記憶體元件接受該繫線的背景擷取。在等待開始後或由其他代理程式記憶體元件或處理作業啟動工作之後，它就不會等待接受背景工作。不支援在進行刪除時同時使用相同的繫線。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

方法 delete_user

依識別碼刪除使用者設定檔記錄。

注意事項

階層式刪除是在後備儲存中進行計畫與執行，因此設定檔刪除與所有範圍的下階刪除都會在一個商店作業中進行。執行重疊刪除之前，此方法會等待此代理程式記憶體元件當時已知之擁有繫線的先前背景擷取。它不會等到等待開始後才接受工作，也不會等到其他代理程式記憶體元件或處理作業啟動工作。不支援在進行刪除時使用並行動作者作用領域。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

方法 get_thread

擷取先前建立的執行緒。

注意事項

優先採用明確的每通電話置換。若省略程式實際執行覆寫，重新開啟的繫線會在回到 SDK 預設值之前使用保存的程式實際執行組態 (若有的話)。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'

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

注意事項

明確的 None 範圍值仍然遵循解析的完全相符規則：exact_*_match=False 會讓該維度維持不限制，而 exact_*_match=True 則只會比對該維度上未限制範圍的記錄。

方法 search_async (非同步)

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

注意事項

明確的 None 範圍值仍然遵循解析的完全相符規則：exact_*_match=False 會讓該維度維持不限制，而 exact_*_match=True 則只會比對該維度上未限制範圍的記錄。

方法 update_memory

依識別碼更新儲存的類似記憶體記錄。

注意事項

省略的欄位會從儲存的記錄中保留。儲存的範圍維持不變。描述資料取代是整個物件取代，而非遞迴的 JSON 合併。

方法 update_memory_async (非同步)

以非同步方式依識別碼更新儲存的類似記憶體記錄。

注意事項

省略的欄位則維持不變。此 API 不支援範圍更新。描述資料取代是整個物件取代，而非遞迴的 JSON 合併。

方法 update_thread

保存繫線描述資料和持續的程式實際執行組態更新。

注意事項

程式實際執行組態是從儲存的對話繫線以及傳遞給此呼叫的明確覆寫 (在保存結果之前符合 get_thread 語意) 進行解析。省略的中繼資料和執行時期組態更新會從儲存的資料解析，而不是從任何先前載入的 OracleThread 執行處理解析，而且只會寫入明確提供的中繼資料更新或永久的 Runtime-config 覆寫。描述資料取代是整個物件取代，而非遞迴的 JSON 合併。繫線擁有權無法透過此 API 變動，因此 user_id 和 agent_id 維持不變。可變的程式實際執行狀態 (例如擷取計數器) 會保持不變。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

方法 wait_for_memory_extraction

等待此從屬端啟動的較早背景記憶體擷取。

此方法會等待已經透過此 OracleAgentMemory 執行處理 (此代理程式記憶體元件擁有的所有繫線) 進行背景擷取。這並不會等到此等待開始、其他代理程式記憶體元件啟動擷取，或是在其他處理作業中執行的擷取啟動後才開始擷取。此等待的擷取失敗計數為已完成。

範例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

方法 wait_for_memory_extraction_async (非同步)

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

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

範例

await client.wait_for_memory_extraction_async(timeout=10)

記憶體擷取

類別 oracleagentmemory.core.MemoryExtractionConfig

基礎：object

自動擷取記憶體的群組設定值。

將此物件傳送至 OracleAgentMemory、create_thread、get_thread 或 update_thread，以設定自動擷取。省略的欄位會繼承自下一個更大的設定。例如，在沒有 memory_extraction_frequency 的情況下建立的繫線會使用代理程式記憶體元件預設值，而元件預設值會回到 SDK 預設值。

範例

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

類別 oracleagentmemory.core.MemoryExtractionMode

基礎：str、Enum

控制自動記憶體擷取工作執行的時間。

INLINE 會在傳回寫入方法之前執行自動擷取。BACKGROUND 會在原始寫入成功後傳回，並在背景中嘗試到期擷取工作。背景擷取最有效率：衍生的記憶體可能會在稍後出現，或者如果背景工作無法完成，永遠不會寫入。

背景 = 'BACKGROUND'

在原始訊息持續性之後返回，並在背景工作中執行最佳效果擷取。

內嵌 = 'INLINE'

在傳回 write 方法之前執行擷取。

類別 oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

基礎：str、Enum

控制背景擷取無法及時排入佇列時發生的狀況。

刪除 = 'DROP'

記錄警告並在佇列容量無法使用時立即繼續。

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

等待佇列容量到設定的逾時為止，然後記錄警告並繼續。

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

等待佇列容量到設定的逾時為止，然後發出 TimeoutError。