Uso de la memoria del agente de Oracle con Oracle Autonomous AI Database

En esta guía se muestra cómo conectar oracleagentmemory a Oracle Autonomous Database (ADB).

En esta guía, aprenderá a:

Prepare un usuario de esquema de ADB para la memoria del agente de Oracle.
Conéctese con TLS sin cartera o con una cartera mTLS.
Inicialice el esquema de memoria gestionada y almacene y busque una memoria.

Indicación: Para la configuración del paquete, consulte Get Started with Agent Memory. Para ejecutar la memoria del agente de Oracle en una base de datos local en contenedores, siga Ejecución local de Oracle AI Database.

Requisitos previos

Necesita una instancia de Oracle Autonomous AI Database disponible que admita Oracle AI Vector Search (Oracle AI Database 23ai o posterior), un administrador de ADB que pueda crear un usuario de base de datos y un entorno Python con oracleagentmemory instalado. Si aún no tiene una base de datos, siga la guía de aprovisionamiento de Autonomous AI Database de Oracle.

La memoria del agente de Oracle utiliza la conexión o el pool proporcionados por la aplicación; no configura la seguridad del transporte de la base de datos en sí. ADB soporta dos opciones de conexión segura:

TLS sin cartera es adecuado para la mayoría de las aplicaciones nuevas. Utiliza credenciales de base de datos y cifra la conexión. Antes de utilizarlo, configure una lista de permitidos de IP (ACL) o un punto final privado para que la aplicación pueda acceder a la base de datos. TLS protege la conexión; la ACL o el punto final privado controla qué redes pueden acceder a la base de datos.
La TLS mutua (mTLS) con una cartera es adecuada cuando ADB requiere mTLS o cuando su organización requiere autenticación de certificado de cliente.

Utilizar usuarios de base de datos independientes en producción

Utilizar dos usuarios de base de datos de ADB en un despliegue de producción:

El propietario del esquema crea, actualiza y es propietario de las tablas e índices de memoria del agente de Oracle.
El usuario de aplicación se conecta cuando la aplicación lee y escribe memorias. Proporcione a este usuario solo los permisos que necesita en los objetos del propietario del esquema.

No utilice las credenciales del propietario del esquema para ejecutar la aplicación. Utilícelos solo al configurar o actualizar el esquema gestionado. Esta guía crea primero el propietario del esquema. Después de la configuración, configure el usuario de la aplicación con SchemaPolicy.REQUIRE_EXISTING. La guía de resolución de problemas muestra los permisos de objeto necesarios para un usuario de aplicación.

Ejecute cada creación o actualización de esquema como una única operación de mantenimiento antes de iniciar las instancias de aplicación que escriben en las tablas gestionadas. Utilice una conexión de propietario de esquema para la operación; no permita que varios clientes ejecuten SchemaPolicy.CREATE_IF_NECESSARY simultáneamente. Una vez que se realiza correctamente, las instancias de aplicación deben utilizar SchemaPolicy.REQUIRE_EXISTING.

Crear un usuario de esquema de ADB

Utilice un usuario de base de datos de ADB dedicado para ser propietario del esquema de memoria del agente de Oracle. En la consola de OCI, abra Database Actions, conéctese como ADMIN y abra la hoja de trabajo SQL. Cree un usuario con una contraseña segura, otorgue los privilegios que utiliza la configuración del esquema gestionado y defina una cuota de almacenamiento enlazada para el usuario:

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

DWROLE incluye los privilegios normales de creación de objetos que utiliza la memoria del agente de Oracle, incluidos CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE y CREATE JOB. CREATE JOB permite que la memoria del agente de Oracle cree un trabajo programado que suprima de forma permanente los registros una vez que caduquen.

La cuota 1G es un límite inicial para esta guía, no una recomendación de tamaño de producción. Seleccione un límite en función de la cantidad de memoria que espera almacenar y la política de retención. Supervise el uso del almacenamiento y aumente la cuota cuando sea necesario; las escrituras fallan cuando el usuario alcanza su cuota. ADB gestiona los tablespaces, por lo que esta guía no crea ninguno.

Conexión con TLS sin cartera

En la consola de OCI, abra la página de detalles de ADB. En Red, configure una ACL que permita la dirección IP de salida de la aplicación o utilice un punto final privado. A continuación, edite Autenticación TLS mutua (mTLS), borre Requerir autenticación TLS mutua (mTLS) y espere a que la base de datos vuelva a Available.

Abra Conexión de base de datos, seleccione TLS en Autenticación TLS y seleccione uno de los servicios de conexión mostrados. Los servicios suelen tener nombres como myadb_low, myadb_medium y myadb_high; seleccionan cómo ADB comparte los recursos de base de datos entre las conexiones. Comience con el nivel de servicio que el administrador de la base de datos recomienda para la carga de trabajo de la aplicación y, a continuación, copie la cadena de conexión. Almacénelo y las credenciales de la base de datos en el sistema de gestión de secretos:

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

Utilice el descriptor TLS exactamente como se ha copiado. Un descriptor mTLS no funciona sin una cartera.

En el ejemplo se crea un pool de conexiones, que es un grupo reutilizable de conexiones de base de datos. Cuando ORACLE_MEMORY_ADB_USE_MTLS no es true, esas conexiones utilizan TLS. Utiliza SchemaPolicy.CREATE_IF_NECESSARY para la primera configuración; utilice SchemaPolicy.REQUIRE_EXISTING en el inicio normal de la aplicación después de que el esquema esté listo.

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"

La extracción automática de memoria está desactivada solo para mantener este ejemplo de conexión enfocado. Configure un LLM y active la extracción cuando la aplicación necesite una extracción automática de memoria duradera.

Referencia de API: OracleAgentMemory

Política de Esquema

Conectar con una cartera mTLS

Utilice esta opción si la configuración de red de ADB requiere mTLS. En la consola de OCI, abra Conexión de base de datos, seleccione una cartera de instancia y descárguela. Extraiga la cartera en un directorio protegido que no esté protegido en el control de origen. La documentación de Oracle recomienda permisos de archivo restrictivos en los archivos de cartera (por ejemplo, utilice chmod 600 en Linux o Unix).

Exporte las credenciales de la base de datos, el directorio de cartera y la contraseña de descarga de cartera. ORACLE_MEMORY_WALLET_PASSWORD es la contraseña que ha proporcionado al descargar el archivo ZIP de cartera; no es la contraseña del usuario de la base de datos. Defina ORACLE_MEMORY_DB_DSN en el alias de servicio en el archivo tnsnames.ora de la cartera, como myadb_low. No utilice la cadena de conexión TLS larga de la consola de ADB para esta configuración de cartera:

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'

En el modo ligero python-oracledb, el directorio de cartera necesita tnsnames.ora y ewallet.pem. Si se define ORACLE_MEMORY_ADB_USE_MTLS en true, en el ejemplo se crea el 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,
)

Almacenar y buscar memoria en ADB

Una vez que el cliente de memoria del agente de Oracle se haya configurado con cualquiera de los pools, cree un thread, agregue una memoria duradera y realice una búsqueda posterior.

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)

Referencia de API: OracleAgentMemory

OracleThread

Resultado de búsqueda de Oracle

Conclusión

En esta guía hemos aprendido a preparar un usuario de ADB, seleccionar TLS o mTLS sin cartera, conectar la memoria del agente de Oracle con un pool python-oracledb y verificar que se puede almacenar y recuperar una memoria desde ADB.

→ Después de haber conectado la memoria de Oracle Agent a ADB, ahora puede continuar con Almacenar y buscar memoria.

Código Completo

El ejemplo completo se incluye en esta guía para que pueda copiar y ejecutar.

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