Exécuter Oracle AI Database localement

Ce guide explique comment exécuter Oracle AI Database localement avec Docker ou Podman et connecter oracleagentmemory à cette base de données.

Dans ce guide, vous apprendrez à :

Prérequis

Installez Docker ou Podman et vérifiez que l'interface de ligne de commande correspondante est disponible dans votre shell. Extrayez ensuite l'image Oracle AI Database Free Lite à partir d'Oracle Container Registry.

Sélectionnez un mot de passe fort pour l'utilisateur Oracle SYSTEM et exportez-le avant de démarrer le conteneur :

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

Démarrer le conteneur Oracle AI Database

Créez un volume nommé afin que les fichiers de base de données persistent après les redémarrages :

docker volume create OracleDBData
podman volume create OracleDBData

Ensuite, démarrez le conteneur :

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

Remarque : si Podman rencontre des problèmes d'étiquetage SELinux sur RHEL, vous pouvez examiner les paramètres de configuration security-opt.

Ensuite, suivez le journal du conteneur jusqu'à ce que la base de données indique qu'elle est prête.

docker logs -f oracle-free-lite
podman logs -f oracle-free-lite

Lorsque le journal contient DATABASE IS READY TO USE!, le processus d'écoute et la base de données pluggable par défaut sont démarrés.

A savoir : Une fois la base de données prête, exécutez une requête simple à partir du conteneur pour vérifier que la base de données pluggable est ouverte.

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;

Vous devez voir FREEPDB1.

Entrez ensuite exit et appuyez sur Enter pour quitter SQL*Plus.

[Facultatif] Création d'un utilisateur Oracle local

Remarque : si vous disposez déjà d'Oracle AI Database et d'un utilisateur d'application, ignorez cette section et passez à l'étape Essayer oracleagentmemory par rapport à la base de données locale. Pour une présentation plus courte de l'API elle-même, reportez-vous à Mémoire de stockage et de recherche.

L'exemple de script de ce guide utilise un utilisateur de base de données local dédié :

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

Sélectionnez un mot de passe fort pour cet utilisateur d'application et exportez-le avant d'exécuter le script :

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

Créez ensuite l'utilisateur dans la base de données pluggable :

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;

Remplacez CHOOSE_A_STRONG_PASSWORD par la même valeur de mot de passe que celle stockée dans ORACLE_MEMORY_DB_PASSWORD.

Vérifiez ensuite que l'utilisateur est prêt :

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;

La première interrogation doit afficher DMUSER_TS en tant que tablespace permanent. La deuxième interrogation doit afficher DMUSER avec le statut OPEN et DMUSER_TS comme tablespace par défaut. La requête de privilège doit inclure au moins CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW, CREATE PROCEDURE, CREATE TRIGGER, CREATE PROPERTY GRAPH et CREATE JOB. CREATE JOB permet à la mémoire de l'agent Oracle de créer le travail de nettoyage en arrière-plan facultatif pour les enregistrements expirés.

Essayez oracleagentmemory sur la base de données locale

Maintenant que vos paramètres de connexion Oracle sont prêts, vous pouvez pointer oracleagentmemory vers FREEPDB1 et exécuter une petite vérification de persistance de bout en bout.

L'exemple suivant effectue deux opérations :

Définissez les variables de connexion de l'application avant d'exécuter l'exemple. L'utilisateur et la chaîne de connexion indiqués dans l'exemple suivant correspondent à la configuration facultative décrite précédemment, mais vous pouvez les remplacer par votre propre utilisateur Oracle et DSN existants :

export ORACLE_MEMORY_DB_USER='dmuser'
export ORACLE_MEMORY_DB_PASSWORD='<your-app-user-password>'
export ORACLE_MEMORY_DB_CONNECT_STRING='localhost:1521/FREEPDB1'

Configurer l'API sauvegardée par 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,
)

Cette configuration utilise Oracle AI Database local, ainsi que les paramètres d'intégration et de fin LiteLLM d'espace réservé que vous pouvez remplacer par vos propres valeurs de fournisseur.

Le premier client utilise SchemaPolicy.RECREATE. Elle crée la banque de démos et les objets de base de données gérés dont elle a besoin. Utilisez cette stratégie uniquement pour une démo jetable ou lorsque vous souhaitez intentionnellement remplacer un magasin. Le second client utilise SchemaPolicy.REQUIRE_EXISTING et ouvre uniquement la banque. Il n'effectue pas de modifications de définition de base de données.

Référence d'API : OracleAgentMemory OracleThread

Ecrire des enregistrements et vérifier la persistance

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

Lorsque cet exemple s'exécute correctement, la deuxième instance d'API de mémoire d'agent Oracle imprime les messages de thread stockés et renvoie les résultats de recherche de la base de données. Cela confirme que les enregistrements ont été conservés dans Oracle plutôt que dans la mémoire de processus.

Nettoyage

Lorsque vous avez terminé avec la base de données locale :

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

Si vous souhaitez également supprimer les fichiers de base de données persistants :

docker volume rm OracleDBData
podman volume rm OracleDBData

Conclusion

Dans ce guide, nous avons appris à démarrer Oracle AI Database Free Lite localement avec Docker ou Podman, à préparer un utilisateur et un tablespace Oracle dédiés pour oracleagentmemory, à connecter une API oracleagentmemory à cette base de données et à vérifier la persistance en rouvrant et en recherchant le même thread via une instance d'API distincte.

→ Après avoir appris à exécuter oracleagentmemory sur une base de données Oracle locale, vous pouvez maintenant passer à Mémoire de stockage et de recherche.

Code complet

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