XERJ: Local AI Search Engine for AI Agents
/xerj
XERJ is a local AI search engine that lets coding agents pull exact passages instead of reading whole files token by token. In a controlled study it achieved the same solve rate as grep while using 2.7x fewer output tokens, and real users report closer to 5x in everyday work. The tradeoff is that you run a self-hosted service and handle its operations yourself. If you are paying for context-window retries on large codebases, that tradeoff is worth making.
What is XERJ?
XERJ is a self-hosted search engine that indexes code, docs, logs, and PDFs, and exposes them via the Elasticsearch REST API. It supports full-text, semantic, and vector search, handles autoindexing without schema configuration, and includes an MCP server so desktop AI assistants can call it as a tool. The primary pitch is token efficiency: agents retrieve passages rather than reading files.
The Token Waste Problem for AI Agents
WordPress core comes in at roughly 5.2M tokens, representing about 26 full context windows, which makes it impractical for an agent to simply read through. XERJ indexes the corpus ahead of time and serves the passage instead, replacing a token-hungry file read with a kilobyte query.
Core Capabilities
- โAutoindexing without schema configuration: XERJ sniffs file types and creates typed indices automatically, handling code via tree-sitter, structured formats like CSV and SQLite, and documents including PDF and DOCX
- โToken-efficient retrieval: agents query a passage instead of loading whole files, which the README measures as 2.7x fewer output tokens than grep at equivalent solve rates
- โFull Elasticsearch API compatibility: existing clients, Kibana, and official libraries connect without modification; the conformance suite passes 1366 of 1369 cases
- โMCP server built into the binary: 13 tools exposed over stdio so desktop assistants and function-calling hosts can wire XERJ in as a tool without separate compilation
- โHybrid and vector search in one query: full-text, semantic, and kNN retrieval without a separate vector database
- โSingle static binary, no JVM: linux macos and windows all have prebuilt binaries for x86 64 and arm64
Practical Applications
- โขReference coding: index similar open-source repos, retrieve how they solved a problem before writing your own code, then cite what you use
- โขCodebase Q&A: index a repo and answer questions about mechanisms with file:line citations instead of directory listings
- โขWith security audits, you can point to a target tree and search for dangerous calls, sink patterns, and secrets across all file types simultaneously.
- โขAgent memory: use the /_memory/{namespace} API to store what an agent learns and recall it by meaning in the next session
- โขMixed formats become typed indices with aggregations for log and incident analysis, treating log analysis the same way as code search
Getting Started with XERJ
Run the installer script: `curl -fsSL https://xerj.org/get | sh` Windows: `irm https://xerj.org/get.ps1 | iex` The binary lands in ~/.local/bin by default. Add it to your PATH if needed. For air-gapped deployments, follow the air-gapped deployment recipe in the docs.
Strengths
- โToken savings are measured, not estimated: the README cites a controlled study with 8 tasks, 4 languages, and 16 runs per arm using real token counts from `claude -p`
- โSingle binary with no JVM, no external dependencies, and prebuilt for the major desktop and server OSes and architectures
- โAutoindexing handles a wide range of file types without manual schema definition, including code via tree-sitter parsing for accurate symbol extraction
- โElasticsearch API compatibility means existing tooling, dashboards, and client libraries work without modification
- โBuilt-in MCP server exposes 13 tools over stdio so desktop AI assistants can use XERJ as a native tool
- โLocal reranking via the /_decide endpoint uses your own labeled examples without sending data to external servers
Important Considerations
- โณSelf-hosted only: you operate and maintain the service with no managed option or SLA, and neural embedding mode requires staging three model files locally before first use
- โณElasticsearch compatibility has gaps: 3 of 1369 conformance cases fail, and scroll has a hard result-set cap that returns a 400 error if exceeded
- โณReranking with Jev is optional but sends result text to TypeSafe's servers when enabled; it is off by default but worth knowing about before turning it on
- โณp99 read latency degrades under concurrent write flood, the only consistent loss against Elasticsearch 8.13.4 in the published benchmarks
- โณThe --insecure flag disables TLS and all auth, making every caller a superuser; it is a dev-machine flag, not a production configuration
XERJ vs. Elasticsearch
Who Benefits from XERJ?
Developers running AI coding assistants who are watching token costs add up from context-window retries and file reads. Security teams auditing codebases where an agent needs to query patterns across a large tree without loading every file. Teams replacing a self-hosted Elasticsearch cluster where the operational overhead outweighs the benefit. Skip it if your codebase is a popular public library that your model already has in context; the token savings are gated by memorization.
Frequently Asked Questions
XERJ is Apache-2.0 licensed with no usage restrictions or CLA required for normal use. The field-report contribution process is CLA-exempt.
XERJ indexes codebases into passages. Instead of loading whole files into context, an agent queries the index and receives the exact passage it needs. The README cites 2.7x fewer output tokens than grep in a controlled study, with real users reporting closer to 5x savings in practice.
Reference coding means indexing similar open-source projects, then retrieving how they solved a problem before writing your own code. The agent cites what it uses. The README reports a 16/16 solve rate in testing with this approach.
Yes. XERJ implements the Elasticsearch REST API including indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex, and _cat endpoints. The README says 1366 of 1369 conformance cases pass.
Only if you enable Jev reranking. That setting sends top results to TypeSafe's servers for scoring. XERJ has a local decision mode that uses your own labeled examples without any external data transfer.
XERJ autoindexes code via tree-sitter, structured formats like CSV, JSON, JSONL, XML, YAML, and SQLite, plus PDF, DOCX, PPTX, XLSX, EPUB, Jupyter notebooks, man pages, HTML, email, and common log formats. Unity projects get first-class treatment with GameObject-level records.
Related repositories
Is xerj worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of xerj.