Motore di memoria QMD

QMD è un componente affiancato di ricerca locale-first che viene eseguito insieme a OpenClaw. Combina BM25, ricerca vettoriale e reranking in un singolo binario, e può indicizzare contenuti oltre ai file di memoria del tuo workspace.

Cosa aggiunge rispetto al motore integrato

• Reranking ed espansione delle query per un richiamo migliore.
• Indicizza directory aggiuntive -- documentazione del progetto, note del team, qualsiasi cosa su disco.
• Indicizza le trascrizioni delle sessioni -- richiama conversazioni precedenti.
• Completamente locale -- viene eseguito con il Plugin provider ufficiale llama.cpp e scarica automaticamente i modelli GGUF.
• Fallback automatico -- se QMD non è disponibile, OpenClaw torna senza interruzioni al motore integrato.

Per iniziare

Prerequisiti

• Installa QMD: npm install -g @tobilu/qmd oppure bun install -g @tobilu/qmd
• Build di SQLite che consenta le estensioni (brew install sqlite su macOS).
• QMD deve trovarsi nel PATH del Gateway.
• macOS e Linux funzionano direttamente. Windows è supportato al meglio tramite WSL2.

Abilitazione

{  memory: {    backend: "qmd",  },}

OpenClaw crea una home QMD autonoma in ~/.openclaw/agents/<agentId>/qmd/ e gestisce automaticamente il ciclo di vita del componente affiancato -- raccolte, aggiornamenti ed esecuzioni degli embedding sono gestiti per te. Preferisce le forme correnti di raccolta QMD e query MCP, ma, quando necessario, usa ancora come fallback flag alternativi per i pattern delle raccolte e nomi di strumenti MCP meno recenti. La riconciliazione all'avvio ricrea inoltre le raccolte gestite obsolete riportandole ai loro pattern canonici quando una raccolta QMD più vecchia con lo stesso nome è ancora presente.

Come funziona il componente affiancato

• OpenClaw crea raccolte dai file di memoria del workspace e da eventuali memory.qmd.paths configurati, quindi esegue qmd update quando il gestore QMD viene aperto e periodicamente in seguito (valore predefinito ogni 5 minuti). Questi aggiornamenti passano attraverso sottoprocessi QMD, non tramite una scansione del filesystem nel processo. Le modalità semantiche eseguono anche qmd embed.
• La raccolta predefinita del workspace traccia MEMORY.md più l'albero memory/. memory.md minuscolo non viene indicizzato come file di memoria radice.
• Lo scanner di QMD ignora i percorsi nascosti e le directory comuni di dipendenze/build come .git, .cache, node_modules, vendor, dist e build. L'avvio del Gateway non inizializza QMD per impostazione predefinita, quindi l'avvio a freddo evita di importare il runtime della memoria o creare il watcher a lunga durata prima che la memoria venga usata per la prima volta.
• Se vuoi comunque inizializzare QMD all'avvio del Gateway, imposta memory.qmd.update.startup su idle o immediate. Con memory.qmd.update.onBoot: true, l'avvio esegue l'aggiornamento iniziale. Con onBoot: false, l'avvio salta quell'aggiornamento immediato ma apre comunque il gestore a lunga durata quando sono configurati intervalli di aggiornamento o embedding, così QMD può gestire il proprio watcher regolare e i timer.
• Le ricerche usano il searchMode configurato (predefinito: search; supporta anche vsearch e query). search è solo BM25, quindi OpenClaw salta le sonde di prontezza vettoriale semantica e la manutenzione degli embedding in quella modalità. Se una modalità non riesce, OpenClaw riprova con qmd query.
• Quando searchMode è query, imposta memory.qmd.rerank su false per usare il percorso di query ibrido di QMD senza il reranker. OpenClaw passa --no-rerank al percorso CLI diretto di QMD e rerank: false allo strumento di query MCP di QMD. Questa opzione richiede QMD 2.1 o versioni successive.
• Con le release di QMD che dichiarano filtri multi-raccolta, OpenClaw raggruppa raccolte della stessa fonte in una sola invocazione di ricerca QMD. Le release QMD più vecchie mantengono il fallback compatibile per singola raccolta.
• Se QMD fallisce completamente, OpenClaw torna al motore SQLite integrato. Tentativi ripetuti nei turni di chat applicano un breve backoff dopo un errore di apertura, così un binario mancante o una dipendenza del componente affiancato rotta non crea una tempesta di tentativi; openclaw memory status e le sonde CLI una tantum ricontrollano comunque QMD direttamente.

Prestazioni di ricerca e compatibilità

OpenClaw mantiene il percorso di ricerca QMD compatibile sia con le installazioni QMD correnti sia con quelle più vecchie.

All'avvio, OpenClaw controlla il testo di aiuto di QMD installato una volta per gestore. Se il binario dichiara il supporto per più filtri di raccolta, OpenClaw cerca in tutte le raccolte della stessa fonte con un unico comando:

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

Questo evita di avviare un sottoprocesso QMD per ogni raccolta di memoria durevole. Le raccolte di trascrizioni delle sessioni restano nel proprio gruppo di fonte, quindi le ricerche miste memory + sessions forniscono comunque al diversificatore dei risultati input da entrambe le fonti.

Le build QMD più vecchie accettano un solo filtro di raccolta. Quando OpenClaw ne rileva una di queste build, mantiene il percorso di compatibilità e cerca in ogni raccolta separatamente prima di unire e deduplicare i risultati.

Per ispezionare manualmente il contratto installato, esegui:

qmd --help | grep -i collection

L'aiuto QMD corrente dice che i filtri di raccolta possono indirizzare una o più raccolte. L'aiuto più vecchio di solito descrive una singola raccolta.

Override dei modelli

Le variabili d'ambiente dei modelli QMD passano invariate dal processo del Gateway, così puoi regolare QMD globalmente senza aggiungere nuova configurazione OpenClaw:

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

Dopo aver cambiato il modello di embedding, riesegui gli embedding in modo che l'indice corrisponda al nuovo spazio vettoriale.

Indicizzazione di percorsi aggiuntivi

Punta QMD a directory aggiuntive per renderle ricercabili:

{  memory: {    backend: "qmd",    qmd: {      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Gli snippet dai percorsi aggiuntivi appaiono come qmd/<collection>/<relative-path> nei risultati di ricerca. memory_get comprende questo prefisso e legge dalla radice della raccolta corretta.

Indicizzazione delle trascrizioni delle sessioni

Abilita l'indicizzazione delle sessioni per richiamare conversazioni precedenti. QMD richiede sia la fonte sessione generale memorySearch sia l'esportatore di trascrizioni QMD:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },}

Le trascrizioni vengono esportate come turni User/Assistant sanificati in una raccolta QMD dedicata sotto ~/.openclaw/agents/<id>/qmd/sessions/. Impostare solo memorySearch.experimental.sessionMemory non esporta le trascrizioni in QMD.

I risultati delle sessioni sono ancora filtrati da tools.sessions.visibility. La visibilità predefinita tree non espone sessioni non correlate dello stesso agente. Se una sessione inviata dal Gateway deve essere richiamabile da una sessione DM separata, imposta intenzionalmente tools.sessions.visibility: "agent".

Ambito della ricerca

Per impostazione predefinita, i risultati di ricerca QMD vengono mostrati nelle sessioni dirette e di canale (non nei gruppi). Configura memory.qmd.scope per modificarlo:

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Quando l'ambito nega una ricerca, OpenClaw registra un avviso con il canale derivato e il tipo di chat, così i risultati vuoti sono più facili da diagnosticare.

Citazioni

Quando memory.citations è auto o on, gli snippet di ricerca includono un piè di pagina Source: <path#line>. Imposta memory.citations = "off" per omettere il piè di pagina pur passando internamente il percorso all'agente.

Quando usarlo

Scegli QMD quando ti serve:

• Reranking per risultati di qualità superiore.
• Cercare documentazione o note del progetto fuori dal workspace.
• Richiamare conversazioni di sessioni passate.
• Ricerca completamente locale senza chiavi API.

Per configurazioni più semplici, il motore integrato funziona bene senza dipendenze aggiuntive.

Risoluzione dei problemi

QMD non trovato? Assicurati che il binario sia nel PATH del Gateway. Se OpenClaw viene eseguito come servizio, crea un symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

Se qmd --version funziona nella tua shell ma OpenClaw segnala ancora spawn qmd ENOENT, è probabile che il processo Gateway abbia un PATH diverso rispetto alla tua shell interattiva. Fissa esplicitamente il binario:

{  memory: {    backend: "qmd",    qmd: {      command: "/absolute/path/to/qmd",    },  },}

Usa command -v qmd nell'ambiente in cui QMD è installato, quindi ricontrolla con openclaw memory status --deep.

Prima ricerca molto lenta? QMD scarica i modelli GGUF al primo utilizzo. Preriscalda con qmd query "test" usando le stesse directory XDG usate da OpenClaw.

Molti sottoprocessi QMD durante la ricerca? Aggiorna QMD se possibile. OpenClaw usa un processo per le ricerche multi-raccolta della stessa fonte solo quando QMD installato dichiara supporto per più filtri -c; altrimenti mantiene il fallback più vecchio per singola raccolta per correttezza.

QMD solo BM25 tenta ancora di compilare llama.cpp? Imposta memory.qmd.searchMode = "search". OpenClaw tratta quella modalità come solo lessicale, non esegue sonde di stato vettoriale QMD né manutenzione degli embedding, e lascia i controlli di prontezza semantica alle configurazioni vsearch o query.

La ricerca scade? Aumenta memory.qmd.limits.timeoutMs (predefinito: 4000ms). Imposta a 120000 per hardware più lento.

Risultati vuoti nelle chat di gruppo? Controlla memory.qmd.scope -- il valore predefinito consente solo sessioni dirette e di canale.

La ricerca nella memoria radice è diventata improvvisamente troppo ampia? Riavvia il Gateway o attendi la prossima riconciliazione all'avvio. OpenClaw ricrea le raccolte gestite obsolete riportandole ai pattern canonici MEMORY.md e memory/ quando rileva un conflitto con lo stesso nome.

Repository temporanei visibili dal workspace causano ENAMETOOLONG o indicizzazione rotta? L'attraversamento di QMD attualmente segue il comportamento dello scanner QMD sottostante anziché le regole symlink integrate di OpenClaw. Tieni i checkout temporanei di monorepo sotto directory nascoste come .tmp/ o fuori dalle radici QMD indicizzate finché QMD non espone attraversamento sicuro rispetto ai cicli o controlli di esclusione espliciti.

Configurazione

Per l'intera superficie di configurazione (memory.qmd.*), le modalità di ricerca, gli intervalli di aggiornamento, le regole di ambito e tutte le altre opzioni, consulta il Riferimento alla configurazione della memoria.

Correlati

• Panoramica della memoria
• Motore di memoria integrato
• Memoria Honcho