Memoria del agente

Esta página presenta la implantación concreta de Oracle AI Agent Memory.

Memoria del Agente de Oracle

Nota: OracleAgentMemory.delete_thread() es la ruta de acceso soportada para la limpieza en cascada de ámbito de thread. Elimina el thread junto con los mensajes asociados, las memorias duraderas y los datos de recuperación gestionados. Es más amplio que OracleThread.delete_message(), que suprime solo la fila de mensaje sin formato. La supresión a nivel de cliente espera la extracción en segundo plano anterior relevante: la supresión de subprocesos espera ese subproceso, la supresión de memoria espera el subproceso del destino almacenado cuando está presente y la supresión de usuarios o agentes espera los subprocesos en propiedad conocidos, independientemente de que esté activada o no la limpieza en cascada. Estas esperas cubren solo el trabajo aceptado por el mismo cliente antes de que comience la espera.

clase oracleagentmemory.core.OracleAgentMemory

Bases: IAgentMemory

Cliente de memoria de agente respaldado por Oracle DB o un almacén proporcionado por el emisor de llamada.

Cree un cliente de memoria.

Advertencia: SchemaPolicy.CREATE_IF_NECESSARY puede ser más caro que el inicio normal del cliente porque puede aplicar DDL de esquema gestionado y reescrituras de datos de mejor esfuerzo antes de que la inicialización se realice correctamente. Planifique la primera apertura de un esquema gestionado anterior como una operación de migración o mantenimiento cuando ese esquema pueda contener muchas filas.

Si la configuración del esquema debe crear el trabajo de depuración de registro caducado gestionado, pero el usuario de la base de datos carece del privilegio Scheduler-job, la inicialización advierte y continúa. Los mensajes y las memorias caducados permanecen ocultos para las lecturas y la búsqueda, pero no se depuran físicamente hasta que un usuario con CREATE JOB o un privilegio de programador equivalente crea el trabajo.

Cuando SchemaPolicy.CREATE_IF_NECESSARY crea por primera vez un índice híbrido gestionado a través de un esquema existente, Oracle explora el texto de búsqueda almacenado y crea el estado de índice híbrido gestionado a partir del modelo de base de datos configurado. El inicio del cliente espera a que termine ese DDL, de modo que planifique la primera actualización híbrida como una operación de migración o mantenimiento para esquemas grandes. SearchIndexSyncMode controla el mantenimiento continuo después de que exista el índice; no hace que la primera creación de índice sea asíncrona.

Ejemplos

Para acceder a un esquema creado por otro usuario de base de datos, configure memory_rw_pool para el usuario de base de datos de aplicación y defina memory_schema_owner en el nombre de base de datos sin comillas del usuario propietario.

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

Utilice un modelo de embebido en la base de datos para aprovechar la búsqueda de índices híbridos de 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étodo add_agent

Agregue un registro de perfil de agente a la tienda.

Notas

Los registros de perfil de agente se almacenan en el almacén de nivel de cliente y se anula el ámbito intencionalmente. El identificador de registro devuelto es el mismo identificador público que la aplicación utiliza como agent_id.

Ejemplos

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)

Agregue un registro de perfil de agente al almacén de forma asíncrona.

Notas

Los registros de perfil de agente se almacenan en el almacén de nivel de cliente y se anula el ámbito intencionalmente. El identificador de registro devuelto es el mismo identificador público que la aplicación utiliza como agent_id.

Ejemplos

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étodo add_image

Agregue un registro de imagen al cliente.

Ejemplos

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)

Conservar una imagen independiente a través del almacén configurado.

Cuando se omite description o None, el LLM configurado genera un título.

método add_memory

Agregue una memoria en el sistema de memoria, atribuida al usuario, agente y thread indicados.

Ejemplos

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)

Agregue una memoria en el sistema de memoria de forma asíncrona.

Ejemplos

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étodo add_user

Agregue un registro de perfil de usuario a la tienda.

Notas

Los registros de perfil de usuario se almacenan en el almacén de nivel de cliente y se anula el ámbito intencionalmente. El identificador de registro devuelto es el mismo identificador público que la aplicación utiliza como user_id.

Ejemplos

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)

Agregue un registro de perfil de usuario a la tienda de forma asíncrona.

Notas

Los registros de perfil de usuario se almacenan en el almacén de nivel de cliente y se anula el ámbito intencionalmente. El identificador de registro devuelto es el mismo identificador público que la aplicación utiliza como user_id.

Ejemplos

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étodo close

Cierre el componente de memoria del agente.

El cierre deja de aceptar nuevo trabajo en segundo plano, incluida la extracción de memoria y la generación de descripciones de imágenes, y espera a que el trabajo pendiente termine hasta el timeout configurado. Si ese timeout caduca, close() devuelve incluso si algún trabajo aún no se ha finalizado. El método es idempotente.

Ejemplos

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)

Cierre de forma asíncrona el componente de memoria del agente.

Este método sigue el mismo comportamiento de cierre que close(). Si el timeout caduca, puede volver mientras el trabajo en segundo plano aún se está ejecutando.

Ejemplos

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

método create_thread

Cree y registre un thread.

Ejemplos

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)

Cree y registre un subproceso de forma asíncrona.

Ejemplos

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étodo delete_agent

Suprimir un registro de perfil de agente por identificador.

Notas

Antes de suprimir el perfil, este método espera hasta 300 segundos para la extracción en segundo plano anterior ya aceptada para threads propios conocidos mediante este componente de memoria de agente. Esta espera se aplica tanto si la limpieza en cascada está activada como si no. La limpieza en cascada se planifica y ejecuta dentro de la tienda de respaldo como una sola operación. El método no espera a que se acepte el trabajo después de que comience la espera o al trabajo iniciado por otro componente o proceso de memoria de agente. El uso simultáneo de ámbito de actor mientras la supresión está en curso no está soportado.

Ejemplos

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)

Suprimir un registro de perfil de agente por identificador de forma asíncrona.

Notas

Este método sigue el comportamiento de simultaneidad y espera de extracción en segundo plano documentado por delete_agent().

Ejemplos

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étodo delete_image

Eliminar un registro de imagen por identificador.

method delete_image_async (async)

Suprima una imagen independiente a través del almacén configurado.

método delete_memory

Eliminar un registro similar a la memoria (por ejemplo, una memoria, un hecho, una preferencia o una directriz) por identificador.

Notas

Antes de suprimir un registro de ámbito de thread, este método resuelve el thread almacenado y espera a que se acepte una extracción en segundo plano anterior mediante este componente de memoria de agente. No espera a threads no relacionados, trabajo aceptado después de que comience la espera o trabajo iniciado por otro componente o proceso de memoria de agente. Los registros sin un ámbito de thread ni identificadores desconocidos no provocan una espera de extracción.

Ejemplos

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)

Eliminar un registro similar a la memoria de forma asíncrona.

Notas

Este método sigue el comportamiento de simultaneidad y espera de extracción en segundo plano documentado por delete_memory().

Ejemplos

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

Suprima una relación por identificador o tupla de punto final completa.

Cuando no se proporciona relation_id, proporcione todos los argumentos de origen, destino, tipo y etiqueta de relación en la orientación de origen a destino almacenada.

Ejemplos

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

Suprima de forma asíncrona una relación por ID o tupla de punto final completa.

método delete_thread

Suprimir todos los registros asociados a un identificador de thread.

Notas

Utilice esta operación cuando necesite la eliminación completa de retención de un thread. El almacén de copia de seguridad suprime el thread junto con los mensajes de ámbito de thread asociados, las memorias duraderas y los datos de recuperación gestionados. Esto difiere de OracleThread.delete_message(), que elimina solo el registro de mensaje sin formato y no se aplica en cascada a las memorias derivadas creadas a partir de ese mensaje. Antes de suprimir el thread, este método espera la extracción en segundo plano anterior ya aceptada para ese thread a través de este componente de memoria de agente. No espera a que se acepte el trabajo en segundo plano después de que comience esa espera o al trabajo iniciado por otro componente o proceso de memoria de agente. No se soporta el uso simultáneo del mismo thread mientras la supresión está en curso.

Ejemplos

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)

Suprimir todos los registros asociados a un identificador de thread de forma asíncrona.

Notas

Utilice esta operación cuando necesite la eliminación completa de retención de un thread. El almacén de copia de seguridad suprime el thread junto con los mensajes de ámbito de thread asociados, las memorias duraderas y los datos de recuperación gestionados. Esto difiere de OracleThread.delete_message(), que elimina solo el registro de mensaje sin formato y no se aplica en cascada a las memorias derivadas creadas a partir de ese mensaje. Antes de suprimir el thread, este método espera la extracción en segundo plano anterior ya aceptada para ese thread a través de este componente de memoria de agente. No espera a que se acepte el trabajo en segundo plano después de que comience esa espera o al trabajo iniciado por otro componente o proceso de memoria de agente. No se soporta el uso simultáneo del mismo thread mientras la supresión está en curso.

Ejemplos

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étodo delete_user

Suprimir un registro de perfil de usuario por identificador.

Notas

Antes de suprimir el perfil, este método espera hasta 300 segundos para la extracción en segundo plano anterior ya aceptada para threads propios conocidos mediante este componente de memoria de agente. Esta espera se aplica tanto si la limpieza en cascada está activada como si no. La limpieza en cascada se planifica y ejecuta dentro de la tienda de respaldo como una sola operación. El método no espera a que se acepte el trabajo después de que comience la espera o al trabajo iniciado por otro componente o proceso de memoria de agente. El uso simultáneo de ámbito de actor mientras la supresión está en curso no está soportado.

Ejemplos

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)

Suprimir un registro de perfil de usuario por identificador de forma asíncrona.

Notas

Este método sigue el comportamiento de simultaneidad y espera de extracción en segundo plano documentado por delete_user().

Ejemplos

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étodo get_thread

Recuperar un subproceso creado anteriormente.

Notas

Las sustituciones explícitas por llamada tienen prioridad. Cuando se omiten las sustituciones de tiempo de ejecución, los threads reabiertos utilizan la configuración de tiempo de ejecución persistente cuando está disponible antes de volver a los valores por defecto del SDK.

Ejemplos

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)

Recuperar un subproceso creado previamente de forma asíncrona.

Notas

Las sustituciones explícitas por llamada tienen prioridad. Cuando se omiten las sustituciones de tiempo de ejecución, los threads reabiertos utilizan la configuración de tiempo de ejecución persistente cuando está disponible antes de volver a los valores por defecto del SDK.

Ejemplos

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'

Cree una relación dirigida entre dos registros almacenados.

Actualmente, ambos puntos finales deben ser registros similares a la memoria: "memory", "fact", "guideline" o "preference". Los tipos de relación incorporados son "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") y "duplicates". "contradicts" y "duplicates" utilizan la misma etiqueta a la inversa.

Solo se puede almacenar una orientación para un par de puntos finales. opposite_relation_type nombra la relación al recorrer de destino a origen. Por ejemplo, si new "supersedes" old, el recorrido inverso es old "is_superseded_by" new.

Ejemplos

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

Cree de forma asíncrona una relación escrita entre los registros almacenados.

Actualmente, ambos puntos finales deben ser registros similares a la memoria: "memory", "fact", "guideline" o "preference". Los tipos de relación incorporados son "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") y "duplicates". "contradicts" y "duplicates" utilizan la misma etiqueta a la inversa.

método list_agents

Enumere los registros de perfil de agente persistentes.

Ejemplos

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)

Enumere los registros de perfil de agente persistentes de forma asíncrona.

Ejemplos

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étodo list_images

Mostrar registros de imágenes independientes persistentes.

Ejemplos

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

method list_images_async (async)

Mostrar registros de imágenes independientes persistentes de forma asíncrona.

Ejemplos

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

método list_memories

Enumere los registros similares a la memoria persistente.

Ejemplos

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)

Mostrar registros similares a memoria persistentes de forma asíncrona.

Ejemplos

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étodo list_messages

Muestre los registros de mensajes de chat persistentes.

Ejemplos

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)

Muestra los registros de mensajes de chat persistentes de forma asíncrona.

Ejemplos

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étodo list_threads

Enumerar los hilos de conversación persistentes.

Ejemplos

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)

Enumerar los hilos de conversación persistentes de forma asíncrona.

Ejemplos

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étodo list_users

Muestra los registros de perfil de usuario persistentes.

Ejemplos

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)

Mostrar registros de perfil de usuario persistentes de forma asíncrona.

Ejemplos

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']

Búsqueda sincrónica de registros relevantes para una consulta.

Notas

Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los registros sin ámbito en esa dimensión.

method search_async (async)

Busque de forma asíncrona registros relevantes para una consulta.

Notas

Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los registros sin ámbito en esa dimensión.

método update_image

Actualizar un registro de imagen almacenada por identificador.

Notas

Los campos omitidos permanecen sin cambios. Esta API no soporta las actualizaciones de ámbito. La sustitución de metadatos es una sustitución de objeto completo, no una fusión JSON recursiva.

method update_image_async (async)

Actualice una imagen independiente a través del almacén configurado.

Omita image para conservar los bytes existentes. Si se proporciona image, se debe proporcionar mime_type. Omita description para conservar la descripción existente. Transfiera None para generar una nueva descripción con el LLM configurado; una descripción no nula la reemplaza directamente. Los metadatos, el registro de hora y la configuración de caducidad se actualizan cuando se proporcionan.

método update_memory

Actualizar un registro similar a la memoria almacenada por identificador.

Notas

Los campos omitidos se conservan del registro almacenado. El ámbito almacenado permanece sin cambios. La sustitución de metadatos es una sustitución de objeto completo, no una fusión JSON recursiva.

method update_memory_async (async)

Actualizar un registro similar a la memoria almacenada por identificador de forma asíncrona.

Notas

Los campos omitidos se conservan del registro almacenado. El ámbito almacenado permanece sin cambios. La sustitución de metadatos es una sustitución de objeto completo, no una fusión JSON recursiva.

Ejemplos

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

Actualización de campos modificables de una relación almacenada.

Los valores omitidos se conservan. Cuando relation_type cambia a un tipo de relación de memoria incorporada, su etiqueta inversa fija sustituye a opposite_relation_type. Transfiera None para timestamp o metadata para borrar ese valor.

Ejemplos

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

Actualizar de forma asíncrona una relación almacenada.

método update_thread

Conservar metadatos de thread y actualizaciones duraderas de configuración en tiempo de ejecución.

Notas

La configuración de tiempo de ejecución se resuelve a partir del thread de conversación almacenado más las sustituciones explícitas transferidas a esta llamada, que coinciden con la semántica get_thread antes de mantener el resultado. Los metadatos omitidos y las actualizaciones de configuración de tiempo de ejecución se resuelven a partir de datos almacenados, no de ninguna instancia OracleThread cargada previamente, y solo se reescriben las actualizaciones de metadatos proporcionadas explícitamente o las sustituciones duraderas de configuración de tiempo de ejecución. La sustitución de metadatos es una sustitución de objeto completo, no una fusión JSON recursiva. La propiedad de los threads no se puede modificar mediante esta API, por lo que user_id y agent_id permanecen sin cambios. El estado de tiempo de ejecución mutable, como los contadores de extracción, se deja sin tocar.

Ejemplos

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)

Conservar los metadatos de thread actualizados y la configuración duradera en tiempo de ejecución de forma asíncrona.

método wait_for_memory_extraction

Espere a que este cliente inicie una extracción de memoria en segundo plano anterior.

Este método espera a que la extracción en segundo plano ya se haya iniciado a través de esta instancia OracleAgentMemory en todos los threads propiedad de este componente de memoria de agente. No espera a que se inicie la extracción después de que comience esta espera, a que se inicie la extracción por otro componente de memoria de agente o a que se ejecute la extracción en otro proceso. Los fallos de extracción cuentan como finalizados para esta espera.

Ejemplos

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)

Espere de forma asíncrona la extracción de memoria en segundo plano anterior.

Este método sigue el mismo comportamiento que wait_for_memory_extraction().

Ejemplos

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

Límites de entrada de imagen

clase oracleagentmemory.core.ImageInputLimitConfig

Bases: object

Configure los límites de solicitud de imagen raw y de imagen de LLM.

Los campos omitidos heredan del siguiente ámbito de configuración más amplio. Los campos de cliente heredan los valores por defecto del SDK, mientras que los campos por thread heredan la configuración del cliente. La validación no se puede desactivar y los valores resueltos no pueden superar el máximo absoluto del SDK.

Ejemplos

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

Extracción de memoria

clase oracleagentmemory.core.MemoryExtractionImageContext

Bases: str, Enum

Seleccione cómo participan las imágenes en la extracción automática de memoria.

DISABLED omite imágenes y descripciones de imágenes de las peticiones de datos de extracción. IMAGE envía partes originales de la imagen. CAPTION envía descripciones de imágenes como texto y requiere que todas las imágenes seleccionadas tengan una descripción que no esté en blanco.

CAPTION = 'CAPTION'

Incluya descripciones como texto y requiera una por cada imagen seleccionada.

DISABLED = 'DISABLED' (Desactivado)

No incluya imágenes ni descripciones de imágenes en las peticiones de datos de extracción.

IMAGEN = 'imagen'

Incluir partes de imagen originales en peticiones de datos de extracción.

MEMORY = 'memoria'

La extracción de memoria específica de la imagen no está soportada actualmente.

clase oracleagentmemory.core.MemoryExtractionConfig

Bases: object

Configuración agrupada para la extracción automática de memoria.

Transfiera este objeto a OracleAgentMemory, create_thread, get_thread o update_thread para configurar la extracción automática. extraction_mode y los valores de la cola en segundo plano también controlan la generación automática de descripciones de imágenes. Cada campo se resuelve de forma independiente. Un valor proporcionado para una operación tiene prioridad, seguido de un valor de thread guardado, el valor de cliente y el valor por defecto de SDK. Los threads nuevos e independientes no tienen ningún valor de thread guardado.

Ejemplos

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

Qué hacer cuando la extracción o las descripciones de imágenes no pueden ponerse en cola inmediatamente.

Los valores omitidos se resuelven en DROP.

Máximo de segundos de espera de trabajo en segundo plano para la capacidad de cola en los modos de espera.

Los valores omitidos se resuelven en 300.0 segundos.

Mensajes después del último resumen válido antes del refrescamiento automático.

Valores inferiores o iguales al refrescamiento de 0 en cada ticket.

Si OAM mantiene resúmenes de contexto para lecturas de thread y peticiones de datos de extracción.

Si las descripciones de extracción e imagen se ejecutan en línea o en segundo plano.

Los valores omitidos se resuelven en BACKGROUND.

Mensajes entre ejecuciones de extracción; valores por debajo de la extracción 0 después de cada adición.

Representación de imagen; la omisión se resuelve en thread, cliente y, a continuación, en DISABLED.

Metadatos de mensajes de origen copiados en memorias extraídas.

Presupuesto de token de entrada para peticiones de datos; los valores por debajo de 1 desactivan el límite.

Ventana de mensajes recientes utilizada para peticiones de datos de extracción; -1 solo utiliza mensajes nuevos.

Instrucciones de llamada opcionales anexadas a peticiones de datos automáticas de resolución de enlaces.

Cómo se resuelven los enlaces automáticos para las memorias extraídas.

Los valores omitidos se resuelven en POST_EXTRACTION.

Presupuesto total de token de entrada para la resolución de enlaces POST_EXTRACTION.

Los valores por debajo de 1 desactivan el límite.

clase oracleagentmemory.core.MemoryExtractionMode

Bases: str, Enum

Controla cuándo se ejecuta la extracción automática y las descripciones de imágenes.

INLINE finaliza el trabajo derivado antes de que se devuelva el método de escritura. BACKGROUND se devuelve después de que la escritura raw se realice correctamente e intenta poner en cola ese trabajo. El trabajo en segundo plano es el mejor esfuerzo: las descripciones generadas y los recuerdos derivados pueden aparecer más tarde o nunca se pueden escribir si no se pueden completar.

FONDO = 'ANTECEDENTES'

Vuelva después de la escritura raw y ejecute el trabajo derivado en segundo plano.

EN LÍNEA = 'EN LÍNEA'

Complete la extracción y las descripciones de las imágenes antes de que se devuelva la escritura.

clase oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases: str, Enum

Controla lo que sucede cuando el trabajo en segundo plano configurado no puede ponerse en cola a tiempo.

A pesar del nombre específico de la extracción, esta configuración también se aplica a la generación automática de descripciones de imágenes en modo de fondo.

BORRAR = 'BORRAR'

Registre una advertencia y continúe inmediatamente cuando la capacidad de la cola no esté disponible.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Espere la capacidad de la cola hasta el timeout configurado y, a continuación, registre una advertencia y continúe.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Espere la capacidad de la cola hasta el timeout configurado y, a continuación, emita TimeoutError.