XERJ（xerj-org/xerj）：让 AI Agent 用检索替代 grep 的本地搜索引擎

一、导读

AI Agent 最大的浪费不是算力，是上下文：一个 Agent 面对陌生代码库，grep 只告诉它「去看这个文件」，而读懂一个文件可能就是上万 token。XERJ 把这件事变成一次千字节级的查询——它是用 Rust 从零写的搜索/向量/日志引擎，主用户不是人类而是 AI Agent：一条 xerj autoindex 让任意文件夹变成可查询索引，兼容 Elasticsearch 8.x 线上协议让存量客户端零迁移直连，官方三臂对照实测让 Claude Code 输出 token 减少 2.7 倍、成本降一半。该项目以单日 +1647 星登上 GitHub Trending（2026-10-17 榜单），本文拆解它的架构原理与落地玩法。

二、项目速览

项目	信息
仓库	xerj-org/xerj，官网 xerj.org
定位	AI-native 搜索、向量与日志分析引擎（Rust 从零实现，与 Elasticsearch/Lucene 不共享任何代码与架构）
Star / 当日涨星	6,634 / +1,647（截至 2026-10-17，GitHub API 与 Trending daily）
主语言 / License	Rust / Apache-2.0
创建时间	2026-06-30；最新 Release v1.0.0-rc.96（2026-10-16，RC 几乎每日一发）
兼容性	ES 8.13 REST 规范 YAML 一致性套件通过 1366/1369，CI 硬门禁零失败
关键数字	61.6 MB 单二进制（无 JVM）；对 ES 8.13.4 全矩阵实测 55 胜 26 平 4 负；写入吞吐 1.72 倍、磁盘占用小 1.61 倍

三、为什么是它：Agent 时代的检索基建缺口

官方文档把动机讲得很直白：WordPress 核心的 PHP 约 520 万 token，相当于 26 个完整上下文窗口，Agent 根本读不完；grep 的命中只是一行，判断这一行意味着打开整个文件。在一次真实的安全审计里，Agent 用 XERJ 跨 1,492 个 PHP 文件工作只花了约 2.6 万 token——约为整棵树的 0.5%。反过来测，Agent 只凭记忆在一个陌生语料上把输入 token 烧到 106 万仍一事无成。

XERJ 对「Agent 面对陌生数据」的三个痛点各给了一个答案：上手难（传统引擎要先设计 mapping 和 ingest 管线，Agent 不会点 Kibana）——用 autoindex 内容嗅探解决；定向难（Agent 的第一个问题是「这里面有什么」）——用 autoindex map 输出数据集、字段类型、示例值与已知坑位；连续性（跨会话记忆需要单独架向量库和嵌入服务）——用内置 /_memory 命名空间按语义召回。Elasticsearch 协议兼容被明确定位为「采用桥」而非使命，类比是 CockroachDB/Neon 说 Postgres 协议但不是 Postgres。

涨星动因大致有三：其一，2026 年 coding agent 全面铺开后，「上下文经济学」成为刚需，检索替代阅读是少数有实测数字支撑的方案（后文详述其二点七倍与成本持平点）；其二，项目礼仪与众不同——任何人（包括 Agent）跑一次就能用，回报只需提交一份实测体验报告的 PR，仓库里已积累 190 份第一手反馈，形成了传播飞轮；其三，RC 版本每日发布、基准成绩单对败绩如实标注，工程可信度在技术社区口口相传。

四、架构原理

4.1 总体架构：16 个 crate 的纯 Rust 栈

XERJ 是一个从存储层写起的引擎，不是 Lucene 的封装。请求面与数据面各成一条流水线：

graph TB
    C["ES 客户端 / Kibana / Agent"] --> API["xerj-api：Axum HTTP :9200（es_compat + native）"]
    API --> Q["xerj-query：ES JSON 解析为 QueryNode 树 + 计划重写执行"]
    Q --> E["xerj-engine：Index::search 编排"]
    E --> S["xerj-storage：WAL + 分片 memtable + 不可变段"]
    E --> F["xerj-fts：BM25 + 分析器 + 倒排"]
    E --> V["xerj-vector：持久化 HNSW + 精确重打分"]
    E --> L["xerj-logs：列式日志 + 保留策略"]
    S --> Z["xerj-compress：LZ4 / Zstd 块压缩"]
    AI["xerj-ai：分块 / 嵌入代理 / 记忆存储"] --> E
    RA["xerj-cluster：内嵌 Raft（集群元数据）"] --> E

横切组件里值得注意的是 xerj-rerank（唯一会把文档文本发往外部服务的搜索期组件，默认关闭且可彻底禁用）与 xerj-wasm（可插拔的转换管线）。整栈只有一个 xerj-server 二进制入口。源码导读路径也有官方指引：REST 面看 es_compat.rs，ES JSON 解析看 parser.rs，检索与落盘的核心在 index.rs 的 Index::search 与 flush 两个实现——贡献者与审查代码的 Agent 都能按图索骥。

4.2 搜索与写入路径：memtable 与段的双查询

一条 POST /{index}/_search 的旅程是：Axum 处理器把 ES JSON 解析成 SearchRequest（QueryNode 树），Index::search() 同时扫描内存 memtable（分片 FTS）与磁盘段（FtsIndexReader + BM25），合并结果——刚写入的文档立即可搜，不需要等 flush。命中物化被限制在 from + size 个候选内，聚合在 size:0 时走列式快速路径，这是它在头对头测试里反超 ES 的地方（Agent 实际爱问的恰是计数、基数、直方图这类分析题）。

写入走 WAL：先追加预写日志（全局原子序号），再进按 2 的幂分片（上限 256）的存储与 FTS 双 memtable，flush 时每个分片各自落成带 LZ4/Zstd 块压缩的不可变段，后台合并压实小段。恢复逻辑无外部协调者：重启时重放 WAL 重建两类 memtable，文档数 = 段内 + memtable。耐久性是按对抗方式验证的——随机崩溃时序矩阵里 11/11 个单元的已确认删除都在重启后存活，合并被结构性设计为「读不动的输入大声中止并保持输入活跃」，不存在静默丢文档。

4.3 混合检索：HNSW 精确重打分与「诚实」的嵌入器

向量侧的选型相当克制：非过滤的顶层 kNN 由持久化 HNSW 图服务，但候选会用精确路径重打分，返回分数与暴力扫描逐位一致——官方基准 recall@10 为 1.00，100 探针均值 0.976（ES 8.13.4 同协议 0.937）；过滤查询、非余弦相似度、SQ8 量化与小索引则干脆退回精确扫描。语义检索的默认嵌入器是 384 维词法特征哈希，文档诚实地标注为「混合词法+向量」而非神经；需要真语义时用 --embed-mode neural 切到内置 Candle 后端（约 90 MB 模型，含在 61.6 MB 二进制里的只有 3.4 MB 推理壳），另有实验性 ONNX 通道，模型契约钉死为 all-MiniLM-L6-v2 兼容的 384 维 FP32 导出，接口不符直接报错而不是猜。为什么默认不上一把神经模型？官方的理由是隐私与零依赖：语义召回应当开箱离线可用，不引外部嵌入服务、不让文本出机；换神经模式是刻意保留的可选升级而非默认。这与业界「效果优先先上云」的惯性相反，却与它「Agent 的本机引擎」的定位自洽。BM25 与向量分数在同一执行器里融合（RRF 或线性），一套查询 DSL 同时拿全文、结构化与语义三种召回。

4.4 autoindex：给 Agent 的数据平面

xerj autoindex <文件夹> 是产品的心脏。它按内容（从不按扩展名）嗅探每个文件，流式抽取 13 个格式族——代码走 tree-sitter 得到符号与行号的 AST 感知索引，CSV/JSON/SQLite/PDF/DOCX/EPUB/Jupyter/mbox（含 Google Takeout）甚至 Unity 场景都各有专属抽取器，推断类型与日期编码，垃圾文件记录而不致命，kill -9 后可续跑。速度参考：对 6,113 个源文件的 Lucene 检出，单线程进程内抽取约 1,500 文件/秒（13 MB/s），其中 tree-sitter 解析占 72%，是单文件下限；重索引按内容哈希增量跳过，典型编辑场景 95% 以上文件零成本。质量上，autoindex 管线在 1,995 文件的秘密清单语料上过了 80/81 个真值检查。索引完后 autoindex map 把数据集、计数、字段示例值、跨数据集关联与现成查询反向喂给 Agent——「这里有什么」不用再猜。

4.5 ES 兼容层：用一致性测试当规格

XERJ 把「Elasticsearch 兼容」做成了可证伪的工程声明：es-yaml-runner 直接执行 ES 8.13 官方 REST 规范的 YAML 套件（search、聚合、向量、bulk、indices、scroll、cluster），硬门禁是零失败——XERJ 返回与测试预期不同，错的是 XERJ。当前 1366/1369 通过，剩下 3 个缺口公开列在仓库里。Kibana 与各家官方客户端库因此可以直接指向 localhost:9200。一个语义差异值得知道：scroll 是有界的预先快照而非走段游标，查询精确总数超出快照窗口会返回 400 而非静默截断，大结果集请用 search_after。

4.6 Agent 接口面：MCP、记忆与第二大脑

xerj mcp 用同一个二进制起一个 stdio MCP 服务器，代理到本地节点，暴露 13 个工具：11 个是已有端点的薄代理（DSL 搜索、语义/向量/混合搜索、xerj_memory_store/recall 记忆读写等），另有 xerj_map（返回 autoindex 目录的字段地图）与 xerj_code_search（直接跑 reference-coding 管线）。工具 schema 从运行中的 tools/list 自动生成、CI 门禁防漂移。/_memory/{namespace} 是持久记忆：存入、按文本/语义/向量召回、去重、元数据过滤、新近度混合；在此之上还有「第二大脑」/_graph 路由——断言与退役带证据的文档间链接、ego/overview 两类视图、八个关系探测器、两跳遍历上限，保留命名空间 .xerj-memory-* 充当租户边界。值得一提的克制：xerj_plan 把自然语言过滤器翻成校验过的查询 DSL，是确定性规则实现，不调 LLM；可选的 Jev 重排是把命中文本发往外部评判服务，默认关闭——外发边界在文档里逐条列明。

4.7 性能与设计取舍

单静态二进制 61.6 MB、无 JVM、亚秒冷启动，Agent 可以把自己的搜索引擎当子进程工具拉起——这是对「Agent 即操作者」最彻底的形态让步，代价是没有 ES 二十年打磨的分布式纵深（集群元数据用内嵌 Raft，但大规模部署尚未有公开案例）。头对头测试对活体 Elasticsearch 8.13.4 全矩阵 55 胜 26 平 4 负：1.72 倍写入吞吐、1.61 倍更小磁盘、列式聚合快路径反超；四场败绩全部是「高倍率写入者的读 p99」，根因写成了公开复盘文档。项目的基准政策是数字须独立对抗复测后才发布，复测若对 XERJ 不利，公开数字当天就改——这在开源搜索引擎里是罕见的纪律。

五、应用场景

场景一：reference coding——让 Agent 先查再写

痛点：coding agent 凭记忆写陌生 API 会反复重试循环，grep 又只给行号，读文件吞上下文。 用法：把与目标问题最相近的开源仓库 clone 下来，xerj autoindex 建索引，Agent 写代码前先检索同类问题的现成解法。官方三臂对照（同一 Claude Code：裸记忆 / 自行 grep / XERJ 检索注入，隐藏测试判卷）给了硬数字：在模型绝无可能背过的 13 个参考库、5 种语言上，裸记忆 21 跑只对 1、烧掉 21.9 美元；grep 与 XERJ 都全对，但 XERJ 输出 token 9,982 对 26,477（2.7 倍差），成本 1.58 对 3.27 美元；一个 Java 任务上裸记忆写出 503 行追加日志仍违约，XERJ 用 103 输出 token 给出正确的 4 行解。配套的成本模型也直白：Opus 5 上输出价是缓存输入价的 50 倍，一个 800 输出 token 的重试圈最多值得 4 万缓存上下文 token 的检索投入。 适用边界：对模型已背熟的流行公共库，检索中性甚至有害——实测里模型能凭记忆复述 256 值量化表，此时裸记忆最便宜。红利区间是私有、内部、小众与截止日期之后的代码。

场景二：Agent 长期记忆与第二大脑

痛点：跨会话记忆要么存文件丢语义，要么单独架向量库加嵌入服务。 用法：MCP 客户端配一段 JSON（xerj mcp + XERJ_URL）即可让桌面 Agent 获得 xerj_memory_store/recall：工作中学到的事实按命名空间落库，召回支持按文本、语义或向量三种方式，附带去重、元数据过滤与新近度混合；需要知识图谱时用 /_graph 断言带证据的链接、两跳内扩展邻域——每条边都记录是谁基于什么断言的，防止 Agent 把自己的幻觉当成既定事实。全部留在本机。 适用边界：记忆质量取决于检索，默认嵌入器是词法的，纯语义联想要开神经模式。

场景三：代码与语料的安全审计

痛点：审计工具逐文件扫描慢且跨格式难。 用法：autoindex 整棵目标树后，用 ES 查询一次横扫所有文件类型找 sink 模式、密钥与危险调用。官方对 WordPress 核心的实例：1,492 个 PHP 文件约 2.6 万 token 完成跨树审计（约占整棵树 0.5%）。 适用边界：AST 索引覆盖 tree-sitter 支持的语言；二进制 artefact 不在射程内。

场景四：日志分析与 Elasticsearch 平替

痛点：ES 的 JVM 内存与运维成本对个人与小团队过重。 用法：兼容协议意味着 Filebeat/Logstash 类采集端与 Kibana 直连不改配置；混合日志格式被 autoindex 抽成带类型的索引，聚合、直方图、分位一应俱全。 适用边界：四项败绩集中在写洪水下的读 p99——高并发写入+重读的生产监控场景要先自测；scroll 语义差异影响导出工具。

六、快速上手

curl -fsSL https://xerj.org/get | sh          # 单二进制，装到 ~/.local/bin
xerj --insecure --data-dir ./data &           # 开发机：仅绑 127.0.0.1，无 TLS 无鉴权
xerj autoindex ~/my-project                   # 一条命令索引任意文件夹
curl "localhost:9200/ax-*/_search?q=checkout+error"
xerj gain                                     # 汇报它帮你省了多少

生产或共享主机一律去掉 --insecure：默认开启鉴权、首启生成 <data-dir>/admin.key，客户端带 XERJ_API_KEY 或 --api-key。接入 Claude Code/Cursor 用 MCP 配置：

{
  "mcpServers": {
    "xerj": {
      "command": "/home/you/.local/bin/xerj",
      "args": ["mcp"],
      "env": { "XERJ_URL": "http://localhost:9200" }
    }
  }
}

最短验证路径是把这句提示词丢给任何 Agent：「读 https://xerj.org/llms.txt ，把 XERJ 设为你的搜索后端，索引 ./docs，然后对每个索引给我一条示例查询。」

七、横向对比

方案	定位	检索能力	Agent 适配	形态	License
XERJ	Agent-first 搜索/向量/日志	BM25 + HNSW kNN + 混合 RRF，AST 感知代码索引	autoindex / 记忆 / 第二大脑 / MCP 13 工具 / llms.txt	61.6 MB 单二进制，无 JVM	Apache-2.0
Elasticsearch 8.13	通用搜索与分析平台	同类能力最全 + 二十年生态	需人工建模与 ingest 管线	JVM 集群	Elastic v2（非纯开源）
Qdrant	纯向量数据库	HNSW/量化向量检索	需外接全文与编排	单二进制/云	Apache-2.0
Meilisearch	面向应用的轻量全文搜索	词法容错搜索为主	REST API，无记忆/Agent 面	单二进制	MIT

（对 ES 的胜负数字来自 XERJ 官方头对头成绩单，方法学与复现脚本公开；Qdrant、Meilisearch 定位描述为项目官方口径，截至 2026-10-17。）与「grep + 临时拼 RAG」的自建路线相比，XERJ 的差异不在单点能力而在交付形态：索引、数据画像、记忆、协议适配与 schema 一站俱全，且全部可离线。

八、局限、风险与社区观察

项目很年轻。 2026-06-30 创建、还在 v1.0 RC 阶段，RC 几乎每日一发，接口与索引格式在 1.0 前仍可能变动；6.6k 星的社区规模意味着踩坑要更多靠自己，好在贡献模型把「跑一次、写一份体验报告 PR」设为最低门槛（此类 PR 豁免 CLA，代码贡献则需一次性签署），仓库已沉淀 190 份第一手反馈可检索。

实测语料是合成的。 reference-coding 案例的 13 个参考库专为「确保不在训练集里」而造，真实私有代码库这一端未测；官方在诚信声明里写明 native-vs-xerj 的差距是在小参考语料上测的（grep 对特征名本就精准），优势在大型私有语料上「应当放大但未验证」。服务端检索增强（富符号 + 标识符分词）经实测在该语料上无提升，也被如实记录。

语义检索默认打折。 默认嵌入器是词法特征哈希，semantic_text 的「语义」成色有限；神经模式（Candle 后端）与 ONNX 通道都标注实验性。基准面的已知短板是写洪水下的读 p99。此外 --insecure 的信任边界要牢记：任何能连上端口的调用者都是超用户，可读可删包括记忆命名空间在内的一切索引——这明确是单机开发形态，不是服务形态。

九、小结与行动建议

XERJ 把「给 Agent 一个引擎」拆成了三件可验证的事：一条命令的索引平面、一张自描述的数据地图、一套带语义召回的持久记忆，再用 ES 协议兼容清空迁移成本。给四类读者的建议：

• 重度 coding agent 用户：先在私有代码库上跑 reference-coding 一周，用 xerj gain 量化收益再决定是否常驻；对公共库为主的项目预期收益有限。
• Agent 应用开发者：把 /_memory 与 MCP 工具当免费的本机记忆层接入，绕开自架向量库；需要强语义时再评估开神经模式的成本。
• ES 小用户：用一致性套件通过率与官方成绩单自查你的工作负载，写少读多的分析场景值得一试；导出类工具注意 scroll 语义差异。
• 研究者：它的「诚信基准」流程（独立对抗复测、败绩复盘公开、合成语料的边界声明）本身就值得当成评测方法论参考。

参考资料

1. xerj-org/xerj 仓库（star、涨星、案例与基准入口，数据获取于 2026-10-17）
2. docs/ARCHITECTURE.md（crate 布局、搜索/写入路径、恢复机制）
3. docs/WHY_XERJ.md（设计论纲：上手/定向/连续性三痛点与工程立场）
4. reference-coding 案例研究与成本模型（三臂实测、损益平衡公式、失效模式）
5. xerj.org/benchmarks（对 Elasticsearch 8.13.4 的全矩阵成绩单）
6. docs/SECOND_BRAIN.md（第二大脑图谱、八探测器与两跳上限）
7. MCP 工具 schema与 llms.txt（Agent 接口面的机读契约）
8. docs/EXPERIMENTAL_ONNX.md（神经嵌入通道的模型契约）