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 d'extraction gérées. Elle est plus large que OracleThread.delete_message(), ce qui supprime uniquement la ligne de message brut. Avant de supprimer le thread, il attend une extraction en arrière-plan acceptée antérieurement déjà connue de ce client pour ce thread. Il ne sérialise pas toutes les opérations simultanées pour le même thread tant que la suppression est en cours.

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.

Avertissement : SchemaPolicy.CREATE_IF_NECESSARY peut être plus coûteux que le démarrage normal du client car il peut appliquer des instructions LDD de schéma géré et réécrire les données au mieux avant la réussite de l'initialisation. Planifiez la première ouverture d'un ancien schéma géré en tant qu'opération de migration ou de maintenance lorsque ce schéma peut contenir de nombreuses lignes.

Si la configuration du schéma doit créer le travail de purge géré des enregistrements expirés mais que l'utilisateur de base de données ne dispose pas du privilège Scheduler-job, l'initialisation avertit et continue. Les messages et les mémoires expirés restent masqués lors des lectures et des recherches, mais ils ne sont pas purgés physiquement tant que le travail n'est pas créé par un utilisateur disposant du privilège CREATE JOB ou d'un planificateur équivalent.

Lorsque SchemaPolicy.CREATE_IF_NECESSARY crée pour la première fois un index hybride géré sur un schéma existant, Oracle analyse le texte de recherche stocké et crée l'état de l'index hybride géré à partir du modèle dans la base de données configuré. Le démarrage du client attend la fin de ce script LDD. Planifiez donc la première mise à niveau hybride en tant qu'opération de migration ou de maintenance pour les schémas volumineux. SearchIndexSyncMode contrôle la maintenance en cours après l'existence de l'index. Il ne rend pas le premier build d'index asynchrone.

Exemples 

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

Utilisez un modèle d'intégration dans la base de données pour exploiter la recherche d'index hybride Oracle :

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

méthode add_agent

Ajoutez un enregistrement de profil d'agent au magasin.

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",
    metadata={"source": "catalog"},
)
'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.

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'

method add_memory_async (async)

Ajoutez de manière asynchrone un enregistrement de mémoire au client.

méthode add_user

Ajoutez un enregistrement de profil utilisateur au magasin.

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.",
    metadata={"source": "crm"},
)
'u1'

méthode close

Fermez le composant de mémoire de l'agent.

La fermeture arrête d'accepter le nouveau travail d'extraction en arrière-plan et attend que l'extraction en arrière-plan en attente se termine jusqu'au délai d'attente configuré. Si ce délai expire, close() renvoie même si certains travaux d'extraction en arrière-plan sont encore inachevés. La méthode est idempotente.

Exemples 

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

method close_async (async)

Fermez de manière asynchrone le composant de mémoire de l'agent.

Cette méthode suit le même comportement d'arrêt que close(). Si le délai expire, il peut revenir alors que le travail d'extraction en arrière-plan est toujours en cours d'exécution.

Exemples 

await client.close_async()

méthode create_thread

Créez et enregistrez un thread.

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.

Remarques

Les suppressions en cascade sont planifiées et exécutées dans le magasin de sauvegarde, de sorte que la suppression de profil et toutes les suppressions enfant ciblées se produisent en une seule opération. Avant l'exécution de la suppression en cascade, cette méthode attend une extraction en arrière-plan antérieure déjà acceptée pour les threads propriétaires connus à ce moment via ce composant de mémoire d'agent. Il n'attend pas le travail accepté après ce début d'attente ou le travail démarré par un autre composant ou processus de mémoire d'agent. L'utilisation simultanée de portée acteur pendant la suppression n'est pas prise en charge.

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.

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

method delete_memory_async (async)

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

méthode delete_thread

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

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 ainsi que les messages associés de portée thread, les mémoires durables et les données d'extraction 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. Avant de supprimer le thread, cette méthode attend une extraction en arrière-plan antérieure déjà acceptée pour ce thread via ce composant de mémoire d'agent. Il n'attend pas le travail en arrière-plan accepté après ce début d'attente ou le travail démarré par un autre composant ou processus de mémoire d'agent. L'utilisation simultanée du même thread pendant la suppression n'est pas prise en charge.

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.

Remarques

Les suppressions en cascade sont planifiées et exécutées dans le magasin de sauvegarde, de sorte que la suppression de profil et toutes les suppressions enfant ciblées se produisent en une seule opération. Avant l'exécution de la suppression en cascade, cette méthode attend une extraction en arrière-plan antérieure déjà acceptée pour les threads propriétaires connus à ce moment via ce composant de mémoire d'agent. Il n'attend pas le travail accepté après ce début d'attente ou le travail démarré par un autre composant ou processus de mémoire d'agent. L'utilisation simultanée de portée acteur pendant la suppression n'est pas prise en charge.

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éé.

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'

Rechercher de manière synchrone les enregistrements pertinents pour une requête.

Remarques

Les valeurs de portée None explicites suivent toujours les règles de correspondance exacte résolues : exact_*_match=False laisse cette dimension sans contrainte, tandis que exact_*_match=True correspond uniquement aux enregistrements sans portée sur cette dimension.

method search_async (async)

Rechercher de manière asynchrone les enregistrements pertinents pour une requête.

Remarques

Les valeurs de portée None explicites suivent toujours les règles de correspondance exacte résolues : exact_*_match=False laisse cette dimension sans contrainte, tandis que exact_*_match=True correspond uniquement aux enregistrements sans portée sur cette dimension.

méthode update_memory

Mettre à jour un enregistrement stocké de type mémoire par identifiant.

Remarques

Les champs omis sont préservés de l'enregistrement stocké. La portée stockée reste inchangée. Le remplacement de métadonnées est un remplacement d'objet entier, et non une fusion JSON récursive.

method update_memory_async (async)

Mettre à jour de manière asynchrone un enregistrement de type mémoire stocké par identifiant.

Remarques

Les champs omis restent inchangés. Ces mises à jour de portée ne sont pas prises en charge par cette API. Le remplacement de métadonnées est un remplacement d'objet entier, et non une fusion JSON récursive.

méthode update_thread

Conserver les métadonnées de thread et les mises à jour de la configuration d'exécution durable.

Remarques

La configuration d'exécution est résolue à partir du thread de conversation stocké plus les remplacements explicites transmis à cet appel, correspondant à la sémantique get_thread avant de conserver le résultat. Les mises à jour de métadonnées et de configuration d'exécution omises sont résolues à partir des données stockées, et non à partir d'une instance OracleThread précédemment chargée. Seules les mises à jour de métadonnées fournies explicitement ou les remplacements de configuration d'exécution durable sont réécrits. Le remplacement de métadonnées est un remplacement d'objet entier, et non une fusion JSON récursive. La propriété des threads n'est pas mutable via cette API. Par conséquent, user_id et agent_id restent inchangés. L'état d'exécution mutable, tel que les compteurs d'extraction, n'est pas modifié.

Exemples 

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

méthode wait_for_memory_extraction

Attendez que l'extraction de mémoire en arrière-plan démarre plus tôt par ce client.

Cette méthode attend que l'extraction en arrière-plan ait déjà démarré via cette instance OracleAgentMemory, sur tous les threads appartenant à ce composant de mémoire d'agent. Il n'attend pas que l'extraction démarre après ce début d'attente, que l'extraction démarre par un autre composant de mémoire d'agent ou que l'extraction s'exécute dans un autre processus. Les échecs d'extraction sont comptabilisés comme terminés pour cette attente.

Exemples 

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (async)

Attendez asynchrone l'extraction de mémoire en arrière-plan précédente.

Cette méthode suit le même comportement que wait_for_memory_extraction().

Exemples 

await client.wait_for_memory_extraction_async(timeout=10)

Extraction de mémoire

classe oracleagentmemory.core.MemoryExtractionConfig

Bases : object

Paramètres groupés pour l'extraction automatique de la mémoire.

Transmettez cet objet à OracleAgentMemory, create_thread, get_thread ou update_thread pour configurer l'extraction automatique. Les champs omis héritent du paramètre plus large suivant. Par exemple, un thread créé sans memory_extraction_frequency utilise la valeur par défaut du composant de mémoire d'agent et la valeur par défaut du composant revient à la valeur par défaut du kit SDK.

Exemples 

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

classe oracleagentmemory.core.MemoryExtractionMode

Bases : str, Enum

Contrôle l'exécution du travail d'extraction automatique de la mémoire.

INLINE exécute l'extraction automatique avant le retour de la méthode d'écriture. BACKGROUND renvoie une fois que l'écriture brute a réussi et que le travail d'extraction dû est tenté en arrière-plan. L'extraction de fond est le meilleur effort : les souvenirs dérivés peuvent apparaître plus tard, ou ne peuvent jamais être écrits si le travail de fond ne peut pas se terminer.

ARRIÈRE-PLAN = 'ARRIÈRE-PLAN'

Retournez après la persistance des messages bruts et exécutez l'extraction au mieux dans le travail en arrière-plan.

EN LIGNE = 'INLINE'

Exécutez l'extraction avant le retour de la méthode d'écriture.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases : str, Enum

Contrôle ce qui se passe lorsque l'extraction en arrière-plan ne peut pas mettre la file d'attente dans le temps.

SUPPRIMER = 'DROP'

Enregistrez un avertissement et continuez immédiatement lorsque la capacité de la file d'attente n'est pas disponible.

ATTENDRE_THEN_DROP = 'ATTENDRE_THEN_DROP'

Attendez la capacité de la file d'attente jusqu'au délai d'attente configuré, puis consignez un avertissement et continuez.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Attendez la capacité de la file d'attente jusqu'au délai d'attente configuré, puis soulevez TimeoutError.