Como estruturar um cofre em Markdown para o agente gastar menos tokens, e por que o motivo mais citado está errado

Um agente capaz nunca carrega o índice. Essa é a descoberta que reorganiza todo o resto.

Um estudo preregistrado publicado em julho de 2026 testou a intuição da divulgação progressiva sobre uma base real de 709 páginas em Markdown, com as páginas interligadas em grafo navegável e mantidas por um LLM. O desenho é limpo: quatro versões do acervo, corpos das páginas byte a byte idênticos entre elas, verificado por um portão de paridade antes da análise. A única coisa que varia é como o agente chega ao conteúdo. Foram 960 execuções.

O piloto derrubou a premissa. Diante de uma pergunta, o modelo infere o caminho provável da página e lê aquele arquivo direto, sem passar pelo índice de 150 KB que a reestruturação foi construída para eliminar. A economia nominal de 99% naquele passo simplesmente não acontece.

Mesmo assim o custo caiu em todos os regimes de acesso. Só que por outro motivo.

Passo 1: escreva um campo summary de uma linha em toda página

É a mudança de maior retorno depois da ferramenta de busca, e a única do trio testado que começou a pagar sozinha.

No frontmatter YAML de cada nota, inclua um campo de resumo em uma linha. Ele não descreve o assunto de forma genérica, ele responde "vale abrir este arquivo para esta pergunta". Resumo do tipo "notas sobre contratos" não roteia nada.

Na ablação do estudo, o custo médio por resposta caiu de US$ 0,711 para US$ 0,599 no regime restrito e de US$ 0,764 para US$ 0,686 no regime livre apenas com a adição dos resumos por página.

Passo 2: não perca tempo movendo estado volátil para fora do índice

Esta é a etapa que a intuição sugere primeiro e que os dados desaconselham.

Tirar do índice a seção de "atividade recente" e jogá-la em um arquivo separado, deixando o índice mais magro, não reduziu custo. Subiu um pouco: de US$ 0,711 para US$ 0,765 no regime restrito, e de US$ 0,764 para US$ 0,807 no livre.

Faz sentido depois de entender o mecanismo. Um índice mais leve só ajuda quem precisa carregá-lo, e o agente capaz não carrega.

Passo 3: use os cabeçalhos como fronteira de fragmento

O Markdown impõe hierarquia semântica pelos níveis #, ## e ###, e isso vale como regra de corte para qualquer sistema de recuperação que você acople depois.

O ganho aqui é de formato, não de arquitetura. Comparações de serialização em bases tabulares mostram que HTML consome quase três vezes mais tokens que os formatos leves para a mesma informação, e que CSV e Markdown ficam na ponta econômica. Um teste com tiktoken sobre um arquivo real deu 13.869 tokens em JSON contra 11.612 em Markdown, cerca de 16% de diferença.

Escreva cada bloco sob um ### de modo que ele faça sentido isolado. Se o parágrafo depende de "conforme visto acima", o fragmento recuperado chega mutilado ao modelo.

Passo 4: dê ao agente uma ferramenta de busca que devolve gists

Este é o item que mais economiza, em todos os regimes testados.

Não é busca vetorial. No estudo, a ferramenta é um script de recuperação por palavra-chave que devolve páginas ranqueadas em formato de gist: título, resumo, e opcionalmente o parágrafo de abertura e os links vizinhos, mais um manifesto. Simples o bastante para você escrever em uma tarde.

O efeito no custo médio por resposta, contra a base sem reestruturação: queda de 30% no regime restrito, 34% no livre e 58% no regime de pré-carga de catálogo. Todos os intervalos de confiança excluem zero.

Passo 5: deixe o agente se rotear, não empurre o catálogo

Aqui está a inversão prática mais útil do estudo.

O regime que concatena o catálogo inteiro no prompt é o que mais economiza com a reestruturação, 58%, porque é o único em que a base realmente paga o custo do índice. Mas é também o único em que a qualidade não se sustentou: a não inferioridade não foi estabelecida ali, com o ponto estimado favorecendo a versão original.

Os regimes de auto-roteamento, em que o agente escolhe o que abrir, entregam economia de cerca de um terço com qualidade não inferior ou melhor. É a troca favorável.

Traduzindo para a sua configuração: dê ferramenta de leitura e busca ao agente e deixe ele decidir. Não monte um pipeline que injeta o mapa de conteúdos inteiro a cada pergunta.

Passo 6: meça acesso, não tamanho de arquivo

Se o mecanismo da economia é acesso mais direcionado, é acesso que você precisa instrumentar.

Duas métricas comportamentais capturaram o efeito: páginas citadas por resposta, que caiu de 6,10 para 4,22, e turnos de ferramenta por resposta, de 4,98 para 4,45. Ambas caem junto com o custo.

Do lado do custo, registre a carga de tokens novos (entrada não cacheada mais criação de cache mais saída, excluindo leitura de cache) além do valor em dólar. O motivo é prático: cache frio contra cache quente pode fazer o mesmo trabalho variar cerca de 12,5 vezes em dólar. Sem essa separação você vai medir o estado do cache achando que está medindo a sua arquitetura.

Passo 7: aceite onde o padrão cobra

A qualidade geral ficou plana, mas o perfil mudou.

Validade de citação melhorou e o excesso de enrolação diminuiu, o que era o objetivo do desenho. Correção e completude caíram um pouco. Isolando as duas dimensões que tiveram concordância confiável entre juiz e revisor humano, o déficit é pequeno mas estatisticamente detectável.

A perda se concentra em um lugar específico: perguntas de agregação, que exigem varredura ampla. Nesse estrato a base original saiu na frente. Faz sentido, porque um conjunto de evidências mais estreito custa completude quando a pergunta precisa de cobertura.

Se o seu uso é majoritariamente "levante tudo que existe sobre X", pense duas vezes. Se é "responda esta pergunta específica", a troca é boa.

Passo 8: trate links bidirecionais como navegação, não como economia

Os links [[nota]] do seu grafo ajudam o agente a se mover e ajudam você a manter o acervo coerente. Só não atribua a eles a economia medida.

O que foi testado e produziu o resultado foi recuperação ranqueada por palavra-chave devolvendo gists, com links vizinhos como campo opcional do retorno. Percorrer o grafo para extrair triplas de conhecimento é uma hipótese diferente, e não foi o que o estudo mediu.

Os números que circulam

Três afirmações comuns sobre essa arquitetura merecem correção.

A economia de "cerca de 60%" existe, mas só no regime de pré-carga de catálogo, que é justamente o regime que você não deveria usar. Sob auto-roteamento, que é o cenário realista, o número medido foi de 30% a 34%.

A ideia de que a arquitetura "praticamente elimina alucinações" não tem respaldo. O resultado de qualidade foi não inferioridade, ou seja, empate dentro de uma margem definida antes do teste. Correção e completude caíram um pouco, não subiram.

E a explicação de que a economia vem de evitar a leitura do índice está errada no caso do agente capaz, que nunca lê o índice. A economia vem de acesso mais direcionado.

O que ainda não se sabe

O estudo tem limitações declaradas pelo próprio autor, e elas importam antes de você reorganizar mil arquivos.

É um corpus único, um modelo de resposta único, uma distribuição de perguntas de uma pessoa só e um único revisor humano, que é o próprio autor. Validade externa para outros acervos, modelos e usuários não está estabelecida.

O portão de confiabilidade preregistrado falhou: a concordância ponderada entre o juiz automático e o revisor humano ficou em 0,23, contra o limiar planejado de 0,60. O autor reporta isso como limitação material, não como verificação aprovada, e sustenta a conclusão de qualidade em análises de sensibilidade.

O harness registrou uso agregado de tokens, sem telemetria por leitura. Páginas citadas e turnos de ferramenta são compatíveis com a hipótese de menos leitura, mas não a provam.

Também não se sabe como o efeito escala para agentes menos capazes. A previsão do autor é que eles se beneficiem mais, justamente por não conseguirem contornar um índice monolítico, mas isso ainda não foi testado.