Mémoire de l'agent

Cette page présente la mise en oeuvre concrète de la mémoire de l'agent Oracle AI Agent.

Mémoire de l'agent Oracle

Note : OracleAgentMemory.delete_thread() est le chemin pris en charge pour le nettoyage en cascade avec une portée d'unité d'exécution. Il supprime le fil ainsi que les messages associés, les mémoires durables et les données vectorielles ou fragmentées gérées. Cette valeur est supérieure à OracleThread.delete_message(), qui supprime uniquement la rangée du message brut.

classe `oracleagentmemory.core.OracleAgentMemory`

Bases : IAgentMemory

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

Créez un client de mémoire.

Paramètres :
- magasin OracleMemoryStore – Instance de magasin 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 magasin au-delà des options du constructeur exposées par OracleAgentMemory.
- connexion object – Connexion/groupe Oracle DB facultatif. Lorsque cette option est fournie, le magasin de base de données est utilisé. La transmission d'une connexion brute active le mode monosession pour cette instance client. Les demandes concurrentes doivent donc utiliser une réserve de connexions à la place. Lorsqu'elle est omise, les appelants doivent transmettre une valeur store explicite.
- embedder IEmbedder | str – Instance de mise en oeuvre d'embedder ou identificateur de modèle d'intégration LiteLLM. Lorsqu'elle est omise, aucun intégrateur n'est attaché et les appelants doivent fournir des vecteurs précalculés au moyen d'API de magasin de niveau inférieur.
- LLM ILlm – Adaptateur LLM facultatif utilisé par les unités d'exécution pour l'extraction de mémoire ou la récapitulation de contexte. Par défaut, les unités d'exécution créées ou chargées à partir de ce client nécessitent un LLM afin que les messages récents puissent être extraits pour des mémoires durables. Transmettez un llm ici, fournissez-en un plus tard dans create_thread ou désactivez-le avec extract_memories=False.
- extract_memories bool – Lorsque True, les unités d'exécution créées ou chargées par ce client nécessitent un GML et l'extraction automatique de mémoire reste activée. Réglez à False pour désactiver l'extraction automatique de mémoire et permettre à ces unités d'exécution de fonctionner sans GML. La valeur par défaut est True. Les LLM d'extraction manquants échouent rapidement.
- schema_policy SchemaPolicy | str – Politique de configuration de schéma de base de données utilisée uniquement lors de la création d'un magasin de base de données à partir de connection. La valeur par défaut est SchemaPolicy.REQUIRE_EXISTING.
- table_name_prefix str – Préfixe de table/d'index de base de données facultatif utilisé uniquement lors de la création d'un magasin de base de données à partir de connection.
Élévations : ValueError – Si une configuration de magasin conflictuelle est fournie, par exemple transmettre store et connection, des options propres à la base de données sans connexion à la base de données, ou omettre 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`

Ajouter un enregistrement de profil d'agent au magasin.

Paramètres :
- agent_id str – Identificateur de l'agent.
- informations str – Informations à structure libre sur l'agent.
Retours : Identificateur du profil d'agent stocké.
Type de retour : str

Notes

Les enregistrements de profil d'agent sont stockés dans le magasin au niveau client et n'ont intentionnellement pas de portée. L'identificateur d'enregistrement retourné est le même identificateur public que celui utilisé par l'application pour 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 :
- contenu 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 d'étendue 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 rangée de mémoire.
- **store_kwargs (Any) – Options d'écriture propres au magasin transmises au magasin dorsal.
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`

Ajouter un enregistrement de profil d'utilisateur au magasin.

Paramètres :
- user_id str – Identificateur d'utilisateur.
- informations str – Informations à structure libre sur l'utilisateur.
Retours : Identificateur du profil d'utilisateur stocké.
Type de retour : str

Notes

Les enregistrements de profil d'utilisateur sont stockés dans le magasin au niveau client et n'ont intentionnellement pas de portée. L'identificateur d'enregistrement retourné est le même identificateur public que celui utilisé par l'application pour 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 enregistrez un thread.

Paramètres :
- thread_id str – Identificateur de fil. Si elle est omise, une nouvelle est générée.
- user_id str – Identificateur d'utilisateur associé à cet enregistrement d'unité d'exécution. Si elle est omise, une nouvelle est générée.
- agent_id str – Identificateur d'agent associé à cet enregistrement d'unité d'exécution. Si elle est omise, une nouvelle est générée.
- métadonnées dict[str, Any] | None – Des métadonnées de type JSON facultatives ont été conservées sur la rangée de l'unité d'exécution.
- LLM ILlm – Remplacement facultatif du LLM pour cette unité d'exécution. S'il est omis, le LLM au niveau client configuré au moment de la construction est utilisé. Par défaut, le client ou l'unité d'exécution doit fournir un LLM afin que l'extraction automatique de mémoire puisse être exécutée. Définissez extract_memories=False ici ou sur le client pour vous désabonner de cette exigence.
- extract_memories bool – Remplacement facultatif par unité d'exécution pour l'extraction automatique de mémoire. Lorsque True, cette unité d'exécution nécessite un GML pour que l'extraction automatique puisse s'exécuter. Réglez à False pour désactiver l'extraction automatique pour cette unité d'exécution et autoriser l'opération sans GML. Lorsqu'il est omis, le paramètre extract_memories au niveau du client est utilisé.
- max_message_token_length int – Taille maximale du message d'invite avant la troncation ou la récapitulation lors de l'extraction de mémoire et des mises à jour du sommaire du contexte. 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 de la réduction des copies de message à temps 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 mémoire. Réglez à -1 pour effectuer une extraction par appel add_messages à l'aide du lot complet des messages nouvellement ajoutés. Lorsqu'elle est omise, la valeur par défaut est -1.
- context_summary_update_frequency int – Fréquence des actualisations du sommaire du contexte. Réglez à -1 pour effectuer une mise à jour sommaire par appel add_messages à l'aide du lot complet des 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. Réglez à -1 pour effectuer une extraction par appel add_messages à l'aide du lot complet des 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 sommaires. Lorsqu'elle est omise, la valeur par défaut est 100_000.
- context_card_token_limit int – Taille maximale, en jetons, des invites de LLM utilisées pour la récapitulation de carte de contexte. Lorsqu'elle est omise, la valeur par défaut est 100_000.
- enable_context_summary bool – Indique s'il faut conserver un sommaire de contexte en cours d'exécution pour cette unité d'exécution.
- **kwargs (Au choix) – Options d'unité d'exécution supplémentaires propres à la mise en oeuvre.
Retours : OracleThread.
Type de retour : OracleThread
Élévations : ValueError – Si aucun GML n'est disponible pour l'extraction automatique de mémoire et que l'unité d'exécution 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`

Sert à supprimer un enregistrement de profil d'agent par code.

Paramètres :
- agent_id str – Identificateur de l'agent dont le profil doit être supprimé.
- cascade bool – Lorsque True (par défaut), supprimez également les enregistrements ciblés pour cet agent. Cela inclut la suppression des threads propriétaires eux-mêmes, des messages et des enregistrements de type mémoire supprimés avec ces threads, ainsi que tout autre enregistrement directement ciblé par un agent, tel que les messages, les mémoires, les directives, les faits ou les préférences. Ce nettoyage de portée est toujours exécuté lorsque l'enregistrement de profil d'agent correspondant est déjà absent. Réglez à False pour supprimer uniquement l'enregistrement de profil.
Retours : Nombre de rangées de profil d'agent supprimées (0 ou 1). Il peut s'agir de 0 lorsque les rangées de portée ont été supprimées lors du nettoyage en cascade.
Type de retour : int

Notes

Les suppressions en cascade sont planifiées et exécutées dans le magasin de sauvegarde, de sorte que la suppression du profil et toutes les suppressions enfants ciblées se produisent dans une opération de magasin.

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`

Supprimez un enregistrement de type mémoire (par exemple, une mémoire, un fait, une préférence ou une directive) par identificateur.

Paramètres : memory_id str – Identificateur de mémoire. L'identificateur peut faire référence à un enregistrement memory, guideline, fact ou preference stocké.
Retours : Nombre de rangées 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`

Supprimez tous les enregistrements associés à un identificateur d'unité d'exécution.

Parameters (Paramètres) : thread_id str – Identificateur de fil à supprimer.
Retours : Nombre de rangées d'unité d'exécution supprimées (0 ou 1).
Type de retour : int

Notes

Utilisez cette opération lorsque vous devez supprimer une unité d'exécution de conservation complète. Le magasin de sauvegarde supprime l'unité d'exécution ainsi que les messages ciblés par unité d'exécution associés, les mémoires durables et les rangées de vecteurs ou de fragments gérées. Cela diffère de OracleThread.delete_message(), qui supprime uniquement l'enregistrement de message brut et n'est pas transmis en cascade aux 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 d'utilisateur par identificateur.

Paramètres :
- user_id str – Identificateur d'utilisateur dont le profil doit être supprimé.
- cascade bool – Lorsque True (par défaut), supprimez également les enregistrements dont la portée est définie pour cet utilisateur. Cela inclut la suppression des threads propriétaires eux-mêmes, des messages et des enregistrements de type mémoire supprimés avec ces threads, et de tous les autres enregistrements directement ciblés par l'utilisateur tels que les messages, les mémoires, les directives, les faits ou les préférences. Ce nettoyage de portée est toujours exécuté lorsque l'enregistrement de profil d'utilisateur correspondant est déjà absent. Réglez à False pour supprimer uniquement l'enregistrement de profil.
Retours : Nombre de rangées de profil d'utilisateur supprimées (0 ou 1). Il peut s'agir de 0 lorsque les rangées de portée ont été supprimées lors du nettoyage en cascade.
Type de retour : int

Notes

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`

Extraire une unité d'exécution créée précédemment.

Paramètres :
- thread_id str – Identificateur utilisé lors de la création de l'unité d'exécution.
- LLM ILlm – Remplacement facultatif du LLM pour l'unité d'exécution rouverte. Lorsqu'il est omis, le LLM au niveau client configuré au moment de la construction est utilisé.
- extract_memories bool – Remplacement facultatif pour l'extraction automatique de mémoire sur l'unité d'exécution rouverte. Lorsqu'il est omis, le paramètre extract_memories au niveau du client est utilisé.
- max_message_token_length int – Remplacement facultatif pour la taille maximale du message d'invite avant la troncation ou la récapitulation lors de l'extraction de mémoire et des mises à jour du sommaire du contexte. Le contenu du message stocké reste inchangé.
- message_shortening_input_token_limit int – Remplacement facultatif pour la taille maximale, en jetons, de l'extrait de message envoyé au LLM lors de la réduction des copies de message à temps d'invite surdimensionnées.
- memory_extraction_window int – Remplacement facultatif pour le nombre de messages récents utilisés lors de l'extraction de mémoire.
- context_summary_update_frequency int – Remplacement facultatif de la fréquence des actualisations contextuelles.
- 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 pour la taille maximale, en jetons, des invites de LLM utilisées pour l'extraction de mémoire et l'exécution des mises à jour sommaires.
- context_card_token_limit int – Remplacement facultatif pour la taille maximale, en jetons, des invites de LLM utilisées pour la récapitulation de carte de contexte.
- enable_context_summary bool – Remplacement facultatif pour indiquer si l'unité d'exécution rouverte doit conserver un sommaire de contexte en cours d'exécution.
Retours : Poignée d'unité d'exécution reconstruite à partir des métadonnées du magasin.
Type de retour : OracleThread
Déclenche :
- KeyError – Si l'ID unité d'exécution est inconnu pour cette instance de client.
- ValueError – Si aucun LLM n'est disponible pour l'extraction automatique de mémoire et que le client n'a pas été configuré avec extract_memories=False.

Notes

Les remplacements explicites par appel ont priorité. Lorsque les remplacements d'exécution sont omis, les unités d'exécution rouvertes utilisent une configuration d'exécution persistante lorsqu'elles sont disponibles avant de revenir aux valeurs par défaut de la trousse 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'

Mémoire de l'agent