Mémoire d'agent

Cette page présente l'implémentation concrète de la mémoire de l'agent Oracle AI.

Mémoire de l'agent Oracle

classe oracleagentmemory.core.OracleAgentMemory

Bases : IAgentMemory

Client de mémoire d'agent soutenu par Oracle DB ou un emplacement de stockage fourni par l'appelant.

Créez un client de mémoire.

• Paramètres:
  • store OracleMemoryStore : instance de stockage préconfigurée facultative. Lorsqu'il est fourni, le client utilise ce magasin directement au lieu d'instancier son propre magasin. Cela est utile lorsque les appelants ont besoin d'une configuration de stockage au-delà des options de constructeur exposées par OracleAgentMemory.
  • connection object : connexion/pool Oracle DB facultatif. Lorsqu'elle est fournie, la banque de données est utilisée. La transmission d'une connexion brute active le mode de session unique pour cette instance client. Par conséquent, les demandes simultanées doivent utiliser un pool de connexions à la place. Lorsqu'ils sont omis, les appelants doivent transmettre un élément store explicite.
  • embedder IEmbedder | str : instance d'implémentation Embedder ou identificateur de modèle d'intégration LiteLLM. Lorsqu'il est omis, aucun intégrateur n'est attaché et les appelants doivent fournir des vecteurs précalculés via des API de stockage de niveau inférieur.
  • LLM ILlm : adaptateur LLM facultatif utilisé par les threads pour l'extraction de mémoire et/ou l'agrégation de contexte. Par défaut, les threads créés ou chargés à partir de ce client nécessitent un LLM afin que les messages récents puissent être extraits pour des mémoires durables. Transmettez llm ici, indiquez-en un plus tard dans create_thread ou désactivez-le avec extract_memories=False.
  • extract_memories bool : lorsque True, les threads créés ou chargés par ce client nécessitent un LLM et l'extraction automatique de la mémoire reste activée. Définissez la valeur sur False pour désactiver l'extraction automatique de la mémoire et permettre à ces threads de fonctionner sans LLM. La valeur par défaut est True. Par conséquent, les LLM d'extraction manquants échouent rapidement.
  • schema_policy SchemaPolicy | str : stratégie de configuration de schéma de base de données utilisée uniquement lors de la construction d'une banque de base de données à partir de connection. La valeur par défaut est SchemaPolicy.REQUIRE_EXISTING.
  • table_name_prefix str : préfixe facultatif de table/d'index de base de données utilisé uniquement lors de la construction d'une banque de base de données à partir de connection.
• Elèves : ValueError – Si une configuration d'emplacement de stockage en conflit est fournie, par exemple en transmettant store et connection, des options propres à la base de données sans connexion à la base de données ou en omettant store et connection.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

méthode add_agent

Ajoutez un enregistrement de profil d'agent au magasin.

• Paramètres:
  • agent_id str : identificateur d'agent.
  • information str : informations de forme libre sur l'agent.
• Renvoie : identificateur du profil d'agent stocké.
• Type de retour : str

Remarques

Les enregistrements de profil d'agent sont stockés dans le magasin de niveau client.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

méthode add_memory

Ajoutez une mémoire dans le système de mémoire, attribuée à l'utilisateur, à l'agent et au thread indiqués.

• Paramètres:
  • content str : contenu de mémoire à conserver.
  • user_id str : identificateurs de portée facultatifs associés à la mémoire stockée.
  • agent_id str : identificateurs de portée facultatifs associés à la mémoire stockée.
  • thread_id str : identificateurs de portée facultatifs associés à la mémoire stockée.
  • memory_id str : identificateur stable fourni par l'appelant facultatif pour cette ligne de mémoire.
  • **store_kwargs (N'importe lequel) – Options d'écriture propres au magasin transférées vers le magasin de sauvegarde.
• Retours : Identificateur de l'enregistrement de mémoire inséré.
• Type de retour : str

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

méthode add_user

Ajoutez un enregistrement de profil utilisateur au magasin.

• Paramètres:
  • user_id str : identificateur utilisateur.
  • information str : informations de forme libre sur l'utilisateur.
• Retours : Identifiant du profil utilisateur stocké.
• Type de retour : str

Remarques

Les enregistrements de profil utilisateur sont stockés dans le magasin de niveau client (non liés à un thread spécifique).

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

méthode create_thread

Créez et inscrivez un thread.

• Paramètres:
  • thread_id str : identificateur de thread. Si elle est omise, une nouvelle est générée.
  • user_id str – Identifiant utilisateur attaché à cet enregistrement de thread. Si elle est omise, une nouvelle est générée.
  • agent_id str : identificateur d'agent attaché à cet enregistrement de thread. Si elle est omise, une nouvelle est générée.
  • LLM ILlm – Remplacement facultatif du LLM pour ce thread. Si elle est omise, le LLM de niveau client configuré au moment de la construction est utilisé. Par défaut, le client ou le thread doit fournir un LLM afin que l'extraction automatique de la mémoire puisse s'exécuter. Définissez extract_memories=False ici ou sur le client pour refuser cette exigence.
  • extract_memories bool : remplacement par thread facultatif pour l'extraction automatique de la mémoire. Lorsque True, ce thread requiert un LLM afin que l'extraction automatique puisse être exécutée. Définissez la valeur sur False pour désactiver l'extraction automatique pour ce thread et autoriser l'opération sans LLM. Lorsqu'il est omis, le paramètre extract_memories de niveau client est utilisé.
  • max_message_token_length int – Taille maximale des messages d'invite avant troncation ou agrégation lors de l'extraction de la mémoire et des mises à jour de résumé contextuel. Le contenu du message stocké reste inchangé. Lorsqu'elle est omise, la valeur par défaut est 15_000 tokens.
  • message_shortening_input_token_limit int – Taille maximale, en jetons, de l'extrait de message envoyé au LLM lors du raccourcissement des copies de message d'invite surdimensionnées. Lorsqu'elle est omise, la valeur par défaut est 30_000 tokens.
  • memory_extraction_window int : nombre de messages récents à inclure lors de l'extraction de la mémoire. Définissez la valeur sur -1 pour effectuer une extraction par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés. Lorsqu'elle est omise, la valeur par défaut est -1.
  • context_summary_update_frequency int – Fréquence des actualisations de résumé contextuel. Définissez la valeur sur -1 pour effectuer une mise à jour récapitulative par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés. La même cadence est réutilisée pour les métadonnées d'agrégation de thread actualisées pendant add_messages. Lorsqu'elle est omise, la valeur par défaut est 4.
  • memory_extraction_frequency int : fréquence des mises à jour d'extraction de mémoire. Définissez la valeur sur -1 pour effectuer une extraction par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés. Lorsqu'elle est omise, la valeur par défaut est -1.
  • memory_extraction_token_limit int : taille maximale de l'invite d'extraction dans les jetons. Lorsqu'elle est omise, la valeur par défaut est 100_000.
  • enable_context_summary bool – Indique s'il faut conserver un récapitulatif du contexte en cours d'exécution pour ce thread.
  • **kwargs (Tout) : options de thread supplémentaires propres à l'implémentation.
• Retours : A OracleThread.
• Type de retour : OracleThread
• Elèves : ValueError – Si aucun LLM n'est disponible pour l'extraction automatique de la mémoire et que le thread et le client n'ont pas été configurés avec extract_memories=False.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

méthode delete_memory

Supprimer un enregistrement de mémoire par identifiant.

• Paramètres : memory_id str – Identificateur de mémoire.
• Retours : nombre de lignes de mémoire supprimées (0 ou 1).
• Type de retour : int

Exemples 

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

méthode delete_thread

Supprimer tous les enregistrements associés à un identificateur de thread.

• Paramètres:
  • thread_id str : identificateur de thread à supprimer.
  • allow_non_existing bool : lorsque True, la suppression d'un thread manquant est traitée comme une opération no-op.
• Renvoie : nombre de lignes de thread supprimées (0 ou 1).
• Type de retour : int

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

méthode get_thread

Récupérer un thread précédemment créé.

• Paramètres:
  • thread_id str – Identificateur utilisé lors de la création du thread.
  • LLM ILlm – Remplacement facultatif du LLM pour le thread rouvert. Lorsqu'il est omis, le LLM de niveau client configuré au moment de la construction est utilisé.
  • extract_memories bool : remplacement facultatif pour l'extraction automatique de la mémoire sur le thread rouvert. Lorsqu'il est omis, le paramètre extract_memories de niveau client est utilisé.
  • max_message_token_length int : remplacement facultatif de la taille maximale des messages d'invite avant troncation ou agrégation lors de l'extraction de la mémoire et des mises à jour de résumé contextuel. Le contenu du message stocké reste inchangé.
  • message_shortening_input_token_limit int : remplacement facultatif de la taille maximale, en jetons, de l'extrait de message envoyé au LLM lors du raccourcissement des copies de message d'invite surdimensionnées.
  • memory_extraction_window int : remplacement facultatif du nombre de messages récents utilisés lors de l'extraction de la mémoire.
  • context_summary_update_frequency int – Remplacement facultatif de la fréquence d'actualisation de la synthèse du contexte.
  • memory_extraction_frequency int : remplacement facultatif de la fréquence des mises à jour d'extraction de mémoire.
  • memory_extraction_token_limit int : remplacement facultatif de la taille maximale de l'invite d'extraction dans les jetons.
  • enable_context_summary bool : remplacement facultatif pour indiquer si le thread rouvert doit conserver un récapitulatif du contexte en cours d'exécution.
• Renvoie : identificateur de thread reconstruit à partir des métadonnées de stockage.
• Type de retour : OracleThread
• Elèves :
  • KeyError – Si l'ID de thread est inconnu de cette instance client.
  • ValueError – Si aucun LLM n'est disponible pour l'extraction automatique de la mémoire et que le client n'a pas été configuré avec extract_memories=False.

Remarques

Les remplacements explicites par appel sont prioritaires. Lorsque des remplacements d'exécution sont omis, les threads rouverts utilisent la configuration d'exécution persistante lorsqu'elle est disponible avant de revenir aux valeurs par défaut du kit SDK.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'