Documentação que você não consulta é um cemitério

Você tem quatrocentos arquivos markdown. Planos, ADRs, runbooks, notas de reunião, logs de sessão, aquele doc de decisão que explica por que o fluxo de auth ficou daquele jeito. Você escreveu tudo pra que o "você do futuro" — e seus agentes — pudessem usar depois. Pergunta rápida: quando foi a última vez que você achou o doc certo na hora exata em que precisou?

Se a resposta honesta é "dei grep, desisti e reescrevi um doc que já existia", você não tem base de conhecimento. Você tem um cemitério write-only.

Minha posição: documentação que você não consulta é só disco que te faz sentir organizado. Conhecimento acumulado só vira alavanca quando você — e os agentes do seu lado — conseguem recuperar a fatia certa sob demanda, em linguagem natural, localmente. Retrieval não é luxo que você pluga depois. É um componente nomeado do harness — o andaime de retrieval, testes, review, rollback e ownership que mantém o trabalho AI-native em pé. Eu rodo um em cima do meu próprio acervo de docs, e vou te dizer o que olhar. Não vou te ensinar a montar. Essa parte tem preço.

Markdown lembra. Retrieval é o que deixa você perguntar.

Existe uma ideia separada e verdadeira circulando: markdown é onde o repo lembra — decisão durável vive em texto plano, não num chat que some no scroll. Beleza. Mas memória que você não consegue recuperar não é memória. É armazenamento. O cemitério não é problema de formato; é problema de retrieval. Você não perde o ADR porque ele 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.

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

Dois eixos, não um: léxico e semântico

Uma base local de verdade busca em dois eixos ao mesmo tempo. Busca léxica (BM25 e parentes) acerta o termo exato — o código de erro, o nome da função, o nome do cliente. Busca semântica usa embeddings pra achar por significado, então "como a gente lida com cliente que cancela no meio do contrato" traz o doc chamado "política de downgrade involuntário" mesmo sem dividir nenhuma palavra-chave.

Você quer os dois, porque consulta nos dois modos dependendo do dia. Não é opinião minha: é como times sérios de retrieval constroem. O texto da Anthropic sobre Contextual Retrieval combina embeddings com BM25 justamente porque nenhum dos dois sozinho dá conta (www.anthropic.com); o padrão vem do paper que batizou retrieval-augmented generation (arxiv.org). A diferença hoje: dá pra rodar uma versão competente localmente, em cima dos seus arquivos, sem mandar um byte pra nuvem de ninguém.

Os critérios que importam mais que a ferramenta

Culto à ferramenta é a armadilha. A pergunta nunca é "qual ferramenta de retrieval é a melhor". É "qual eu consigo dominar, auditar e abandonar sem dor". Meus critérios, em ordem:

• Local primeiro. Seu acervo de docs é plano, contexto de cliente, estratégia pela metade. Isso não pertence ao índice de um terceiro por padrão. Retrieval local mantém o grafo privado privado.
• CLI antes de SDK antes de MCP. Se a ferramenta me dá uma superfície de linha de comando de verdade, eu scripto, agendo e inspeciono. CLI → SDK → MCP é minha ordem de adoção exatamente por isso — quanto mais pra baixo nessa lista, mais lock-in e mais frágil o sandbox.
• Retrieval aponta, não manda. O índice é um ponteiro pra um doc relevante, não a fonte da verdade. A realidade atual se confirma lendo o arquivo, o histórico do git, os testes, o sistema vivo. Trate o índice como evangelho e ele vai entregar pro seu agente, com toda a confiança, uma decisão que você reverteu três meses atrás.

Funciona não é critério. Sobrevive é critério. Um setup de retrieval que brilha na demo e apodrece em um mês nunca foi infraestrutura.

Os modos de falha que ninguém põe na landing page

Assumir retrieval é assumir os modos de falha dele. Três que mordem:

Defasagem. Um índice que não ressincronizou mente com confiança total. Ele devolve o runbook velho, o agente age em cima dele, e você debuga um problema que já estava resolvido. Uma base de conhecimento vale o tanto que ela está fresca — e freshness dá trabalho, não é setup de uma vez só.

Ruído afogando sinal. O instinto é indexar tudo. Não faça. Joga todo log de sessão e nota descartável lá dentro e seus docs duráveis somem — a qualidade do retrieval cai, o custo de embedding sobe, o risco de vazamento aumenta. Existe um ponto de virada real onde a tagarelice efêmera vira a maioria da coleção e a coisa boa para de aparecer. "Menos é melhor" não é minimalismo por estética; é higiene de retrieval.

"É só usar uma janela de contexto gigante." A objeção da moda: o modelo lê um milhão de tokens agora, então pra que recuperar? Porque contexto é budget, não HD. Enfiar tudo a cada chamada é mais lento, mais caro, menos auditável — e ainda manda seu acervo de docs privado pro modelo toda vez. Retrieval é como você se mantém preciso e local. Contexto longo complementa; não aposenta.

Posição

Uma base de conhecimento local e consultável — léxica e semântica, sua e mantida fresca — é infraestrutura mínima pra quem trabalha do lado de agentes em qualquer escala real. Não porque está na moda. Porque a alternativa é um cemitério de docs que você vai reescrever do zero e um agente planejando em cima de um contexto que ele não consegue alcançar.

A ferramenta que eu uso hoje é substituível. A disciplina não é: assuma ela, mantenha fresca, indexe sinal e não ruído, e trate como ponteiro, não como evangelho. Funciona não é critério. Sobrevive é critério.

Aqui você lê o porquê. O como — montar isso em cima do SEU corpo de docs, com as separações de domínio, a freshness e o perímetro de contribuição que o seu caso exige — é onde fica específico pra você. Precisa de mão, não de mapa? Mentoria na Carevia.