Memoria del agente

Esta página presenta la implantación concreta de memoria del agente de Oracle AI.

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. Antes de suprimir el thread, espera la extracción en segundo plano aceptada anteriormente que este cliente ya conoce para ese thread. No serializa todas las operaciones simultáneas para el mismo thread mientras la supresión está en curso.

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

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

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

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'

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 un registro de memoria al cliente de forma asíncrona.

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'

método close

Cierre el componente de memoria del agente.

El cierre deja de aceptar el nuevo trabajo de extracción en segundo plano y espera a que la extracción de memoria en segundo plano pendiente termine hasta el timeout configurado. Si ese timeout caduca, close() devuelve incluso si algún trabajo de extracción en segundo plano 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 de extracción en segundo plano aún se está ejecutando.

Ejemplos

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

método delete_agent

Suprimir un registro de perfil de agente por identificador.

Notas

Las supresiones en cascada se planifican y ejecutan dentro del almacén de copia de seguridad para que la supresión del perfil y todas las supresiones secundarias de ámbito se realicen en una sola operación de almacén. Antes de que se ejecute la supresión en cascada, este método espera la extracción en segundo plano anterior ya aceptada para los threads en propiedad conocidos en ese momento a través de este componente de memoria de agente. No espera a que se acepte el trabajo después de que comience esa 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

método delete_memory

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

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 de forma asíncrona un registro similar a la memoria (por ejemplo, una memoria, un hecho, una preferencia o una directriz) por identificador.

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

método delete_user

Suprimir un registro de perfil de usuario por identificador.

Notas

Las supresiones en cascada se planifican y ejecutan dentro del almacén de copia de seguridad para que la supresión del perfil y todas las supresiones secundarias de ámbito se realicen en una sola operación de almacén. Antes de que se ejecute la supresión en cascada, este método espera la extracción en segundo plano anterior ya aceptada para los threads en propiedad conocidos en ese momento a través de este componente de memoria de agente. No espera a que se acepte el trabajo después de que comience esa 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

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="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'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_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 de forma asíncrona un registro similar a la memoria 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.

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

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

await client.wait_for_memory_extraction_async(timeout=10)

Extracción de memoria

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. Los campos omitidos se heredan de la siguiente configuración más amplia. Por ejemplo, un thread creado sin memory_extraction_frequency utiliza el valor por defecto del componente de memoria del agente y el valor por defecto del componente vuelve al valor por defecto del SDK.

Ejemplos

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

clase oracleagentmemory.core.MemoryExtractionMode

Bases: str, Enum

Controla cuándo se ejecuta el trabajo de extracción automática de memoria.

INLINE ejecuta la extracción automática antes de que se devuelva el método de escritura. BACKGROUND se devuelve después de que la escritura raw se realiza correctamente y el trabajo de extracción debido se intenta en segundo plano. La extracción de fondo es el mejor esfuerzo: los recuerdos derivados pueden aparecer más tarde o nunca se pueden escribir si el trabajo de fondo no se puede completar.

FONDO = 'ANTECEDENTES'

Vuelva después de la persistencia de mensajes raw y ejecute la extracción de mejor esfuerzo en el trabajo en segundo plano.

EN LÍNEA = 'EN LÍNEA'

Ejecute la extracción antes de que se devuelva el método de escritura.

clase oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases: str, Enum

Controla lo que sucede cuando la extracción en segundo plano no se puede poner en cola a tiempo.

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.