Usar a Memória do Oracle Agent com o Oracle Autonomous AI Database

Este guia mostra como conectar o oracleagentmemory ao Oracle Autonomous Database (ADB).

Neste guia, você aprenderá a:

Dica: Para configurar o pacote, consulte Conceitos Básicos da Memória do Agente. Para executar a Memória do Oracle Agent em um banco de dados local em contêiner, siga Executar o Oracle AI Database localmente.

Pré-requisitos

Você precisa de um Oracle Autonomous AI Database disponível que suporte o Oracle AI Vector Search (Oracle AI Database 23ai ou posterior), um administrador do ADB que possa criar um usuário de banco de dados e um ambiente Python com o oracleagentmemory instalado. Se você ainda não tiver um banco de dados, siga o guia de provisionamento do Autonomous AI Database da Oracle.

A Memória do Agente Oracle usa a conexão ou o pool fornecido pelo seu aplicativo; ela não configura a própria segurança de transporte do banco de dados. O ADB suporta duas opções de conexão segura:

Usar usuários separados do banco de dados em produção

Use dois usuários de banco de dados ADB em uma implantação de produção:

Não use as credenciais do proprietário do esquema para executar o aplicativo. Use-os somente ao configurar ou fazer upgrade do esquema gerenciado. Este guia cria primeiro o proprietário do esquema. Após a configuração, configure o usuário do aplicativo com SchemaPolicy.REQUIRE_EXISTING. O guia de solução de problemas lista as concessões de objeto necessárias para um usuário do aplicativo.

Execute cada criação ou upgrade de esquema como uma única operação de manutenção antes de iniciar as instâncias do aplicativo que gravam nas tabelas gerenciadas. Use uma conexão esquema-proprietário para a operação; não permita que vários clientes executem SchemaPolicy.CREATE_IF_NECESSARY simultaneamente. Depois de bem-sucedido, as instâncias do aplicativo deverão usar SchemaPolicy.REQUIRE_EXISTING.

Criar um usuário de esquema do ADB

Use um usuário de banco de dados ADB dedicado para possuir o esquema de Memória do Oracle Agent. Na Console do OCI, abra o serviço Database Actions, acesse como ADMIN e abra a planilha SQL. Crie um usuário com uma senha forte, conceda os privilégios usados pela configuração do esquema gerenciado e defina uma cota de armazenamento limitada para o usuário:

CREATE USER oam_owner IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT DWROLE TO oam_owner;
ALTER USER oam_owner QUOTA 1G ON DATA;

DWROLE inclui os privilégios normais de criação de objeto que a Memória do Agente Oracle usa, incluindo CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE e CREATE JOB. CREATE JOB permite que a Memória do Agente Oracle crie um job programado que exclua permanentemente registros após a expiração.

A cota 1G é um limite inicial para este guia, não uma recomendação de dimensionamento de produção. Selecione um limite com base na quantidade de memória que você espera armazenar e na sua política de retenção. Monitore o uso do armazenamento e aumente a cota quando necessário; as gravações falham quando o usuário atinge sua cota. O ADB gerencia tablespaces; portanto, este guia não cria um.

Estabelecer conexão com o TLS sem uma wallet

Na Console do OCI, abra a página de detalhes do ADB. Em Rede, configure uma ACL que permita o endereço IP de saída do aplicativo ou use um ponto final privado. Em seguida, edite Autenticação de TLS Mútuo (mTLS), desmarque Exigir autenticação mTLS (TLS mútuo) e aguarde o banco de dados retornar a Available.

Abra Conexão do banco de dados, selecione TLS em Autenticação de TLS e selecione um dos serviços de conexão listados. Os serviços geralmente têm nomes como myadb_low, myadb_medium e myadb_high; eles selecionam como o ADB compartilha recursos de banco de dados entre conexões. Comece com o nível de serviço que o administrador do banco de dados recomenda para a carga de trabalho do aplicativo e, em seguida, copie sua string de conexão. Armazene-o e as credenciais do banco de dados no seu sistema de gerenciamento de segredos:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='<copied TLS connection string>'

Use o descritor TLS exatamente como copiado. Um descritor mTLS não funciona sem uma wallet.

O exemplo cria um pool de conexões, que é um grupo reutilizável de conexões de banco de dados. Quando o ORACLE_MEMORY_ADB_USE_MTLS não é true, essas conexões usam TLS. Ele usa SchemaPolicy.CREATE_IF_NECESSARY para a primeira configuração; use SchemaPolicy.REQUIRE_EXISTING na inicialização normal do aplicativo após o esquema estar pronto.

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"

A extração automática de memória está desativada apenas para manter este exemplo de conexão focado. Configure um LLM e ative a extração quando o aplicativo precisar de extração automática de memória durável.

Referência de API: OracleAgentMemory Política de Esquema

Estabelecer conexão com uma wallet mTLS

Use esta opção se a configuração de rede ADB exigir mTLS. Na Console do OCI, abra Conexão de banco de dados, selecione uma Wallet de instância e faça download dela. Extraia a wallet em um diretório protegido que não tenha sido submetido a check-in no controle de origem. A documentação da Oracle recomenda permissões de arquivo restritivas em arquivos de wallet (por exemplo, use chmod 600 no Linux ou Unix).

Exporte as credenciais do banco de dados, o diretório da wallet e a senha de download da wallet. ORACLE_MEMORY_WALLET_PASSWORD é a senha fornecida quando você fez download do arquivo ZIP da wallet; não é a senha do usuário do banco de dados. Defina ORACLE_MEMORY_DB_DSN como o alias de serviço no arquivo tnsnames.ora da wallet, como myadb_low. Não use a string de conexão TLS longa da console do ADB para esta configuração de wallet:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='myadb_low'
export ORACLE_MEMORY_WALLET_DIR='/secure/path/to/wallet'
export ORACLE_MEMORY_WALLET_PASSWORD='<wallet-download-password>'
export ORACLE_MEMORY_ADB_USE_MTLS='true'

No modo Thin python-oracledb, o diretório da wallet precisa de tnsnames.ora e ewallet.pem. A definição de ORACLE_MEMORY_ADB_USE_MTLS como true faz com que o exemplo crie o pool mTLS antes de inicializar OracleAgentMemory.

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)

Armazenar e pesquisar memória no ADB

Depois que o cliente de Memória do Oracle Agent tiver sido configurado com um dos pools, crie um thread, adicione uma memória durável e pesquise-a novamente.

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)
Referência de API: OracleAgentMemory OracleThread Resultado do OracleSearch

Conclusão

Neste guia, aprendemos a preparar um usuário do ADB, selecionar TLS ou mTLS sem wallet, conectar a Memória do Agente Oracle a um pool python-oracledb e verificar se uma memória pode ser armazenada e recuperada do ADB.

→ Tendo conectado a Memória do Oracle Agent ao ADB, agora você pode prosseguir para Armazenar e Pesquisar Memória.

Código Inteiro

O exemplo completo está incluído neste guia para você copiar e executar.

#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 - Oracle Autonomous AI Database
#-------------------------------------------------------------

##Configure an Autonomous AI Database TLS connection pool

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"



##Configure an Autonomous AI Database mTLS connection pool

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)



##Store and search memory in Autonomous AI Database

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)