Exécuter Oracle AI Database localement

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

Dans cet article, vous apprendrez à :

• Extraire et démarrer Oracle AI Database avec Docker ou Podman.

• Vous pouvez éventuellement créer un utilisateur et un tablespace Oracle locaux pour oracleagentmemory.

• Configurez une API oracleagentmemory soutenue par Oracle avec l'intégration LiteLLM et des adaptateurs LLM.

• Vérifiez que les enregistrements persistent en rouvrant le même thread via une deuxième instance d'API.

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 du registre Oracle Container.

Choisissez 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:

docker pull container-registry.oracle.com/database/free:latest-lite

Podman:

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:

docker volume create OracleDBData

Podman:

podman volume create OracleDBData

Ensuite, démarrez le conteneur :

Docker:

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:

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:

docker logs -f oracle-free-lite

Podman:

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.

Une fois la base de données prête, connectez-vous à la base de données.

Docker:

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

Podman:

podman exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

Exécutez une requête simple à partir du conteneur pour vérifier que la base de données pluggable est ouverte.

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

Si vous disposez déjà d'une base de données Oracle AI Database et d'un utilisateur d'application, ignorez cette section et passez à la section suivante, Essayez oracleagentmemory sur 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 pour un utilisateur.

L'exemple de script de cet article 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",
)

Choisissez 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:

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

Podman:

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 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 et CREATE PROCEDURE.

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 ci-dessous effectue deux opérations :

• Il crée une première instance d'API de mémoire d'agent qui écrit des messages et des mémoires.
• Il crée une deuxième instance d'API de mémoire d'agent qui rouvre le même thread et le réinterroge à partir d'Oracle.

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 ci-dessous correspondent à la configuration facultative précédente, 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.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_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")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)

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.

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)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
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 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:

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

Podman:

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

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

Docker:

docker volume rm OracleDBData

Podman:

podman volume rm OracleDBData

Conclusion

Dans cet article, 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.

A savoir : Après avoir appris à exécuter oracleagentmemory sur une base de données Oracle AI Database locale, vous pouvez maintenant passer à Stockage et recherche de mémoire pour un utilisateur.

Code complet

#Copyright © 2026 Oracle and/or its affiliates.
#isort:skip_file
#fmt: off
#%%[markdown]
#Agent Memory Code Example - Run Oracle DB locally
#--------------------------------------------------------


#How to use:
#Create a new Python virtual environment and install the latest oracleagentmemory version.

#You can now run the script
#1. As a Python file:
#```bash
#python howto_run_oracledb.py
#```
#2. As a Notebook (in VSCode):
#When viewing the file,
#- press the keys Ctrl + Enter to run the selected cell
#- or Shift + Enter to run the selected cell and move to the cell below


##Configure the local Oracle connection

#%%
import os

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"

import oracledb

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_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")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)


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:
        print(
            f"- [{result.record.record_type}] "
            f"id={result.id} "
            f"user_id={result.record.user_id} "
            f"thread_id={result.record.thread_id} "
            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=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
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"],
    )
)