Ejecutar Oracle AI Database localmente

En este artículo se muestra cómo ejecutar Oracle AI Database localmente con Docker o Podman y conectar oracleagentmemory a esa base de datos.

En este artículo, aprenderá a:

• Tire e inicie Oracle AI Database con Docker o Podman.

• Opcionalmente, cree un usuario de Oracle local y un tablespace para oracleagentmemory.

• Configure una API oracleagentmemory respaldada por Oracle con incrustaciones de LiteLLM y adaptadores de LLM.

• Verifique que los registros se mantienen volviendo a abrir el mismo thread a través de una segunda instancia de API.

Requisitos

Instale Docker o Podman y asegúrese de que la CLI correspondiente esté disponible en el shell. A continuación, extraiga la imagen de Oracle AI Database Free Lite del registro de contenedores de Oracle.

Seleccione una contraseña segura para el usuario SYSTEM de Oracle y exporte antes de iniciar el contenedor:

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

Iniciar el contenedor de Oracle AI Database

Cree un volumen con nombre para que los archivos de base de datos se mantengan tras los reinicios:

Docker:

docker volume create OracleDBData

Podman:

podman volume create OracleDBData

A continuación, inicie el contenedor:

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

Nota: Si Podman detecta problemas de etiquetado de SELinux en RHEL, es posible que desee consultar los parámetros de configuración de security-opt.

A continuación, siga el log de contenedor hasta que la base de datos informe que está lista.

Docker:

docker logs -f oracle-free-lite

Podman:

podman logs -f oracle-free-lite

Cuando el log contiene DATABASE IS READY TO USE!, el listener y la base de datos conectable por defecto están activos.

Una vez que la base de datos esté lista, conéctese a la base de datos.

Docker:

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

Podman:

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

Ejecute una consulta simple desde el contenedor para confirmar que la PDB está abierta.

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

Debe ver FREEPDB1.

A continuación, introduzca exit y pulse Enter para salir de SQL*Plus.

[Opcional] Crear un usuario local de Oracle

Si ya tiene una instancia de Oracle AI Database y un usuario de aplicación, omita esta sección y continúe con la siguiente sección, Pruebe oracleagentmemory en la base de datos local. Para obtener un recorrido virtual de estilo de inicio rápido más corto de la propia API, consulte Almacenamiento y búsqueda de memoria para un usuario.

El script de ejemplo de este artículo utiliza un usuario de base de datos local dedicado:

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

Seleccione una contraseña segura para ese usuario de aplicación y exporte antes de ejecutar el script:

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

A continuación, cree el usuario dentro de la 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;

Sustituya CHOOSE_A_STRONG_PASSWORD por el mismo valor de contraseña que almacena en ORACLE_MEMORY_DB_PASSWORD.

A continuación, verifique que el usuario está listo:

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;

La primera consulta debe mostrar DMUSER_TS como tablespace permanente. La segunda consulta debe mostrar DMUSER con el estado OPEN y DMUSER_TS como tablespace por defecto. La consulta de privilegios debe incluir al menos CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW y CREATE PROCEDURE.

Pruebe oracleagentmemory con la base de datos local

Ahora que la configuración de la conexión de Oracle está lista, puede apuntar a oracleagentmemory en FREEPDB1 y ejecutar una pequeña comprobación de persistencia completa.

El siguiente ejemplo hace dos cosas:

• Crea una primera instancia de API de memoria de agente que escribe mensajes y memorias.
• Crea una segunda instancia de API de memoria de agente que vuelve a abrir el mismo thread y la vuelve a consultar desde Oracle.

Defina las variables de conexión de la aplicación antes de ejecutar el ejemplo. La cadena de usuario y conexión que se muestra a continuación coincide con la configuración opcional anterior, pero puede sustituirla por su propio usuario de Oracle y 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'

Configurar la API con copia de seguridad de Oracle

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,
)

Esta configuración utiliza la Oracle AI Database local junto con los valores de embebido y finalización de LiteLLM del marcador de posición que puede sustituir por sus propios valores de proveedor.

Escritura de registros y verificación de la persistencia

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

Cuando este ejemplo se ejecuta correctamente, la segunda instancia de la API de memoria del agente imprime los mensajes de thread almacenados y devuelve los resultados de búsqueda de la base de datos. Esto confirma que los registros se mantuvieron en Oracle en lugar de solo en la memoria del proceso.

Limpieza

Cuando haya terminado con la base de datos local:

Docker:

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

Podman:

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

Si también desea suprimir los archivos de base de datos persistentes:

Docker:

docker volume rm OracleDBData

Podman:

podman volume rm OracleDBData

Conclusión

En este artículo, hemos aprendido a iniciar Oracle AI Database Free Lite localmente con Docker o Podman, preparar un usuario y tablespace de Oracle dedicados para oracleagentmemory, conectar una API oracleagentmemory a esa base de datos y verificar la persistencia volviendo a abrir y buscando el mismo thread a través de una instancia de API independiente.

Consejo: después de haber aprendido a ejecutar oracleagentmemory en una instancia local de Oracle AI Database, ahora puede continuar con Almacenar y buscar memoria para un usuario.

Código Completo

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