在本機執行 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 登錄中提取 Oracle AI Database Free Lite 影像。

為 Oracle SYSTEM 使用者選擇一個強式密碼，然後先匯出該密碼，再啟動容器：

export ORACLE_PWD='<your-secure-password>'

Docker：

docker pull container-registry.oracle.com/database/free:latest-lite

Podman：

podman pull container-registry.oracle.com/database/free:latest-lite

啟動 Oracle AI Database 容器

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

Docker：

docker volume create OracleDBData

Podman：

podman volume create OracleDBData

然後啟動容器：

Docker：

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：

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：

docker logs -f oracle-free-lite

Podman：

podman logs -f oracle-free-lite

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

資料庫就緒之後，請連線至資料庫。

Docker：

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

Podman：

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

從容器內部執行簡單查詢，以確認 PDB 已開啟。

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：

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

Podman：

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 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。

對本機資料庫試用 oracleagentmemory

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

以下範例有兩個事項：

它會建立第一個寫入訊息與記憶體的「代理程式記憶體 API」執行處理。
它會建立第二個「代理程式記憶體 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.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_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")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)

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

撰寫記錄並驗證持續性

#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)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
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"],
    )
)

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

清除

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

Docker：

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

Podman：

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

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

Docker：

docker volume rm OracleDBData

Podman：

podman volume rm OracleDBData

結論

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

提示：已瞭解如何對本機 Oracle AI Database 執行 oracleagentmemory，您現在可以繼續單一使用者的儲存和搜尋記憶體。

完整代碼

#Copyright © 2026 Oracle and/or its affiliates.
#isort:skip_file
#fmt: off
#%%[markdown]
#Agent Memory Code Example - Run Oracle DB locally
#--------------------------------------------------------


#How to use:
#Create a new Python virtual environment and install the latest oracleagentmemory version.

#You can now run the script
#1. As a Python file:
#```bash
#python howto_run_oracledb.py
#```
#2. As a Notebook (in VSCode):
#When viewing the file,
#- press the keys Ctrl + Enter to run the selected cell
#- or Shift + Enter to run the selected cell and move to the cell below


##Configure the local Oracle connection

#%%
import os

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

import oracledb

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_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")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)


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:
        print(
            f"- [{result.record.record_type}] "
            f"id={result.id} "
            f"user_id={result.record.user_id} "
            f"thread_id={result.record.thread_id} "
            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=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
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"],
    )
)