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

Remarque : OracleAgentMemory.delete_thread() est le chemin pris en charge pour le nettoyage en cascade de niveau thread. Il supprime le thread avec les messages associés, les mémoires durables et les données vectorielles ou de bloc gérées. Elle est plus large que OracleThread.delete_message(), ce qui supprime uniquement la ligne de message brut.

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 et sont intentionnellement annulés. L'identificateur d'enregistrement renvoyé est le même que l'identificateur public que l'application utilise comme agent_id.

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 et sont intentionnellement annulés. L'identificateur d'enregistrement renvoyé est le même que l'identificateur public que l'application utilise comme user_id.

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.
  • metadata dict[str, Any] | None : les métadonnées de type JSON facultatives sont conservées sur la ligne du thread.
  • 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. Lorsqu'elle est omise, la valeur par défaut est -1.
  • 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, en jetons, des invites de LLM utilisées pour l'extraction de mémoire et l'exécution des mises à jour récapitulatives. Lorsqu'elle est omise, la valeur par défaut est 100_000.
  • context_card_token_limit int – Taille maximale, en jetons, des invites LLM utilisées pour la synthèse des cartes de contexte. 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_agent

Supprimer un enregistrement de profil d'agent par identifiant.

• Paramètres:
  • agent_id str : identificateur d'agent dont le profil doit être enlevé.
  • cascade bool : lorsque True (par défaut), supprimez également les enregistrements ciblés sur cet agent. Cela inclut la suppression des threads propriétaires eux-mêmes, les messages et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée agent directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Ce nettoyage ciblé s'exécute quand la ligne agent-profile correspondante est déjà absente. Définissez la valeur sur False pour enlever uniquement l'enregistrement de profil.
• Retours : nombre de lignes de profil d'agent supprimées (0 ou 1). Il peut toujours s'agir de 0 lorsque des lignes de portée ont été enlevées lors du nettoyage en cascade.
• Type de retour : int

Remarques

Les suppressions en cascade sont planifiées et exécutées à l'intérieur de la banque de sauvegarde, de sorte que la suppression de profil et toutes les suppressions enfant ciblées se produisent en une seule opération.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

méthode delete_memory

Supprimer un enregistrement de type mémoire (par exemple, une mémoire, un fait, une préférence ou une consigne) par identifiant.

• Paramètres : memory_id str – Identificateur de mémoire. L'identificateur peut faire référence à un enregistrement memory, guideline, fact ou preference stocké.
• Renvoie : nombre de lignes de type 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.
• Renvoie : nombre de lignes de thread supprimées (0 ou 1).
• Type de retour : int

Remarques

Utilisez cette opération lorsque vous avez besoin d'une suppression complète de la conservation d'un thread. Le magasin de sauvegarde supprime le thread avec les messages de portée thread associés, les mémoires durables et les lignes de vecteur ou de bloc gérées. Cela diffère de OracleThread.delete_message(), qui supprime uniquement l'enregistrement de message brut et ne se répercute pas sur les mémoires dérivées créées à partir de ce message.

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 delete_user

Supprimer un enregistrement de profil utilisateur par identifiant.

• Paramètres:
  • user_id str : identificateur utilisateur dont le profil doit être supprimé.
  • cascade bool – Lorsque True (par défaut), supprimez également les enregistrements ciblés pour cet utilisateur. Cela inclut la suppression des threads propriétaires eux-mêmes, les messages et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée utilisateur directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Ce nettoyage ciblé s'exécute toujours lorsque la ligne de profil utilisateur correspondante est déjà absente. Définissez la valeur sur False pour enlever uniquement l'enregistrement de profil.
• Retours : nombre de lignes de profil utilisateur supprimées (0 ou 1). Il peut toujours s'agir de 0 lorsque des lignes de portée ont été enlevées lors du nettoyage en cascade.
• Type de retour : int

Remarques

Les suppressions en cascade sont planifiées et exécutées à l'intérieur de la banque de sauvegarde, de sorte que la suppression de profil et toutes les suppressions enfant ciblées se produisent en une seule opération.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
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, dans les jetons, des invites LLM utilisées pour l'extraction de mémoire et l'exécution des mises à jour récapitulatives.
  • context_card_token_limit int – Remplacement facultatif de la taille maximale, dans les jetons, des invites LLM utilisées pour la synthèse des cartes contextuelles.
  • 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'