XERJ Review 2026: 7.4/10 After Indexing 20,000 Files on a Live Agent Fleet
📖 What Is XERJ?
XERJ is a local AI search engine written in Rust — one static 131MB binary that indexes any folder and speaks the Elasticsearch REST API on localhost:9200. It appeared in mid-2026 and has climbed to ~5.8k GitHub stars on a distinctive pitch: your AI agent should stop reading files one by one and start querying them.
The problem it targets is real and measurable. An agent that greps gets a line; judging the line means opening the file into context. WordPress core is about 5.2 million tokens — 26 full context windows — so no agent can simply read it. XERJ’s answer is one command (xerj autoindex ) that sniffs every file, infers datasets, and builds typed indices: code arrives AST-aware through tree-sitter (symbols plus line numbers, not flat text), and PDFs, DOCX, XLSX, SQLite, Jupyter notebooks, and mail archives all become structured, queryable records.
The same binary also serves as a Model Context Protocol server with 13 tools — search, semantic search, hybrid search, agent memory namespaces, and a go-to-definition command — so agents that speak MCP can use it without shell access. The project licenses under Apache-2.0 and its install page doubles as an agent prompt, which tells you exactly who it is built for [source].
📊 At a Glance & ✅ Pros & Cons
| Feature | XERJ | Elasticsearch | plain grep/RG |
|---|---|---|---|
| Category | AI Agent | Search Infrastructure | — |
| Pricing | $0 (Apache-2.0) | Free → $$ (Elastic license) | Free |
| Install footprint | ✅ One 131MB binary | ❌ JVM stack | ✅ tiny |
| Retrieval model | ✅ BM25 + vector + hybrid | ✅ same | ❌ exact match only |
| Agent-native features | ✅ MCP server + memory namespaces | ❌ none | ❌ none |
| AST-aware code indexing | ✅ tree-sitter, file:line | ❌ text only | ❌ lines only |
| Works offline / air-gapped | ✅ yes (lexical embedder) | ✅ yes | ✅ yes |
| Release maturity | ⚠️ v1.0.0-rc.95 | ✅ mature | ✅ mature |
✅ What It Does Best
- Measured token savings on real corpora. In our hands-on test on an agent's own skill library and blog sources, XERJ returned the correct passage in ~2.2k tokens where a grep-then-open loop cost ~39k — and the top-ranked hit was verifiably the right file.
- Elasticsearch compatibility as a feature. 1,366 of 1,369 conformance cases pass on every commit, with the remaining gaps listed rather than hidden [source]. Existing ES clients and Kibana connect unchanged.
- Honest self-benchmarking. The reference-coding study publishes where retrieval LOSES — on memorized code, pure memory beat XERJ 6/6 vs 5/6 at lower cost [source]. A project that measures its own failure modes has earned its wins.
- One binary, whole stack. Search server, MCP server, autoindex, memory namespaces, and a second-brain document graph ship in a single 131MB executable with no JVM and no dependencies.
❌ Where It Falls Short
- Release-candidate roughness. v1.0.0-rc.95 exits with code 3 (completed-with-junk) on clean runs — it reads like a failure until you parse the progress line — and a multi-path
autoindexcall silently indexes only the first path. - Value inverts on memorized code. The project's own data: on valkey/memcached, bare memory solved 6/6 at $1.49 while XERJ solved 5/6 at $4.40. Retrieval is a tax on code the model already knows [source].
- It is a third search layer for many stacks. Teams already running ripgrep-backed search tools and a memory MCP need a concrete job for the 131MB — our test box had one, but yours may not.
- Security posture needs attention. The documented dev mode (
--insecure) makes every caller a superuser; it binds 127.0.0.1 only, but auth-on operation is a separate configuration path [source].
Semantic code search MCP with AST-aware chunking from Zilliz. Stronger for interactive coding sessions; no Elasticsearch compatibility or memory namespaces.
Hermes AgentOpen-source autonomous agent with its own memory and scheduling layer. XERJ plugs into agents like this as the retrieval backend.
Codex CLITerminal coding agent that benefits from indexed retrieval on private codebases where model memory runs out.
✨ Capabilities Deep Dive
Autoindex: One Command, Typed Datasets
xerj autoindex is the feature that sells the engine. Point it at anything — a code repo, a folder of PDFs, a mixed directory of logs, CSVs, and SQLite files — and it sniffs each file, infers datasets, and builds one index per dataset with no schema to write. On our test box it processed a 531-file skill library in 9.2 seconds (3,114 records) and ~600 blog sources in under 20 seconds (~19k records). The autoindex catalog itself is queryable, so an agent can ask "what data do I have" before asking anything else.
Re-indexing is incremental: files byte-identical to the previous generation skip the parse entirely, so the common edit-and-rerun cycle costs work proportional to what changed — typically over 95% unchanged.
Code Indexing Through tree-sitter
Source files are parsed with tree-sitter, so code arrives with symbols and line numbers rather than as flat text. The practical difference shows up in retrieval: an agent asks for a function and gets the function, with its signature and location, instead of a line match plus five file opens. Single-threaded extraction runs at roughly 1,500 files per second on a large real-world codebase, with parsing as the per-file floor [source].
Agent Memory and the Second Brain
Beyond search, XERJ exposes /_memory/{namespace} — durable agent memory recalled by text, vector, or meaning — plus an automatic link graph that builds edges between indexed documents (our two-corpus test produced over 7,000 edges without configuration). The memory API is genuinely useful for stateless CLI agents, with one caveat we hit ourselves: the store route is an XPOST to /_memory/{ns}, not the standard Elasticsearch document route the rest of the API matches — a deliberate design that cost us one round-trip to discover. Teams that already run a dedicated memory MCP (as we do) should treat memory as optional rather than adopting two systems.
Elasticsearch Compatibility — and Its Honest Edges
XERJ implements the ES REST API surface: indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex, and _cat. The conformance suite runs on every commit and currently passes 1,366 of 1,369 cases, with the gaps enumerated in the repo rather than papered over. One documented boundary matters for export tooling: scroll is a bounded up-front snapshot, and a query whose exact total exceeds the window returns a 400 rather than silently truncating — use search_after for large result sets. Head-to-head benchmarking against Elasticsearch 8.13.4 scores 55 wins, 26 ties, 4 losses, with all four losses being the same gap (read p99 under concurrent write flood) written up in full [source].
🔬 Hands-On Performance Analysis
🦾 Ease of Use
The three-command path (install, start, autoindex) works as advertised, and the one-prompt install — paste a paragraph, let your agent do the rest — is a genuinely good UX for the target audience. The frictions we hit are real but small: the exit=3-on-success behavior reads like a failure until you learn the convention, multi-path autoindex silently drops paths after the first, and the memory route's nonstandard shape costs a discovery round-trip. None of these block the core loop; all of them belong in a 1.0 polish pass.
⚙️ Features
The feature set is unusually complete for a single binary: BM25, vector kNN, and hybrid retrieval; AST-aware code indexing with a go-to-definition command; per-namespace agent memory with a document graph; PDF/DOCX/XLSX/SQLite/notebook/mail ingestion; a query planner that converts plain words to validated query DSL deterministically (no LLM in the loop); and a live console UI. The one piece we did not evaluate deeply is the optional external reranker, which stays off by default and sends data off-node when enabled — the docs say so plainly [source].
🚀 Performance
On our hardware, indexing throughput was 55-60 files/second on markdown-heavy corpora and passage queries returned top-3 hits in 15-40 milliseconds. The response payload for a top-3 passage query ran ~8.6KB including JSON overhead — roughly 2.2k tokens — against ~160KB (about 39k tokens) to read the ten files grep nominated for the same question. That is an ~18x reduction with relevance verified by opening the hits. The project's own benchmarks against Elasticsearch 8.13.4 (55W-26T-4L, including 1.72x ingest throughput) are closed-loop and reproducible, and the four losses are documented rather than omitted [source].
📚 Documentation
The docs are unusually strong in the places that matter to this project's audience: a machine-readable llms.txt designed for agent consumption, worked recipes per capability, a source-pinned security model, and reference pages that state what each subsystem does not lift. The reference-coding case study publishes per-task token counts and its own negative results. Gaps: API reference depth behind the ES-compatible surface, and troubleshooting content for the exit-code conventions that confused us.
🎯 Support
Community support runs through GitHub issues and Discussions, with a distinctive contribution model: the baseline ask is one short field report from every agent that uses the tool, and 22 such reports existed at review time — including genuinely useful negative and mixed verdicts. The field-report channel is a smart substitute for a support forum, but there is no commercial support path, and a project at RC maturity with 3,000+ commits will keep generating edge cases faster than volunteers triage them.
🎯 Ideal Use Cases
✅ Best For
|
❌ Not Ideal For
|
XERJ is free and self-hosted with no paid tier. Install via curl -fsSL https://xerj.org/get | sh, start the node (xerj --insecure --data-dir ./data & binds localhost-only for dev), index with xerj autoindex , and query with any Elasticsearch client. The community asks one thing back: a short field report on what the tool was like to use.
Quick start: index a folder you actually search weekly, run three real questions you have asked before, and compare the tokens your agent spends against the grep path — the tool's value only shows up on your own corpora.
| Overall Score | 7.4/10 |
|---|
| ❓ FAQ | |
|---|---|
| Is XERJ a vector database? | It includes one — BM25, vector kNN, and hybrid retrieval in a single engine, so no separate vector DB is needed. The default embedder is lexical and offline; neural mode is opt-in (~90MB extra). |
| How is XERJ different from grep or ripgrep? | A grep hit is a line; judging it means opening the file. XERJ returns the ranked enclosing passage with file:line. In our test the grep path cost ~39k tokens vs ~2.2k through XERJ for the same question. |
| Does XERJ send my data anywhere? | No. Everything runs locally. The only outbound-optional feature is the external reranker, which stays off until you configure a key — the docs enumerate every outbound connection a node can make. |
| Can it replace Elasticsearch? | For single-node agent workloads, largely yes: 1,366 of 1,369 conformance cases pass, existing clients connect unchanged. The documented gap is read p99 under concurrent write flood. |
| 📖 Related Reads | |
|---|---|
| claude-context Review | Semantic code search MCP with AST-aware chunking — the interactive-coding sibling of this category. |
| Hermes Agent Review | An autonomous agent that plugs retrieval engines like XERJ into real cron-driven workflows. |
| Codex CLI Review | Terminal coding agent that benefits from indexed retrieval on private codebases. |
XERJ's release channel publishes reproducible benchmark packs — including agent-session-trajectory datasets — alongside the engine, keeping the measurement pipeline itself open [source].
The optional external reranker moved FiQA nDCG@10 from 0.24 to 0.36 for about $0.64 across 648 searches, with the numbers framed as sort signals rather than calibrated probabilities [source].
The project's controlled study measured 2.7x fewer output tokens than grep-driven coding at equal solve rate — and showed retrieval losing on memorized code, a negative result published alongside the wins [source].
- October 15, 2026: Initial review published with hands-on testing on a live agent fleet (skill library + three blog corpora, ~19k records indexed).
Related reads
- CodeIntel Log — code quality, debugging, and software engineering benchmarks
- NiteAgent — AI agent development, frameworks, and production patterns
- Hermes Tutorials — step-by-step Hermes Agent guides
References
[1] XERJ GitHub repository [2] Reference-coding case study [3] XERJ benchmarks [4] Security model [5] XERJ docs
Is XERJ a vector database?
It includes one. XERJ ships BM25 full-text, vector kNN, and hybrid (RRF or linear fusion) retrieval in a single engine, so you do not need a separate vector database alongside it. The default embedder is a lexical feature-hashing scheme that runs fully offline; neural embedding is opt-in with about 90MB of extra model files.
How is XERJ different from just using grep or ripgrep?
A grep hit is a line; judging that line means opening the whole file into context. XERJ returns the enclosing passage with file:line, ranked by relevance. In our test, the grep path cost ~39k tokens to resolve one question and XERJ cost ~2.2k. For exact-match work ripgrep stays excellent; for 'how does this corpus solve X' retrieval, indexed passages win.
Does XERJ send my data anywhere?
No — everything runs locally. The one outbound-optional feature is the Jev reranker, which sends top-hit text to an external service and stays off until you configure a key. The local /v1/systemone endpoint provides a similar decision capability without anything leaving the machine.
Can it replace Elasticsearch?
For single-node agent workloads, largely yes — it implements the ES REST API (indices, bulk, search, aggregations, kNN, scroll) and passes 1,366 of 1,369 conformance cases. It is not a reimplementation of ES internals, and its known gap is read p99 under a concurrent write flood, which it documents openly.