Memoria del agente

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

Memoria del Agente de Oracle

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.

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 (no están vinculados a un thread específico).

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.
  • 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. Se vuelve a utilizar la misma cadencia para los metadatos de resumen de thread refrescados durante add_messages. Cuando se omite, el valor por defecto es 4.
  • 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 de petición de datos de extracción en tokens. 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_memory

Suprimir un registro de memoria por identificador.

• Parámetros: memory_id str: identificador de memoria.
• Devoluciones: número de filas de 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.
  • allow_non_existing bool: cuando True, la supresión de un thread faltante se trata como un proceso no operativo.
• Devoluciones: número de filas de thread suprimidas (0 o 1).
• Tipo de devolución: int

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 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 de petición de datos de extracción en tokens.
  • 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'