代理程式記憶體

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

Oracle 代理程式記憶體

類別 oracleagentmemory.core.OracleAgentMemory

基本：IAgentMemory

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

建立記憶體從屬端。

• 參數：
  • store OracleMemoryStore – 選擇性的預先配置存放區執行處理。提供時，從屬端會直接使用此存放區，而不是建立自己的存放區。當呼叫程式在 OracleAgentMemory 顯示的建構子選項之外需要儲存組態時，此功能會很有用。
  • connection object – 選擇性 Oracle DB 連線 / 集區。提供時，會使用資料庫存放區。傳送原始連線可為此從屬端執行處理啟用單一階段作業模式，因此並行要求應改用連線集區。省略時，呼叫者必須傳送明確的 store。
  • embedder IEmbedder | str – Embedder 實作實例或 LiteLLM 內嵌模型識別碼。省略時，不會附加內嵌器，且呼叫者必須透過較低層級的存放區 API 提供預先計算的向量。
  • LLM ILlm – 供執行緒用於記憶體擷取和 / 或環境定義摘要的選擇性 LLM 配接器。依照預設，從此從屬端建立或載入的繫線需要 LLM，因此可針對持久的記憶體處理最新的訊息。請在此處傳送 llm、在 create_thread 中稍後提供，或選擇退出 extract_memories=False。
  • extract_memories bool – 若為 True，則此用戶端建立或載入的執行緒需要 LLM，而自動記憶體擷取則會維持啟用狀態。設為 False 以停用自動記憶體擷取，並允許這些繫線在沒有 LLM 的情況下運作。預設為 True，因此遺漏擷取 LLM 會快速失敗。
  • schema_policy SchemaPolicy | str – 資料庫綱要設定原則，只在從 connection 建構資料庫存放區時使用。預設為 SchemaPolicy.REQUIRE_EXISTING。
  • table_name_prefix str – 僅在從 connection 建構資料庫存放區時，才使用選擇性的資料庫表格 / 索引前置碼。
• 發出：ValueError – 如果提供衝突的存放區組態，例如同時傳送 store 和 connection、沒有資料庫連線的資料庫特定選項，或同時省略 store 和 connection。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

方法 add_agent

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

• 參數：
  • agent_id str – 代理程式 ID。
  • 資訊 str – 代理程式的任意格式資訊。
• 傳回：預存代理程式設定檔的 ID。
• 傳回類型： str

注意事項

客服員資料檔記錄會儲存在用戶端層級商店中。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

方法 add_memory

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

• 參數：
  • content str – 要保留的記憶體內容。
  • user_id str – 與已儲存記憶體關聯的選擇性範圍識別碼。
  • agent_id str – 與儲存的記憶體關聯的選擇性範圍識別碼。
  • thread_id str – 與儲存的記憶體關聯的選擇性範圍識別碼。
  • memory_id str – 此記憶體資料列的選擇性呼叫程式提供穩定 ID。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之記憶體記錄的 ID。
• 傳回類型： str

範例

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_user

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

• 參數：
  • user_id str – 使用者 ID。
  • 資訊 str – 使用者的任意格式資訊。
• 傳回：已儲存使用者設定檔的 ID。
• 傳回類型： str

注意事項

使用者基本資料記錄儲存在用戶端層級儲存區中 (與特定執行緒無關)。

範例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

方法 create_thread

建立並登錄執行緒。

• 參數：
  • thread_id str – 繫線 ID。如果省略，則會產生新的項目。
  • user_id str – 附加至此執行緒記錄的使用者識別碼。如果省略，則會產生新的項目。
  • agent_id str – 附加至此執行緒記錄的代理程式識別碼。如果省略，則會產生新的項目。
  • LLM ILlm – 此執行緒的選擇性 LLM 覆寫。如果省略，則會使用在施工階段設定的用戶端層級 LLM。依照預設，從屬端或繫線必須提供 LLM，才能執行自動記憶體擷取。請在此或用戶端上設定 extract_memories=False 以選擇退出該要求。
  • extract_memories bool – 可選的依執行緒覆寫功能，用於自動擷取記憶體。當 True 時，此繫線需要 LLM 才能執行自動擷取。設為 False 以停用此繫線的自動擷取，並允許沒有 LLM 的作業。省略時，會使用用戶端層級的 extract_memories 設定。
  • max_message_token_length int – 在記憶體擷取和相關資訊環境摘要更新期間截斷或摘要之前的提示時間訊息大小上限。儲存的訊息內容維持不變。省略時，預設為 15_000 記號。
  • message_shortening_input_token_limit int – 縮短過大提示時間訊息複本時，傳送給 LLM 之訊息摘錄的最大大小 (記號)。省略時，預設為 30_000 記號。
  • memory_extraction_window int – 記憶體擷取期間要包括的最新訊息數目。設為 -1，即可使用整批新增的訊息，對每一 add_messages 呼叫執行一次擷取。省略時，預設為 -1。
  • context_summary_update_frequency int – 內容摘要重新整理的頻率。設為 -1，即可使用整批新增的訊息，對每一 add_messages 呼叫執行一次摘要更新。在 add_messages 期間重新整理的繫線摘要描述資料會重複使用相同的節奏。省略時，預設為 4。
  • memory_extraction_frequency int – 記憶體擷取更新頻率。設為 -1，即可使用整批新增的訊息，對每一 add_messages 呼叫執行一次擷取。省略時，預設為 -1。
  • memory_extraction_token_limit int – 記號的擷取提示大小上限。省略時，預設為 100_000。
  • enable_context_summary bool – 是否保留此執行緒的執行中相關資訊環境摘要。
  • **kwargs ( 任一 ) – 其他實行特定的繫線選項。
• 傳回：OracleThread 。
• 傳回類型：OracleThread
• 摘要：ValueError – 如果沒有 LLM 可用於自動記憶體擷取，且繫線和從屬端未設定 extract_memories=False。

範例

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_memory

依 ID 刪除記憶體記錄。

• 參數： memory_id str – 記憶體 ID。
• 傳回：已刪除的記憶體列數 (0 或 1)。
• 傳回類型：整數

範例

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_thread

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

• 參數：
  • thread_id str – 要刪除的繫線 ID。
  • allow_non_existing bool – 當 True 時，刪除遺漏的執行緒會被視為 no-op。
• 傳回：已刪除的繫線資料列數目 (0 或 1)。
• 傳回類型：整數

範例

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

方法 get_thread

擷取先前建立的執行緒。

• 參數：
  • thread_id str – 建立執行緒時使用的識別碼。
  • LLM ILlm – 選用的 LLM 會覆寫重新開啟的執行緒。省略時，會使用在施工期間設定的用戶端層級 LLM。
  • extract_memories bool – 可選擇覆寫重新開啟執行緒上的自動記憶體擷取。省略時，會使用從屬端層次 extract_memories 設定。
  • max_message_token_length int – 在記憶體擷取和相關資訊環境摘要更新期間截斷或摘要之前，選擇性覆寫提示時間訊息大小上限。儲存的訊息內容維持不變。
  • message_shortening_input_token_limit int – 縮短過大提示時間訊息複本時，傳送給 LLM 之訊息摘錄的最大大小 (記號) 可選擇性覆寫。
  • memory_extraction_window int – 記憶體擷取期間使用之最近訊息數目的選擇性覆寫。
  • context_summary_update_frequency int – 內容摘要重新整理頻率的選擇性覆寫。
  • memory_extraction_frequency int – 記憶體擷取更新頻率的選擇性覆寫。
  • memory_extraction_token_limit int – 權杖中擷取提示大小上限的選擇性覆寫。
  • enable_context_summary bool – 重新開啟之繫線是否應保留執行中的相關資訊環境摘要的選擇性覆寫。
• 傳回：從存放區描述資料重新建構的繫線處理。
• 傳回類型：OracleThread
• 發生：
  • KeyError – 如果此用戶端實例未知執行緒 ID。
  • ValueError – 如果沒有可供自動記憶體擷取使用的 LLM，且用戶端未設定 extract_memories=False。

注意事項

優先採用明確的每通電話置換。若省略程式實際執行覆寫，重新開啟的繫線會在回到 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'