Introduction à la mémoire de l'agent

Cet article vous guide tout au long de l'installation de la mémoire d'agent et de l'exécution d'opérations de mémoire de base, notamment le stockage et l'extraction du contexte utilisateur.

Prérequis

Vérifiez que vous disposez des éléments suivants :

Configuration requise pour les fonctionnalités d'Oracle AI Database

La banque de données sauvegardée par la base de données de la mémoire d'agent Oracle requiert Oracle AI Database 23ai ou une version ultérieure (version de base de données 23.4 ou ultérieure). Pour Oracle AI Vector Search, définissez le paramètre d'initialisation COMPATIBLE de la base de données sur 23.4.0 ou une version ultérieure.

La stratégie de recherche sélectionnée comporte les exigences supplémentaires suivantes :

Pendant l'initialisation du schéma géré, la mémoire de l'agent Oracle valide la version de la base de données connectée avant d'exécuter le script DDL et signale une action de mise à niveau lorsque la stratégie de recherche sélectionnée n'est pas disponible.

Configuration de la base de données gérée

Lorsqu'un propriétaire de schéma crée ou recrée une banque de mémoire, le package Python de mémoire de l'agent Oracle prépare les objets de base de données gérés dont il a besoin. Le propriétaire a besoin des privilèges système Oracle CREATE TABLE et CREATE PROCEDURE.

Connectez-vous en tant que propriétaire du schéma pour la configuration du schéma. Une connexion d'application utilisant schema_owner accède à un emplacement de stockage existant et doit utiliser SchemaPolicy.REQUIRE_EXISTING. Elle ne crée ni ne met à jour les objets de base de données gérés du propriétaire.

Installation du kit SDK

Vous trouverez toutes les versions et plates-formes prises en charge de oracleagentmemory sur la page de téléchargement de logiciel.

Pour installer la mémoire de l'agent, exécutez :

pip install "oracleagentmemory==26.8.0"

L'installation avec pip tire des roues binaires prédéfinies sur les plates-formes prises en charge.

Journalisation et tests de diagnostic

Oracle AI Agent Memory émet des messages de diagnostic via la journalisation Python standard sous les noms de journaliseur commençant par oracleagentmemory. Le kit SDK ne configure pas de gestionnaires ou de niveaux de journalisation. Les applications peuvent acheminer ces journaux vers leur console, fichier ou pipeline d'observabilité existant. Certains enregistrements de journal utilisent les champs extra de la journalisation Python pour des diagnostics structurés sécurisés, qui peuvent être capturés par des gestionnaires de journalisation structurés.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

Pour le dépannage dans les environnements contrôlés, activez les journaux DEBUG :

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Conservez les déploiements de production à un niveau autre que DEBUG. Les journaux DEBUG sont destinés au développement et à la prise en charge des diagnostics, et le texte des messages de journal ne doit pas être traité comme une API publique stable.

Purge des enregistrements de durée de vie et expirés

Les messages et les mémoires sauvegardés par Oracle DB peuvent expirer automatiquement grâce à une combinaison de valeurs par défaut de conservation au niveau du schéma et de valeurs ttl_days/ttl_anchor par enregistrement sur les API d'écriture et de mise à jour.

Lorsque la mémoire de l'agent Oracle crée ou met à niveau son schéma géré, elle crée également un travail de purge DBMS_SCHEDULER quotidien qui enlève physiquement les lignes expirées, leurs blocs d'extraction et les blocs d'extraction orphelins dont la ligne source prise en charge n'existe plus. Si la configuration de schéma doit créer ce travail mais que l'utilisateur de base de données ne dispose pas de CREATE JOB, la configuration se termine par un avertissement : les lignes expirées restent filtrées hors des lectures et des recherches, mais les blocs expirés et orphelins ne sont pas purgés physiquement tant qu'un utilisateur privilégié n'a pas créé le travail. Sous SchemaPolicy.REQUIRE_EXISTING, un travail de purge manquant est toléré et consigné au niveau DEBUG.

Les schémas à mémoire liée créent également un déclencheur qui valide de nouveau les mémoires restantes après la suppression d'un lien, y compris lorsque le travail de purge supprime une mémoire expirée et qu'Oracle met ses liens en cascade. Le propriétaire du schéma a besoin de CREATE TRIGGER lors de la création ou de la mise à niveau du schéma ; les utilisateurs d'exécution standard n'ont pas besoin de ce privilège.

Pour obtenir le modèle de conservation complet, la configuration MemoryRetentionConfig, les requêtes de vérification de purge, la création manuelle de travaux d'administrateur de base de données et des exemples Python à l'aide de TimeToLiveAnchor, reportez-vous à Utilisation du délai de vie pour les messages et les mémoires.

Autorisations de schéma Linked-Memory

Le schéma de mémoire liée inclut un graphique de propriétés Oracle SQL et un déclencheur de base de données qui conserve l'état de cycle de vie correct lorsque des liens sont supprimés.

Si vous définissez memory_store_id, le nom du graphique géré est préfixé de la même manière que les tables. Par exemple, memory_store_id="SALES" crée SALES_MEMORY_GRAPH.

Les valeurs APP_SCHEMA et APP_USER sont des espaces réservés. Remplacez-les par vos noms utilisateur de base de données. Les exemples utilisent des majuscules car les identificateurs Oracle sans guillemets sont stockés en majuscules.

  1. Lors de la configuration du schéma, accordez au propriétaire du schéma CREATE PROPERTY GRAPH et CREATE TRIGGER. Ils sont requis avec SchemaPolicy.CREATE_IF_NECESSARY ou SchemaPolicy.RECREATE chaque fois que le graphique géré ou le déclencheur de suppression de lien doit être créé. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    Accordez-les à nouveau avant une mise à niveau ultérieure du kit SDK si cette mise à niveau doit créer ou recréer le graphique géré ou le déclencheur de suppression de lien.

  2. Au cours de l'exécution normale de l'application, déterminez l'utilisateur qui se connecte à Oracle :
    • Si l'utilisateur d'exécution est APP_SCHEMA, aucune autorisation de graphique supplémentaire n'est nécessaire. Le propriétaire du graphique peut accéder à son propre graphique.
    • Si l'utilisateur d'exécution est différent, exécutez la commande suivante en tant que APP_SCHEMA après la configuration du schéma. Le nom de graphique par défaut est MEMORY_GRAPH. Utilisez le nom préfixé lorsque memory_store_id est défini. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      L'utilisateur runtime a également besoin de l'accès normal à la base de données requis par le reste du déploiement de la mémoire de l'agent Oracle.

SchemaPolicy.REQUIRE_EXISTING ignore la première étape car il s'attend à ce que le graphique et le déclencheur existent déjà. Un utilisateur d'exécution distinct a toujours besoin d'accéder au graphique de propriétés gérées.

Initialiser l'instance de mémoire

Créez une instance OracleAgentMemory en configurant l'intégrateur, le LLM et la connexion de base de données.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

Remarque : par défaut, les schémas Oracle AI Database gérés ne définissent pas de période de conservation pour les messages et les mémoires. Configurez les paramètres de durée de vie MemoryRetentionConfig ou par enregistrement pour utiliser une période de conservation différente. Pour plus d'informations, reportez-vous à Utilisation du délai de vie pour les messages et les mémoires.

Stocker les entrées de mémoire

Commencez par créer un thread, ajouter des messages et stocker une entrée de mémoire pour l'utilisateur.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Récupérer les entrées de mémoire

Rechercher des mémoires à l'aide d'une requête de portée utilisateur.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Sortie :

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Remarque : La sortie affichée est illustrative. Les versions futures peuvent renvoyer des types de résultats, des champs ou des prescriptions supplémentaires.

Compatibilité des modèles

Les grands modèles de langage (LLM) et les modèles d'intégration suivants sont compatibles avec oracleagentmemory.

LLM

Les grands modèles de langage (LLM) suivants ont été confirmés comme compatibles.

Modèles hébergés par OCI

OpenAI

LLM auto-hébergés

Anthropique

Gémeaux

Intégrations

Les modèles d'intégration suivants ont été confirmés comme compatibles.

Modèles hébergés par OCI

OpenAI

LLM auto-hébergés

Gémeaux