Introduzione alla memoria agente

Questo articolo guida l'utente nell'installazione della memoria agente e nell'esecuzione delle operazioni di memoria di base, inclusa la memorizzazione e il recupero del contesto utente.

Prerequisiti

Verificare di disporre dei dati elencati di seguito.

Requisiti delle funzionalità di Oracle AI Database

L'area di memorizzazione supportata dal database di Oracle Agent Memory richiede Oracle AI Database 23ai o versione successiva (database 23.4 o versione successiva). Per Oracle AI Vector Search, impostare il parametro di inizializzazione COMPATIBLE del database su 23.4.0 o versione successiva.

La strategia di ricerca selezionata prevede i seguenti requisiti aggiuntivi:

Durante l'inizializzazione dello schema gestito, la memoria dell'agente Oracle convalida la versione del database connesso prima di eseguire DDL e segnala un'azione di upgrade quando la strategia di ricerca selezionata non è disponibile.

Impostazione database gestito

Quando un proprietario dello schema crea o ricrea un'area di memorizzazione della memoria, il pacchetto Python Oracle Agent Memory prepara gli oggetti di database gestiti di cui ha bisogno. Il proprietario deve disporre dei privilegi di sistema CREATE TABLE e CREATE PROCEDURE Oracle.

Connettersi come proprietario dello schema per l'impostazione dello schema. Una connessione all'applicazione che utilizza schema_owner accede a un'area di memorizzazione esistente e deve utilizzare SchemaPolicy.REQUIRE_EXISTING; non crea né aggiorna gli oggetti di database gestiti del proprietario.

Installare l'SDK

È possibile trovare tutte le versioni e le piattaforme supportate di oracleagentmemory nella pagina di download del software.

Per installare la memoria dell'agente, eseguire:

pip install "oracleagentmemory==26.8.0"

L'installazione con pip estrae ruote binarie predefinite su piattaforme supportate.

Log e diagnostica

Oracle AI Agent Memory emette messaggi di diagnostica tramite il log Python standard sotto i nomi dei logger che iniziano con oracleagentmemory. L'SDK non configura gli handler o i livelli di log; le applicazioni possono instradare questi log alla console, al file o alla pipeline di osservabilità esistente. Alcuni record di log utilizzano i campi extra del log Python per una diagnostica strutturata sicura, che può essere acquisita dagli handler di log strutturati.

import logging

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

Per la risoluzione dei problemi in ambienti controllati, abilitare i log DEBUG:

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

Mantieni le distribuzioni di produzione a un livello non DEBUG. I log DEBUG sono destinati alla diagnostica di sviluppo e supporto e il testo dei messaggi di log non deve essere considerato come un'API pubblica stabile.

Rimozione Time-to-Live e record scaduti

I messaggi e le memorie supportati da Oracle DB possono scadere automaticamente tramite una combinazione di valori predefiniti di conservazione a livello di schema e valori ttl_days/ttl_anchor per record nelle API di scrittura e aggiornamento.

Quando Oracle Agent Memory crea o aggiorna lo schema gestito, crea anche un job giornaliero di rimozione DBMS_SCHEDULER che rimuove fisicamente le righe scadute, i relativi chunk di recupero e i chunk di recupero orfani la cui riga di origine supportata non esiste più. Se l'impostazione dello schema deve creare tale job ma l'utente del database non dispone di CREATE JOB, l'impostazione viene completata con un'avvertenza: le righe scadute rimangono filtrate dalle letture e dalla ricerca, ma i chunk scaduti e isolati non vengono rimossi fisicamente finché un utente con privilegi non crea il job. In SchemaPolicy.REQUIRE_EXISTING, un job di rimozione mancante è tollerato e registrato a livello DEBUG.

Gli schemi di memoria collegata creano anche un trigger che riconvalida le memorie sopravvissute dopo l'eliminazione di un collegamento, incluso quando il job di rimozione elimina una memoria scaduta e Oracle applica in cascata i relativi collegamenti. Il proprietario dello schema ha bisogno di CREATE TRIGGER durante la creazione o l'aggiornamento dello schema; gli utenti runtime normali non hanno bisogno di tale privilegio.

Per il modello di conservazione completo, l'impostazione MemoryRetentionConfig, le query di verifica dei job di rimozione, la creazione manuale dei job DBA e gli esempi Python che utilizzano TimeToLiveAnchor, vedere Usa Time-to-Live per messaggi e memorie.

Autorizzazioni schema memoria collegata

Lo schema linked-memory include un grafico delle proprietà Oracle SQL e un trigger del database che mantiene lo stato del ciclo di vita corretto quando i collegamenti vengono eliminati.

Se si imposta memory_store_id, il nome del grafico gestito viene preceduto allo stesso modo delle tabelle. Ad esempio, memory_store_id="SALES" crea SALES_MEMORY_GRAPH.

I valori APP_SCHEMA e APP_USER sono segnaposto. Sostituirli con i nomi utente del database. Gli esempi utilizzano le lettere maiuscole perché gli identificativi Oracle senza virgolette sono memorizzati in maiuscolo.

  1. Durante l'impostazione dello schema, concedere al proprietario dello schema CREATE PROPERTY GRAPH e CREATE TRIGGER. Questi sono necessari con SchemaPolicy.CREATE_IF_NECESSARY o SchemaPolicy.RECREATE ogni volta che è necessario creare il trigger di eliminazione del grafico o del collegamento gestito. 
    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;

    Concedere di nuovo prima di un aggiornamento SDK successivo se l'aggiornamento deve creare o ricreare il trigger grafico gestito o di eliminazione dei collegamenti.

  2. Durante il normale runtime delle applicazioni, decidere quale utente si connette a Oracle:
    • Se l'utente runtime è APP_SCHEMA, non è necessario alcun privilegio grafico aggiuntivo. Il proprietario del grafico può accedere al proprio grafico.
    • Se l'utente runtime è diverso, eseguire quanto segue come APP_SCHEMA dopo l'impostazione dello schema. Il nome del grafico predefinito è MEMORY_GRAPH; utilizzare il nome con prefisso quando è impostato memory_store_id. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      L'utente runtime richiede anche il normale accesso al database richiesto dal resto della distribuzione della memoria dell'agente Oracle.

SchemaPolicy.REQUIRE_EXISTING salta il primo passo perché prevede che il grafico e il trigger esistano già. Un utente runtime separato deve ancora accedere al grafico delle proprietà gestite.

Inizializza istanza di memoria

Creare un'istanza OracleAgentMemory configurando l'embedder, l'LLM e la connessione al database.

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: per impostazione predefinita, gli schemi gestiti di Oracle AI Database non impostano un periodo di conservazione per i messaggi e le memorie. Configurare le impostazioni Time To Live MemoryRetentionConfig o per record per utilizzare un periodo retention diverso. Per ulteriori informazioni, vedere Usa Time-to-Live per messaggi e memorie.

Memorizza voci memoria

Iniziare creando un thread, aggiungendo messaggi e memorizzando una voce di memoria per l'utente.

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

Recupera voci di memoria

Cerca le memorie utilizzando una query con ambito utente.

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

Output:

- [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: l'output mostrato è illustrativo. Le versioni future possono restituire tipi di risultati, campi o ordini aggiuntivi.

Compatibilità modello

I seguenti LLM (Large Language Models) e modelli di incorporamento sono compatibili con oracleagentmemory.

LLM

I seguenti LLM (Large Language Models) sono stati confermati come compatibili.

Modelli ospitati su OCI

OpenAI

LLM self-hosted

Antropico

Segno zodiacale

Incorporamenti

I seguenti modelli di incorporamento sono stati confermati compatibili.

Modelli ospitati su OCI

OpenAI

LLM self-hosted

Segno zodiacale