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 vectoriales o fragmentarios gestionados. Es más amplio que OracleThread.delete_message(), que suprime solo la fila de mensaje sin formato.

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.

Parámetros:
- store OracleMemoryStore – Instancia de almacén preconfigurada opcional. Cuando se proporciona, el cliente utiliza este almacén directamente en lugar de instanciar su propio almacén. Esto resulta útil cuando los emisores de llamadas necesitan una configuración de almacén más allá de las opciones del constructor expuestas por OracleAgentMemory.
- connection object: conexión/agrupación Oracle DB opcional. Cuando se proporciona, se utiliza el almacén de base de datos. La transferencia de una conexión raw activa el modo de sesión única para esta instancia de cliente, por lo que las solicitudes simultáneas deben utilizar un pool de conexiones en su lugar. Cuando se omite, los emisores de llamadas deben transferir un store explícito.
- embedder IEmbedder | str: instancia de implementación de embebido o un identificador de modelo de embebido de LiteLLM. Cuando se omite, no se asocia ningún embebedor y los emisores de llamadas deben proporcionar vectores calculados previamente a través de API de almacenamiento de nivel inferior.
- LLM ILlm: adaptador LLM opcional que utilizan los threads para la extracción de memoria o el resumen de contexto. Por defecto, los threads creados o cargados desde este cliente requieren un LLM para que los mensajes recientes se puedan extraer para memorias duraderas. Pase llm aquí, proporcione uno más tarde en create_thread o excluya extract_memories=False.
- extract_memories bool: cuando True, los threads creados o cargados por este cliente requieren un LLM y la extracción automática de memoria permanece activada. Establézcalo en False para desactivar la extracción automática de memoria y permitir que esos threads funcionen sin un LLM. El valor predeterminado es True, por lo que los LLM de extracción que faltan fallan rápidamente.
- schema_policy: SchemaPolicy | str política de configuración del esquema de base de datos que se utiliza solo al crear un almacén de base de datos a partir de connection. El valor por defecto es SchemaPolicy.REQUIRE_EXISTING.
- table_name_prefix str: prefijo de índice/tabla de base de datos opcional que solo se utiliza al crear un almacén de base de datos a partir de connection.
Incidencias: ValueError: si se proporciona una configuración de almacén en conflicto, como transferir store y connection, opciones específicas de base de datos sin una conexión de base de datos u omitir store y connection.

Ejemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

método `add_agent`

Agregue un registro de perfil de agente a la tienda.

Parámetros:
- agent_id str: identificador de agente.
- information str: información de formato libre sobre el agente.
Devoluciones: identificador del perfil de agente almacenado.
Tipo de retorno: str

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")
'a1'

método `add_memory`

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

Parámetros:
- content str: contenido de memoria que se debe mantener.
- user_id str: identificadores de ámbito opcionales asociados con la memoria almacenada.
- agent_id str: identificadores de ámbito opcionales asociados con la memoria almacenada.
- thread_id str: identificadores de ámbito opcionales asociados con la memoria almacenada.
- memory_id str: identificador estable proporcionado por el emisor de llamada opcional para esta fila de memoria.
- **store_kwargs (Cualquiera): opciones de escritura específicas del almacén reenviadas al almacén de copia de seguridad.
Devoluciones: identificador del registro de memoria insertado.
Tipo de devolución: str

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'

método `add_user`

Agregue un registro de perfil de usuario a la tienda.

Parámetros:
- user_id str: identificador de usuario.
- information str: información de formato libre sobre el usuario.
Devoluciones: identificador del perfil de usuario almacenado.
Tipo de devolución: str

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.")
'u1'

método `create_thread`

Cree y registre un thread.

Parámetros:
- thread_id str: identificador de thread. Si se omite, se genera uno nuevo.
- user_id str: identificador de usuario adjunto a este registro de thread. Si se omite, se genera uno nuevo.
- agent_id str: identificador de agente asociado a este registro de thread. Si se omite, se genera uno nuevo.
- metadata dict[str, Any] | None: los metadatos opcionales similares a JSON se mantienen en la fila del thread.
- LLM ILlm: sustitución de LLM opcional para este thread. Si se omite, se utiliza el LLM de nivel de cliente configurado en el momento de la construcción. Por defecto, el cliente o el thread deben proporcionar un LLM para que se pueda ejecutar la extracción automática de memoria. Defina extract_memories=False aquí o en el cliente para excluirse de ese requisito.
- extract_memories bool: sustitución opcional por thread para la extracción automática de memoria. Cuando True, este thread necesita un LLM para que se pueda ejecutar la extracción automática. Defina esta opción en False para desactivar la extracción automática para este thread y permitir la operación sin un LLM. Cuando se omite, se utiliza el valor extract_memories de nivel de cliente.
- max_message_token_length int: tamaño máximo de mensaje de tiempo de petición de datos antes del truncamiento o el resumen durante la extracción de memoria y las actualizaciones de resumen de contexto. El contenido del mensaje almacenado permanece sin cambios. Cuando se omite, el valor por defecto es 15_000 tokens.
- message_shortening_input_token_limit int: tamaño máximo, en tokens, del extracto de mensaje enviado al LLM al acortar las copias de mensajes de tiempo de petición de datos de gran tamaño. Cuando se omite, el valor por defecto es 30_000 tokens.
- memory_extraction_window int: número de mensajes recientes que se deben incluir durante la extracción de memoria. Defina esta opción en -1 para realizar una extracción por llamada add_messages mediante el lote completo de mensajes recién agregados. Cuando se omite, el valor por defecto es -1.
- context_summary_update_frequency: int frecuencia de actualizaciones de resumen de contexto. Defina esta opción en -1 para realizar una actualización de resumen por llamada add_messages mediante el lote completo de mensajes recién agregados. Cuando se omite, el valor por defecto es -1.
- memory_extraction_frequency: int frecuencia de actualizaciones de extracción de memoria. Defina esta opción en -1 para realizar una extracción por llamada add_messages mediante el lote completo de mensajes recién agregados. Cuando se omite, el valor por defecto es -1.
- memory_extraction_token_limit int: tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para la extracción de memoria y la ejecución de actualizaciones de resumen. Cuando se omite, el valor por defecto es 100_000.
- context_card_token_limit int: tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para el resumen de tarjetas de contexto. Cuando se omite, el valor por defecto es 100_000.
- enable_context_summary bool: indica si se debe mantener un resumen de contexto en ejecución para este thread.
- **kwargs (cualquiera): opciones de subprocesos adicionales específicas de la implementación.
Devoluciones: OracleThread.
Tipo de retorno: OracleThread
Incidencias: ValueError: si no hay ningún LLM disponible para la extracción automática de memoria y el thread y el cliente no se han configurado con extract_memories=False.

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.

Parámetros:
- agent_id str: identificador de agente cuyo perfil se debe eliminar.
- cascade bool: cuando True (valor por defecto), también se suprimen registros con ámbito para este agente. Esto incluye la eliminación de los propios hilos, los mensajes y los registros similares a la memoria eliminados con esos hilos, y cualquier resto de registros directamente de ámbito de agente, como mensajes, recuerdos, directrices, hechos o preferencias. Esta limpieza en el ámbito se sigue ejecutando cuando la fila de perfil de agente coincidente ya está ausente. Establézcalo en False para eliminar solo el registro de perfil.
Devoluciones: número de filas de perfil de agente suprimidas (0 o 1). Esto puede seguir siendo 0 cuando se eliminaron filas de ámbito durante la limpieza en cascada.
Tipo de devolución: int

Notas

Las supresiones en cascada se planifican y ejecutan dentro del almacén de copia de seguridad para que la supresión de perfil y todas las supresiones secundarias de ámbito se realicen en una sola operación de almacén.

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.

Parámetros: memory_id str: identificador de memoria. El identificador puede hacer referencia a un registro memory, guideline, fact o preference almacenado.
Devoluciones: número de filas similares a la memoria suprimidas (0 o 1).
Tipo de devolución: int

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

método `delete_thread`

Suprimir todos los registros asociados a un identificador de thread.

Parámetros: thread_id str: identificador de thread para suprimir.
Devoluciones: número de filas de thread suprimidas (0 o 1).
Tipo de devolución: int

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 las filas de vector o fragmento gestionadas. 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.

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.

Parámetros:
- user_id str: identificador de usuario cuyo perfil se debe eliminar.
- cascade bool: cuando True (predeterminado), también se suprimen registros con ámbito para este usuario. Esto incluye la eliminación de los propios hilos, los mensajes y los registros similares a la memoria eliminados con esos hilos, y cualquier registro de ámbito de usuario que quede directamente, como mensajes, recuerdos, directrices, hechos o preferencias. Esta limpieza de ámbito se sigue ejecutando cuando la fila de perfil de usuario coincidente ya está ausente. Establézcalo en False para eliminar solo el registro de perfil.
Devoluciones: número de filas de perfil de usuario suprimidas (0 o 1). Esto puede seguir siendo 0 cuando se eliminaron filas de ámbito durante la limpieza en cascada.
Tipo de devolución: int

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.

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.

Parámetros:
- thread_id str: identificador que se utiliza al crear el thread.
- LLM ILlm: sustitución de LLM opcional para el subproceso reabierto. Cuando se omite, se utiliza el LLM de nivel de cliente configurado en el momento de la construcción.
- extract_memories bool: sustitución opcional para la extracción automática de memoria en el thread reabierto. Cuando se omite, se utiliza el valor extract_memories de nivel de cliente.
- max_message_token_length int: sustitución opcional para el tamaño máximo de mensaje de tiempo de petición de datos antes del truncamiento o el resumen durante la extracción de memoria y las actualizaciones de resumen de contexto. El contenido del mensaje almacenado permanece sin cambios.
- message_shortening_input_token_limit int: sustitución opcional para el tamaño máximo, en tokens, del extracto de mensaje enviado al LLM al acortar las copias de mensajes de tiempo de petición de datos de gran tamaño.
- memory_extraction_window int: sustitución opcional para el número de mensajes recientes utilizados durante la extracción de memoria.
- context_summary_update_frequency: int sustitución opcional para la frecuencia de refrescamientos de resumen de contexto.
- memory_extraction_frequency int: sustitución opcional para la frecuencia de las actualizaciones de extracción de memoria.
- memory_extraction_token_limit int: sustitución opcional para el tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para la extracción de memoria y la ejecución de actualizaciones de resumen.
- context_card_token_limit int: sustitución opcional para el tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para el resumen de tarjetas de contexto.
- enable_context_summary bool: sustitución opcional para determinar si el subproceso reabierto debe mantener un resumen de contexto en ejecución.
Devoluciones: manejador de threads reconstruido a partir de metadatos del almacén.
Tipo de retorno: OracleThread
Incrementos:
- KeyError: si el ID de subproceso es desconocido para esta instancia de cliente.
- ValueError: si no hay ningún LLM disponible para la extracción automática de memoria y el cliente no se configuró con extract_memories=False.

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'

Memoria del agente