에이전트 오프라인 검색이 너무 답답해서 로컬 검색 엔진 직접 만들어봤습니다

AI 에이전트 쓰다 보면 웹 검색 없이는 정말 한계가 크다는 걸 느끼게 됩니다. 그런데 에어갭 환경이거나 민감한 데이터를 다룰 때는 인터넷 접근을 열어줄 수가 없더라고요.

기존에 ZIM 서버나 오프라인 위키 도구들이 있긴 한데, 실제로 LLM이 쓰기엔 문제가 많았습니다. 거대한 HTML을 그대로 컨텍스트에 밀어넣거나, 검색이 너무 단순해서 원하는 문서를 못 찾는 식이었죠.

그래서 Claude Code의 Web-Fetch, Web-Search 도구를 역분석해서 드롭인 대체제를 만들었습니다. 핵심은 SQLite FTS5에 콘텐츠를 인덱싱하고 BM25 랭킹을 적용한 검색 엔진입니다. 제목 부스팅, 동의어 확장, 접두사 매칭까지 넣어서 LLM 입장에서는 실제 웹 검색과 거의 동일한 경험을 제공합니다.

Kiwix ZIM 아카이브뿐 아니라 크롤링 기능도 내장되어 있어서, 사내 Confluence나 프라이빗 문서도 함께 인덱싱할 수 있습니다. 아키텍처는 무거운 콘텐츠 서버를 중앙에 두고 에이전트는 경량 클라이언트만 돌리는 구조로 설계했습니다.

제공하는 도구는 Google Search(BM25 검색)와 visit_page(마크다운 반환) 두 가지입니다. 오프라인 에이전트나 로컬 스택을 구축하시는 분들께 도움이 되면 좋겠습니다.