Come usare QMD

Cos'è QMD in pratica

QMD è un motore locale per ricerca semantica e query su una raccolta di documenti.

Nel mio setup lo uso come layer di retrieval sopra il vault second-brain, in particolare sulle note Markdown dentro:

• 00_Inbox
• 01_Topics
• 02_Notes

Nel workflow con OpenClaw non sostituisce l'indice deterministico del vault: lo affianca.

In pratica:

• l'indice locale/deterministico serve per struttura, link, tag, MOC, metadati
• QMD serve per retrieval semantico e query più intelligenti sul testo

Dove lo sto usando

Root principali del setup locale:

• vault: /home/medio/.openclaw/workspace/second-brain
• index root: /home/medio/.openclaw/workspace/second-brain-index
• QMD config: /home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-config
• QMD cache: /home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-cache
• collection usata: vault-notes

Nel mio workflow:

• sb-index ricostruisce l'indice del vault
• poi richiama il refresh QMD
• i workflow Lobster/OpenClaw usano questo stack per refine e retrieval

Comandi top

1. Creare la collection

qmd collection add /home/medio/.openclaw/workspace/second-brain \
  --name vault-notes \
  --mask '{00_Inbox,01_Topics,02_Notes}/**/*.md'

Serve a dire a QMD quale vault indicizzare e quali file includere.

2. Vedere le collection

qmd collection list

Utile per verificare che vault-notes esista davvero.

3. Aggiornare la collection

qmd update

Riscansiona i file e aggiorna lo stato della collection.

4. Generare / aggiornare embeddings

qmd embed

Serve per la parte semantica. Senza questo, search / query possono essere limitati o incoerenti.

5. Ricerca semantica semplice

qmd search "bash scripting linux" -c vault-notes -n 5 --json

Buona per trovare note simili o affini al testo della query.

6. Query più ricca

qmd query "come uso bash per scripting e comandi linux" -c vault-notes -n 5 --json

È la modalità più “intelligente”, ma anche più pesante.

Differenza pratica tra qmd search e qmd query

qmd search

Usalo quando vuoi:

• retrieval leggero
• risultati veloci
• basso impatto hardware
• cercare note semanticamente vicine

Sul VPS usavo soprattutto questo, perché la macchina era limitata e volevo evitare roba troppo pesante.

qmd query

Usalo quando vuoi:

• una query più interpretata/espansa
• recupero più ricco
• migliore qualità su domande formulate in linguaggio naturale

Sul desktop di casa ora posso provarlo meglio, perché ho più margine hardware.

Contro:

• primo avvio più costoso
• può scaricare modelli locali
• warm-up iniziale più lento
• su CPU può essere sensibilmente più pesante

Nota importante sul primo uso di qmd query

Nel mio test reale, il primo qmd query ha scaricato modelli locali aggiuntivi e ha fatto warm-up.

Quindi il primo run non va giudicato come latenza normale.

Dopo il caching iniziale, il comportamento dovrebbe essere più stabile.

Per questo motivo:

• su VPS piccolo: ha senso preferire qmd search
• su desktop: qmd query diventa più realistico

Come lo uso con OpenClaw

Nel mio setup OpenClaw non chiama QMD “a mano” ogni volta.

Il pattern corretto è:

1. il vault vive in second-brain
2. sb-index aggiorna l'indice deterministico
3. lo stesso workflow aggiorna QMD
4. i workflow di refine o assistenza possono poi usare QMD per retrieval/query

Esempio pratico di refresh coerente con il workflow:

qmd collection add /home/medio/.openclaw/workspace/second-brain \
  --name vault-notes \
  --mask '{00_Inbox,01_Topics,02_Notes}/**/*.md'
qmd update
qmd embed

Nel progetto locale questo refresh viene richiamato dentro il flusso sb-index, che a sua volta può essere eseguito anche via Lobster.

Esempi pratici

Search sulla collection del vault

export XDG_CONFIG_HOME=/home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-config
export XDG_CACHE_HOME=/home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-cache
qmd search "openclaw telegram cron" -c vault-notes -n 5 --json

Query sulla collection del vault

export XDG_CONFIG_HOME=/home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-config
export XDG_CACHE_HOME=/home/medio/.openclaw/workspace/second-brain-index/qmd/xdg-cache
qmd query "come sto usando qmd con openclaw e second-brain" -c vault-notes -n 5 --json

Regola pratica

• se voglio velocità e costo basso: qmd search
• se voglio retrieval più ricco e posso permettermi più peso locale: qmd query
• dopo modifiche al vault: qmd update + qmd embed
• nel mio setup OpenClaw: lasciare che sb-index tenga allineato anche QMD

In breve

QMD è il layer semantico del mio second-brain locale.

Su VPS piccolo ha senso usarlo in modo conservativo, soprattutto con search.
Su desktop più forte ha senso esplorare anche query, tenendo presente il costo del primo warm-up e dei modelli locali.