QMD — Motor de Busca Local para Documentos

QMD (Query Markup Documents) é um motor de busca on-device para notas Markdown, knowledge bases, transcrições de reuniões e documentação técnica. Combina busca por palavras-chave (BM25), busca semântica vetorial e re-ranking via LLM — tudo rodando localmente.

Repositório: https://github.com/tobi/qmd
Pacote: @tobilu/qmd
Licença: MIT | Stars: ~16.5k

Instalação

npm install -g @tobilu/qmd
# ou
bun install -g @tobilu/qmd
# ou sem instalar
npx @tobilu/qmd ...

Requisitos:

Node.js >= 22 ou Bun >= 1.0.0
macOS: brew install sqlite (suporte a extensões)

Modelos GGUF (baixados automaticamente)

Modelo	Finalidade	Tamanho
`embeddinggemma-300M-Q8_0`	Embeddings vetoriais	~300MB
`qwen3-reranker-0.6b-q8_0`	Re-ranking	~640MB
`qmd-query-expansion-1.7B-q4_k_m`	Expansão de queries (fine-tuned)	~1.1GB

Modelos ficam em ~/.cache/qmd/models/. Para corpora multilíngues (CJK), pode-se usar Qwen3-Embedding via QMD_EMBED_MODEL.

Uso Básico (CLI)

Coleções

qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection list
qmd collection remove myproject

Contexto (melhora relevância da busca)

qmd context add qmd://notes "Notas pessoais e ideias"
qmd context add qmd://docs "Documentação de trabalho"
qmd context list

Indexação e Embeddings

qmd update          # re-indexa as coleções
qmd embed           # gera embeddings vetoriais
qmd embed -f        # força re-embedding de tudo

Busca

Comando	Tipo
`qmd search "termo"`	BM25 full-text (rápido)
`qmd vsearch "como fazer X"`	Semântico vetorial
`qmd query "planejamento trimestral"`	Híbrido + re-ranking (melhor qualidade)

# Opções úteis
qmd query -n 10 --min-score 0.3 "design de API"
qmd search --json "autenticação"       # saída JSON para agentes
qmd search --files --all --min-score 0.3 "API"  # lista de arquivos
 
# Recuperar documento específico
qmd get "docs/readme.md"
qmd get "#abc123"                      # por docid
qmd get notes/meeting.md:50 -l 100    # a partir da linha 50
qmd multi-get "journals/2025-05*.md"  # por glob

Integração com Agentes (MCP)

QMD expõe um servidor MCP para integração com Claude e outros agentes.

Ferramentas MCP expostas: query, get, multi_get, status

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "qmd": { "command": "qmd", "args": ["mcp"] }
  }
}

Claude Code:

claude plugin marketplace add tobi/qmd
claude plugin install qmd@qmd

Servidor HTTP compartilhado (evita recarregar modelos a cada requisição):

qmd mcp --http              # inicia em localhost:8181
qmd mcp --http --daemon     # em background
qmd mcp stop                # para o daemon

Pipeline de Busca Híbrida

Expansão de query via LLM fine-tuned → gera variações
Busca paralela BM25 (FTS5) + vetorial para cada variação
Fusão RRF (Reciprocal Rank Fusion, k=60) com peso ×2 para query original
Top 30 candidatos passam para re-ranking
Re-ranking LLM (qwen3-reranker) com confiança via logprobs
Blend posicional final:
- Rank 1-3: 75% RRF / 25% reranker
- Rank 4-10: 60% / 40%
- Rank 11+: 40% / 60%

Interpretação de scores:

Score	Relevância
0.8–1.0	Alta
0.5–0.8	Moderada
0.2–0.5	Parcial
0.0–0.2	Baixa

Uso como SDK (Node.js / Bun)

npm install @tobilu/qmd

import { createStore } from '@tobilu/qmd'
 
const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
    },
  },
})
 
const results = await store.search({ query: "fluxo de autenticação" })
await store.close()

Métodos principais: search(), searchLex(), searchVector(), get(), multiGet(), update(), embed(), addCollection(), addContext().

Armazenamento

Índice em: ~/.cache/qmd/index.sqlite
Tabelas: collections, documents, documents_fts (FTS5), content_vectors, vectors_vec, llm_cache, path_contexts
Chunks de ~900 tokens com 15% de overlap e detecção inteligente de quebras (favorece headings e blocos de código)

Alisson's Notes

Explorador

qmd