grep 대신 인덱스를 쥐여 준다: xerj-org/xerj v1.0.0-rc.96의 autoindex·ES 호환 엔진·에이전트 메모리 심층 해부

코딩 에이전트에게 낯선 코드베이스를 맡기면 가장 먼저 새는 건 돈이 아니라 컨텍스트다. grep은 ‘어느 줄’인지는 알려 주지만, 그 줄이 정답인지 판단하려면 결국 파일을 통째로 읽어야 한다. 오늘(2026-10-17) GitHub Trending Rust 일간 1위에 오른 xerj-org/xerj는 이 문제를 “에이전트 옆에 검색 엔진을 하나 띄워 주자”로 푼다. 폴더를 가리키면 스키마 없이 알아서 인덱싱하고(autoindex), Elasticsearch 8.x 와이어 프로토콜로 질의를 받고, MCP로 에이전트에 꽂히며, /_memory로 장기 기억까지 맡는 단일 Rust 바이너리다.

이 글은 설치 튜토리얼이 아니라 실무자 관점의 해부다. 저장소 구조와 크레이트 계층, autoindex 파이프라인, 검색·벡터·메모리 경로, 보안 경계, 그리고 박스에서 직접 돌린 rc.96 스모크 결과(좋은 것과 걸리는 것 모두)를 정리했다. 수치는 모두 2026-10-17 오전(KST)에 확인한 값이며, 프로젝트 자체 측정치는 “프로젝트 주장”으로 구분해 적었다.

한눈에 보기: 오늘 체크아웃 기준

무엇을 해결하려는가: ‘읽기’를 ‘질의’로 바꾸기

문서 docs/WHY_XERJ.md는 이 프로젝트를 “Rust로 다시 쓴 Elasticsearch”로 읽지 말라고 못 박는다. 설계 대상은 대시보드를 보는 사람이 아니라 AI 에이전트이고, ES 호환은 Postgres 프로토콜을 말하는 CockroachDB처럼 ‘도입 다리’일 뿐이라는 입장이다. 에이전트가 처음 보는 데이터 앞에서 겪는 세 가지 문제를 이렇게 정의한다.

대표 사용처로 내세우는 건 reference coding이다. 지금 짜려는 기능과 가장 가까운 오픈소스 저장소를 클론·인덱싱해 두고, 코드를 쓰기 전에 “그 프로젝트는 이걸 어떻게 풀었나”를 구절 단위로 꺼내 쓰게 하는 루프다. 이 루프는 바이너리에 xerj corpus / xerj code 서브커맨드로 들어 있다.

프로젝트가 공개한 reference coding 측정치

README 기준 8개 과제·4개 언어·조건당 16회, 실제 claude -p 토큰 집계다. 즉 grep 대비 출력 토큰 2.7배 절감, 같은 해결률이라는 주장이다. 다만 프로젝트 스스로 “모델이 외운 코드인지가 효과를 가른다”고 적는다. 사내·니치·컷오프 이후 코드에서는 이득이 크지만, 모델이 이미 잘 아는 유명 라이브러리에서는 중립이거나 오히려 해롭다. 사용자 체감 “약 5배” 수치는 field report 기반이라 통제 실험이 아니다.

아키텍처: 바이너리 하나, 리스너 셋, 크레이트 열여덟

docs/ARCHITECTURE.md의 조감도는 HTTP 계층(xerj-api, Axum) 아래에 질의 파서(xerj-query), 통합 엔진(xerj-engine), 그 밑으로 저장·전문검색·벡터·로그·압축 크레이트가 깔리는 구조다. 박스에서 서버를 띄우면 리스너가 세 개 열린다: 127.0.0.1:9200(ES 호환), :8080(native REST), :8081(gRPC). GET /는 ES 8.13.0 모양의 응답을 돌려줘 기존 클라이언트가 그대로 붙는다.

쓰기·읽기·복구 경로

실무적으로 의미 있는 대목은 “flush 전후로 답이 바뀌는” 버그 클래스를 계속 잡고 있다는 점이다. rc.96 CHANGELOG의 첫 항목들이 바로 그것이다 — 추론된 text 필드가 doc_values: true로 남아 flush 이후 terms가 토큰화되지 않은 원문으로 답하던 문제, 같은 조건에서 term이 flush 후 0건으로 떨어지던 문제, 세그먼트를 가로지르는 페이지의 동점 정렬(score DESC, seq_no ASC, _id ASC)이 깨지던 문제가 수정됐다. 엔진이 젊다는 신호이자, 회귀를 공개적으로 추적한다는 신호다.

autoindex: ‘스키마 없음’은 어떻게 가능한가

autoindex는 확장자가 아니라 바이트 내용으로 포맷을 판별(sniff)하고, 데이터셋 단위로 인덱스를 쪼갠다. 소스 코드는 tree-sitter로 파싱돼 심볼·종류(function/struct/const…)·시작/끝 줄 번호가 필드로 들어가므로, 에이전트는 “줄”이 아니라 “함수”를 받는다. 실패는 치명적이지 않고 junk로 기록되며, kill -9 이후 재개 가능하다는 것이 설계 원칙이다.

방어적 설계도 눈에 띈다. ROADMAP에 따르면 .xls를 읽는 calamine 0.26.1이 악성 BIFF에 panic-safe하지 않고 엔진은 panic=abort로 빌드되므로, .xls는 rlimit이 걸린 xerj __extract-xls 워커 서브프로세스에서 파싱한다. 신뢰할 수 없는 덤프를 인덱싱해도 죽는 건 워커뿐이라는 얘기다. 재인덱싱은 콘텐츠 해시 기반 증분이라 바이트가 같은 파일은 파싱을 건너뛴다(해시 계산 자체는 매번 수행).

검색·벡터·메모리: 세 개의 질의 표면

1) Elasticsearch 호환 질의

인덱스·문서·bulk·search·aggregations·mappings·kNN·scroll·reindex·_cat을 구현했고, ES 8.13 REST spec YAML 스위트 기반 적합성 테스트가 매 커밋 돈다. README 기준 1,366/1,369 통과이며 남은 격차는 테스트 디렉터리에 공개돼 있다. 한 가지 함정: scroll은 세그먼트를 걷는 커서가 아니라 상한이 있는 선행 스냅샷이라, 정확한 total이 창을 넘으면 조용히 잘라내지 않고 400을 돌려준다. 대량 내보내기는 search_after를 써야 한다.

2) 벡터·하이브리드

kNN은 필터 없는 경우 영속 HNSW 후보를 정확 재채점해 점수가 정확 경로와 비트 단위로 일치하도록 했고, 필터·비코사인·SQ8·소형 인덱스는 정확 스캔으로 떨어진다. 프로젝트 측정으로는 공식 벤치 쿼리 recall@10 1.00, 100-probe 평균 0.976(같은 프로토콜의 ES 8.13.4는 0.937)이다.

3) 에이전트 메모리 /_memory

메모리는 예약 네임스페이스 .xerj-memory-*에 저장되고, role_descriptors 없이 발급한 Unscoped 키로는 접근할 수 없다. 즉 “검색용 키”와 “기억용 키”를 분리할 수 있다는 점이 별도 벡터DB를 붙이는 구성보다 깔끔한 부분이다.

MCP: 13개 도구

xerj mcp는 노드를 띄우지 않는다. stdio로 클라이언트와, HTTP로 XERJ_URL(기본 http://localhost:9200)의 노드와 대화하는 프록시일 뿐이라 신뢰 경계는 노드 쪽 설정이 결정한다. 도구 스키마는 라이브 tools/list에서 생성해 CI(scripts/mcp-schema-check.sh)로 고정한다.

설치와 실행: README 명령 그대로

# 공식 원라이너(설치 스크립트)
curl -fsSL https://xerj.org/get | sh

# 로컬 개발: TLS·인증 끔(루프백 전용)
xerj --insecure --data-dir ./data &
xerj init                                  # Claude Code/Cursor에 MCP + skill 연결
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment"
xerj def "euler_to_rotationmatrix"
xerj gain                                  # 감사 로그 기반 실사용 집계

# 인증 켠 기본 기동(권장: 공유 호스트)
xerj --data-dir ./data &                   # 첫 부팅 시 admin.key 생성
export XERJ_API_KEY="$(cat ./data/admin.key)"
xerj autoindex ~/my-project

# reference coding 루프
xerj corpus add xerj-storage https://github.com/spacejam/sled
xerj corpus index xerj-storage
xerj code xerj-storage "how does sled fsync its WAL segment on rotation?"

# 소스 빌드 + 적합성 스위트
git clone https://github.com/xerj-org/xerj && cd xerj/engine
cargo build --release -p xerj-server
cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml

박스 스모크 테스트: rc.96을 직접 돌려 보니

환경: x86_64 Linux 박스, xerj-1.0.0-rc.96-x86_64-unknown-linux-musl.tar.gz(31.6MB)를 Releases에서 받아 sha256 일치 확인, --insecure --data-dir ./data로 루프백 기동. 코퍼스는 이 저장소의 xerj-autoindex·xerj-mcp 크레이트 사본(Rust 코드 + 테스트 픽스처). GPU·neural 임베더는 쓰지 않았다.

autoindex가 exit code 3(completed-with-junk)으로 끝난 이유는 테스트 픽스처 안의 zip/tgz 두 개를 열지 않았기 때문이다. 실패가 아니라 “아카이브는 풀어서 다시 돌려라”는 안내와 함께 기록된다 — CI에서 exit code를 그대로 성공/실패로 쓰면 오탐이 날 수 있으니 3을 별도 처리해야 한다.

한국어 메모리 회상: 기본값 그대로면 조심

원인은 단순하다. 기본 분석 경로에서는 조사가 붙은 어절(“MacBook에서”)이 하나의 토큰으로 남아, 어간만으로는 매치되지 않았다. xerj-fts에는 한글·한자·가나를 바이그램으로 쪼개는 cjk 분석기가 들어 있으므로 한국어 문서 인덱스는 매핑에서 이를 지정하는 것이 맞고, 메모리를 ‘의미’로 회상하려면 --embed-mode neural(또는 proxy)을 켜야 한다. 기본 lexical 임베더로 semantic 회상을 기대하면 위처럼 동률 점수가 나온다. 이건 문서가 이미 정직하게 경고한 부분이지만, 한국어 사용자에게는 체감 차이가 크다.

보안 모델: –insecure는 진짜로 ‘슈퍼유저’다

새 노드는 127.0.0.1에만 바인딩하고, TLS가 꺼진 상태로 다른 인터페이스에 바인딩하려 하면 server.allow_insecure_network_bind = true를 명시하지 않는 한 기동을 거부한다. 반대로 말하면 README의 빠른 시작(--insecure)을 팀 서버에 그대로 옮기면, 포트에 닿는 모든 호출자가 모든 인덱스와 모든 에이전트 기억을 읽고 지울 수 있다. 외부로 텍스트가 나가는 경로는 문서가 전부 열거한다: rerank(TypeSafe의 Jev로 상위 hit 텍스트 전송), proxy 임베딩, WAL tap. 셋 다 운영자가 켜야 동작한다.

대안과 비교: 어디에 놓을 도구인가

정리하면 XERJ의 경쟁자는 ES의 쿼리 DSL이 아니라 “폴더를 에이전트가 답할 수 있게 만들려고 사람이 짜는 수집 파이프라인”이다. 프로젝트 문서도 그렇게 평가해 달라고 요청한다. 이미 ES/OpenSearch 클러스터와 한국어 분석기를 운영 중이라면 XERJ는 대체재라기보다 에이전트 전용 로컬 사이드카로 보는 편이 현실적이다.

벤치마크를 읽는 법

프로젝트는 “재현하지 못한 수치는 우리 것까지 의심하라”고 적고, 패배 4건을 별도 문서로 남겼다. 태도는 좋지만 모두 자체 하네스 결과라는 점은 변하지 않는다. 도입 전에는 demo/playbooks와 scripts/bench/로 자기 코퍼스에서 다시 재 보는 것이 맞다.

한계와 주의점 체크리스트

도입 판단 가이드

XERJ가 오늘 Rust 트렌딩 꼭대기에 오른 이유는 “ES를 Rust로 다시 썼다”가 아니라, 에이전트가 파일을 읽는 대신 질의하게 만드는 온보딩·오리엔테이션·기억을 바이너리 하나에 묶었기 때문이다. 박스에서 확인한 범위에서는 autoindex·def·ES 집계·증분 재인덱싱이 문서대로 동작했고, 걸리는 지점은 한국어 기본 분석, 메모리 점유, rc 단계의 성숙도였다. 사내 코드나 잡다한 조사 폴더를 에이전트에게 맡기고 있다면, 루프백 전용 --data-dir 하나로 반나절 시험해 볼 가치는 충분하다.