Ricerca nella memoria

memory_search trova note pertinenti dai tuoi file di memoria, anche quando la formulazione differisce dal testo originale. Funziona indicizzando la memoria in piccoli frammenti e cercandoli con embedding, parole chiave o entrambi.

Avvio rapido

La ricerca in memoria usa gli embedding OpenAI per impostazione predefinita. Per usare un altro backend di embedding, imposta esplicitamente un provider:

{  agents: {    defaults: {      memorySearch: {        provider: "openai", // or "gemini", "local", "ollama", "openai-compatible", etc.      },    },  },}

Per configurazioni multi-endpoint con provider specifici per la memoria, provider può anche essere una voce personalizzata models.providers.<id>, ad esempio ollama-5080, quando quel provider imposta api: "ollama" o un altro proprietario di adattatore per embedding di memoria.

Per embedding locali senza chiave API, installa @openclaw/llama-cpp-provider e imposta provider: "local". I checkout sorgente potrebbero comunque richiedere l'approvazione della build nativa: pnpm approve-builds e poi pnpm rebuild node-llama-cpp.

Alcuni endpoint di embedding compatibili con OpenAI richiedono etichette asimmetriche come input_type: "query" per le ricerche e input_type: "document" o "passage" per i frammenti indicizzati. Configurale con memorySearch.queryInputType e memorySearch.documentInputType; consulta il Riferimento alla configurazione della memoria.

Provider supportati

Come funziona la ricerca

OpenClaw esegue due percorsi di recupero in parallelo e unisce i risultati:

flowchart LR
    Q["Query"] --> E["Embedding"]
    Q --> T["Tokenize"]
    E --> VS["Vector Search"]
    T --> BM["BM25 Search"]
    VS --> M["Weighted Merge"]
    BM --> M
    M --> R["Top Results"]

• Ricerca vettoriale trova note con significato simile ("gateway host" corrisponde a "the machine running OpenClaw").
• Ricerca per parole chiave BM25 trova corrispondenze esatte (ID, stringhe di errore, chiavi di configurazione).

Se è disponibile un solo percorso, l'altro viene eseguito da solo. La modalità intenzionale solo FTS (provider: "none") e la selezione automatica/predefinita del provider possono comunque usare il ranking lessicale quando gli embedding non sono disponibili.

I provider di embedding espliciti non locali sono diversi. Se imposti memorySearch.provider su un provider concreto con backend remoto e quel provider non è disponibile in runtime, memory_search segnala la memoria come non disponibile invece di usare silenziosamente risultati solo FTS. Questo mantiene visibile un provider semantico configurato ma non funzionante. Imposta provider: "none" per un richiamo deliberatamente solo FTS, oppure correggi la configurazione del provider/autenticazione per ripristinare il ranking semantico.

Migliorare la qualità della ricerca

Due funzionalità opzionali aiutano quando hai una cronologia di note ampia:

Decadimento temporale

Le note vecchie perdono gradualmente peso nel ranking, così le informazioni recenti emergono per prime. Con l'emivita predefinita di 30 giorni, una nota del mese scorso ottiene il 50% del suo peso originale. I file sempre attuali come MEMORY.md non subiscono mai decadimento.

MMR (diversità)

Riduce i risultati ridondanti. Se cinque note menzionano tutte la stessa configurazione del router, MMR garantisce che i risultati principali coprano argomenti diversi invece di ripetersi.

Abilitarli entrambi

{  agents: {    defaults: {      memorySearch: {        query: {          hybrid: {            mmr: { enabled: true },            temporalDecay: { enabled: true },          },        },      },    },  },}

Memoria multimodale

Con Gemini Embedding 2, puoi indicizzare immagini e file audio insieme al Markdown. Le query di ricerca restano testuali, ma trovano corrispondenze nei contenuti visivi e audio. Consulta il Riferimento alla configurazione della memoria per la configurazione.

Ricerca nella memoria di sessione

Puoi opzionalmente indicizzare le trascrizioni delle sessioni così memory_search può richiamare conversazioni precedenti. È una scelta esplicita tramite memorySearch.experimental.sessionMemory e sources: ["sessions"]; l'elenco di origini predefinito è solo memoria. Il flag sperimentale abilita l'indicizzazione delle trascrizioni di sessione, mentre sources controlla se i frammenti di sessione vengono cercati.

I risultati delle sessioni rispettano tools.sessions.visibility: l'impostazione predefinita tree espone solo la sessione corrente e le sessioni che ha generato. Per richiamare una sessione non correlata dello stesso agente inviata dal Gateway da una sessione DM separata, amplia intenzionalmente la visibilità a agent.

Quando usi QMD, imposta anche memory.qmd.sessions.enabled: true così le trascrizioni vengono esportate in una raccolta QMD. Consulta il riferimento alla configurazione per i dettagli.

Risoluzione dei problemi

Nessun risultato? Esegui openclaw memory status per controllare l'indice. Se è vuoto, esegui openclaw memory index --force.

Solo corrispondenze per parole chiave? Il tuo provider di embedding potrebbe non essere configurato. Controlla openclaw memory status --deep.

Gli embedding locali vanno in timeout? ollama, lmstudio e local usano per impostazione predefinita un timeout batch inline più lungo. Se l'host è semplicemente lento, imposta agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds e riesegui openclaw memory index --force.

Testo CJK non trovato? Ricostruisci l'indice FTS con openclaw memory index --force.

Ulteriori letture

• Active Memory -- memoria dei sotto-agenti per sessioni di chat interattive
• Memoria -- layout dei file, backend, strumenti
• Riferimento alla configurazione della memoria -- tutte le opzioni di configurazione

Correlati

• Panoramica della memoria
• Active Memory
• Motore di memoria integrato