La ricerca nella memoria di OpenClaw

Lo strumento di ricerca nella memoria trova le note pertinenti nei file di memoria di un agente anche quando la formulazione differisce dal testo originale: suddivide la memoria in piccoli frammenti e li cerca con embedding, parole chiave o entrambi. Gli embedding di OpenAI sono il valore predefinito e sono supportati una dozzina di provider, tra cui uno locale gestito che non richiede chiavi API. Ecco come si svolge una ricerca, il ranking che la documentazione illustra, il richiamo tramite trigger che viene eseguito prima di una risposta, le regole di fallback, la memoria delle sessioni e l’elenco per la risoluzione dei problemi.

I provider e i due percorsi

• La chiave provider indica uno tra OpenAI, Gemini, Voyage, Mistral, Bedrock, DeepInfra, GitHub Copilot, Ollama, LM Studio, un endpoint generico compatibile con OpenAI oppure local, che installa un server llama.cpp verificato e un piccolo modello di embedding di circa un terzo di gigabyte; funziona anche una voce di provider personalizzata, se usa un tipo di API supportato.
• Due percorsi di recupero vengono eseguiti in parallelo e poi uniti: la ricerca vettoriale trova significati simili, così una query sull’host del Gateway trova una nota sulla macchina che esegue OpenClaw, e la ricerca per parole chiave BM25 trova termini esatti come ID, stringhe di errore e chiavi di configurazione. Se è disponibile un solo percorso, quello viene eseguito da solo.
• La ricerca per nome file indicizza i percorsi separatamente dal contenuto, così un percorso esatto, un nome base o una radice del nome si posiziona prima delle corrispondenze parziali, mentre gli estratti provengono comunque dal contenuto delle note.
• Alcuni endpoint compatibili con OpenAI richiedono tipi di input asimmetrici per query e documenti, che si impostano con due chiavi di configurazione.

Le note vecchie perdono gradualmente peso nel ranking, così le informazioni recenti emergono per prime.

Il ranking

Il motore integrato applica una formula deterministica: la rilevanza ibrida moltiplicata per il decadimento per recenza e per un moltiplicatore di importanza. L’importanza viene valutata una sola volta, quando una voce viene scritta da un flusso di memoria che ha già un modello nel ciclo, e un punteggio mancante è neutro. Le note giornaliere datate decadono con un tempo di dimezzamento di trenta giorni, quindi la nota del mese scorso vale la metà del suo peso originale, mentre i file curati di memoria e utente e i file senza data restano sempre validi. La documentazione cita l’articolo Generative Agents come fonte della combinazione di rilevanza, recenza e importanza, senza aggiungere una chiamata al modello al momento della query. Un passaggio di diversità riordina poi i candidati valutati per ridurre gli estratti quasi identici, con un’impostazione fissa orientata alla rilevanza e un insieme di candidati limitato, senza modificare i punteggi né chiamare un provider. Le corrispondenze per parole chiave vengono conservate quando tutti i risultati classificati scendono sotto il punteggio minimo configurato, e la ricerca ibrida riempie i posti rimanenti con risultati trovati solo per parole chiave.

Il richiamo tramite trigger e le regole di fallback

• Nei turni interattivi idonei, il motore confronta il messaggio in arrivo con brevi frasi trigger salvate sulle voci indicizzate e può aggiungere fino a tre voci compatte al contesto nascosto prima della risposta; sono idonee solo le voci promosse e attendibili dei file radice di memoria e utente, e le note giornaliere, le trascrizioni importate e quelle di sessione non vengono mai inserite automaticamente.
• Impostare il provider su none disattiva di proposito gli embedding per una ricerca solo per parole chiave; lasciarlo non impostato o su auto fa ripiegare sul ranking solo per parole chiave quando la configurazione degli embedding o una richiesta non riesce, come accade anche con il provider local, e l’indicizzazione registra comunque il testo per la ricerca per parole chiave prima della prima ricerca.
• Se indichi esplicitamente qualsiasi altro provider e questo fallisce al momento della richiesta, lo strumento segnala la memoria come non disponibile invece di degradare in silenzio, il che mantiene visibile una configurazione non funzionante; la soluzione è correggere la configurazione del provider o dell’autenticazione, oppure usare none per un richiamo deliberatamente solo per parole chiave.

La guida alla memoria di OpenClaw spiega i file in cui si cerca, mentre il dreaming di OpenClaw è la scansione notturna che decide cosa vi viene promosso e quindi cosa il richiamo tramite trigger può inserire.

Memoria delle sessioni e risoluzione dei problemi

Il richiamo esatto a testo completo dalle trascrizioni spetta allo strumento di ricerca delle sessioni; l’indicizzazione delle trascrizioni nella ricerca nella memoria è facoltativa e si attiva con un flag sperimentale e un elenco di sorgenti, con un’opzione corpus per cercare solo nelle note, impostazioni di visibilità con valore predefinito all e l’accesso tra agenti regolato dall’impostazione da agente ad agente. Immagini e audio possono essere indicizzati insieme al Markdown con un modello di embedding Gemini, ma solo sotto percorsi aggiuntivi, non nelle radici di memoria predefinite. Quando non ci sono risultati, controlla lo stato dell’indice e ricostruiscilo; quando tornano solo corrispondenze per parole chiave, probabilmente il provider di embedding non è configurato, come mostra lo stato dettagliato; quando gli embedding locali vanno in timeout, controlla gli endpoint del server gestito prima di ricostruire; e un testo CJK che non si riesce a trovare richiede una ricostruzione forzata dell’indice. Per i modelli locali accanto ai quali si collocano i provider locali vedi la guida ai modelli locali di OpenClaw, e per le trascrizioni che l’opzione facoltativa indicizza vedi la guida alle sessioni di OpenClaw.

Su Diali

Su Diali la ricerca nella memoria funziona con il provider di embedding che la tua chiave del modello le mette a disposizione e, quando non ce n’è nessuno, ripiega sul percorso per parole chiave descritto dalla documentazione; in entrambi i casi le note risiedono nello spazio di lavoro persistente dell’assistente. OpenClaw ospitato su Diali è l’assistente.

• Vettoriale per il significato, BM25 per i termini esatti, uniti.
• Rilevanza per recenza per importanza; le note giornaliere si dimezzano ogni trenta giorni.
• Un provider esplicito non funzionante viene segnalato, mai nascosto.