XERJ
A local-first search engine and MCP server that lets coding agents retrieve exact code passages instead of grepping through files.
- Source repo
- xerj-org/xerj
- Stars
- ★ 19k
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers using Claude Code or Cursor who want their agent to clone and index similar open-source projects and retrieve the mechanism before writing new code.
- Not a fit if
- Teams needing multi-tenant, auth-on production search out of the box
- Users who want a fully managed cloud search service with no local data directory
- Migrations that require Elasticsearch internals, not just the REST API
- Website
- xerj.org ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-19latest release v1.0.0-rc.104 (2026-11-19)+6.4 ★/day over 7 days
- Source review
- 65/100 · Some gaps
What does this agent do, and when should you use it?
XERJ is a single-binary local search engine written in Rust that doubles as an MCP server for AI agents. Running xerj autoindex <folder> makes it sniff and index code, docs, logs, JSONL/CSV, PDFs, SQLite, Office files and more, parsing source through tree-sitter so records carry symbols and line numbers. It exposes an Elasticsearch-compatible REST API (indices, bulk, search, aggregations, kNN, scroll, _cat) and supports BM25 full-text, vector and hybrid retrieval. It provides durable agent memory at /_memory/{namespace} and a relationship layer at /_graph, and it plugs into Claude Code, Cursor and other MCP clients through xerj mcp over stdio. Starting with rc.101 it also ships an optional XERJ Query-1 facts model (off by default, enabled with --facts-model-dir) that turns a question into a small program over stored subject/relation/value facts and returns cited answers. The deployment boundary is one user on one dev machine: a fresh node binds 127.0.0.1, and --insecure turns off TLS and authentication.
You start a node that listens on port 9200 with xerj --insecure --data-dir ~/xerj-data, then run xerj autoindex <folder>. The node sniffs each file, infers datasets, and builds one index per dataset: source files go through tree-sitter and gain symbols and line numbers, while CSV, JSON, JSONL, YAML, SQLite, PDF, DOCX, PPTX, XLSX, EPUB, mbox and common log formats each become typed records. You query the result through Elasticsearch-compatible endpoints such as _search, _cat/indices, knn and semantic, or through CLI commands like xerj search, xerj def, xerj code and xerj batch-search, which return passages with file:line citations. xerj mcp is a stdio MCP server that proxies tools like xerj_search, xerj_semantic_search, xerj_vector_search, xerj_hybrid_search, xerj_memory_store/_recall and xerj_brain_* to the running node named by XERJ_URL. With --facts-model-dir, POST /_facts/{ns}/_bulk writes subject/relation/value facts and POST /_facts/{ns}/_ask returns a verified answer with a final_status such as ANSWER, UNKNOWN or CONFLICT.
- Developers using Claude Code or Cursor who want their agent to clone and index similar open-source projects and retrieve the mechanism before writing new code.
- Security teams auditing a large codebase (WordPress core is cited as about 5.2M tokens) who need to query for sinks, secrets and dangerous calls across every file type.
- Agent builders who want durable cross-session memory by writing project notes to /_memory/notes and recalling them semantically next session.
- Small teams that want to point existing Elasticsearch clients and Kibana dashboards at a single-binary, no-JVM replacement.
- Data engineers who need unified search and aggregation over mixed log, JSONL and CSV corpora without standing up a separate vector database.
- Researchers who want an agent to answer from explicitly written structured facts with citations, or to get an explicit UNKNOWN/CONFLICT instead of a guess.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
curl -fsSL https://xerj.org/get | shirm https://xerj.org/get.ps1 | iexnix run github:xerj-org/xerj -- --versioncurl -fsSL https://xerj.org/get | sh -s -- --with-model
- Environment variables
XERJ_API_KEYXERJ_URL- Config files
~/.local/bin~/.local/share/xerj/model- Install notes cover
- Windows · macOS · Linux
How do you install or deploy this agent?
Official one-line installers exist for the sh-based platforms (Linux, macOS, Windows Git Bash/MSYS/Cygwin) and PowerShell. The sh installer places xerj in ~/.local/bin and does not edit PATH; the PowerShell installer adds its directory to the user PATH.
curl -fsSL https://xerj.org/get | shirm https://xerj.org/get.ps1 | iexnix run github:xerj-org/xerj -- --versionBuilding from source needs a stable Rust toolchain:
git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
./target/release/xerj --insecure --data-dir ~/xerj-dataHow do you use this agent?
Start the node, then point autoindex at any folder:
xerj --insecure --data-dir ~/xerj-data &
xerj autoindex ~/my-projectIf the node runs with auth (the default without --insecure), autoindex needs the same key:
export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)"
xerj autoindex ~/my-projectQuery through the Elasticsearch API or the CLI:
curl localhost:9200/_cat/indices
curl "localhost:9200/ax-*/_search?q=checkout+error"
xerj search "how do we rotate the WAL segment"
xerj def "euler_to_rotationmatrix"Register it as an MCP server in a client config (the node must already be running):
{
"mcpServers": {
"xerj": {
"command": "/home/you/.local/bin/xerj",
"args": ["mcp"],
"env": { "XERJ_URL": "http://localhost:9200" }
}
}
}To enable XERJ Query-1 facts QA:
curl -fsSL https://xerj.org/get | sh -s -- --with-model
xerj --facts-model-dir ~/.local/share/xerj/model --insecure --data-dir ~/xerj-data &
curl -s localhost:9200/_facts | grep -o '"state":"loaded"'What are this agent's strengths and limitations?
- One static Rust binary with no JVM or external service dependencies, prebuilt for Linux, macOS and Windows on x86-64 and arm64.
- Speaks the Elasticsearch REST API, so existing clients, dashboards and tooling connect unchanged; the repo ships an ES-YAML conformance suite.
- xerj autoindex requires no schema and handles code (AST-aware), PDF, Office, EPUB, mbox, SQLite and common log formats.
- Native MCP support through xerj mcp, with 26 documented client configurations and 6 marked as actually tested.
- The default embedder is lexical and fully offline, so agent memory and RAG work on a laptop with no GPU.
- The documented --insecure mode disables TLS and auth, making every reachable caller a superuser; it is scoped to one user on a dev machine.
- rc.101 upgrades the data directory to format 4 and rc.100 cannot open it again, so rollbacks need a backup.
- The XERJ Query-1 model ships as a proprietary binary bundle and its training/evaluation data are not public yet; it is off by default.
- Query-1 has documented gaps: sums and totals, and large fact sets (all 20 test questions declined at 95,000 facts).
- Elasticsearch compatibility is API-level only; scroll is a bounded snapshot and oversized exact totals are refused with 400.
- Some optional features need extra model downloads or, for Jev reranking, send result text to a third party.
How does this agent compare with similar options?
The README benchmarks XERJ head-to-head against Elasticsearch 8.13.4 (latest run: 55 wins, 26 ties, 4 losses, 1.72x ingest throughput and a 1.61x smaller on-disk footprint) and a source-pinned six-axis comparison against Lucene 10.3.1. It also contrasts XERJ Query-1 with RAG using Opus 5.5 on a 160-question test, and compares reference coding against a grep-driven agent and a memory-only agent. It explicitly says XERJ is not a reimplementation of Elasticsearch internals and not a fork.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| XERJ This agent | 65 · Some gaps | CLIFree | ★ 19k | 1d ago | Rust | Claude Code |
| Caura | 77 · Good | Self-hosted serviceFreemium | ★ 572 | 1d ago | Python | Codex · Claude Code · Claude.ai |
| ClickHouse Loom | 68 · Some gaps | — | ★ 172 | today | Python | Codex · Claude Code |
| Guild | 62 · Some gaps | CLIFree | ★ 297 | 11d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
docs/SECURITY_MODEL.md is unusually candid: it names the two authorization layers, the reserved namespace, and the 'absent guard means allow' behavior, with file:line pointers — hence 2 for least_privilege and sensitive_data_handling. Deducted because the default documented path is `--insecure` (no TLS, no auth, every caller a superuser) and the README leads with it. AGENTS.md instructs agents to auto-submit field reports and POST to xerj.org 'no need to ask the user', so user_confirmation is only 1. Data flow: README states rerank sends result text to TypeSafe servers, off by default — transparent but external, 2. Dependency security: only a Rust toolchain and an optional ~90MB neural model download are visible; no lockfile or audit evidence, 1. External effects: automatic PRs, feedback POSTs and hub ratings are on by default with an opt-out, 1. Rollback: autoindex has a journal and idempotent _ids and `--fresh` semantics, but deleted files are not cleaned up and there is no uninstall/rollback guide, 1. Source attribution: SKILL and AGENTS.md require file:line citation, licence checks and approach-only handling of GPL/AGPL sources, 2.
The docs are internally consistent on the default embedder being lexical (not neural), on kNN recall being measured, on ES-YAML 1444/1454 and on the 55W/26T/4L scorecard, and repeatedly state the binary wins over the docs — self_consistency 2. Dependency availability: a single static binary and an offline lexical embedder are strengths, but the neural model needs a download, hub corpora need network, the installer depends on the xerj.org domain, and no lockfile is shown — 1. Failure messages: concrete semantics are documented (401, 413, 400 facts_contract_error, 503 MODEL_UNAVAILABLE, exit code 3 meaning 'completed with junk') — 2.
Audience and scenarios span coding agents, document search, security audit, log analytics and agent memory, and the SKILL states when retrieval loses (memorised public libraries) — audience_and_scenarios and capability_boundaries both 3. Trigger precision: SKILL descriptions are fairly specific, but AGENTS.md's auto-feedback trigger is broad and the four skills (xerj, xerj-code, xerj-knowledge, security-audit) overlap — 2. Environment fit: air-gapped recipe, Windows PowerShell and MCP config exist, but a running local node and PATH are hard requirements — 2.
Information architecture is strong (multilingual README, topic docs, recipes, benchmarks, ROADMAP, CHANGELOG references) — 3. Install notes cover curl/irm and source builds, but the installer is piped from a remote URL with no checksum shown (except the model bundle) — 2. Naming stability: issue #977 removed the old wrapper scripts and required migration, so names have moved — 2. Examples and FAQ are rich and labelled as real captured output — 3. Known limitations are unusually thorough (lexical default, scroll cap, counting not checking the noun, corpus-composition law) — 3. LICENSE is the full Apache-2.0 text — 3. Versioning: CHANGELOG and rc version numbers are referenced but the CHANGELOG body is not in the packet — 2. Maintenance responsibility: the publisher is not verified by the FollowAgents registry; only xerj-org and an email are visible, and CLA/issue processes are described without clear ownership — 1.
Output usability: ranked passages with file:line, a data map and ready-to-send queries are genuinely useful, but depend on a running node and on using filter_path/size:0 correctly — 2. Marginal value: measured gains on unmemorised code, neutral-to-negative on popular public libraries; real but narrow — 2. Cost benefit: the docs themselves frame it as spending input tokens to save output tokens, with savings varying by corpus composition and extra indexing/storage cost — 2.
claim_traceability: most numbers point to case studies, the benchmarks directory, scripts/bench and issue numbers, but headline figures (2.7x, ~5x field reports) live on off-repo pages that cannot be checked from the packet — 2. cross_source_corroboration: README, AGENTS.md, SKILL and TOKEN_USAGE agree on the lexical default and on when retrieval pays off — 2. fact_inference_separation: AGENTS.md explicitly requires separating verified from assumed and forbids invented benchmarks, and the translated README notes figures were not re-measured — 2.
- The default examples use `--insecure`, disabling TLS and auth so any caller reaching the port is a superuser; on shared hosts start with auth enabled instead.
- AGENTS.md tells agents to auto-submit field reports and POST to xerj.org without asking the user; set `--disable-feedback` or `XERJ_DISABLE_FEEDBACK=true` when running inside someone else's repository.
- The installer is executed via `curl | sh` from a remote domain with no checksum in the packet; only the model bundle ships a sha256.
- Rerank sends retrieved result text to external TypeSafe servers; it is off until a key is configured, but read docs/RERANK.md before enabling it.
- autoindex does not remove documents for files that disappeared, and `--fresh` is refused once a durable corpus generation exists; deletions and renames need the documented incremental path.
- The publisher is not verified by the FollowAgents registry and maintenance responsibility/update path is unclear; verify provenance independently before adoption.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.0.0-rc.104 xerj v1.0.0-rc.104
Release notes excerpt
All platforms. rc.104 supersedes v1.0.0-rc.103. rc.103 was published Linux-only, and releases on this repository are immutable once published, so its macOS and Windows builds could not be attached to it. rc.104 is the rc.103 code (no pull request merged to main in between; the only source change is the version string) with all eight targets: Linux x86_64 and aarch64 (glibc and musl, plus .deb for both glibc targets), macOS x86_64 and aarch64, Windows x86_64 and aarch64, the XERJ Query-1 model bundle (the rc.102 bundle, unchanged, under the rc.104 name) and one SHA256SUMS. `releases/l …View on GitHub ↗ -
v1.0.0-rc.102 xerj v1.0.0-rc.102
-
v1.0.0-rc.101 xerj v1.0.0-rc.101
FAQ
Does it need a GPU or an external LLM API?
How compatible is it with Elasticsearch really?
Is it safe by default?
What happens if I upgrade to rc.101?
Can I use it as a shared production search cluster?
Is XERJ free?
Does XERJ work on Windows?
irm https://xerj.org/get.ps1 | iex.Is XERJ open source?
Is XERJ still maintained?
Who makes XERJ?
What is XERJ's official website?
Thanks — we use this to improve the page.