本地运行 Oracle AI Database

本文介绍如何使用 Docker 或 Podman 在本地运行 Oracle AI Database，并将 oracleagentmemory 连接到该数据库。

在本文中，您将学习如何：

使用 Docker 或 Podman 提取并启动 Oracle AI Database。
（可选）为 oracleagentmemory 创建本地 Oracle 用户和表空间。
使用 LiteLLM 嵌入和 LLM 适配器配置 Oracle 支持的 oracleagentmemory API。
通过第二个 API 实例重新打开同一线程来验证记录是否存在。

Prerequisites

安装 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 Container

创建命名卷，使数据库文件在重新启动后持久保存：

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 本身的简短快速入门式演练，请参见 Store and Search Memory for One User 。

本文中的示例脚本使用专用本地数据库用户：

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 后，现在可以转至 Store and Search Memory for One User 。

完整代码

#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"],
    )
)

本地运行 Oracle AI Database

Prerequisites

启动 Oracle AI Database Container

［可选］ 创建本地 Oracle 用户

针对本地数据库试用 oracleagentmemory

配置 Oracle 备份的 API

写入记录并验证持久性

清除

小结

完整代码

［可选］创建本地 Oracle 用户