XERJ: a local, Elasticsearch-compatible index for agents that would otherwise grep your code
XERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.
At a glance
- What is it?
- XERJ is an Apache-2.0 Rust binary that indexes any folder with one command and answers queries over BM25, kNN or a hybrid of both. Its pitch is token savings for coding agents; its strongest constraint is that the value depends on how much the model already knows the code.
- Who is it for?
- Adopt XERJ if your agents work on private, internal, niche or post-cutoff code and you want a single static binary with no JVM and no schema to write. Do not adopt it if your workload is mostly popular public libraries the model already memorised, since the README states the gain is neutral to harmful there.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem XERJ attacks: agents reading files to find files
The README frames the problem in token terms. An agent that greps pulls whole files into its context and still has to read them; the project states this reached up to 1.06M input tokens on one corpus in its measurements. XERJ's answer is to make the corpus queryable first, so the agent asks for a passage instead of dragging a file in.
The audience is narrow and specific. It is not a general search product for end users. It is for people running coding agents on repositories that are private, internal, niche, or written after the model's training cutoff. The README is unusually direct about this boundary: the value is gated by memorisation, and the approach is neutral to harmful on popular public libraries the model already knows. That single sentence disqualifies a large share of casual use cases, and it is the most honest thing in the repository.
The second audience is anyone who wants search, RAG, security audits or agent memory over mixed files without writing a schema or configuring a pipeline. The README lists code, docs, logs, PDFs, SQLite and awkward CSVs as inputs to the same primitive.
How autoindex turns a folder into typed indices
The mechanism is described as sniffing. XERJ inspects every file, works out what it is, and creates one index per dataset it finds. There is no schema file to write and no pipeline to configure, which is the whole point of calling it autoindex rather than ingest.
Querying sits on three modes the README names explicitly: BM25, kNN, and hybrid. The default embedder is lexical and offline. A neural embedder is opt-in and the README notes it downloads roughly 90 MB, so the zero-config path does not pull a model by default. That is a deliberate trade-off: lexical search over code identifiers is often enough for exact symbol and phrase lookups, while semantic retrieval costs a download and presumably more CPU.
The compatibility claim is the other architectural decision. XERJ presents an Elasticsearch-compatible API, so existing clients are expected to work unchanged. The README cites an ES-YAML conformance figure of 1366/1369. That number is a claim from the project's own benchmark page, not an independent certification, and the three missing cases are not enumerated in the README. Treat the gap as the first thing to probe if you plan to point an existing client at it.
Deployment shape matters here too. The README advertises a single static binary with no JVM, which is a direct contrast to running an Elasticsearch cluster. That is the real comparison an engineer should make, not feature lists.
Installing XERJ and running a first query
The README gives a one-line installer and a short sequence. The install script is fetched over HTTPS and piped to a shell, which is the usual pattern for this kind of tool and carries the usual risk: you are executing a remote script. The README does not document a checksum or signature verification step for that path, so if that matters to you, use the hand-verified install the README points to instead.
curl -fsSL https://xerj.org/get | shAfter installing, the README starts the server in the background with an explicit data directory. Note the --insecure flag in the project's own example; the README does not explain what it disables, so read the install documentation before exposing the port beyond localhost.
xerj --insecure --data-dir ./data &The next command wires the engine into an editor. The README says xerj init configures Claude Code or Cursor over MCP plus a skill in one command.
xerj initThen point it at a folder. This is the primitive everything else builds on.
xerj autoindex ~/my-projectQuery it. The README's own example searches for a phrase and returns ranked passages with file and line positions.
xerj search "how do we rotate the WAL segment"There is also a definition lookup that returns a file:line plus a signature, and a gain command the README describes as counting rather than estimating what the tool did for you.
xerj def "euler_to_rotationmatrix"
xerj gainThe README also offers a one-prompt install for agents, which hands the whole setup to the model using https://xerj.org/llms.txt as the documentation entry point.
The token numbers, and why they are not a general claim
The README's central table compares three arms on eight tasks across four languages, sixteen runs per arm, using real claude -p token counts. From memory only: 260,916 output tokens, $11.18, 11/16 solved. A grep-driven agent: 26,477 tokens, $3.27, 16/16. XERJ: 9,982 tokens, $1.58, 16/16.
Read that carefully. The headline 2.7x is XERJ against grep, not against memory. Against memory alone the gap is 26x, but memory also failed five of sixteen runs, so it is not a like-for-like comparison of a working method. The README also mentions up to 278x fewer tokens on a single Java task, which is a single-task figure and should be read as such. Field reports from users are described as roughly 5x end to end, and those are self-reported, not controlled.
The stated condition is memorisation. The corpus in the study was code the model had not memorised. On a well-known open source library, the model does not need to retrieve anything, and the README concedes the approach is neutral to harmful. So the correct question is not whether XERJ saves tokens, but whether your code is the kind the model has already seen. Internal services, post-cutoff dependencies and proprietary schemas are where the claim applies.
Where XERJ is the wrong tool
The memorisation boundary is the first and largest limitation, and it is the project's own. If your agents mostly touch React, Django or other widely represented code, you are paying indexing and query cost for retrieval the model did not need.
There are operational constraints as well. The README's own startup example uses --insecure, and the README does not explain the security model behind that flag. Until you have read the install and deployment documentation, you should not treat the default example as production guidance. The neural embedder is opt-in and downloads roughly 90 MB, so any air-gapped environment is on the lexical path unless you mirror that download.
The compatibility claim is a claim. 1366/1369 ES-YAML conformance means three cases do not pass, and the README does not say which. If your client depends on a specific Elasticsearch behaviour, verify it rather than assuming the API is a drop-in replacement.
Finally, the feedback model is unusual and worth weighing. The README describes joining the community by sending one short field report as a commit or PR, with field-report PRs exempt from the CLA. That is a real obligation attached to using a free binary, and it is not how most Apache-2.0 projects operate. If your organisation cannot contribute back a report, read the CONTRIBUTING and CLA files before you build a dependency on it.
XERJ compared with running Elasticsearch itself
The obvious alternative is Elasticsearch, since XERJ implements its API. The difference in approach is operational, not conceptual. Elasticsearch is a distributed system: a JVM, a cluster, shards, replicas, and a separate schema and mapping step before data is queryable. XERJ is a single static binary with no JVM that sniffs files and creates indices on its own.
That means XERJ trades cluster-scale horizontal scaling and the mature Elasticsearch ecosystem for a local, low-ceremony process. If you need multi-node replication, cross-cluster search or the full aggregations surface, the compatibility layer is not the same product, and three failing conformance cases are a reminder of that. If you need one machine to answer questions about a folder, the Elasticsearch path asks you to stand up and operate far more than the task requires.
The other alternative is doing nothing: let the agent keep grepping. That is a legitimate choice, and the README's own table shows grep solved 16/16, just at 26,477 output tokens against 9,982. The decision is whether the token and cost difference justifies an extra service in your stack. For a small repository queried occasionally, it probably does not.
Licence, maintenance and upgrade cost
XERJ is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notices. The repository carries both a LICENSE and a NOTICE file, and Apache-2.0 obligations around NOTICE are where teams most often slip. That is a description of the licence terms, not legal advice; check with your own counsel if you are redistributing a modified binary.
The maintenance signal is strong on activity. The last push was on 2026-09-15, and the repository is not archived. Recent releases are numbered v1.0.0-rc.74, v1.0.0-rc.73 and v1.0.0-rc.72, published on 2026-09-08, 2026-09-08 and 2026-08-31 respectively. Note the rc in every one of those tags: this is release-candidate software, not a 1.0.0 final. The README also notes that xerj feedback may not exist on every build and tells you to check xerj --help, which is a sign that binaries differ across versions.
The upgrade cost follows from that. A fast release cadence on release candidates means you should pin a version and read CHANGELOG.md before moving, rather than tracking latest. The CLA.md and CONTRIBUTING.md files matter if you intend to send the field report the project asks for, since the README states field-report PRs are CLA-exempt while other contributions presumably are not.
Editorial conclusion
Adopt XERJ if your agents work on private, internal, niche or post-cutoff code and you want a single static binary with no JVM and no schema to write. Do not adopt it if your workload is mostly popular public libraries the model already memorised, since the README states the gain is neutral to harmful there. Before rolling it out, verify two things yourself: that your Elasticsearch client actually passes the ES-YAML conformance suite the project publishes, and that the token accounting from xerj gain matches your own billing for one real task.
Frequently asked questions
How do I install XERJ?
The README gives a one-line installer, curl -fsSL https://xerj.org/get | sh, and points to a hand-verified install section for Windows and for anyone who prefers not to pipe a remote script into a shell. After installing, the README starts the server with xerj --insecure --data-dir ./data & and wires it into an editor with xerj init.
Does XERJ work with existing Elasticsearch clients?
The README states that XERJ is Elasticsearch compatible so existing clients just work, and cites an ES-YAML conformance figure of 1366/1369. The README does not list which cases fail, so verify your specific client behaviour before relying on it.
What is XERJ's main use case?
The README calls reference coding the main use case: point an agent at a task, have it clone and index the open-source repositories closest to the task, and reuse how they solved the problem before writing code. The same autoindex primitive covers search, RAG, security audits and agent memory over code, docs, logs, PDFs, SQLite and CSVs.
When does XERJ not save tokens?
The README states the value is gated by memorisation: XERJ wins on private, internal, niche or post-cutoff code, and is neutral to harmful on popular public libraries the model already knows. If your agents mostly work on widely represented open source code, the retrieval may add cost without reducing tokens.
Community notes