Execute o Oracle AI Database Localmente

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

Neste guia, você aprenderá a:

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 Oracle Container Registry.

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

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

Inicie o Oracle AI Database Container

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

docker volume create OracleDBData
podman volume create OracleDBData

Em seguida, inicie o recipiente:

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

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 logs -f oracle-free-lite
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.

Dica: Depois que o banco de dados estiver pronto, execute uma consulta simples de dentro do contêiner para confirmar se o PDB está aberto.

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;

Você deverá ver FREEPDB1.

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

[Opcional] Criar um Usuário Oracle Local

Observação: Se você já tiver um usuário do Oracle AI Database e de um aplicativo, ignore esta seção e continue com 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.

O script de exemplo neste guia 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",
)

Selecione 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 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;

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, CREATE PROCEDURE, CREATE TRIGGER, CREATE PROPERTY GRAPH e CREATE JOB. CREATE JOB permite que a Memória do Agente Oracle crie o job de limpeza de segundo plano opcional para registros expirados.

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 a seguir faz duas coisas:

Defina as variáveis de conexão do aplicativo antes de executar o exemplo. O usuário e a string de conexão mostrados no exemplo a seguir correspondem à configuração opcional descrita anteriormente, 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.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,
)

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.

O primeiro cliente usa SchemaPolicy.RECREATE. Ele cria o armazenamento de demonstração e os objetos de banco de dados gerenciados necessários. Use esta política apenas para uma demonstração descartável ou quando quiser substituir intencionalmente uma loja. O segundo cliente usa SchemaPolicy.REQUIRE_EXISTING e só abre o armazenamento; ele não faz alterações na definição do banco de dados.

Referência de API: OracleAgentMemory OracleThread

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

Quando este exemplo é executado com sucesso, a segunda instância da API de Memória do Agente Oracle 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.

Limpar

Quando terminar com o banco de dados local:

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

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

docker volume rm OracleDBData
podman volume rm OracleDBData

Conclusão

Neste guia, aprendemos a iniciar o Oracle AI Database Free Lite localmente com o Docker ou Podman, preparar um usuário e um 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.

→ Depois de aprender a executar o oracleagentmemory em um banco de dados Oracle local, agora você pode prosseguir para Armazenar e Pesquisar Memória.

Código Inteiro

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