在 Oracle Autonomous AI Database 中使用 Oracle Agent Memory

本指南說明如何將 oracleagentmemory 連線至 Oracle Autonomous Database (ADB)。

在本指南中，您將學習如何：

準備 Oracle 代理程式記憶體的 ADB 綱要使用者。
使用無公事包 TLS 或使用 mTLS 公事包連線。
初始化受管理記憶體綱要，並儲存及搜尋記憶體。

提示：如需設定套裝程式，請參閱開始使用代理程式記憶體。若要改為對容器化本機資料庫執行 Oracle 代理程式記憶體，請依照在本機執行 Oracle AI Database 。

先決條件

您需要一個支援 Oracle AI Vector Search (Oracle AI Database 23ai 或更新版本) 的可用 Oracle Autonomous AI Database、一個可以建立資料庫使用者的 ADB 管理員，以及一個已安裝 oracleagentmemory 的 Python 環境。如果您還沒有資料庫，請遵循 Oracle 的 Autonomous AI Database 佈建指南。

「Oracle 代理程式記憶體」會使用您應用程式所提供的連線或集區；它不會設定資料庫傳輸安全本身。ADB 支援兩種安全連線選項：

TLS (不含公事包) 適用於大部分的新應用程式。它使用資料庫證明資料並加密連線。在使用 IP 允許清單 (ACL) 或專用端點之前，請先設定讓應用程式能夠連線資料庫。TLS 保護連線；ACL 或專用端點可控制哪些網路可以連線資料庫。
當 ADB 需要 mTLS 或您的組織需要從屬端憑證認證時，搭配公事包的共同 TLS (mTLS) 就適用。

在生產環境中使用個別資料庫使用者

在實際執行部署中使用兩個 ADB 資料庫使用者：

綱要擁有者可建立、升級及擁有「Oracle 代理程式記憶體」表格和索引。
應用程式使用者會在應用程式讀取和寫入記憶體時連線。僅將此使用者授予綱要擁有者物件所需的權限。

請勿使用綱要擁有者的證明資料來執行應用程式。只有在設定或升級受管理綱要時才使用。本指南會先建立綱要擁有者。設定之後，請使用 SchemaPolicy.REQUIRE_EXISTING 設定應用程式使用者。疑難排解指南列出應用程式使用者所需的物件授權。

開始寫入受管理表格的應用程式執行處理之前，請先以單一維護作業的方式執行每一個綱要建立或升級。針對作業使用一個綱要擁有者連線；不允許多個從屬端同時執行 SchemaPolicy.CREATE_IF_NECESSARY。成功之後，應用程式執行處理應該使用 SchemaPolicy.REQUIRE_EXISTING。

建立 ADB 綱要使用者

使用專用 ADB 資料庫使用者擁有「Oracle 代理程式記憶體」綱要。在 OCI 主控台中，開啟資料庫動作，以 ADMIN 身分登入，然後開啟 SQL 工作表。建立具有強式密碼的使用者、授予受管理綱要設定所使用的權限，以及為使用者設定連結的儲存體配額：

CREATE USER oam_owner IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT DWROLE TO oam_owner;
ALTER USER oam_owner QUOTA 1G ON DATA;

DWROLE 包括 Oracle Agent Memory 使用的一般物件建立權限，包括 CREATE TABLE、CREATE SEQUENCE、CREATE PROCEDURE 以及 CREATE JOB。CREATE JOB 可讓 Oracle 代理程式記憶體建立排定的工作，在記錄過期後永久刪除記錄。

1G 配額是本指南的起始限制，不是生產大小調整建議。根據您預期儲存的記憶體大小和保留原則選取限制。監督儲存體使用狀況並視需要增加配額；當使用者達到配額時寫入失敗。ADB 會管理表格空間，因此本指南不會建立表格空間。

使用不含公事包的 TLS 連線

在 OCI 主控台中，開啟 ADB 詳細資訊頁面。在網路底下，設定 ACL 以允許應用程式的輸出 IP 位址，或使用專用端點。然後編輯雙向 TLS (mTLS) 認證，清除需要雙向 TLS (mTLS) 認證，並等待資料庫返回 Available。

開啟資料庫連線，選取 TLS 認證底下的 TLS ，然後選取列出的連線服務之一。服務通常具有 myadb_low、myadb_medium 和 myadb_high 等名稱；它們會選取 ADB 如何在連線之間共用資料庫資源。從資料庫管理員針對應用程式的工作負載建議的服務層次開始，然後複製其連線字串。將它和資料庫證明資料儲存在加密密碼管理系統中：

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='<copied TLS connection string>'

請完全依照複製的方式使用 TLS 描述區。若無公事包，mTLS 描述區便無法運作。

此範例會建立一個連線集區，這是一個可重複使用的資料庫連線群組。當 ORACLE_MEMORY_ADB_USE_MTLS 不是 true 時，這些連線會使用 TLS。它使用 SchemaPolicy.CREATE_IF_NECESSARY 進行第一次設定；在綱要就緒之後，在一般應用程式啟動時使用 SchemaPolicy.REQUIRE_EXISTING。

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"

停用自動記憶體擷取功能，只會讓此連線範例保持焦點。設定 LLM，並在應用程式需要自動持久記憶體擷取時啟用擷取功能。

API 參考： OracleAgentMemory

綱要原則

使用 mTLS 公事包連線

如果 ADB 網路組態需要 mTLS，請使用此選項。在 OCI 主控台中，開啟資料庫連線，選取執行處理公事包並進行下載。將公事包解壓縮至未存入來源控制的受保護目錄。Oracle 文件建議限制公事包檔案的檔案權限 (例如，在 Linux 或 Unix 上使用 chmod 600)。

匯出資料庫證明資料、公事包目錄以及公事包下載密碼。ORACLE_MEMORY_WALLET_PASSWORD 是您在下載公事包 ZIP 檔案時所提供的密碼；它不是資料庫使用者的密碼。將 ORACLE_MEMORY_DB_DSN 設為公事包 tnsnames.ora 檔案中的服務別名，例如 myadb_low。請勿將 ADB 主控台中的長 TLS 連線字串用於此公事包組態：

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='myadb_low'
export ORACLE_MEMORY_WALLET_DIR='/secure/path/to/wallet'
export ORACLE_MEMORY_WALLET_PASSWORD='<wallet-download-password>'
export ORACLE_MEMORY_ADB_USE_MTLS='true'

在 python-oracledb 精簡模式中，公事包目錄需要 tnsnames.ora 和 ewallet.pem。將 ORACLE_MEMORY_ADB_USE_MTLS 設定為 true 會讓範例在起始 OracleAgentMemory 之前建立 mTLS 集區。

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)

在 ADB 中儲存並搜尋記憶體

Oracle 代理程式記憶體從屬端設定任一集區之後，請建立繫線、新增持久記憶體，然後再搜尋回該記憶體。

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)

API 參考： OracleAgentMemory

繁體中文

OracleSearch 結果

結論

在本指南中，我們會瞭解如何準備 ADB 使用者、選取無公事包 TLS 或 mTLS、使用 python-oracledb 集區連線 Oracle 代理程式記憶體，以及驗證是否可以儲存和擷取 ADB 的記憶體。

→ 將 Oracle 代理程式記憶體連線到 ADB 之後，您現在可以繼續進行儲存並搜尋記憶體。

完整代碼

本指南中包含完整的範例，可供您複製和執行。

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Oracle Autonomous AI Database
#-------------------------------------------------------------

##Configure an Autonomous AI Database TLS connection pool

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"



##Configure an Autonomous AI Database mTLS connection pool

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)



##Store and search memory in Autonomous AI Database

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)