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

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.

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 utilisateur sont stockés dans le magasin au 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 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.
- 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. La même fréquence est réutilisée pour les métadonnées de récapitulation d'unité d'exécution 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. 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 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 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_memory`

Supprimer un enregistrement de mémoire par identificateur.

Paramètres : memory_id str – Identificateur de mémoire.
Retours : Nombre de rangées 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`

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

Paramètres :
- thread_id str – Identificateur de fil à supprimer.
- allow_non_existing bool – Lorsque True, la suppression d'une unité d'exécution manquante est considérée comme sans opération.
Retours : Nombre de rangées d'unité d'exécution 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`

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 de l'invite d'extraction dans les jetons.
- 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