Execute o Oracle AI Database Localmente

Este artigo mostra como executar o Oracle AI Database localmente com Docker ou Podman e conectar o oracleagentmemory a esse banco de dados.

Neste artigo, você aprenderá a:

• Obtenha e inicie o Oracle AI Database com Docker ou Podman.

• Opcionalmente, crie um usuário Oracle local e um tablespace para oracleagentmemory.

• Configure uma API oracleagentmemory com suporte da Oracle com incorporação LiteLLM e adaptadores LLM.

• Verifique se os registros persistem reabrindo o mesmo thread por meio de uma segunda instância de API.

Pré-requisitos

Instale o Docker ou o Podman e certifique-se de que a CLI correspondente esteja disponível no shell. Em seguida, extraia a imagem do Oracle AI Database Free Lite do registro do Oracle Container.

Escolha uma senha forte para o usuário do Oracle SYSTEM e exporte-a antes de iniciar o contêiner:

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

Inicie o Oracle AI Database Container

Crie um volume nomeado para que os arquivos do banco de dados persistam nas reinicializações:

Docker:

docker volume create OracleDBData

Podman:

podman volume create OracleDBData

Em seguida, inicie o recipiente:

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

Observação: Se o Podman encontrar problemas de rotulagem do SELinux no RHEL, talvez você queira examinar os parâmetros de configuração security-opt.

Em seguida, siga o log do contêiner até que o banco de dados informe que ele está pronto.

Docker:

docker logs -f oracle-free-lite

Podman:

podman logs -f oracle-free-lite

Quando o log contém DATABASE IS READY TO USE!, o listener e o banco de dados plugável padrão ficam ativos.

Quando o banco de dados estiver pronto, conecte-se ao banco de dados.

Docker:

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

Podman:

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

Execute uma consulta simples de dentro do contêiner para confirmar se o PDB está aberto.

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

Você deverá ver FREEPDB1.

Em seguida, digite exit e pressione Enter para sair do SQL*Plus.

[Opcional] Criar um Usuário Oracle Local

Se você já tiver um Oracle AI Database e um usuário de aplicativo, ignore esta seção e continue com a próxima seção, Tente oracleagentmemory no banco de dados local. Para obter um passo a passo mais curto no estilo de início rápido da própria API, consulte Armazenar e Procurar Memória por um Usuário.

O script de exemplo neste artigo usa um usuário de banco de dados 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",
)

Escolha uma senha forte para esse usuário do aplicativo e exporte-a antes de executar o script:

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

Em seguida, crie o usuário dentro do 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;

Substitua CHOOSE_A_STRONG_PASSWORD pelo mesmo valor de senha que você armazena em ORACLE_MEMORY_DB_PASSWORD.

Em seguida, verifique se o usuário está pronto:

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;

A primeira consulta deve mostrar DMUSER_TS como um tablespace permanente. A segunda consulta deve mostrar DMUSER com o status OPEN e DMUSER_TS como o tablespace padrão. A consulta de privilégio deve incluir pelo menos CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW e CREATE PROCEDURE.

Experimente a oracleagentmemory no Banco de Dados Local

Agora que suas definições de conexão da Oracle estão prontas, você pode apontar oracleagentmemory para FREEPDB1 e executar uma pequena verificação de persistência de ponta a ponta.

O exemplo abaixo faz duas coisas:

• Ele cria uma primeira instância da API de Memória do Agente que grava mensagens e memórias.
• Ele cria uma segunda instância da API de Memória do Agente que reabre o mesmo thread e a consulta de volta da Oracle.

Defina as variáveis de conexão do aplicativo antes de executar o exemplo. O usuário e a string de conexão mostrados abaixo correspondem à configuração opcional anterior, mas você pode substituí-los por seu próprio usuário Oracle e DSN existentes:

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 a API com Backup da 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,
)

Essa configuração usa o Oracle AI Database local junto com as definições de incorporação e conclusão do LiteLLM do placeholder que você pode substituir pelos valores do seu próprio provedor.

Gravar Registros e Verificar Persistência

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

Quando este exemplo é executado com sucesso, a segunda instância da API de Memória do Agente imprime as mensagens de thread armazenadas e retorna os resultados da pesquisa do banco de dados. Isso confirma que os registros foram persistidos na Oracle, em vez de mantidos apenas na memória do processo.

Limpeza

Quando terminar com o banco de dados local:

Docker:

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

Podman:

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

Se você também quiser excluir os arquivos de banco de dados persistidos:

Docker:

docker volume rm OracleDBData

Podman:

podman volume rm OracleDBData

Conclusão

Neste artigo, aprendemos a iniciar o Oracle AI Database Free Lite localmente com Docker ou Podman, preparar um usuário e tablespace dedicados da Oracle para oracleagentmemory, conectar uma API oracleagentmemory a esse banco de dados e verificar a persistência reabrindo e pesquisando o mesmo thread por meio de uma instância de API separada.

Dica: Depois de aprender a executar o oracleagentmemory em um Oracle AI Database local, agora você pode prosseguir para Armazenar e Pesquisar Memória para um Usuário.

Código Inteiro

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