XERJ: um buscador local para agentes de código que entrega os próprios números

É raro encontrar um projeto cuja característica mais interessante seja a própria confissão.

XERJ é um motor de busca em Rust para código e documentos, feito para agentes de código, com protocolo de rede compatível com Elasticsearch e licença Apache-2.0. Tem uma tabela de benchmarks com valores reais em dólares. Tem também uma nota do mantenedor admitindo que o número de estrelas no GitHub está inflado cerca de treze vezes por uma coorte sintética, e pedindo que ninguém cite esse número.

As duas coisas valem seu tempo, e estão relacionadas.

O problema que ele ataca

Quando um agente de código precisa entender uma base de código, o movimento padrão é grep. O grep é honesto: encontra linhas que casam com um padrão. Mas um agente usando grep precisa ler arquivos para saber se o casamento importa, e ler arquivos é justamente o que enche uma janela de contexto. Um único arquivo grande pode consumir mais tokens do que a resposta valia.

A alternativa do XERJ é um índice local. Aponte para uma pasta e o autoindex fareja tipos de arquivo, infere datasets, descarta lixo e constrói um índice separado por dataset. O log de uma execução real no repositório diz assim: 593 datasets inferidos, 1.955 arquivos lixo ou ignorados na fase A, depois a fase B indexando 25.329 arquivos com oito workers, terminando em 158,1 segundos com 83.103 registros ativos.

O código é parseado com tree-sitter, mantendo símbolos e números de linha em vez de achatar tudo em texto. É por isso que xerj def <symbol> consegue devolver um arquivo, uma linha e uma assinatura: um salto para a definição em todo o repositório, que era o que o agente precisava desde o começo.

O benchmark, lido com cuidado

O projeto rodou oito tarefas em quatro linguagens, dezesseis execuções por braço, e mediu o consumo real de tokens do claude -p em vez de estimar. Três configurações: só memória, guiada por grep e XERJ.

Só memória usou 260.916 tokens de saída, custou US$ 11,18 e resolveu 11 de 16. O grep usou 26.477 tokens, custou US$ 3,27 e resolveu as 16. O XERJ usou 9.982 tokens, custou US$ 1,58 e também resolveu as 16.

Ou seja: cerca de 2,7 vezes menos tokens de saída que o grep, 26 vezes menos que depender da memória do modelo, sem mudança na taxa de acerto. O melhor caso isolado — uma tarefa Java — economizou 278 vezes. Usuários relatam cerca de 5x de ponta a ponta.

Agora a ressalva que faz este artigo valer a pena. A manchete do repositório afirma “40x menos tokens que o grep”. O experimento controlado no corpo diz 2,7x. Não são a mesma afirmação, e a distância entre elas é exatamente o padrão que torna o marketing baseado em benchmark pouco confiável. Em crédito do projeto, o próprio README diz para preferir o número do corpo. Uma manchete que exagera e uma nota de rodapé que corrige é um jeito estranho de entregar, mas pelo menos a correção está lá.

A restrição que ninguém menciona nos posts de lançamento

Aqui está a frase que quase todo projeto de “busca para agentes” omite: o benefício depende de o modelo já conhecer o código.

Em código privado, interno, de nicho ou posterior ao corte de treino, a recuperação economiza muito, porque o modelo realmente não consegue adivinhar. Em bibliotecas open source populares que o modelo já viu dez mil vezes, o índice é neutro ou ativamente prejudicial: você gasta tokens recuperando o que o modelo já sabia.

Essa única restrição muda como você deve implantar isso. Não é um upgrade universal. É um remédio para um modo de falha específico: agentes trabalhando em código sobre o qual ninguém escreveu um post.

A flag --insecure é uma fronteira de confiança de verdade

Rodar xerj --insecure desliga TLS e a autenticação da API. Qualquer um que alcance a porta é efetivamente superusuário: ler, escrever, apagar todos os índices, incluindo tudo sob /_memory. Isso é aceitável no notebook de um desenvolvedor e catastrófico em qualquer coisa compartilhada.

Os padrões são melhores que a flag. Um nó novo se liga a 127.0.0.1, e um bind em texto claro para um endereço que não seja loopback se recusa a iniciar a menos que você defina explicitamente server.allow_insecure_network_bind = true. O projeto também registra que rodar inseguro em 0.0.0.0 foi uma vulnerabilidade real — clientes da LAN podiam escrever sem autorização — e que já foi corrigida. Dar nome à própria vulnerabilidade passada é um bom hábito.

A divulgação que deveria ser modelo

Em um commit de instrumentação, o mantenedor escreveu que as estrelas e forks do repositório foram amplificados cerca de treze vezes por uma coorte sintética, que os dados reais de instalação são escassos — cerca de 145 downloads de assets de release e por volta de 28 instalações concluídas — e que o Cloudflare RUM parou de registrar em julho, então o gráfico de tráfego zero no site é um artefato.

Para um projeto com promessa de compatibilidade com Elasticsearch e 1.371 testes de conformidade passando (zero falhas, três pulados), isso é algo notável de publicar. Também diz algo sobre o estado atual dos sinais de open source: número de estrelas é uma superfície de marketing, e qualquer um que rode um loop de crescimento consegue movê-lo. Os únicos números em que vale confiar são os que um autor oferece contra o próprio interesse.

Outras coisas que você vai encontrar

A instalação é um curl canalizado para o shell, que verifica SHA256 e se recusa a prosseguir se não encontrar uma ferramenta de checksum — uma proteção incomumente sensata para esse padrão. As builds são musl estático com jemalloc, Linux primeiro, Windows por instalação manual. Há um servidor MCP expondo treze ferramentas, incluindo xerj_plan e xerj_map, e o xerj init conecta Claude Code ou Cursor com um comando. kNN com quantização scalar8 é suportado. O deploy multinó vem com um chart Helm e um arquivo compose.

A versão é 1.0.0-rc.x, e a CLI ainda se move. O CLA é adaptado do da Apache, com uma nota do mantenedor de que nenhum advogado revisou e restam dois campos de preenchimento. Muitos commits são escritos por agentes de código e marcados como tal, o que é transparente e também um motivo para ler o código do qual você depende.

Programar por referência, o caso de uso que ninguém mede

Enterrada no README está a aplicação mais interessante: apontar o índice para o projeto open source mais próximo do problema que você está resolvendo e então escrever sua própria versão com a referência no contexto.

É assim que muita engenharia real acontece — achar a biblioteca que já resolveu, ler, e então implementar algo mais estreito. Fazer mal significa colar meio repositório num prompt. Fazer bem significa poder perguntar “onde este projeto trata backpressure” e receber um arquivo, uma linha e uma assinatura de função.

Isso também mostra os limites do benchmark acima. Programar por referência exige baixar e indexar o repositório de outra pessoa, o que custa tempo, disco e rede. A economia chega na segunda e na terceira consulta, não na primeira. Quem for avaliar deve medir a sessão inteira, não uma tarefa.

A promessa de compatibilidade com Elasticsearch

O XERJ fala o protocolo de rede do Elasticsearch, e o projeto reporta 1.371 testes de conformidade passando, zero falhas e três pulados. Se isso se sustenta, ferramentas já escritas para Elasticsearch podem apontar para ele com mudanças mínimas, e times que vêm pagando um cluster para guardar alguns milhões de documentos têm uma saída.

A crítica à licença SSPL do Elasticsearch é justa: SSPL não é open source no sentido da OSI, e isso importa para empresas que querem lançar um produto em cima de um motor de busca. Mas “compatível” é um espectro. Cobertura do Query DSL, agregações e comportamento dos analisadores são onde as diferenças aparecem, e a suíte de conformidade é o único jeito de saber de que lado da linha você está.

Você deveria usar?

Se seus agentes trabalham em código interno, repositórios privados grandes, ou logs e documentos que nenhum modelo viu, o caso é razoável: um índice local, Apache-2.0, compatível com ES, com consciência de símbolos via tree-sitter e um benchmark honesto. Se seu trabalho é majoritariamente em bibliotecas públicas, você provavelmente vai achar o grep e uma boa configuração de ripgrep igualmente eficazes e com muito menos para manter.

E se você levar uma coisa só deste projeto, leve o hábito da divulgação em vez do motor de busca. Uma ferramenta que diz que os próprios números estão inflados merece mais atenção do que uma que diz ser quarenta vezes melhor.