開始使用代理程式記憶體

本文將引導您完成安裝「代理程式記憶體」及執行基本記憶體作業，包括儲存及擷取使用者相關資訊環境。

必備條件

確保您符合以下條件：

安裝 SDK

若要安裝「代理程式記憶體」，請執行：

pip install "oracleagentmemory==26.6.0"

使用 pip 進行安裝時，會在支援的平台上提取預先建立的二進位操控盤。

記錄與診斷

從 oracleagentmemory 開始，Oracle AI 代理程式記憶體會透過日誌記錄器名稱下的標準 Python 記錄發出診斷訊息。SDK 不會設定處理程式或日誌層次；應用程式可以將這些日誌遞送至其現有主控台、檔案或可觀察性管線。部分日誌記錄使用 Python 日誌記錄的 extra 欄位進行安全結構化診斷，可透過結構化記錄處理程式擷取。

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

若要在受控制環境中進行疑難排解，請啟用 DEBUG 日誌：

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

將生產部署保持在非 DEBUG 層級。DEBUG 日誌是供開發及支援診斷之用，不應將日誌訊息文字視為穩定的公用 API。

起始記憶體執行處理

設定內嵌程式、LLM 以及資料庫連線，以建立 OracleAgentMemory 執行處理。

import oracledb

from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(connection=db_pool, embedder=embedder, llm=llm)

注意：依照預設，受管理的 Oracle Database 綱要不會設定訊息和記憶體的保留期間。將 MemoryRetentionConfig 或每一記錄存留時間設定值設定為使用不同的保留期間。如需詳細資訊，請參閱使用訊息和記憶體的存留時間。

儲存記憶體項目

首先，請先建立執行緒、新增訊息以及儲存使用者的記憶體項目。

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

擷取記憶體項目

使用使用者範圍的查詢搜尋記憶體。

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

輸出：

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

注意：顯示的輸出為圖解式。未來版本可能會傳回其他結果類型、欄位或排序。

模型相容性

自 2026 年 4 月起，下列大型語言模型 (LLM) 與內嵌模型與 oracleagentmemory 相容。

LLM

下列大型語言模型 (LLM) 已確認相容。

OCI 代管模型

OpenAI

自主代管 LLM

人類

雙子座

嵌入

已確認下列內嵌模型相容。

OCI 代管模型

OpenAI

雙子座