Utilisation de la mémoire de l'agent Oracle avec Oracle Autonomous AI Database

Ce guide explique comment connecter oracleagentmemory à Oracle Autonomous Database (ADB).

Dans ce guide, vous apprendrez à :

Préparez un utilisateur de schéma ADB pour la mémoire de l'agent Oracle.
Connectez-vous avec un portefeuille TLS sans portefeuille ou avec un portefeuille mTLS.
Initialisez le schéma de mémoire gérée et stockez et recherchez une mémoire.

Conseil : pour la configuration des packages, reportez-vous à Introduction à la mémoire de l'agent. Pour exécuter la mémoire de l'agent Oracle sur une base de données locale conteneurisée, suivez plutôt Exécuter Oracle AI Database localement.

Prérequis

Vous avez besoin d'une base de données Oracle Autonomous AI Database disponible qui prend en charge Oracle AI Vector Search (Oracle AI Database 23ai ou version ultérieure), d'un administrateur ADB qui peut créer un utilisateur de base de données et d'un environnement Python avec oracleagentmemory installé. Si vous ne disposez pas encore d'une base de données, suivez le guide de provisionnement de la base de données Autonomous AI d'Oracle.

La mémoire de l'agent Oracle utilise la connexion ou le pool fourni par l'application. Elle ne configure pas la sécurité du transport de base de données elle-même. ADB prend en charge deux options de connexion sécurisée :

TLS sans portefeuille convient à la plupart des nouvelles applications. Il utilise les informations d'identification et de connexion à la base de données et crypte la connexion. Avant de l'utiliser, configurez une liste d'autorisation d'adresses IP ou une adresse privée afin que l'application puisse atteindre la base de données. TLS protège la connexion ; l'ACL ou l'adresse privée contrôle les réseaux qui peuvent atteindre la base de données.
TLS mutuel (mTLS) avec un portefeuille convient lorsque ADB requiert mTLS ou lorsque votre organisation requiert une authentification par certificat client.

Utiliser des utilisateurs de base de données distincts en production

Utilisez deux utilisateurs de base de données ADB dans un déploiement de production :

Le propriétaire du schéma crée, met à niveau et détient les tables et index de mémoire d'agent Oracle.
L'utilisateur d'application se connecte lorsque l'application lit et écrit des mémoires. Accordez à cet utilisateur uniquement les droits d'accès dont il a besoin sur les objets du propriétaire du schéma.

N'utilisez pas les informations d'identification du propriétaire du schéma pour exécuter l'application. Utilisez-les uniquement lors de la configuration ou de la mise à niveau du schéma géré. Ce guide crée d'abord le propriétaire du schéma. Après la configuration, configurez l'utilisateur de l'application avec SchemaPolicy.REQUIRE_EXISTING. Le guide de dépannage répertorie les autorisations d'objet requises par un utilisateur d'application.

Exécutez chaque création ou mise à niveau de schéma en tant qu'opération de maintenance unique avant de démarrer les instances d'application qui écrivent dans les tables gérées. Utilisez une connexion de propriétaire de schéma pour l'opération ; n'autorisez pas plusieurs clients à exécuter SchemaPolicy.CREATE_IF_NECESSARY simultanément. Une fois qu'il a réussi, les instances d'application doivent utiliser SchemaPolicy.REQUIRE_EXISTING.

Créer un utilisateur de schéma ADB

Utilisez un utilisateur de base de données ADB dédié pour détenir le schéma de mémoire de l'agent Oracle. Dans la console OCI, ouvrez Database Actions, connectez-vous en tant que ADMIN et ouvrez la feuille de calcul SQL. Créez un utilisateur avec un mot de passe fort, accordez les privilèges utilisés par la configuration du schéma géré et définissez un quota de stockage limité pour l'utilisateur :

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

DWROLE inclut les privilèges de création d'objet standard utilisés par la mémoire de l'agent Oracle, notamment CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE et CREATE JOB. CREATE JOB permet à la mémoire de l'agent Oracle de créer un travail programmé qui supprime définitivement les enregistrements après leur expiration.

Le quota 1G est une limite de début pour ce guide et non une recommandation de dimensionnement de la production. Sélectionnez une limite en fonction de la quantité de mémoire que vous prévoyez de stocker et de votre stratégie de conservation. Surveillez l'utilisation du stockage et augmentez le quota si nécessaire ; les écritures échouent lorsque l'utilisateur atteint son quota. ADB gère les tablespaces. Par conséquent, ce guide ne crée pas de tablespace.

Connexion avec TLS sans portefeuille

Dans la console OCI, ouvrez la page de détails ADB. Sous Réseau, configurez une liste de contrôle d'accès qui autorise l'adresse IP sortante de l'application ou utilisez une adresse privée. Modifiez ensuite Authentification TLS mutuelle (mTLS), désélectionnez Exiger une authentification TLS mutuelle (mTLS) et attendez que la base de données revienne à Available.

Ouvrez Connexion à la base de données, sélectionnez TLS sous Authentification TLS, puis sélectionnez l'un des services de connexion répertoriés. Les services portent généralement des noms tels que myadb_low, myadb_medium et myadb_high. Ils sélectionnent la façon dont ADB partage les ressources de base de données entre les connexions. Commencez par le niveau de service recommandé par l'administrateur de base de données pour la charge globale de l'application, puis copiez sa chaîne de connexion. Stockez-le et les informations d'identification de base de données dans votre système de gestion des clés secrètes :

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

Utilisez le descripteur TLS exactement tel que copié. Un descripteur mTLS ne fonctionne pas sans portefeuille.

L'exemple crée un pool de connexions, qui est un groupe réutilisable de connexions de base de données. Lorsque ORACLE_MEMORY_ADB_USE_MTLS n'est pas true, ces connexions utilisent TLS. Il utilise SchemaPolicy.CREATE_IF_NECESSARY pour la première configuration. Utilisez SchemaPolicy.REQUIRE_EXISTING lors du démarrage normal de l'application une fois le schéma prêt.

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"

L'extraction automatique de mémoire est désactivée uniquement pour que cet exemple de connexion reste ciblé. Configurez un LLM et activez l'extraction lorsque l'application a besoin d'une extraction automatique de mémoire durable.

Référence d'API : OracleAgentMemory

Stratégie de schéma

Se connecter à un portefeuille mTLS

Utilisez cette option si la configuration réseau ADB requiert mTLS. Dans la console OCI, ouvrez Connexion à la base de données, sélectionnez un portefeuille d'instance et téléchargez-le. Extrayez le "wallet" dans un répertoire protégé qui n'est pas archivé dans le contrôle source. La documentation Oracle recommande des droits d'accès restrictifs sur les fichiers de portefeuille (par exemple, utilisez chmod 600 sous Linux ou Unix).

Exportez les informations d'identification de base de données, le répertoire de portefeuille et le mot de passe de téléchargement de portefeuille. ORACLE_MEMORY_WALLET_PASSWORD est le mot de passe que vous avez fourni lorsque vous avez téléchargé le fichier ZIP de portefeuille. Il ne s'agit pas du mot de passe de l'utilisateur de base de données. Définissez ORACLE_MEMORY_DB_DSN sur l'alias de service dans le fichier tnsnames.ora du portefeuille, tel que myadb_low. N'utilisez pas la longue chaîne de connexion TLS de la console ADB pour cette configuration de portefeuille :

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 mode léger python-oracledb, le répertoire de portefeuille a besoin de tnsnames.ora et ewallet.pem. Si vous définissez ORACLE_MEMORY_ADB_USE_MTLS sur true, l'exemple crée le pool mTLS avant d'initialiser 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,
)

Stocker et rechercher de la mémoire dans ADB

Une fois que le client de mémoire de l'agent Oracle a été configuré avec l'un ou l'autre pool, créez un thread, ajoutez une mémoire durable et relancez la recherche.

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)

Référence d'API : OracleAgentMemory

OracleThread

OracleSearchResult

Conclusion

Dans ce guide, nous avons appris à préparer un utilisateur ADB, à sélectionner TLS ou mTLS sans portefeuille, à connecter la mémoire de l'agent Oracle à un pool python-oracledb et à vérifier qu'une mémoire peut être stockée et extraite à partir d'ADB.

→ Une fois la mémoire de l'agent Oracle connectée à ADB, vous pouvez maintenant passer à Mémoire de stockage et de recherche.

Code complet

L'exemple complet est inclus dans ce guide pour que vous puissiez le copier et l'exécuter.

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