Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs: keep the README data directory outside the indexed tree (#1686)

xerj-org703c8b9431be
diff --git a/README.ar.md b/README.ar.md
index 0f0b30630..60ff7da94 100644
--- a/README.ar.md
+++ b/README.ar.md
@@ -49,7 +49,7 @@ and search how they solved a problem before writing code.
```sh
curl -fsSL https://xerj.org/get | sh
-xerj --insecure --data-dir ./data &
+xerj --insecure --data-dir ~/xerj-data &
xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment" # ranked passages, file:line
@@ -59,6 +59,12 @@ xerj gain # what it did for you — count
<div dir="rtl">
+احتفظ بمجلد البيانات خارج أي مجلد ستفهرسه بـ autoindex. المجلد `data/` ليس ضمن قائمة التجاهل المدمجة، لذا فإن `--data-dir ./data` داخل شجرة تفهرسها لاحقا يجعل العقدة تفهرس تخزينها الخاص.
+
+</div>
+
+<div dir="rtl">
+
تثبيت Windows والتثبيت المتحقق منه يدويا تحت [التثبيت اليدوي](#التثبيت-اليدوي).
علم `--insecure` حد ثقة لا إجراء شكلي. يعطل TLS ومصادقة مفتاح API، فكل من يصل إلى المنفذ مستخدم بصلاحيات المشرف الأعلى يستطيع قراءة كل فهرس وحذفه، بما في ذلك كل فضاء أسماء `/_memory`. هو لجهاز تطوير يستخدمه شخص واحد: العقدة الجديدة لا تربط إلا `127.0.0.1`، وربط النص الواضح على أي واجهة أخرى يرفض الإقلاع ما لم تسمح به صراحة. النموذج الكامل في
@@ -97,7 +103,7 @@ xerj gain # what it did for you — count
</div>
```sh
-xerj --insecure --data-dir ./data & # start it
+xerj --insecure --data-dir ~/xerj-data & # start it
xerj autoindex ~/my-project # point it at anything
```
@@ -171,7 +177,7 @@ irm https://xerj.org/get.ps1 | iex
ملف ثنائي ساكن واحد، بلا JVM وبلا تبعيات. مبني مسبقا لـ Linux وmacOS وWindows على x86-64 وarm64. يمكنك أيضا [البناء من المصدر](#البناء-من-المصدر). يتحدث بواجهة Elasticsearch، فيعمل العملاء ولوحات المعلومات والأدوات القائمة عليه بلا تغيير.
-أوامر أولى بعد التثبيت (يطبع المثبت أين استقر `xerj`؛ أضفه إلى PATH إن لزم): `xerj --insecure --data-dir ./data &`، انتظر حتى يجيب `http://localhost:9200`، ثم `xerj autoindex ~/my-project`. انظر [فهرسة مجلد](#فهرسة-مجلد).
+أوامر أولى بعد التثبيت (يطبع المثبت أين استقر `xerj`؛ أضفه إلى PATH إن لزم): `xerj --insecure --data-dir ~/xerj-data &`، انتظر حتى يجيب `http://localhost:9200`، ثم `xerj autoindex ~/my-project`. انظر [فهرسة مجلد](#فهرسة-مجلد).
لمضيف بلا وصول إلى الإنترنت وقت التشغيل، اتبع
[وصفة النشر المعزول](./docs/recipes/air-gapped-deployment.md). المضمّن المعجمي الافتراضي يعمل بلا شبكة؛ الوضع العصبي يحتاج ملفات النموذج الثلاثة مجهزة محليا قبل أول عملية دلالية.
@@ -183,7 +189,7 @@ irm https://xerj.org/get.ps1 | iex
</div>
```sh
-xerj --insecure --data-dir ./data & # local dev: no TLS, no auth
+xerj --insecure --data-dir ~/xerj-data & # local dev: no TLS, no auth
xerj autoindex ~/my-project
```
@@ -196,8 +202,8 @@ xerj autoindex ~/my-project
</div>
```sh
-xerj --data-dir ./data & # auth on: key minted on first boot
-export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key
+xerj --data-dir ~/xerj-data & # auth on: key minted on first boot
+export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)" # <data_dir>/admin.key
xerj autoindex ~/my-project
```
@@ -262,7 +268,7 @@ curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{
</div>
```sh
-xerj --insecure --data-dir ./data & # 1. the node the tools query
+xerj --insecure --data-dir ~/xerj-data & # 1. the node the tools query
xerj mcp # 2. MCP stdio server (your client runs this)
```
@@ -369,7 +375,7 @@ XERJ_EXTRACT_BENCH=/path/to/repo cargo test -p xerj-autoindex --release \
git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
-./target/release/xerj --insecure --data-dir ./data
+./target/release/xerj --insecure --data-dir ~/xerj-data
```
<div dir="rtl">
diff --git a/README.es.md b/README.es.md
index adbc91f72..e9f780bf2 100644
--- a/README.es.md
+++ b/README.es.md
@@ -51,7 +51,7 @@ O ejecútalo tú mismo:
```sh
curl -fsSL https://xerj.org/get | sh
-xerj --insecure --data-dir ./data &
+xerj --insecure --data-dir ~/xerj-data &
xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment" # ranked passages, file:line
@@ -59,6 +59,8 @@ xerj def "euler_to_rotationmatrix" # go-to-definition: file:line +
xerj gain # what it did for you — counted, not estimated
```
+Deja ese directorio de datos fuera de cualquier carpeta que vayas a indexar con autoindex. `data/` no está en la lista de ignorados integrada, así que `--data-dir ./data` dentro de un árbol que luego indexas hace que el nodo indexe su propio almacenamiento.
+
Windows y una instalación comprobada a mano están en [Instalación manual](#instalación-manual).
Esa opción `--insecure` es un límite de confianza, no un formalismo. Desactiva TLS y la
@@ -124,7 +126,7 @@ búsqueda, RAG, auditorías de seguridad y memoria de agentes, sin esquema que e
sin pipeline que configurar.
```sh
-xerj --insecure --data-dir ./data & # start it
+xerj --insecure --data-dir ~/xerj-data & # start it
xerj autoindex ~/my-project # point it at anything
```
@@ -212,7 +214,7 @@ Habla la API de Elasticsearch, así que los clientes, paneles y herramientas que
funcionan contra él sin cambios.
Primeros comandos después de instalar (el instalador imprime dónde quedó `xerj`; añádelo a
-tu PATH si hace falta): `xerj --insecure --data-dir ./data &`, espera a que
+tu PATH si hace falta): `xerj --insecure --data-dir ~/xerj-data &`, espera a que
`http://localhost:9200` responda y luego `xerj autoindex ~/my-project`. Véase
[Indexar una carpeta](#indexar-una-carpeta).
@@ -226,7 +228,7 @@ modelo preparados en local antes de la primera operación semántica.
Arranca el servidor y apunta `autoindex` a lo que sea:
```sh
-xerj --insecure --data-dir ./data & # local dev: no TLS, no auth
+xerj --insecure --data-dir ~/xerj-data & # local dev: no TLS, no auth
xerj autoindex ~/my-project
```
@@ -241,8 +243,8 @@ pásale a `autoindex` la misma clave. Nunca la toma de `xerj.toml`; pasa `--api-
define `XERJ_API_KEY`, o cada petición vuelve con `401 Unauthorized`:
```sh
-xerj --data-dir ./data & # auth on: key minted on first boot
-export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key
+xerj --data-dir ~/xerj-data & # auth on: key minted on first boot
+export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)" # <data_dir>/admin.key
xerj autoindex ~/my-project
```
@@ -330,7 +332,7 @@ que acabas de instalar es el servidor MCP. No hay nada más que descargar ni nad
compilar:
```sh
-xerj --insecure --data-dir ./data & # 1. the node the tools query
+xerj --insecure --data-dir ~/xerj-data & # 1. the node the tools query
xerj mcp # 2. MCP stdio server (your client runs this)
```
@@ -477,7 +479,7 @@ Necesitas una cadena de herramientas de Rust estable.
git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
-./target/release/xerj --insecure --data-dir ./data
+./target/release/xerj --insecure --data-dir ~/xerj-data
```
Para correr la suite de conformidad contra un servidor en marcha:
diff --git a/README.ja-JP.md b/README.ja-JP.md
index d217b373f..3d8110912 100644
--- a/README.ja-JP.md
+++ b/README.ja-JP.md
@@ -46,7 +46,7 @@ and search how they solved a problem before writing code.
```sh
curl -fsSL https://xerj.org/get | sh
-xerj --insecure --data-dir ./data &
+xerj --insecure --data-dir ~/xerj-data &
xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment" # ranked passages, file:line
@@ -54,6 +54,8 @@ xerj def "euler_to_rotationmatrix" # go-to-definition: file:line +
xerj gain # what it did for you — counted, not estimated
```
+データディレクトリは、autoindex するフォルダの外に置いてください。組み込みの無視リストに `data/` は入っていないので、これから索引するツリーの中で `--data-dir ./data` とすると、ノードが自分のストレージまで索引します。
+
Windows と、手作業で検証しながらインストールする方法は [手動インストール](#手動インストール) にあります。
`--insecure` フラグは形式的なものではなく、信頼境界です。TLS と API キー認証を無効にするため、
@@ -113,7 +115,7 @@ grep を使うエージェントはファイル全体をコンテキストに取
パイプラインを設定する必要もありません。
```sh
-xerj --insecure --data-dir ./data & # start it
+xerj --insecure --data-dir ~/xerj-data & # start it
xerj autoindex ~/my-project # point it at anything
```
@@ -193,7 +195,7 @@ irm https://xerj.org/get.ps1 | iex
Elasticsearch API を話すため、既存のクライアント、ダッシュボード、ツールがそのまま動きます。
インストール後の最初のコマンド(インストーラーが `xerj` の配置先を表示するので、必要なら PATH に
-追加してください): `xerj --insecure --data-dir ./data &` を実行し、`http://localhost:9200` が応答する
+追加してください): `xerj --insecure --data-dir ~/xerj-data &` を実行し、`http://localhost:9200` が応答する
まで待ってから、`xerj autoindex ~/my-project` を実行します。[フォルダをインデックスする](#フォルダをインデックスする)
を参照してください。
@@ -207,7 +209,7 @@ Elasticsearch API を話すため、既存のクライアント、ダッシュ
サーバーを起動し、`autoindex` を任意の対象に向けます:
```sh
-xerj --insecure --data-dir ./data & # local dev: no TLS, no auth
+xerj --insecure --data-dir ~/xerj-data & # local dev: no TLS, no auth
xerj autoindex ~/my-project
```
@@ -220,8 +222,8 @@ xerj autoindex ~/my-project
`--api-key` を渡すか `XERJ_API_KEY` を設定しないと、すべてのリクエストが `401 Unauthorized` になります:
```sh
-xerj --data-dir ./data & # auth on: key minted on first boot
-export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key
+xerj --data-dir ~/xerj-data & # auth on: key minted on first boot
+export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)" # <data_dir>/admin.key
xerj autoindex ~/my-project
```
@@ -300,7 +302,7 @@ function calling のホストは Model Context Protocol を通じてツールに
ありません:
```sh
-xerj --insecure --data-dir ./data & # 1. the node the tools query
+xerj --insecure --data-dir ~/xerj-data & # 1. the node the tools query
xerj mcp # 2. MCP stdio server (your client runs this)
```
@@ -434,7 +436,7 @@ CI でよくあるケースで、通常は 95% 以上が未変更です。変更
git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
-./target/release/xerj --insecure --data-dir ./data
+./target/release/xerj --insecure --data-dir ~/xerj-data
```
稼働中のサーバーに対して適合性テストスイートを実行するには:
diff --git a/README.md b/README.md
index a06dd7e60..04b1c7540 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ Or run it yourself:
```sh
curl -fsSL https://xerj.org/get | sh
-xerj --insecure --data-dir ./data &
+xerj --insecure --data-dir ~/xerj-data &
xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment" # ranked passages, file:line
@@ -58,6 +58,10 @@ xerj def "euler_to_rotationmatrix" # go-to-definition: file:line +
xerj gain # what it did for you — counted, not estimated
```
+Keep that data directory outside any folder you will autoindex. `data/` is not in the
+built-in ignore list, so `--data-dir ./data` inside a tree you then index makes the node
+index its own storage.
+
Windows and a hand-verified install are under [Install by hand](#install-by-hand).
That `--insecure` flag is a trust boundary, not a formality. It turns off TLS and API-key
@@ -117,7 +121,7 @@ awkward CSVs into typed, queryable indices for search, RAG, security audits and
memory, with no schema to write and no pipeline to configure.
```sh
-xerj --insecure --data-dir ./data & # start it
+xerj --insecure --data-dir ~/xerj-data & # start it
xerj autoindex ~/my-project # point it at anything
```
@@ -197,7 +201,7 @@ and arm64. You can also [build from source](#build-from-source). It speaks the E
API, so existing clients, dashboards and tooling work against it unchanged.
First commands after install (the installer prints where `xerj` landed; add it to your PATH
-if needed): `xerj --insecure --data-dir ./data &`, wait until `http://localhost:9200`
+if needed): `xerj --insecure --data-dir ~/xerj-data &`, wait until `http://localhost:9200`
responds, then `xerj autoindex ~/my-project`. See [Index a folder](#index-a-folder).
For a host with no runtime internet access, follow the
@@ -210,7 +214,7 @@ semantic operation.
Start the server, then point `autoindex` at anything:
```sh
-xerj --insecure --data-dir ./data & # local dev: no TLS, no auth
+xerj --insecure --data-dir ~/xerj-data & # local dev: no TLS, no auth
xerj autoindex ~/my-project
```
@@ -224,8 +228,8 @@ key up from `xerj.toml`; pass `--api-key` or set `XERJ_API_KEY`, or every reques
`401 Unauthorized`:
```sh
-xerj --data-dir ./data & # auth on: key minted on first boot
-export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key
+xerj --data-dir ~/xerj-data & # auth on: key minted on first boot
+export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)" # <data_dir>/admin.key
xerj autoindex ~/my-project
```
@@ -304,7 +308,7 @@ tools through the Model Context Protocol, and the binary you just installed is t
server. There is nothing else to download and nothing to compile:
```sh
-xerj --insecure --data-dir ./data & # 1. the node the tools query
+xerj --insecure --data-dir ~/xerj-data & # 1. the node the tools query
xerj mcp # 2. MCP stdio server (your client runs this)
```
@@ -442,7 +446,7 @@ You need 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 ./data
+./target/release/xerj --insecure --data-dir ~/xerj-data
```
To run the conformance suite against a running server:
diff --git a/README.zh-CN.md b/README.zh-CN.md
index ec117130f..2134645c8 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -36,7 +36,7 @@ XERJ 是一款受到社区信赖的本地 AI 搜索引擎,能自动为任意
```sh
curl -fsSL https://xerj.org/get | sh
-xerj --insecure --data-dir ./data &
+xerj --insecure --data-dir ~/xerj-data &
xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment" # ranked passages, file:line
@@ -44,6 +44,8 @@ xerj def "euler_to_rotationmatrix" # go-to-definition: file:line +
xerj gain # what it did for you — counted, not estimated
```
+把数据目录放在你将要 autoindex 的文件夹之外。内置忽略列表不包含 `data/`,因此在即将索引的目录树里使用 `--data-dir ./data` 会让节点把自己的存储也索引进去。
+
`xerj init` 一条命令即可把 XERJ 接入 Claude Code 或 Cursor(MCP 与技能);`search` 返回排序后的代码片段及 `file:line`,`def` 定位符号定义并显示签名,`gain` 显示实际统计的使用收益。
Windows 安装方法和手动检查安装的说明见[手动安装](#手动安装)。
@@ -77,7 +79,7 @@ XERJ 与 grep 组都完成了 16/16 个任务,输出 token 用量约为 grep
参考代码工作流建立在同一个基础能力上:`xerj autoindex <folder>` 把一批文件变成智能体可查询的语料。一条命令就能为代码、文档、日志、PDF、SQLite 和难处理的 CSV 建立带类型的索引,用于搜索、RAG、安全审计和智能体记忆,无须编写 schema 或配置数据管道。
```sh
-xerj --insecure --data-dir ./data & # start it
+xerj --insecure --data-dir ~/xerj-data & # start it
xerj autoindex ~/my-project # point it at anything
```
@@ -135,7 +137,7 @@ irm https://xerj.org/get.ps1 | iex
单个静态二进制程序,无须 JVM 或其他依赖。提供 Linux、macOS 和 Windows 的 x86-64、arm64 预编译版本,也可以[从源码构建](#从源码构建)。XERJ 兼容 Elasticsearch API,已有的客户端、仪表盘和工具可以直接连接。
-安装器会输出 `xerj` 的安装位置,必要时将其加入 `PATH`。安装后先运行 `xerj --insecure --data-dir ./data &`,等待 `http://localhost:9200` 能响应,再执行 `xerj autoindex ~/my-project`。详见[索引文件夹](#索引文件夹)。
+安装器会输出 `xerj` 的安装位置,必要时将其加入 `PATH`。安装后先运行 `xerj --insecure --data-dir ~/xerj-data &`,等待 `http://localhost:9200` 能响应,再执行 `xerj autoindex ~/my-project`。详见[索引文件夹](#索引文件夹)。
运行环境无法访问互联网时,请参考[离线部署指南](./docs/recipes/air-gapped-deployment.md)。默认词法嵌入器可离线运行;神经模式则需要在首次语义操作前,将三个模型文件准备在本地。
@@ -144,7 +146,7 @@ irm https://xerj.org/get.ps1 | iex
启动服务,再将文件夹路径交给 `autoindex`:
```sh
-xerj --insecure --data-dir ./data & # local dev: no TLS, no auth
+xerj --insecure --data-dir ~/xerj-data & # local dev: no TLS, no auth
xerj autoindex ~/my-project
```
@@ -153,8 +155,8 @@ xerj autoindex ~/my-project
不带 `--insecure` 的启动默认开启认证,包括通过配置文件启动的情况。此时需要把同一把密钥交给 `autoindex`。它不会从 `xerj.toml` 中读取密钥,必须传入 `--api-key` 或设置 `XERJ_API_KEY`,否则每个请求都会返回 `401 Unauthorized`:
```sh
-xerj --data-dir ./data & # auth on: key minted on first boot
-export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key
+xerj --data-dir ~/xerj-data & # auth on: key minted on first boot
+export XERJ_API_KEY="$(cat ~/xerj-data/admin.key)" # <data_dir>/admin.key
xerj autoindex ~/my-project
```
@@ -205,7 +207,7 @@ curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{
有些智能体无法执行 shell 命令。桌面助手和支持函数调用的宿主可通过 Model Context Protocol(MCP)访问工具,安装得到的 XERJ 二进制程序本身就包含 MCP 服务,无须额外下载或编译:
```sh
-xerj --insecure --data-dir ./data & # 1. the node the tools query
+xerj --insecure --data-dir ~/xerj-data & # 1. the node the tools query
xerj mcp # 2. MCP stdio server (your client runs this)
```
@@ -291,7 +293,7 @@ XERJ_EXTRACT_BENCH=/path/to/repo cargo test -p xerj-autoindex --release \
git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
-./target/release/xerj --insecure --data-dir ./data
+./target/release/xerj --insecure --data-dir ~/xerj-data
```
对已运行的服务执行一致性测试:
diff --git a/engine/crates/xerj-api/tests/readme_data_dir.rs b/engine/crates/xerj-api/tests/readme_data_dir.rs
new file mode 100644
index 000000000..2522a6cf0
--- /dev/null
+++ b/engine/crates/xerj-api/tests/readme_data_dir.rs
@@ -0,0 +1,45 @@
+//! The root README quickstart must keep the node data directory outside any
+//! folder an agent will autoindex. `landing/llms.txt` already says why:
+//! `data/` is not in the built-in ignore list, so `--data-dir ./data` inside
+//! that tree makes the node index its own storage. The root READMEs are the
+//! page an agent copies first, and they used to show `./data`.
+
+use std::path::PathBuf;
+
+fn readme(name: &str) -> String {
+ let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+ .join("../../..")
+ .join(name);
+ std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()))
+}
+
+#[test]
+fn quickstart_puts_the_data_dir_outside_the_indexed_tree() {
+ for name in [
+ "README.md",
+ "README.zh-CN.md",
+ "README.ja-JP.md",
+ "README.es.md",
+ "README.ar.md",
+ ] {
+ let text = readme(name);
+ assert!(
+ text.contains("xerj --insecure --data-dir ~/xerj-data &"),
+ "{name} quickstart must start the node at ~/xerj-data"
+ );
+ assert!(
+ text.contains("~/xerj-data/admin.key"),
+ "{name} must read the admin key from the same directory"
+ );
+ assert!(
+ !text.contains("xerj --insecure --data-dir ./data")
+ && !text.contains("xerj --data-dir ./data"),
+ "{name} still starts a node inside ./data"
+ );
+ }
+ let en = readme("README.md");
+ assert!(
+ en.contains("outside any folder you will autoindex"),
+ "the English README must say why ./data is the wrong place"
+ );
+}