開始使用代理程式記憶體

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

先決條件

確保您符合以下條件：

Oracle AI Database 功能需求

Oracle 代理程式記憶體的資料庫備份存放區需要 Oracle AI Database 23ai 或更新版本 (資料庫版本 23.4 或更新版本)。對於 Oracle AI Vector Search，請將資料庫 COMPATIBLE 初始化參數設為 23.4.0 或更新版本。

選取的搜尋策略有下列其他需求：

在受管理綱要初始化期間，Oracle 代理程式記憶體會先驗證連線的資料庫版本，再執行 DDL，並在選取的搜尋策略無法使用時報告升級動作。

受管理資料庫設定

當綱要擁有者建立或重新建立記憶體存放區時，Oracle Agent Memory Python 套裝程式會準備它所需的受管理資料庫物件。擁有者需要 Oracle CREATE TABLE 和 CREATE PROCEDURE 系統權限。

以綱要設定的綱要擁有者身分連線。使用 schema_owner 的應用程式連線會存取現有的存放區，而且必須使用 SchemaPolicy.REQUIRE_EXISTING；它不會建立或更新擁有者的受管理資料庫物件。

安裝 SDK

您可以在軟體下載頁面找到 oracleagentmemory 的所有版本和支援平台。

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

pip install "oracleagentmemory==26.8.0"

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

記錄與診斷

Oracle AI Agent Memory 會在以 oracleagentmemory 開頭的日誌名稱下，透過標準 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。

存留時間和過期 - 記錄永久清除

透過綱要層次保留預設值和寫入和更新 API 時每一記錄的 ttl_days / ttl_anchor 值組合，Oracle DB 備份的訊息和記憶體即可自動到期。

當 Oracle Agent Memory 建立或升級其管理的綱要時，也會建立每日的 DBMS_SCHEDULER 永久清除工作，實際移除過期的資料列、其擷取區塊，以及支援的來源資料列已不存在的獨立擷取區塊。如果綱要設定需要建立該工作，但資料庫使用者缺少 CREATE JOB，則設定完成時會出現警告：過期的資料列仍會被篩除無法讀取和搜尋，但是過期和孤立的區塊要等到授權的使用者建立工作後才會實際永久清除。在 SchemaPolicy.REQUIRE_EXISTING 下，容許遺漏的永久清除工作，並記錄在 DEBUG 層次。

連結記憶體綱要也會建立一個觸發程式，在刪除連結之後重新驗證存留的記憶體，包括永久清除工作刪除過期的記憶體時，以及 Oracle 將其連結連鎖。綱要擁有者在建立或升級綱要時需要 CREATE TRIGGER；一般程式實際執行使用者不需要該權限。

如需完整的保留模型、MemoryRetentionConfig 設定、整個清除工作驗證查詢、手動建立 DBA 工作，以及使用 TimeToLiveAnchor 的 Python 範例，請參閱使用訊息和記憶體的存留時間。

連結的記憶體綱要權限

link-memory 綱要包含 Oracle SQL 特性圖表，以及刪除連結時將生命週期狀態保持正確的資料庫觸發程式。

如果您設定 memory_store_id，受管理圖表名稱前面會加上與表格相同的方式。例如，memory_store_id="SALES" 會建立 SALES_MEMORY_GRAPH。

APP_SCHEMA 和 APP_USER 值都是預留位置。以您的資料庫使用者名稱取代它們。範例使用大寫，因為未引用的 Oracle ID 會以大寫形式儲存。

  1. 在綱要設定期間，授與綱要擁有者 CREATE PROPERTY GRAPH 和 CREATE TRIGGER。每當必須建立受管理圖表或連結刪除觸發程式時，SchemaPolicy.CREATE_IF_NECESSARY 或 SchemaPolicy.RECREATE 都需要這些參數。 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    如果升級需要建立或重新建立受管理圖表或連結刪除觸發程式，請在稍後 SDK 升級前再次授予它們。

  2. 在一般應用程式執行階段，決定哪位使用者連線至 Oracle：
    • 如果程式實際執行使用者是 APP_SCHEMA，就不需要額外的圖表授權。圖表擁有者可以存取自己的圖表。
    • 如果程式實際執行使用者不同，請在綱要設定之後以 APP_SCHEMA 身分執行下列動作。預設圖表名稱為 MEMORY_GRAPH；設定 memory_store_id 時，請使用字首名稱。 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      程式實際執行使用者也需要其他「Oracle 代理程式記憶體」建置所需的一般資料庫存取。

SchemaPolicy.REQUIRE_EXISTING 會略過第一個步驟，因為它預期圖表和觸發條件已經存在。個別的程式實際執行使用者仍然需要存取受管理特性圖表。

起始記憶體執行處理

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

import oracledb

from oracleagentmemory.core import SchemaPolicy
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,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

注意：依照預設，受管理的 Oracle AI 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.

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

模型相容性

下列大型語言模型 (LLM) 和內嵌模型與 oracleagentmemory 相容。

LLM

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

OCI 代管模型

OpenAI

自主代管 LLM

人類

雙子座

嵌入

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

OCI 代管模型

OpenAI

自行代管的 LLM

雙子座