Introducción a la memoria del agente

Este artículo le guiará a través de la instalación de la memoria del agente y la realización de operaciones básicas de memoria, incluido el almacenamiento y la recuperación del contexto del usuario.

Requisitos previos

Asegúrese de que tiene:

Requisitos de funciones de Oracle AI Database

El almacén respaldado por base de datos de la memoria del agente de Oracle necesita Oracle AI Database 23ai o posterior (versión de base de datos 23.4 o posterior). Para Oracle AI Vector Search, defina el parámetro de inicialización COMPATIBLE de la base de datos en 23.4.0 o posterior.

La estrategia de búsqueda seleccionada tiene estos requisitos adicionales:

Durante la inicialización del esquema gestionado, la memoria del agente de Oracle valida la versión de la base de datos conectada antes de ejecutar DDL e informa de una acción de cambio de versión cuando la estrategia de búsqueda seleccionada no está disponible.

Configuración de base de datos gestionada

Cuando un propietario de esquema crea o vuelve a crear un almacén de memoria, el paquete Python de memoria de agente de Oracle prepara los objetos de base de datos gestionados que necesita. El propietario necesita los privilegios del sistema CREATE TABLE y CREATE PROCEDURE de Oracle.

Conéctese como propietario del esquema para la configuración del esquema. Una conexión de aplicación que utilice schema_owner accede a un almacén existente y debe utilizar SchemaPolicy.REQUIRE_EXISTING; no crea ni actualiza los objetos de base de datos gestionados del propietario.

Instalación del SDK

Puede encontrar todas las versiones y plataformas soportadas de oracleagentmemory en la página Descarga de Software.

Para instalar la memoria del agente, ejecute:

pip install "oracleagentmemory==26.8.0"

La instalación con pip extrae ruedas binarias predefinidas en plataformas soportadas.

Registro y diagnóstico

Oracle AI Agent Memory emite mensajes de diagnóstico mediante el registro de Python estándar en nombres de registrador que comienzan con oracleagentmemory. El SDK no configura manejadores ni niveles de log; las aplicaciones pueden enrutar estos logs a su pipeline de observabilidad, archivo o consola existente. Algunos registros de log utilizan los campos extra del registro de Python para realizar diagnósticos estructurados seguros, que pueden capturar los manejadores de registro estructurados.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

Para la resolución de problemas en entornos controlados, active los logs DEBUG:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Mantener los despliegues de producción en un nivel que no sea DEBUG. Los logs DEBUG están diseñados para el desarrollo y el diagnóstico de soporte, y el texto del mensaje de log no se debe tratar como una API pública estable.

Depuración de registro de tiempo de vida y caducado

Los mensajes y las memorias respaldados por Oracle DB pueden caducar automáticamente mediante una combinación de valores por defecto de retención a nivel de esquema y valores ttl_days/ttl_anchor por registro en las API de escritura y actualización.

Cuando la memoria del agente de Oracle crea o actualiza su esquema gestionado, también crea un trabajo de depuración diario DBMS_SCHEDULER que elimina físicamente las filas caducadas, sus fragmentos de recuperación y los fragmentos de recuperación huérfanos cuya fila de origen soportada ya no existe. Si la configuración del esquema necesita crear ese trabajo pero el usuario de la base de datos carece de CREATE JOB, la configuración se completa con una advertencia: las filas caducadas permanecen filtradas fuera de las lecturas y la búsqueda, pero los fragmentos caducados y huérfanos no se depuran físicamente hasta que un usuario con privilegios crea el trabajo. En SchemaPolicy.REQUIRE_EXISTING, se tolera un trabajo de depuración que falta y se registra en el nivel DEBUG.

Los esquemas de memoria enlazada también crean un disparador que vuelve a validar las memorias supervivientes después de suprimir un enlace, incluso cuando el trabajo de depuración suprime una memoria caducada y Oracle aplica en cascada sus enlaces. El propietario del esquema necesita CREATE TRIGGER durante la creación o actualización del esquema; los usuarios de tiempo de ejecución normales no necesitan ese privilegio.

Para conocer el modelo de retención completo, la configuración de MemoryRetentionConfig, las consultas de verificación de trabajos de depuración, la creación manual de trabajos de DBA y los ejemplos de Python que utilizan TimeToLiveAnchor, consulte Uso del tiempo de actividad para mensajes y recuerdos.

Permisos de esquema de memoria enlazada

El esquema de memoria enlazada incluye un gráfico de propiedades de Oracle SQL y un disparador de base de datos que mantiene el estado del ciclo de vida correcto cuando se suprimen los enlaces.

Si define memory_store_id, el nombre del gráfico gestionado tiene el mismo prefijo que las tablas. Por ejemplo, memory_store_id="SALES" crea SALES_MEMORY_GRAPH.

Los valores APP_SCHEMA y APP_USER son marcadores de posición. Reemplácelos por los nombres de usuario de la base de datos. Los ejemplos utilizan mayúsculas porque los identificadores de Oracle sin comillas se almacenan en mayúsculas.

  1. Durante la configuración del esquema, otorgue al propietario del esquema CREATE PROPERTY GRAPH y CREATE TRIGGER. Son necesarios con SchemaPolicy.CREATE_IF_NECESSARY o SchemaPolicy.RECREATE siempre que se deba crear el disparador gestionado de supresión de enlaces o gráficos. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    Otorguelos de nuevo antes de una actualización de SDK posterior si esa actualización necesita crear o volver a crear el gráfico gestionado o el disparador de supresión de enlaces.

  2. Durante el tiempo de ejecución normal de la aplicación, decida qué usuario se conecta a Oracle:
    • Si el usuario de tiempo de ejecución es APP_SCHEMA, no se necesita ningún permiso de gráfico adicional. El propietario del gráfico puede acceder a su propio gráfico.
    • Si el usuario de tiempo de ejecución es diferente, ejecute lo siguiente como APP_SCHEMA después de configurar el esquema. El nombre de gráfico por defecto es MEMORY_GRAPH; utilice el nombre con prefijo cuando se defina memory_store_id. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      El usuario de tiempo de ejecución también necesita el acceso normal a la base de datos que necesita el resto del despliegue de memoria del agente de Oracle.

SchemaPolicy.REQUIRE_EXISTING omite el primer paso porque espera que el gráfico y el disparador ya existan. Un usuario de tiempo de ejecución independiente aún necesita acceso al gráfico de propiedades gestionadas.

Inicialización de la Instancia de Memoria

Cree una instancia de OracleAgentMemory configurando la conexión al embebido, el LLM y la base de datos.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

Nota: Por defecto, los esquemas gestionados de Oracle AI Database no definen un período de retención para los mensajes y las memorias. Configure los valores de tiempo de vida por registro o MemoryRetentionConfig para utilizar un período de retención diferente. Para obtener más información, consulte Uso del tiempo de actividad para mensajes y recuerdos.

Almacenar entradas de memoria

Comience por crear un thread, agregar mensajes y almacenar una entrada de memoria para el usuario.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Recuperar entradas de memoria

Buscar memorias mediante una consulta de ámbito de usuario.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Salida:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Nota: La salida mostrada es ilustrativa. Las versiones futuras pueden devolver tipos de resultados, campos o indicaciones adicionales.

Compatibilidad de modelo

Los siguientes modelos de lenguaje grande (LLM) y modelos de inserción son compatibles con oracleagentmemory.

LLM

Se ha confirmado que los siguientes modelos de lenguaje grandes (LLM) son compatibles.

Modelos alojados en OCI

OpenAI

LLM autoalojados

Antropología

Géminis

Incrustaciones

Se ha confirmado que los siguientes modelos de incrustación son compatibles.

Modelos alojados en OCI

OpenAI

LLM autoalojados

Géminis