QMD — Mecanismo de Busca Local de Conhecimento
QMD é o mecanismo de busca local vetorial + de palavras-chave sobre os espaços de trabalho do usuário. Use-o antes de responder perguntas que já podem estar documentadas — especialmente para contexto sobre pessoas, projetos, decisões e trabalhos passados.
Fluxo de Trabalho
O fluxo de trabalho é sempre:
- Buscar documentos candidatos.
- Recuperar a fonte completa com
qmd getouqmd multi-get. - Responder a partir do texto recuperado, citando caminhos ou docids.
Não responda apenas a partir de trechos quando o usuário precisar de fatos, decisões, citações ou nuances. Trechos são apenas pistas.
Ao relatar o que você recuperou, uma nota compacta é suficiente; não cole arquivos inteiros a menos que necessário:
Recuperado: #abc123 wiki/projects/GenAICategorizer.md, #def432 memory/2026-05-26.md
Escolha o modo de busca correto
| Modo | Comando | Quando usar |
|---|---|---|
| BM25 de palavras-chave | qmd search | Palavras exatas, títulos, nomes, símbolos de código, frases raras |
| Híbrido + reclassificação | qmd query | Redação indireta, recall conceitual, melhor qualidade |
| Estruturado | qmd query com campos lex:/vec:/hyde: | Buscas difíceis que precisam de âncoras exatas + recall semântico |
Busca simples:
qmd search "status do projeto da equipe challenger" -n 10
qmd search '"GenAI Categorizer"' -c wiki-main -n 5
Busca semântica de conceitos:
qmd query "a qualidade das decisões depende de explicitar suposições e contexto" -n 10
Busca estruturada (buscas difíceis):
qmd query $'intent: Encontrar a nota conceitual sobre métricas como instrumentos sem deixar OKRs substituírem o julgamento.\nlex: instrumentos de cockpit OKR Goodhart métricas julgamento\nvec: orientado a dados não impulsionado por métricas julgamento de produto\nhyde: Uma nota conceitual diz que métricas são úteis como instrumentos de cockpit, mas líderes devem permanecer orientados a dados em vez de impulsionados por métricas porque OKRs e dashboards podem distorcer o julgamento do produto.'
Campos da busca estruturada:
intent:declara o que você está tentando encontrar e o que evitar.lex:termos exatos, aliases, títulos e palavras raras.vec:parafraseia a ideia em linguagem natural.hyde:descreve o documento ou resposta que satisfaria a solicitação.
Recuperar fontes
qmd get "#abc123" # por docid dos resultados da busca
qmd get "wiki/projects/GenAICategorizer.md" --full # por caminho
qmd multi-get "#abc123,#def432" --md # lote por docids
qmd multi-get 'memory/2026-05-*.md' -l 80 # lote por glob
Use multi-get ao comparar vários resultados ou reunir contexto entre páginas. Use --full quando a fonte exata for importante.
Coleções por agente
Cada agente tem seu próprio índice QMD com configuração isolada via XDG. A lista de agentes está em ${OPENCLAW_HOME}/config/agents.map. Ao buscar a partir da CLI, use o wrapper XDG do agente:
# agente principal
XDG_CONFIG_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-config XDG_CACHE_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-cache qmd query "..."
# agente de desenvolvimento e qualquer outro — mesmo padrão, troque o nome do agente
Coleções do agente principal
| Coleção | O que contém |
|---|---|
identity-main | Documentos principais — ALMA, IDENTIDADE, FERRAMENTAS, AGENTES, REDE, índice de MEMÓRIA |
wiki-main | Córtex de conhecimento durável. Wiki — comportamentos de agentes (regras entre agentes), projetos, ferramentas, conceitos, pessoas. Principal repositório de memória durável a partir de 2026-05-28. |
memory-main | Arquivos de memória diária (YYYY-MM-DD.md) — camada de captura de 7 dias que promove conteúdo para wiki-main |
workspace-docs-main | Markdown completo do espaço de trabalho (referências, tarefas, transferências, aprendizados) |
skills-main | Definições de habilidades (arquivos SKILL.md) |
agents-*-identity | Documentos raiz de identidade/configuração de outros agentes (espaços de trabalho por agente) |
agents-*-memory | Arquivos de memória diária de outros agentes (espaços de trabalho por agente) |
agents-*-wiki | Wikis duráveis de outros agentes (espaços de trabalho por agente) — o agente principal pode consultar conhecimento durável especializado diretamente. |
handoffs-* | Arquivos de transferência por agente (principal, desenvolvimento e qualquer outro) |
Sugestões de coleções especializadas
Os nomes das coleções abaixo são da própria configuração QMD de cada agente especializado. A partir do agente principal, use os equivalentes entre agentes (agents-<agente>-wiki, agents-<agente>-memory).
| O que você está procurando | Agente | Coleções principais (dentro desse agente) | A partir do agente principal |
|---|---|---|---|
| Projetos de código, configurações de build, decisões de engenharia | dev | projects-dev, identity-dev, wiki-dev | agents-dev-wiki, agents-dev-memory |
Escopo de contexto e coleção
O metadado context: do QMD (definido em index.yml ou via qmd context add) melhora a relevância da busca ao descrever o que cada coleção contém. Ele é retornado junto com os resultados.
Limite as buscas com -c quando buscas amplas se desviarem para o corpus errado:
qmd search "notas diárias esta semana" -c agents-dev-memory -n 10
qmd query "status do projeto GenAI" -c wiki-main -c projects-dev -n 10
Omita -c para buscar em tudo.
Diagnóstico
qmd status # contagens das coleções e embeddings pendentes
qmd update # reindexar (use após adicionar/editar arquivos nos caminhos indexados)
qmd embed # gerar/recriar vetores após a atualização
Se qmd query ou qmd vsearch falhar (modelo/GPU indisponível), volte para qmd search com termos lexicais mais fortes.
Observação: documentos mais antigos referenciam qmd doctor — esse subcomando não está presente na versão atual da CLI. Use qmd status para saúde e qmd update/qmd embed para reparos.
Ferramentas MCP
Ao usar MCP (o padrão para agentes OpenClaw), prefira consultas estruturadas:
{
"searches": [
{ "type": "lex", "query": "status da equipe challenger" },
{ "type": "vec", "query": "qual é o estado atual do projeto da equipe challenger" }
],
"intent": "Encontrar status do projeto, não conceitos gerais sobre a equipe.",
"limit": 10
}
Armadilhas
- Não pare em trechos. Busque documentos antes de fazer afirmações.
- Não abuse da busca semântica. Se você sabe títulos ou termos exatos, BM25 é mais rápido e frequentemente melhor.
- Não mude índices casualmente.
qmd collection add,qmd updateeqmd embedalteram o estado local e podem ser caros. - Comandos baseados em modelo podem ser sensíveis ao ambiente. Se
qmd queryou a reclassificação falhar, volte paraqmd searchcom termos lexicais mais fortes. - Redação ambígua do usuário precisa de intenção. Adicione
intent:em vez de esperar que a expansão da consulta adivinhe o domínio correto. - Nomes de coleção são importantes. Limite com
-cquando a consulta puder corresponder a vários domínios. - Recência: QMD não decai resultados antigos. Para memória sensível ao tempo, verifique nomes de arquivo — YYYY-MM-DD mais próximo de hoje é mais atual.
Configuração e manutenção
Execute estes apenas quando solicitado. Buscar e recuperar são seguros; mutação de índice não é casual.
qmd collection add ~/notes --name notes # alternativa CLI para editar index.yml
qmd context add qmd://notes "Descrição" # alternativa CLI para context: em index.yml
qmd update # reindexar coleções
qmd embed # gerar/recriar vetores
qmd status # verificação de saúde após alterações