XERJ: lập chỉ mục codebase để agent bớt tốn token hơn grep
XERJ là công cụ tìm kiếm AI cục bộ, lập chỉ mục code, tài liệu, log và PDF để agent truy hồi passage kèm file:line. Case study do dự án công bố ghi nhận ít output token hơn workflow grep trong bài thử nghiệm reference coding.
Agent sửa một lỗi trong codebase thường bắt đầu bằng grep, mở nhiều file rồi kéo cả những đoạn dài vào context. Vấn đề không chỉ là thời gian tìm kiếm: token cũng bị dùng cho rất nhiều nội dung không liên quan trực tiếp đến task.
XERJ đi theo hướng lập chỉ mục thư mục trước, sau đó trả về các passage được xếp hạng kèm file:line. Với developer dùng coding agent, đây là một lớp truy hồi để agent tìm bằng chứng trong codebase thay vì đọc file tuần tự.
XERJ là gì?
XERJ là công cụ tìm kiếm AI chạy cục bộ, viết bằng Rust và phát hành theo giấy phép Apache-2.0.
Theo README của dự án, lệnh autoindex có thể lập chỉ mục code, tài liệu, log, PDF, SQLite và CSV. Công cụ tự nhận dạng loại dữ liệu và tạo chỉ mục theo dataset, thay vì yêu cầu người dùng tự viết schema hoặc dựng pipeline.
Với mã nguồn, dự án cho biết XERJ dùng tree-sitter để lấy symbol và số dòng, không chỉ xử lý code như văn bản phẳng. Hai ví dụ lệnh được README nêu là:
sh
xerj search "how do we rotate the WAL segment"
xerj def "eulertorotationmatrix"
search trả về các passage đã xếp hạng cùng vị trí file:line.
def phục vụ nhu cầu tìm định nghĩa symbol, trả về vị trí và signature.
Với một monorepo, thư mục runbook hoặc tập log sự cố, mục tiêu là đưa vào context đúng đoạn cần thiết để agent phân tích và viết code, thay vì nạp nguyên file.
Case study của dự án: ít token hơn grep
Use case được XERJ nhấn mạnh là reference coding: agent tìm và lập chỉ mục các repository mã nguồn mở gần với bài toán đang làm, truy hồi cách chúng xử lý vấn đề rồi mới viết code.
Trong case study do dự án công bố, bài thử nghiệm gồm 8 task, 4 ngôn ngữ và 16 lần chạy cho mỗi phương án. Dự án cho biết các task dùng code mà model chưa ghi nhớ, với token count thực tế từ claude -p.
| Cách làm | Output tokens | Chi phí | Solved |
|---|---:|---:|---:|
| Chỉ dựa vào kiến thức model | 260.916 | 11,18 USD | 11/16 |
| Agent dùng grep | 26.477 | 3,27 USD | 16/16 |
| XERJ | 9.982 | 1,58 USD | 16/16 |
Theo số liệu này, XERJ dùng ít output token hơn grep khoảng 2,7 lần trong khi cùng đạt 16/16 task. README cũng nêu một task Java có chênh lệch tới 278 lần. Các field report trong repository ghi nhận mức giảm token khoảng 5 lần trong công việc thường ngày.
Tuy nhiên, đây là số liệu của chính dự án, không phải benchmark độc lập. README cũng nêu rõ lợi ích phụ thuộc vào mức độ model đã biết code: XERJ phù hợp hơn với code nội bộ, dữ liệu riêng, thư viện niche hoặc code mới. Với thư viện công khai phổ biến mà model đã nắm tốt, lớp truy hồi bổ sung có thể không đem lại lợi ích, thậm chí gây bất lợi.
Luồng cài đặt và lập chỉ mục cục bộ
README cung cấp quy trình sau cho môi trường phát triển cục bộ:
sh
curl -fsSL https://xerj.org/get | sh
xerj --insecure --data-dir ./data &
xerj init
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment"
xerj def "eulertorotationmatrix"
xerj gain
Ý nghĩa từng bước:
Cài XERJ.
Khởi động dịch vụ và lưu dữ liệu chỉ mục trong ./data.
Chạy xerj init để tích hợp với Claude Code hoặc Cursor qua MCP và skill, theo mô tả của README.
Lập chỉ mục project bằng xerj autoindex ~/my-project.
Dùng search để tìm passage theo câu hỏi; dùng def khi đã biết tên symbol.
Dùng xerj gain để xem số liệu lợi ích mà công cụ đã ghi nhận.
README minh họa rằng quá trình autoindex có thể hiển thị số dataset được suy luận, file bị bỏ qua, số file đang lập chỉ mục, worker và record đang hoạt động.
Để thử nghiệm thực tế, nên bắt đầu từ một repository nhỏ hoặc một thư mục gồm code, runbook và log. Đặt tiêu chí cụ thể: agent có tìm đúng hàm, cấu hình hoặc đoạn log nhanh và chính xác hơn workflow grep hiện tại hay không?
Dùng với agent và reference coding
README đưa ra prompt cài đặt cho agent như sau:
text
Install XERJ (docs: https://xerj.org/llms.txt), index this project's sources, and set up
reference coding: clone and index the open-source repos closest to what we're building,
and search how they solved a problem before writing code.
Một workflow hợp lý là:
Agent nhận task sửa lỗi hoặc thêm tính năng.
Agent tìm repository tham khảo gần với bài toán.
XERJ trả về các đoạn code liên quan thay vì buộc agent đọc file theo thứ tự.
Agent dùng kết quả truy hồi để đề xuất patch.
Developer vẫn kiểm tra API contract, test và sự khác biệt kiến trúc giữa dự án tham khảo với hệ thống của mình.
Ngoài reference coding, README định vị XERJ cho các nhu cầu:
Codebase Q&A và RAG: truy hồi passage kèm file:line từ repository.
Phân tích log và sự cố: lập chỉ mục dữ liệu nhiều định dạng.
Rà soát bảo mật phòng thủ: tìm kiếm pattern, secret hoặc lời gọi rủi ro trong cây mã nguồn.
Agent memory dài hạn: lưu và truy hồi thông tin theo namespace /memory/{namespace}.
Dự án cũng tuyên bố tương thích Elasticsearch. Tuy nhiên, tài liệu được cung cấp ở đây không mô tả chi tiết endpoint, phiên bản hay phạm vi tương thích; đội ngũ nên xác minh kỹ trước khi tích hợp vào hệ thống hiện có.
Lưu ý quan trọng về --insecure
Cờ --insecure không phải thiết lập để dùng cho môi trường chia sẻ. Theo README, cờ này tắt TLS và xác thực API key. Bất kỳ caller nào truy cập được cổng dịch vụ đều có quyền đọc và xóa mọi index, bao gồm các namespace /memory.
Dự án mô tả đây là ranh giới tin cậy dành cho một người dùng trên máy phát triển. Node mới mặc định bind vào 127.0.0.1; nếu bind cleartext sang interface khác, XERJ sẽ từ chối khởi động trừ khi người dùng chủ động cho phép.
Vì vậy, trước khi lập chỉ mục log, tài liệu vận hành hoặc code riêng, hãy coi thư mục --data-dir như một bản sao của dữ liệu nhạy cảm và kiểm soát quyền truy cập phù hợp.
Kết luận
XERJ không thay thế việc hiểu codebase hay review thay đổi do agent tạo ra. Giá trị của nó nằm ở việc giúp agent tìm đúng bằng chứng trước khi suy luận, đặc biệt với code riêng hoặc dữ liệu mà model chưa biết.
Nếu workflow hiện tại đang đầy các vòng grep → đọc file → grep tiếp, hãy thử lập chỉ mục một project cục bộ và đo bằng task thật của team. Case study của dự án cho thấy tiềm năng giảm token; giá trị thực tế sẽ phụ thuộc vào độ chính xác của kết quả truy hồi trong codebase của bạn.