Mémoire d'agent

Cette page présente l'implémentation concrète d'Oracle AI Agent Memory.

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. La suppression au niveau du client attend l'extraction en arrière-plan précédente appropriée : la suppression du thread attend ce thread, la suppression de la mémoire attend le thread de la cible stockée lorsqu'elle est présente, et la suppression de l'utilisateur ou de l'agent attend les threads connus, que le nettoyage en cascade soit activé ou non. Ces attentes ne couvrent que le travail accepté par le même client avant le début de l'attente.

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

Pour accéder à un schéma créé par un autre utilisateur de base de données, configurez memory_rw_pool pour l'utilisateur de base de données d'application et définissez memory_schema_owner sur le nom de base de données non borné de l'utilisateur propriétaire.

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),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

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,
    memory_store_id=memory_store_id,
)

méthode add_agent

Ajoutez un enregistrement de profil d'agent au magasin.

Notes

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'

method add_agent_async (async)

Ajoutez un enregistrement de profil d'agent au magasin de manière asynchrone.

Notes

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,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

méthode add_image

Ajoutez un enregistrement d'image au client.

Exemples

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

method add_image_async (async)

Conserver une image autonome via le magasin configuré.

Lorsque description est omis ou None, le LLM configuré génère une légende.

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 une mémoire dans le système de mémoire de manière asynchrone.

Exemples

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

méthode add_user

Ajoutez un enregistrement de profil utilisateur au magasin.

Notes

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'

method add_user_async (async)

Ajouter un enregistrement de profil utilisateur au magasin de manière asynchrone.

Notes

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,
)
import asyncio
asyncio.run(client.add_user_async(
    "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 en arrière-plan, y compris l'extraction de mémoire et la génération de description d'image, et attend que le travail en attente se termine jusqu'au délai d'attente configuré. Si ce délai expire, close() renvoie même si certains travaux 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 être renvoyé alors que le travail en arrière-plan est toujours en cours d'exécution.

Exemples

import asyncio
asyncio.run(client.close_async())

méthode create_thread

Créez et inscrivez 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'

method create_thread_async (async)

Créez et enregistrez un thread de manière asynchrone.

Exemples

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

méthode delete_agent

Supprimer un enregistrement de profil d'agent par identifiant.

Notes

Avant de supprimer le profil, cette méthode attend jusqu'à 300 secondes pour une extraction en arrière-plan antérieure déjà acceptée pour les threads propriétaires connus via ce composant de mémoire d'agent. Cette attente s'applique que le nettoyage en cascade soit activé ou non. Le nettoyage en cascade est planifié et exécuté dans le magasin de sauvegarde en une seule opération. La méthode n'attend pas que le travail soit accepté après le début de l'attente ou que le travail soit 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

method delete_agent_async (async)

Supprimer un enregistrement de profil d'agent par identifiant de manière asynchrone.

Notes

Cette méthode suit le comportement d'attente et de simultanéité d'extraction en arrière-plan documenté par delete_agent().

Exemples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

méthode delete_image

Supprimer un enregistrement d'image par identifiant.

method delete_image_async (async)

Supprimez une image autonome via le magasin configuré.

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.

Notes

Avant de supprimer un enregistrement de portée thread, cette méthode résout son thread stocké et attend une extraction en arrière-plan antérieure acceptée via ce composant de mémoire d'agent. Il n'attend pas les threads non liés, le travail accepté après le début de l'attente ou le travail démarré par un autre composant ou processus de mémoire d'agent. Les enregistrements sans portée de thread et sans identificateurs inconnus ne provoquent pas d'attente d'extraction.

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 un enregistrement de type mémoire de manière asynchrone.

Notes

Cette méthode suit le comportement ciblé d'attente et de simultanéité d'extraction en arrière-plan documenté par delete_memory().

Exemples

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

Supprimez une relation par identificateur ou complétez le tuple d'adresse.

Lorsqu'aucun élément relation_id n'est fourni, indiquez tous les arguments source, cible, type et relation-label dans l'orientation source-cible stockée.

Exemples

client.delete_record_link(relation_id="relation-id")
1

Supprimez de manière asynchrone une relation par ID ou complétez le tuple d'adresse.

méthode delete_thread

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

Notes

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

method delete_thread_async (async)

Supprimer tous les enregistrements associés à un identificateur de thread de manière asynchrone.

Notes

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,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

méthode delete_user

Supprimer un enregistrement de profil utilisateur par identifiant.

Notes

Avant de supprimer le profil, cette méthode attend jusqu'à 300 secondes pour une extraction en arrière-plan antérieure déjà acceptée pour les threads propriétaires connus via ce composant de mémoire d'agent. Cette attente s'applique que le nettoyage en cascade soit activé ou non. Le nettoyage en cascade est planifié et exécuté dans le magasin de sauvegarde en une seule opération. La méthode n'attend pas que le travail soit accepté après le début de l'attente ou que le travail soit 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

method delete_user_async (async)

Supprimer un enregistrement de profil utilisateur par identifiant de manière asynchrone.

Notes

Cette méthode suit le comportement d'attente et de simultanéité d'extraction en arrière-plan documenté par delete_user().

Exemples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("u-delete"))
1

méthode get_thread

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

Notes

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="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

method get_thread_async (async)

Récupérez un thread précédemment créé de manière asynchrone.

Notes

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,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

Créez une relation dirigée entre deux enregistrements stockés.

Actuellement, les deux adresses doivent être des enregistrements de type mémoire : "memory", "fact", "guideline" ou "preference". Les types de relation intégrés sont "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") et "duplicates". "contradicts" et "duplicates" utilisent le même libellé à l'envers.

Une seule orientation peut être stockée pour une paire d'adresses. opposite_relation_type nomme la relation lors de l'acheminement de la cible vers la source. Par exemple, si new "supersedes" old, le parcours inverse est old "is_superseded_by" new.

Exemples

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Créez de manière asynchrone une relation typée entre les enregistrements stockés.

Actuellement, les deux adresses doivent être des enregistrements de type mémoire : "memory", "fact", "guideline" ou "preference". Les types de relation intégrés sont "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") et "duplicates". "contradicts" et "duplicates" utilisent le même libellé à l'envers.

méthode list_agents

Répertorier les enregistrements de profil d'agent persistants.

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'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

method list_agents_async (async)

Répertorier les enregistrements de profil d'agent persistants de manière asynchrone.

Exemples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

méthode list_images

Répertorier les enregistrements d'image autonome persistants.

Exemples

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

method list_images_async (async)

Répertorier les enregistrements d'image autonome persistants de manière asynchrone.

Exemples

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

méthode list_memories

Répertorier les enregistrements de type mémoire persistants.

Exemples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

method list_memories_async (async)

Répertoriez de manière asynchrone les enregistrements de type mémoire persistants.

Exemples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

méthode list_messages

Répertorier les enregistrements de message de discussion persistants.

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")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

method list_messages_async (async)

Répertorier les enregistrements de messages de discussion persistants de manière asynchrone.

Exemples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

méthode list_threads

Répertorier les threads de conversation persistants.

Exemples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

method list_threads_async (async)

Répertoriez les threads de conversation persistants de manière asynchrone.

Exemples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

méthode list_users

Répertorier les enregistrements de profil utilisateur persistants.

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'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

method list_users_async (async)

Répertorier les enregistrements de profil utilisateur persistants de manière asynchrone.

Exemples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

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

Notes

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.

Notes

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_image

Mettre à jour un enregistrement d'image stocké par identifiant.

Notes

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.

method update_image_async (async)

Mettez à jour une image autonome via le magasin configuré.

Omettez image pour conserver les octets existants. Si image est fourni, mime_type doit l'être. Omettez description pour conserver la description existante. Transmettez None pour générer une nouvelle description avec le LLM configuré ; une description non NULL la remplace directement. Les paramètres de métadonnées, d'horodatage et d'expiration sont mis à jour lorsqu'ils sont fournis.

méthode update_memory

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

Notes

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 un enregistrement stocké de type mémoire par identifiant de manière asynchrone.

Notes

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.

Exemples

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

Mettez à jour les champs mutables d'une relation stockée.

Les valeurs omises sont conservées. Lorsque relation_type passe à un type de relation de mémoire intégré, son libellé inverse fixe remplace opposite_relation_type. Transmettez None pour timestamp ou metadata pour effacer cette valeur.

Exemples

client.update_record_link("relation-id", relation_type="supports")
1

Mettez à jour une relation stockée de manière asynchrone.

méthode update_thread

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

Notes

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

method update_thread_async (async)

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

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

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

Limites d'entrée d'image

classe oracleagentmemory.core.ImageInputLimitConfig

Bases : object

Configurer les limites de demande d'image brute et de LLM.

Les champs omis héritent de la portée de configuration plus large suivante. Les champs client héritent des valeurs par défaut du kit SDK, tandis que les champs par thread héritent de la configuration client. La validation ne peut pas être désactivée et les valeurs résolues ne peuvent pas dépasser les maxima absolus du kit SDK.

Exemples

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

Extraction de mémoire

classe oracleagentmemory.core.MemoryExtractionImageContext

Bases : str, Enum

Sélectionnez la façon dont les images participent à l'extraction automatique de mémoire.

DISABLED omet les images et les descriptions d'image des invites d'extraction. IMAGE envoie les parties originales de l'image. CAPTION envoie des descriptions d'image sous forme de texte et exige que chaque image sélectionnée ait une description non vide.

CAPTION = 'CAPTION'

Inclure les descriptions sous forme de texte et en exiger une pour chaque image sélectionnée.

DÉSACTIVÉ = 'DISABLED'

N'incluez pas d'images ou de descriptions d'images dans les invites d'extraction.

IMAGE = 'IMAGE'

Inclure les parties d'image d'origine dans les invites d'extraction.

MEMORY = 'MEMORY'

L'extraction de mémoire propre à l'image n'est pas prise en charge actuellement.

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. extraction_mode et les paramètres de file d'attente en arrière-plan contrôlent également la génération automatique de description d'image. Chaque champ est résolu indépendamment. Une valeur fournie pour une opération est prioritaire, suivie d'une valeur de thread enregistrée, de la valeur client et de la valeur par défaut du kit SDK. Les threads nouveaux et autonomes n'ont pas de valeur de thread enregistrée.

Exemples

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

Que faire lorsque l'extraction ou les descriptions d'image ne peuvent pas mettre immédiatement en file d'attente.

Les valeurs omises sont résolues en DROP.

Nombre maximal de secondes pendant lesquelles le travail en arrière-plan attend la capacité de la file d'attente en modes d'attente.

Les valeurs omises sont résolues en 300.0 secondes.

Messages après le dernier récapitulatif valide avant actualisation automatique.

Les valeurs inférieures ou égales à 0 sont actualisées à chaque vérification.

Indique si OAM gère les récapitulatifs de contexte pour les lectures de thread et les invites d'extraction.

Si l'extraction et les descriptions d'image s'exécutent en ligne ou en arrière-plan.

Les valeurs omises sont résolues en BACKGROUND.

Messages entre les exécutions d'extraction. Les valeurs inférieures à 0 sont extraites après chaque ajout.

Représentation d'image ; l'omission se résout en thread, client, puis DISABLED.

Métadonnées de message source copiées dans les mémoires extraites.

Budget de jeton d'entrée pour les invites ; les valeurs inférieures à 1 désactivent la limite.

Fenêtre de message récent utilisée pour les invites d'extraction ; -1 n'utilise que les nouveaux messages.

Instructions facultatives de l'appelant ajoutées aux invites de résolution automatique des liens.

Comment les liens automatiques sont résolus pour les mémoires extraites.

Les valeurs omises sont résolues en POST_EXTRACTION.

Budget total du jeton d'entrée pour la résolution de lien POST_EXTRACTION.

Les valeurs inférieures à 1 désactivent la limite.

classe oracleagentmemory.core.MemoryExtractionMode

Bases : str, Enum

Contrôle l'exécution de l'extraction automatique et des descriptions d'image.

INLINE termine le travail dérivé avant le retour de la méthode d'écriture. BACKGROUND renvoie une fois que l'écriture brute a réussi et tente de mettre ce travail en file d'attente. Le travail en arrière-plan est le meilleur effort : les descriptions générées et les mémoires dérivées peuvent apparaître plus tard ou ne jamais être écrites si elles ne peuvent pas se terminer.

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

Retour après l'écriture brute et exécution du travail dérivé en arrière-plan.

EN LIGNE = 'INLINE'

Complétez l'extraction et les descriptions d'image avant le retour de l'écriture.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases : str, Enum

Contrôle ce qui se passe lorsque le travail en arrière-plan configuré ne peut pas être mis en file d'attente dans le temps.

Malgré le nom spécifique à l'extraction, ce paramètre s'applique également à la génération automatique de description d'image en mode arrière-plan.

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.