在本機執行 Oracle AI Database

本指南說明如何使用 Docker 或 Podman 在本機執行 Oracle AI Database，並將 oracleagentmemory 連線至該資料庫。

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

• 使用 Docker 或 Podman 提取並啟動 Oracle AI Database。
• 選擇性地建立 oracleagentmemory 的本機 Oracle 使用者和表格空間。
• 使用 LiteLLM 內嵌和 LLM 轉接器設定 Oracle 支持的 oracleagentmemory API。
• 請透過第二個 API 執行處理重新開啟相同的繫線，以驗證記錄是否持續存在。

先決條件

請安裝 Docker 或 Podman，並確定 Shell 中有對應的 CLI。然後從 Oracle Container Registry 提取 Oracle AI Database Free Lite 映像檔。

為 Oracle SYSTEM 使用者選取一個強式密碼，然後在啟動容器之前匯出：

• Docker
• Podman

export ORACLE_PWD='<your-secure-password>'
docker pull container-registry.oracle.com/database/free:latest-lite

export ORACLE_PWD='<your-secure-password>'
podman pull container-registry.oracle.com/database/free:latest-lite

啟動 Oracle AI Database 容器

建立具名磁碟區，讓資料庫檔案在重新啟動後仍會保留：

• Docker
• Podman

docker volume create OracleDBData

podman volume create OracleDBData

然後啟動容器：

• Docker
• Podman

docker run -d \
  --name oracle-free-lite \
  -p 1521:1521 \
  -e ORACLE_PWD="$ORACLE_PWD" \
  -v OracleDBData:/opt/oracle/oradata \
  container-registry.oracle.com/database/free:latest-lite

podman run -d \
  --name oracle-free-lite \
  -p 1521:1521 \
  -e ORACLE_PWD="$ORACLE_PWD" \
  -v OracleDBData:/opt/oracle/oradata \
  container-registry.oracle.com/database/free:latest-lite

注意：如果 Podman 在 RHEL 發生 SELinux 標籤問題，您可能會想要查看 security-opt 組態參數。

然後依照容器日誌進行，直到資料庫報告已就緒為止。

• Docker
• Podman

docker logs -f oracle-free-lite

podman logs -f oracle-free-lite

日誌包含 DATABASE IS READY TO USE! 時，監聽器和預設的可插拔資料庫會啟動。

秘訣：資料庫就緒之後，請從容器內部執行簡單查詢來確認 PDB 已開啟。

• Docker
• Podman

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

podman exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

SELECT sys_context('USERENV', 'CON_NAME') AS container_name FROM dual;

您應該會看到 FREEPDB1。

然後輸入 exit，然後按 Enter 離開 SQL*Plus。

[ 選擇性 ] 建立本機 Oracle 使用者

注意：如果您已有 Oracle AI Database 和應用程式使用者，請略過此區段並繼續對照本機資料庫嘗試 oracleagentmemory 。如需 API 本身較短的快速入門樣式逐步解說，請參閱儲存和搜尋記憶體。

本指南中的範例命令檔使用專用的本機資料庫使用者：

DB_USER = os.environ.get("ORACLE_MEMORY_DB_USER", "dmuser")
DB_PASSWORD = os.environ["ORACLE_MEMORY_DB_PASSWORD"]
DB_CONNECT_STRING = os.environ.get(
    "ORACLE_MEMORY_DB_CONNECT_STRING",
    "localhost:1521/FREEPDB1",
)

為該應用程式使用者選取一個強式密碼，然後在執行命令檔之前匯出該密碼：

export ORACLE_MEMORY_DB_PASSWORD='<your-app-user-password>'

然後在 PDB 內建立使用者：

• Docker
• Podman

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

podman exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

CREATE TABLESPACE dmuser_ts
DATAFILE '/opt/oracle/oradata/FREE/FREEPDB1/dmuser_ts01.dbf'
SIZE 200M
AUTOEXTEND ON NEXT 100M
SEGMENT SPACE MANAGEMENT AUTO;

CREATE USER dmuser IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW,
      CREATE PROCEDURE, CREATE TRIGGER, CREATE PROPERTY GRAPH,
      CREATE JOB TO dmuser;
ALTER USER dmuser DEFAULT TABLESPACE dmuser_ts;
ALTER USER dmuser QUOTA UNLIMITED ON dmuser_ts;

將 CHOOSE_A_STRONG_PASSWORD 取代為您儲存在 ORACLE_MEMORY_DB_PASSWORD 中的相同密碼值。

然後驗證使用者已就緒：

SELECT tablespace_name, contents
FROM dba_tablespaces
WHERE tablespace_name = 'DMUSER_TS';

SELECT username, account_status, default_tablespace, temporary_tablespace
FROM dba_users
WHERE username = 'DMUSER';

SELECT privilege
FROM dba_sys_privs
WHERE grantee = 'DMUSER'
ORDER BY privilege;

第一個查詢應該將 DMUSER_TS 顯示為永久表格空間。第二個查詢應該顯示 DMUSER，其狀態為 OPEN，而 DMUSER_TS 則是預設表格空間。權限查詢應至少包括 CREATE SESSION、CREATE TABLE、CREATE SEQUENCE、CREATE VIEW、CREATE PROCEDURE、CREATE TRIGGER、CREATE PROPERTY GRAPH 和 CREATE JOB。CREATE JOB 可讓 Oracle 代理程式記憶體建立過期記錄的選擇性背景清除工作。

對本機資料庫試用 oracleagentmemory

現在您的 Oracle 連線設定值已就緒，您可以將 oracleagentmemory 指向 FREEPDB1，然後執行小型的端對端持續性檢查。

下列範例執行兩個動作：

• 它會建立第一個寫入訊息與記憶體的 Oracle 代理程式記憶體 API 執行處理。
• 它會建立第二個 Oracle 代理程式記憶體 API 執行處理，重新開啟相同的繫線，然後從 Oracle 查詢。

請先設定應用程式連線變數，再執行範例。下列範例中顯示的使用者和連線字串與先前所述的選擇性設定相符，但您可以將它們取代為您現有的 Oracle 使用者和 DSN：

export ORACLE_MEMORY_DB_USER='dmuser'
export ORACLE_MEMORY_DB_PASSWORD='<your-app-user-password>'
export ORACLE_MEMORY_DB_CONNECT_STRING='localhost:1521/FREEPDB1'

設定 Oracle 備份的 API

import os

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"

import oracledb

from oracleagentmemory.apis.records import ScopedRecord
from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="YOUR_LLM_MODEL",
    api_base="YOUR_LLM_API_BASE",
    api_key="YOUR_LLM_API_KEY",
)
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
MEMORY_STORE_ID = "T_ORAMEM_DEMO"

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    memory_store_id=MEMORY_STORE_ID,
)

此組態使用本機 Oracle AI Database 和預留位置 LiteLLM 內嵌和完成設定值，您可以將它取代為自己的提供者值。

第一個用戶端使用 SchemaPolicy.RECREATE。它會建立示範存放區及其所需的受管理資料庫物件。此原則僅適用於可棄用示範或刻意要取代商店時。第二個從屬端使用 SchemaPolicy.REQUIRE_EXISTING，只會開啟存放區；不會變更資料庫定義。

API 參考： OracleAgentMemory

繁體中文

撰寫記錄並驗證持續性

#Keep the same user identifier for the same end user across sessions so
#durable memory can be retrieved consistently.
user_id = "user_123"

thread = agent_memory.create_thread(user_id=user_id)
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
#add_memory adds memory to the DB
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)
persisted_thread = agent_memory2.get_thread(thread.thread_id)

print("Messages stored in Oracle:")
print_messages(persisted_thread.get_messages())

print("\nSearch results for 'orange juice':")
print_search_results(
    agent_memory2.search(
        query="orange juice",
        user_id=user_id,
        max_results=5,
        record_types=["memory", "message"],
    )
)

當此範例順利執行時，第二個「Oracle 代理程式記憶體 API」執行處理會列印儲存的繫線訊息，並傳回資料庫的搜尋結果。這可確認記錄已保存在 Oracle 中，而不是僅保留在處理記憶體中。

清除

當您使用本機資料庫完成時：

• Docker
• Podman

docker stop oracle-free-lite
docker rm oracle-free-lite

podman stop oracle-free-lite
podman rm oracle-free-lite

如果您也想刪除持續保存的資料庫檔案：

• Docker
• Podman

docker volume rm OracleDBData

podman volume rm OracleDBData

結論

在本指南中，我們學會如何使用 Docker 或 Podman 在本機啟動 Oracle AI Database Free Lite、為 oracleagentmemory 準備專用的 Oracle 使用者和表格空間、將 oracleagentmemory API 連線至該資料庫，以及透過個別的 API 執行處理重新開啟和搜尋相同的執行緒來驗證持續性。

→ 瞭解如何對本機 Oracle 資料庫執行 oracleagentmemory 之後，您現在可以繼續進行儲存和搜尋記憶體。

完整代碼

#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 - Run Oracle DB locally
#--------------------------------------------------------

##Configure the local Oracle connection

import os

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"

import oracledb

from oracleagentmemory.apis.records import ScopedRecord
from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="YOUR_LLM_MODEL",
    api_base="YOUR_LLM_API_BASE",
    api_key="YOUR_LLM_API_KEY",
)
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
MEMORY_STORE_ID = "T_ORAMEM_DEMO"

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    memory_store_id=MEMORY_STORE_ID,
)

def print_messages(messages: list) -> None:
    for message in messages:
        print(f"[{message.role}] {message.content}")

def print_search_results(results: list) -> None:
    for result in results:
        scope_text = ""
        if isinstance(result.record, ScopedRecord):
            scope_text = (
                f"user_id={result.record.user_id} "
                f"thread_id={result.record.thread_id} "
            )
        print(
            f"- [{result.record.record_type}] "
            f"id={result.id} "
            f"{scope_text}"
            f"content={result.content}"
        )

##Create data and query it

#Keep the same user identifier for the same end user across sessions so
#durable memory can be retrieved consistently.
user_id = "user_123"

thread = agent_memory.create_thread(user_id=user_id)
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
#add_memory adds memory to the DB
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)
persisted_thread = agent_memory2.get_thread(thread.thread_id)

print("Messages stored in Oracle:")
print_messages(persisted_thread.get_messages())

print("\nSearch results for 'orange juice':")
print_search_results(
    agent_memory2.search(
        query="orange juice",
        user_id=user_id,
        max_results=5,
        record_types=["memory", "message"],
    )
)