1만 개 넘는 문서를 못 찾을 때, Claude와 페어링해서 만드는 로컬 검색기

핵심 요약 (TL;DR)

개발자 James Sparenberg가 개인 문서 1만 개 이상을 검색할 수 없어 Claude를 페어 프로그래머 삼아 만든 로컬 시맨틱 검색기 DocuBrowser가 HN 188포인트, GitHub 424스타로 급부상했습니다. SQLite FTS5 + Ollama nomic-embed-text 스택으로 인터넷·API 키·계정 없이 4GB RAM에서 돌아가고, GPL-3 배포입니다.

바이브코더가 마주치는 가장 확실한 아이디어의 원천은 '자기 자신의 반복 짜증'입니다. 노트북에 쌓인 PDF, ebook, docx, 마크다운 노트가 만 개를 넘어가면 macOS 스팟라이트도, 구글 드라이브도 못 찾아냅니다. 파일명으로 검색하니 필터가 잘못됐고, 본문으로 검색하려니 인덱스가 없죠. 이 짜증 하나에서 DocuBrowser가 나왔습니다.

스택 선택의 논리 — 왜 이 조합이었나

James Sparenberg가 고른 스택을 뜯어보면 판단이 보입니다. SQLite FTS5는 키워드 매칭용입니다. 정확한 단어가 기억나는 문서를 찾을 때 이만한 게 없습니다. Ollama의 nomic-embed-text 임베딩 모델은 시맨틱 서치용입니다. "작년에 읽은 리더십 관련 뭐였지"처럼 개념만 기억날 때 씁니다. dolphin3 LLM은 검색 결과를 요약합니다. 세 층이 겹치니 단어를 정확히 알든, 개념만 알든 어느 쪽으로도 진입할 수 있는 거예요.

의도적으로 뺀 것도 많습니다. 인터넷 연결 없이 돌아갑니다. OpenAI API 키가 없습니다. 계정도 없습니다. per-query 비용이 0입니다. 이 네 가지가 겹치면 개인 아카이브, 법무 자료, 의료 기록처럼 '클라우드에 못 올리는 도메인'이 열립니다. HN 톱 코멘터의 문장이 승점 요인을 정확히 짚습니다. "모든 개인 문서를 남의 클라우드에 밀어 넣는 게 싫다."

Claude 페어링의 흔적

DocuBrowser 리포지토리는 흥미로운 자기 인증을 담고 있습니다. README에 이렇게 쓰여 있습니다. "DocuBrowser is developed with Claude as an active coding partner." 여기서 그치지 않고, Claude 세션을 이어붙일 때 필요한 context 파일까지 리포에 커밋되어 있습니다. Claude Code나 Claude Desktop을 새 세션으로 열 때마다 이 파일을 붙여주면 이전 결정들이 승계되는 방식이죠.

아마 여러분도 최근 몇 주간 비슷한 워크플로우를 시도했을 겁니다. James의 리포는 그걸 남에게 보여줄 수 있는 형태로 정리한 첫 공개 사례에 가깝습니다.

재현해보고 싶다면 — 최소 스택

그대로 쓰는 게 가장 빠릅니다. Linux는 RPM·DEB·tgz, Windows는 zip, macOS는 dmg로 배포되고 있고, 소스는 github.com/linuxrebel/DocuBrowser에서 받을 수 있어요. 문서 포맷 13종 이상(PDF·docx·pptx·xlsx·ebook·마크다운 등)을 지원하고, PII 필터와 중복 감지까지 붙어 있습니다.

직접 축소판을 짜보고 싶다면 이 순서를 권합니다. (1) pdfplumber·python-docx로 텍스트를 추출합니다. (2) SQLite FTS5에 청크 단위로 넣습니다. (3) Ollama로 nomic-embed-text를 로컬 구동해 임베딩을 뽑습니다. (4) 검색 쿼리도 같은 모델로 임베딩해 코사인 유사도로 정렬합니다. 하루면 돌아가는 프로토타입이 나옵니다.

ollama pull nomic-embed-text
ollama pull dolphin3
# SQLite FTS5는 표준 sqlite3에 내장

FAQ

Q. 얼마나 큰 RAM이 필요한가요?
저자는 4GB RAM VM에서도 돌아간다고 명시했지만 8GB를 권장합니다. 임베딩 모델 자체가 몇백 MB를 차지합니다.

Q. 이미 Obsidian이나 Notion에서 검색되는데 굳이 왜?
Obsidian은 자기 vault 안만 봅니다. Notion은 클라우드로 문서를 올려야 하죠. DocuBrowser는 폴더에 있는 걸 그대로 인덱싱해 시맨틱 검색까지 붙입니다. 겹치지 않는 자리입니다.

Q. Claude와의 페어 프로그래밍 컨텍스트 파일은 어떻게 관리하나요?
DocuBrowser 리포의 예시가 참고할 만합니다. 세션 종료 전에 "이 결정 요약해줘"를 요청하고 그 응답을 커밋하는 게 실용적인 패턴입니다.

소스: DocuBrowser GitHub · HN 스레드