QMD: documentação que você não consulta é um cemitério

Você tem quatrocentos arquivos markdown. Decisões de arquitetura, manuais de operação, notas de reunião, aquele documento que explica por que o login ficou daquele jeito. Você escreveu tudo isso para o "você do futuro" e para os seus agentes de IA usarem depois. Pergunta honesta: quando foi a última vez que você achou o arquivo certo, na hora exata em que precisou dele?

Se a resposta sincera é "procurei pela palavra que eu lembrava, não achei, e reescrevi um documento que já existia", você não tem uma base de conhecimento. Você tem um cemitério em que cada lápide é um arquivo que ninguém lê.

Minha posição: documentação que você não consegue consultar é só uma pasta cheia de arquivos com um pouco de culpa em cima. Este texto é sobre o que separa as duas coisas. Vou usar um caso concreto do começo ao fim, e voltar sempre a uma ferramenta de verdade: o QMD, um projeto gratuito e de código aberto que faz exatamente isso na sua própria máquina.

O caso: a decisão que você não acha

Seis meses atrás o seu time decidiu não usar fila de mensagens para um fluxo específico de pagamento, e escreveu o porquê num documento. Hoje um desenvolvedor novo pergunta: "por que a gente não usa fila aqui?". Você sabe que existe um documento. Você só não lembra o nome do arquivo, nem as palavras exatas que usou.

Você busca por "fila", do jeito que programadores fazem com um grep. Vinte e sete resultados, nenhum é o certo. Você tenta "message queue", "fila de mensagens", "assíncrono". O documento usava a palavra "broker", que você não lembrou de buscar. Depois de dez minutos, você desiste e responde de cabeça. A decisão escrita existe, está salva no histórico do projeto, e é inútil, porque o sistema de recuperação é a sua memória, e a sua memória falhou.

O problema não é que você escreveu o documento errado. É que escrever e recuperar são duas coisas diferentes, e você só resolveu a primeira.

Por que buscar pela palavra não basta

Busca exata acha a palavra que você lembra. Não acha a ideia que você esqueceu que escreveu. Esse buraco é o jogo inteiro.

Uma base de conhecimento de verdade busca em dois eixos ao mesmo tempo. O primeiro é a busca léxica, que acerta o termo literal: o código de erro, o nome da função, o nome do cliente. O segundo é a busca semântica, que acha por significado. Foi ela que faltou no exemplo: "por que não usamos fila" deveria ter trazido o documento sobre "broker" mesmo sem dividir nenhuma palavra-chave.

O Simon Willison tem a melhor descrição que eu já vi para isso. Ele chama a busca semântica de "busca por vibe": o documento e a sua pergunta têm a mesma vibe, segundo uma representação multidimensional esquisita do significado das palavras, e isso é absurdamente útil. É a frase certa porque é honesta sobre os dois lados. Funciona surpreendentemente bem, e é fundamentalmente difuso. Você não recebe a resposta, recebe os candidatos mais prováveis.

Os dois eixos juntos vencem qualquer um sozinho

Aqui não é opinião, é resultado medido. A Anthropic publicou um texto de engenharia sobre Contextual Retrieval em que combina embeddings com busca léxica clássica (na versão deles, com contexto adicionado a cada trecho) justamente porque nenhum dos dois sozinho dá conta. Os números são concretos: juntar os dois eixos reduziu as falhas de recuperação em 49 por cento, e somando uma etapa de reranking, em 67 por cento. O padrão não é novo, ele vem do paper que batizou o termo retrieval-augmented generation, de 2020. A novidade é que hoje dá para rodar uma versão competente disso localmente, em cima dos seus próprios arquivos, sem mandar um byte para a nuvem de ninguém.

É exatamente o que o qmd, uma ferramenta de código aberto do Tobi Lütke, faz. Ela indexa os seus markdowns e combina BM25, busca vetorial e reranking por modelo de linguagem, tudo rodando na sua máquina via modelos locais. Cito o qmd não para te dizer qual ferramenta usar, mas porque ele prova que dá: o que parecia coisa de laboratório de IA hoje é um programa gratuito e de código aberto que roda na sua própria máquina, em cima dos seus documentos.

O QMD de perto, e a ideia que vale roubar

Vale olhar o que o QMD é, porque ele carrega uma decisão de design que a maioria das ferramentas de busca ignora. Quem o escreveu é o Tobi Lütke, o fundador e CEO da Shopify. Um sujeito que poderia delegar qualquer coisa sentou e publicou de graça uma ferramenta de linha de comando para procurar nos próprios arquivos. Isso por si só é um sinal do momento: recuperação local deixou de ser projeto de doutorado e virou utilitário que cabe num fim de semana.

Por baixo, o QMD faz o que descrevi acima: indexa os seus arquivos, busca pelos dois eixos ao mesmo tempo, funde os resultados e reordena com um modelo que roda na sua própria máquina, sem mandar nada para fora. Mas a parte que eu destacaria não é essa. É a que o próprio autor destaca no manual como a feature principal do QMD, avisando para não dormir nessa: a árvore de contexto.

A ideia é simples e poderosa. Você anexa uma frase de contexto a uma pasta inteira, por exemplo "transcrições das reuniões de produto", e essa frase volta junto sempre que um documento daquela pasta aparece numa busca. Parece bobo até você pensar no que isso resolve. Um trecho solto que diz "decidimos não fazer" é ruído. O mesmo trecho com a etiqueta "decisão de arquitetura, fluxo de pagamento, junho" é uma resposta. O contexto que vive na sua cabeça, e que some quando você esquece o arquivo, passa a viajar grudado no documento. É a diferença entre um agente de IA escolhendo o documento certo e ele chutando o mais parecido.

Não é a única ferramenta que faz busca híbrida local, e não importa. O que importa é que o padrão existe num formato que você consegue dominar, auditar e abandonar sem dor. Esse é o critério, e a ferramenta é só a prova de que o critério é alcançável hoje.

Onde a busca semântica te trai

Se eu parasse aqui seria propaganda de busca semântica. A própria descrição do Willison contém o aviso: "vibe" é poderoso e é difuso. Três armadilhas reais.

A primeira: a busca semântica recupera o que parece relacionado, não o que está correto. Ela vai te trazer o documento sobre a decisão antiga de fila com a mesma confiança com que traria um documento que fala de fila mas decidiu o contrário. Parecido com a sua pergunta não é a mesma coisa que verdadeiro para o seu caso.

A segunda: embedding tem viés do momento em que foi gerado. Se você indexou os docs há três meses e o vocabulário do seu time mudou, a vibe envelhece. Recuperação sem atualização é um retrato desatualizado do seu próprio acervo.

A terceira: a tentação de confiar no primeiro resultado. O valor de uma base consultável não é ela te dar uma resposta. É ela te dar o ponteiro para a fonte, que você abre e lê. No instante em que você trata o resultado da busca como verdade em vez de candidato, você trocou um cemitério por uma fonte de erro confiante.

Recuperação não te dá a resposta. Te dá o ponteiro para a fonte. Quem decide se a fonte vale é você, depois de abri-la.

Os critérios que importam mais que a ferramenta

A pergunta nunca é "qual ferramenta de recuperação é a melhor". É "qual eu consigo dominar, auditar e abandonar sem dor". Meus critérios, em ordem:

• Local primeiro. O seu acervo é decisão, contexto de cliente, estratégia pela metade. Isso não pertence ao índice de um terceiro por padrão. Recuperação local mantém o que é privado, privado.
• **CLI antes de SDK antes de MCP.** Se a ferramenta me dá uma linha de comando de verdade, eu scripto, agendo e inspeciono. Quanto mais para o fundo dessa lista você vai, mais preso à ferramenta você fica e menos enxerga o que ela faz por dentro. A superfície mais simples que resolve costuma ser a mais durável.
• Verificar antes de confiar. Toda recuperação devolve candidatos. O passo que separa uma base útil de uma fábrica de alucinação é abrir a fonte e conferir antes de agir sobre ela.

A implementação disso depende do seu acervo, do seu risco e do quanto você tolera informação desatualizada, e é por isso que nenhum post honesto te entrega como receita. O que generaliza é o critério.

A posição

Markdown é onde o repositório lembra. Mas memória que você não consegue recuperar não é memória, é armazenamento. O cemitério não é um problema de formato, é um problema de recuperação. Você não perde a decisão porque ela estava na extensão errada. Você perde porque nada responde "onde a gente decidiu X, e por quê?" sem você lembrar do nome do arquivo primeiro.

A medida honesta da sua base de conhecimento não é quantos arquivos ela tem. É quanto tempo leva, agora, para você achar a decisão sobre a fila. Se a resposta for "primeiro eu preciso lembrar onde guardei", você não tem uma base. Você tem um cemitério bem organizado.

A boa notícia é que a saída deixou de ser exótica. Um projeto como o QMD prova que dá para rodar uma base consultável de verdade localmente, hoje, em cima dos seus próprios arquivos. A ferramenta vai mudar. O critério não muda: você consegue achar a decisão, agora?