RAG 대신 가상 파일시스템: Mintlify가 AI 문서 어시스턴트를 재설계한 방법

AI 문서 어시스턴트를 만들 때 가장 먼저 떠오르는 방법은 **RAG(Retrieval-Augmented Generation)**다. 문서를 청크로 잘라 벡터 DB에 저장하고, 사용자 질의와 유사한 청크를 찾아 LLM에 주입하는 방식이다.

그런데 Mintlify는 이 방식을 버렸다. 대신 에이전트에게 가상 파일시스템을 제공하는 방향을 선택했다. 결과는 놀라웠다: 세션 부팅 시간 46초 → 100ms, 대화당 추가 비용 $0.0137 → $0으로 줄었다. HN에서 200점 이상을 기록하며 개발자들의 주목을 받았다.

RAG의 한계: 무엇이 문제였는가

RAG는 분명히 유용하다. 하지만 Mintlify가 운영하면서 맞닥뜨린 한계는 명확했다.

첫째, 분산된 정보 취합이 안 된다. 답이 여러 페이지에 걸쳐 있을 때, Top-K 청크 검색은 그 조각들을 정확히 모아주지 못한다. "이 API 파라미터의 타입은 뭔가요?"라는 질문이 레퍼런스 페이지와 가이드 페이지 둘 다에 걸쳐 있다면, RAG는 둘 중 하나만 가져올 가능성이 높다.

둘째, 정확한 구문을 못 찾는다. 개발자는 종종 exact_function_name 같은 정확한 문자열을 찾는다. 의미론적 유사도 기반 검색은 이 경우 실패하기 쉽다. grep은 이걸 완벽하게 해결한다.

셋째, 에이전트가 스스로 탐색할 수 없다. RAG에서 에이전트는 수동적이다. 검색 결과가 부족해도 "다른 폴더도 봐야 할까?"를 스스로 판단할 수 없다.

ChromaFS: 가상 파일시스템의 작동 원리

Mintlify의 해결책은 간단하지만 우아하다. 에이전트에게 실제 파일시스템을 주는 대신, 파일시스템처럼 느껴지는 환경을 만들어준다.

핵심은 just-bash(Vercel Labs)라는 TypeScript 기반 bash 재구현체다. grep, cat, ls, find, cd 명령어를 지원하며, 플러그인 가능한 IFileSystem 인터페이스를 제공한다. Mintlify는 이 인터페이스 위에 ChromaFS를 구현했다. 모든 파일시스템 명령이 실제 디스크 대신 Chroma 벡터 DB 쿼리로 변환된다.

ChromaFS vs 실제 샌드박스 성능 비교

월 85만 건의 대화를 처리하는 Mintlify에서 대화당 $0.0137이면 연간 약 $14만 달러의 비용이다. ChromaFS로 이 비용이 사실상 0에 가까워진다.

디렉토리 트리 부트스트래핑과 접근 제어

ChromaFS의 기술적 구현에서 가장 흥미로운 부분은 접근 제어다.

파일 트리는 Chroma 컬렉션 내에 __path_tree__라는 gzip JSON 문서로 저장된다. 각 경로에는 isPublic과 groups 필드가 있어, 사용자의 세션 토큰에 따라 접근 가능한 파일 목록이 동적으로 달라진다. 에이전트는 접근 권한이 없는 파일이 존재한다는 사실조차 알 수 없다.

{
  "auth/oauth": { "isPublic": true, "groups": [] },
  "internal/billing": { "isPublic": false, "groups": ["admin", "billing"] }
}

초기화 이후 ls, cd, find 명령은 로컬 메모리의 트리를 사용하므로 네트워크 호출이 없다. 같은 사이트에 대한 이후 세션은 캐시된 트리를 재사용한다.

AI 에이전트가 파일시스템으로 수렴하는 이유

Mintlify 팀은 블로그에서 흥미로운 관찰을 공유했다: "에이전트는 파일시스템을 기본 인터페이스로 수렴하고 있다." grep, cat, ls, find만 있으면 에이전트가 필요로 하는 모든 탐색이 가능하기 때문이다.

이는 AI 에이전트 보안 취약점 연구에서 논의된 에이전트 샌드박싱 문제와도 연결된다. 진짜 파일시스템 대신 가상 파일시스템을 제공하면, 에이전트가 의도치 않게 민감한 시스템 경로에 접근하는 위험도 차단된다.

또한 LiteLLM 공급망 공격 사례처럼 AI 인프라가 공격 대상이 되는 현실에서, 에이전트에게 실제 파일시스템 권한을 주는 것 자체가 리스크임을 ChromaFS는 역설적으로 보여준다.

한국 개발자를 위한 실용 가이드

Mintlify의 사례는 국내 SaaS·문서화 서비스를 개발하는 팀에게 직접 적용 가능한 인사이트를 담고 있다.

RAG를 언제 쓰고, 가상 파일시스템을 언제 써야 할까?

ChromaFS는 오픈소스로 공개되지 않았지만, just-bash 라이브러리는 공개되어 있다. 국내 개발자라면 Chroma, Qdrant, pgvector 등 자신이 사용하는 벡터 DB 위에 같은 개념을 구현할 수 있다.

Claude Code의 파일 구조 설계를 함께 참고하면, AI 에이전트가 코드베이스를 탐색하는 방식을 설계할 때 도움이 된다.

---

FAQ

Q1: RAG와 ChromaFS를 함께 사용할 수 있나요?

A: 가능합니다. ChromaFS는 파일시스템 명령을 Chroma 쿼리로 변환하므로, 내부적으로는 여전히 벡터 DB를 사용합니다. 의미론적 검색(grep -r의 의미론적 변형)과 정확한 문자열 검색을 함께 지원할 수 있습니다.

Q2: just-bash는 어디서 구할 수 있나요?

A: github.com/vercel-labs/just-bash에서 오픈소스로 제공됩니다. TypeScript로 구현된 bash 서브셋으로, 플러그인 파일시스템 인터페이스를 통해 어떤 백엔드든 연결할 수 있습니다.

Q3: 이 방식이 모든 문서 AI에 적용 가능한가요?

A: 구조화된 문서(기술 문서, API 레퍼런스, 코드베이스)에 특히 효과적입니다. 비구조화된 텍스트(뉴스, 소셜 미디어)는 의미론적 검색이 더 유리할 수 있어, 사용 사례에 따라 접근법을 선택해야 합니다.

Q4: 접근 제어(ACL)는 어떻게 구현되나요?

A: 파일 트리를 초기화할 때 사용자 세션 토큰을 기준으로 접근 가능한 경로만 포함합니다. 에이전트는 처음부터 권한 없는 경로의 존재를 모르므로, 실수로도 접근을 시도하지 않습니다.

Q5: 이 방식의 단점은 무엇인가요?

A: 문서가 자주 업데이트되는 경우 Chroma DB와 파일 트리의 동기화가 필요합니다. 또한 복잡한 자연어 질의('이 개념과 가장 관련 있는 섹션은?')는 단순 grep으로 해결하기 어려울 수 있어, 의미론적 검색 레이어를 추가로 구현해야 합니다.