XERJ: un motore di ricerca locale per agenti di codice che ammette i propri numeri

È raro trovare un progetto la cui caratteristica più interessante sia la propria ammissione.

XERJ è un motore di ricerca in Rust per codice e documenti, pensato per gli agenti di coding, con un protocollo wire compatibile con Elasticsearch e licenza Apache-2.0. Ha una tabella di benchmark con cifre reali in dollari. Ha anche una nota del maintainer che ammette che il numero di stelle su GitHub è gonfiato di circa tredici volte da una coorte sintetica, e chiede di non citarlo.

Entrambe le cose meritano il tuo tempo, e sono collegate.

Il problema che affronta

Quando un agente di coding deve capire una codebase, la mossa predefinita è grep. Grep è onesto: trova le righe che corrispondono a un pattern. Ma un agente che usa grep deve leggere i file per capire se la corrispondenza conta, e leggere file è esattamente ciò che riempie una finestra di contesto. Un solo file grande può consumare più token di quanto valesse la risposta.

L’alternativa di XERJ è un indice locale. Puntalo su una cartella e autoindex annusa i tipi di file, inferisce i dataset, scarta la spazzatura e costruisce un indice separato per dataset. Il log di un’esecuzione reale nel repository dice così: 593 dataset inferiti, 1.955 file spazzatura o saltati nella fase A, poi la fase B che indicizza 25.329 file con otto worker, conclusa in 158,1 secondi con 83.103 record attivi.

Il codice viene analizzato con tree-sitter, conservando simboli e numeri di riga invece di appiattire tutto in testo. Per questo xerj def <symbol> può restituire un file, una riga e una firma: un salto alla definizione su tutto il repository, esattamente ciò di cui l’agente aveva bisogno fin dall’inizio.

Il benchmark, letto con attenzione

Il progetto ha eseguito otto task in quattro linguaggi, sedici run per braccio, e ha misurato il consumo reale di token di claude -p invece di stimarlo. Tre configurazioni: solo memoria, guidata da grep e XERJ.

Solo memoria: 260.916 token di output, 11,18 $, 11 task su 16 risolti. Grep: 26.477 token, 3,27 $, tutti e 16 risolti. XERJ: 9.982 token, 1,58 $, anche tutti e 16.

Quindi circa 2,7 volte meno token di output rispetto a grep, 26 volte meno che affidarsi alla memoria del modello, senza cambiamenti nel tasso di risoluzione. Il miglior caso singolo — un task Java — ha risparmiato 278 volte. Gli utenti riportano circa 5x end-to-end.

Ora l’avvertenza che rende questo articolo necessario. Il titolo del repository dichiara “40x meno token di grep”. L’esperimento controllato nel corpo dice 2,7x. Non sono la stessa affermazione, e lo scarto tra le due è esattamente il pattern che rende inaffidabile il marketing basato sui benchmark. A merito del progetto, il README stesso dice di preferire la cifra del corpo. Un titolo che esagera e una nota a piè di pagina che lo corregge è un modo strano di pubblicare, ma almeno la correzione c’è.

Il vincolo che nessuno cita nei post di lancio

Ecco la frase che quasi tutti i progetti di “ricerca per agenti” omettono: il beneficio dipende dal fatto che il modello conosca già il codice.

Su codice privato, interno, di nicchia o successivo al cutoff di training, il retrieval fa risparmiare molto, perché il modello davvero non può indovinare. Sulle librerie open source popolari che il modello ha visto diecimila volte, l’indice è neutro o attivamente dannoso: spendi token per recuperare ciò che il modello già sapeva.

Questo singolo vincolo cambia il modo in cui distribuirlo. Non è un upgrade universale. È un rimedio a una modalità di fallimento specifica: agenti che lavorano su codice su cui nessuno ha scritto un post.

Il flag --insecure è un vero confine di fiducia

Eseguire xerj --insecure disabilita TLS e l’autenticazione API. Chiunque raggiunga la porta è di fatto superutente: leggere, scrivere, cancellare ogni indice, compreso tutto ciò che sta sotto /_memory. Va bene sul portatile di un singolo sviluppatore, è catastrofico su qualsiasi cosa condivisa.

I default sono migliori del flag. Un nuovo nodo si lega a 127.0.0.1, e un bind in chiaro su un indirizzo non loopback si rifiuta di partire a meno che tu non imposti esplicitamente server.allow_insecure_network_bind = true. Il progetto registra anche che eseguire insecure su 0.0.0.0 è stata una vera vulnerabilità — i client in LAN potevano scrivere senza autorizzazione — e che è stata corretta. Dare un nome alla propria vulnerabilità passata è una buona abitudine.

L’ammissione che dovrebbe essere un modello

In un commit di instrumentation, il maintainer ha scritto che stelle e fork del repository sono stati amplificati di circa tredici volte da una coorte sintetica, che i dati reali di installazione sono scarsi — circa 145 download di asset di release e circa 28 installazioni completate — e che Cloudflare RUM ha smesso di registrare a luglio, quindi il grafico a traffico zero sul sito è un artefatto.

Per un progetto con una promessa di compatibilità Elasticsearch e 1.371 test di conformità superati (zero fallimenti, tre saltati), è una cosa notevole da pubblicare. Dice anche qualcosa sullo stato attuale dei segnali open source: il numero di stelle è una superficie di marketing, e chiunque faccia girare un growth loop può muoverlo. Gli unici numeri di cui fidarsi sono quelli che un autore offre contro il proprio interesse.

Altre cose che incontrerai

L’installazione è un curl piped allo shell, che verifica SHA256 e rifiuta di procedere se non trova uno strumento di checksum: una guardia insolitamente assennata per quel pattern. Le build sono musl statico con jemalloc, Linux first, Windows con installazione manuale. C’è un server MCP che espone tredici strumenti, tra cui xerj_plan e xerj_map, e xerj init collega Claude Code o Cursor con un comando. È supportato kNN con quantizzazione scalar8. Il deployment multi-nodo arriva con un chart Helm e un file compose.

La versione è 1.0.0-rc.x, e la CLI si muove ancora. Il CLA è adattato da quello di Apache, con una nota del maintainer che nessun avvocato l’ha revisionato e restano due campi segnaposto. Molti commit sono scritti da agenti di coding e etichettati come tali, il che è trasparente e anche un motivo per leggere il codice da cui dipendi.

Il coding per riferimento, il caso d’uso che nessuno benchmarka

Sepolta nel README c’è l’applicazione più interessante: punta l’indice sul progetto open source più vicino al problema che stai risolvendo, poi scrivi la tua versione con il riferimento nel contesto.

È così che si fa molta ingegneria reale: trovi la libreria che l’ha già risolto, la leggi, poi implementi qualcosa di più stretto. Farlo male significa incollare mezzo repository in un prompt. Farlo bene significa poter chiedere “dove gestisce il backpressure questo progetto” e ottenere un file, una riga e una firma di funzione.

Mostra anche i limiti del benchmark sopra. Il coding per riferimento richiede di scaricare e indicizzare il repository di qualcun altro, il che costa tempo, disco e rete. Il risparmio arriva alla seconda e terza query, non alla prima. Chi valuta dovrebbe misurare l’intera sessione, non un task.

La promessa di compatibilità con Elasticsearch

XERJ parla il protocollo wire di Elasticsearch, e il progetto riporta 1.371 test di conformità superati, zero fallimenti e tre saltati. Se regge, gli strumenti già scritti per Elasticsearch possono puntare a lui con modifiche minime, e i team che pagano un cluster per tenere qualche milione di documenti hanno una via d’uscita.

La critica alla licenza SSPL di Elasticsearch è giusta: SSPL non è open source nel senso OSI, e questo conta per le aziende che vogliono costruire un prodotto sopra un motore di ricerca. Ma “compatibile” è uno spettro. Copertura del Query DSL, aggregazioni e comportamento degli analyzer sono i punti in cui emergono le differenze, e la suite di conformità è l’unico modo per sapere da che parte della linea ti trovi.

Dovresti usarlo?

Se i tuoi agenti lavorano su codice interno, repository privati grandi, o log e documenti che nessun modello ha visto, il caso è discreto: un indice locale, Apache-2.0, compatibile ES, con consapevolezza dei simboli via tree-sitter e un benchmark onesto. Se il tuo lavoro è soprattutto su librerie pubbliche, probabilmente troverai grep e una buona configurazione di ripgrep altrettanto efficaci e molto meno da mantenere.

E se prendi una sola cosa da questo progetto, prendi l’abitudine all’ammissione invece del motore di ricerca. Uno strumento che ti dice che i suoi numeri sono gonfiati merita più attenzione di uno che ti dice che è quaranta volte meglio.