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

At a glance

How it runs
CLISelf-hosted serviceMCP server
Works with
Universal · cross-platformClaude Code
Cost
Free, no paid service needed
Setup effort
Medium · a few setup steps
You'll need
Rust stable toolchain (only for building from source)Shell / CLINetwork accessLocal filesystemMCP Server
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.

  1. 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.
  2. 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.
  3. Agent builders who want durable cross-session memory by writing project notes to /_memory/notes and recalling them semantically next session.
  4. Small teams that want to point existing Elasticsearch clients and Kibana dashboards at a single-binary, no-JVM replacement.
  5. Data engineers who need unified search and aggregation over mixed log, JSONL and CSV corpora without standing up a separate vector database.
  6. 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 | sh
  • irm https://xerj.org/get.ps1 | iex
  • nix run github:xerj-org/xerj -- --version
  • curl -fsSL https://xerj.org/get | sh -s -- --with-model
Environment variables
XERJ_API_KEY XERJ_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 | sh
irm https://xerj.org/get.ps1 | iex
nix run github:xerj-org/xerj -- --version

Building 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-data

How do you use this agent?

Start the node, then point autoindex at any folder:

xerj --insecure --data-dir ~/xerj-data &
xerj autoindex ~/my-project

If 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-project

Query 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?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Some gaps
65/ 100 5-point scale 3.3 / 5
This review covers the source as of Nov 11, 2026. The project has shipped 1 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 14/29
Reliability 8/14
Adaptability 15/18
Convention 14/18
Effectiveness 9/13
Verifiability 5/8
Why each dimension lost points
Trust14 / 29 · 2.4/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention14 / 18 · 3.9/5

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.

Effectiveness9 / 13 · 3.5/5

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.

Verifiability5 / 8 · 3.1/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 50e4ffded551 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/xerj.svg)](https://followagents.com/en/agents/xerj)
<a href="https://followagents.com/en/agents/xerj"><img src="https://followagents.com/badge/xerj.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. 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 ↗
  2. v1.0.0-rc.102 xerj v1.0.0-rc.102
  3. v1.0.0-rc.101 xerj v1.0.0-rc.101

FAQ

Does it need a GPU or an external LLM API?
No. The default embedder is offline lexical feature hashing and XERJ Query-1 runs on CPU with no GPU. Neural embeddings and Jev reranking are opt-in; the latter sends result text to TypeSafe's servers.
How compatible is it with Elasticsearch really?
It implements the REST API layer: indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex and _cat. The conformance suite currently passes 1444 of 1454 cases, but scroll is a bounded up-front snapshot, so queries whose exact total exceeds the window get a 400 instead of a truncated result.
Is it safe by default?
Starting without --insecure turns auth on and mints an admin key at <data-dir>/admin.key on first boot; a fresh node binds 127.0.0.1 only. --insecure disables TLS and API-key auth and is meant for a single-user dev machine.
What happens if I upgrade to rc.101?
The first write upgrades the data directory to format 4, and rc.100 cannot open it again. Keep a copy of the old data directory if you may need to roll back.
Can I use it as a shared production search cluster?
The README positions it as local-first and single-user. Shared hosts need auth configured, and the project's own benchmark lists read p99 under a high-rate writer as the common cause of all four losses.
Is XERJ free?
Yes. XERJ is free to use and does not need a paid service.
Does XERJ work on Windows?
Yes. The install notes on this page include a Windows command: irm https://xerj.org/get.ps1 | iex.
Is XERJ open source?
Yes. The source code is on GitHub (xerj-org/xerj) under the Apache-2.0 licence.
Is XERJ still maintained?
Yes. The latest commit on GitHub is from 2026-11-19, within the last 30 days. The latest release is v1.0.0-rc.104 (2026-11-19).
Who makes XERJ?
XERJ is published on GitHub by the account xerj-org. FollowAgents has not verified which person or company is behind that account.
What is XERJ's official website?
The project's GitHub repository lists https://xerj.org as its website. That link is set by the repository owner; the source code itself is on GitHub (xerj-org/xerj).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts