XERJ: Local-First Search Engine and MCP Server for Agents

What XERJ is

XERJ is a local-first search engine and Model Context Protocol (MCP) server for AI agents. It ships as one Rust binary that indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search and agent memory, all behind an Elasticsearch-compatible API. The README says it works with Claude Code, Cursor and any MCP client.

The problem it targets is context waste. Coding agents that grep a repository pull whole files into their context window and still have to read them; the README cites WordPress core's PHP as roughly 5.2 million tokens, or 26 full context windows. XERJ indexes a folder once and lets the agent query for the exact passage, returned with file:line references. The headline use case the project calls "reference coding": the agent clones and indexes open-source repositories close to the task, then retrieves how they solved a problem before writing its own code.

It is aimed at developers running coding agents locally, teams that want search and RAG without operating a separate vector database, and anyone who wants Elasticsearch-style search on a laptop without a JVM.

How it works

XERJ runs as a server node on port 9200 and speaks the Elasticsearch REST API: indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex and the _cat endpoints. The README says Kibana and the official client libraries connect to it directly, and stresses that it is API-compatible rather than a reimplementation or fork of Elasticsearch.

The autoindex command is the ingestion path. XERJ sniffs every file in a folder, works out what it is, and creates one index per dataset it finds, with no schema or pipeline to write. Source files are parsed with tree-sitter so code arrives with symbols and line numbers instead of flat text. The README lists CSV, JSON, JSONL, XML, YAML, SQLite, PDF, DOCX, PowerPoint, Excel, EPUB, Jupyter notebooks, man pages, HTML, mail (.eml and mbox) and common log formats, plus dedicated handling of Unity projects. Re-indexing is incremental: byte-identical files skip the parse and carry their previous result forward.

Agents connect in one of two ways: through the CLI (xerj search, xerj def) or through xerj mcp, an MCP stdio server built into the same binary that proxies to the node named by XERJ_URL.

Key features

• Hybrid retrieval in one engine: BM25 full-text, kNN vector search and hybrid fusion using the same knn and semantic syntax an Elasticsearch client would send.
• AST-aware code search: tree-sitter indexing so an agent can retrieve a function, plus a go-to-definition command that returns file:line and the signature.
• Agent memory: a /_memory/{namespace} API stores what an agent learns and recalls it by text, meaning or vector in a later session.
• Seventeen MCP tools: search, semantic, vector and hybrid search, memory store and recall, "second brain" link tools, a rule-based plain-words-to-query planner, an index field map and a code-search tool. Tool schemas are generated from a live tools/list and checked in CI.
• Optional reranking: adding "rerank": {} to a search sends the top results to Jev, an external judge service from TypeSafe AI; a local /_decide endpoint answers the same kind of question from documents you have already labelled.
• Offline by default: the default embedder is lexical feature-hashing and works offline; a neural embedder is opt-in and downloads about 90 MB of model files.
• Read-only sharing: xerj share gives guest access to one indexed folder through a link and a passcode.
• Single static binary: prebuilt for Linux, macOS and Windows on x86-64 and arm64, with no JVM and no dependencies.

Getting started

The README's quick path installs the binary, starts a local dev node, wires XERJ into Claude Code or Cursor, and indexes a project:

curl -fsSL https://xerj.org/get | sh
xerj --insecure --data-dir ~/xerj-data &
xerj init
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment"
xerj def "euler_to_rotationmatrix"
xerj gain

xerj gain reports what XERJ did for you. On Windows the installer is irm https://xerj.org/get.ps1 | iex. Keep the data directory outside any folder you autoindex, otherwise the node will index its own storage.

Without --insecure, auth is on and a key is minted on first boot. autoindex does not read the key from the config file, so pass it explicitly:

xerj --data-dir ~/xerj-data &
export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)"
xerj autoindex ~/my-project

Because the API is Elasticsearch's, querying is plain HTTP:

curl localhost:9200/_cat/indices
curl "localhost:9200/ax-*/_search?q=checkout+error"

For MCP hosts, run xerj mcp as the server command with an absolute path to the binary, since desktop-launched hosts do not inherit your shell's PATH. 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

Use cases

• Reference coding: index the open-source projects nearest your problem and let the agent retrieve how they solved it before it writes code.
• Codebase Q&A and RAG: ask for a mechanism and get the passage with file:line instead of a directory listing.
• Security audits: index a target tree and query for sink patterns, secrets and dangerous calls across every file type at once.
• Log and incident analysis: mixed log formats become typed indices with Elasticsearch-style aggregations.
• Agent long-term memory: store notes in a /_memory namespace and recall them by meaning next session.
• A lightweight Elasticsearch replacement for development or small deployments that speak the same wire protocol.

How it compares

The README compares XERJ directly with Elasticsearch. It reports a closed-loop benchmark against Elasticsearch 8.13.4 scoring 55 wins, 26 ties and 4 losses, including 1.72x ingest throughput and a 1.61x smaller on-disk footprint, and writes up the four losses (read p99 under a concurrent high-rate writer) instead of hiding them. Its conformance suite passes 1,366 of 1,369 Elasticsearch YAML cases. These are the project's own measurements; the README itself advises treating numbers you cannot reproduce with skepticism.

For agent workflows the comparison it draws is against grep and against the model's memory: in its reference-coding case study (8 tasks, 4 languages, 16 runs per arm) it reports 2.7x fewer output tokens than a grep-driven agent at the same 16/16 solve rate. The README also notes the limits: the gain is largest on private, niche or post-cutoff code and neutral to harmful on popular libraries the model already knows. A docs page compares its storage and search design with Lucene 10.3.1.

Things to know before adopting

• Licence: Apache-2.0. Code contributions require signing a CLA once per contributor; field-report pull requests are exempt.
• --insecure is a real trust boundary: it disables TLS and API-key auth, making every caller that can reach the port a superuser over every index and memory namespace. A fresh node binds 127.0.0.1 only and refuses a cleartext bind on other interfaces unless explicitly allowed. Use auth on any shared host.
• Outbound data: reranking sends the text of top results to TypeSafe's servers. It stays off until a key is set, and [rerank] enabled = false forbids it; proxy embeddings and the WAL tap can also send text when configured.
• Embedder defaults: semantic search uses lexical feature-hashing unless the node runs the neural embedder, which downloads model files; air-gapped hosts need those staged in advance.
• Scroll limits: scroll is a bounded snapshot, and queries whose total exceeds it are refused with a 400; use search_after for large exports.
• Maturity: the repository was created at the end of June 2026 and its star count has grown very quickly. It is young software with a fast release cadence, so pin a version and review the security model docs before relying on it.
• Install script: the default install pipes a script from xerj.org into the shell; read it first or build from source if that is a concern.

Project activity

As of October 2026 the repository has about 12,600 stars. It was created in June 2026, is written in Rust, is licensed under Apache-2.0 and was receiving commits on the day of writing. The project keeps a roadmap, changelog, milestones and a public project board, and the README asks users to contribute short field reports describing what they indexed and how it went.

Source code is at github.com/xerj-org/xerj, and guides, recipes and benchmark results are on xerj.org.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/xerj?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)