Mintlify, AI 문서 어시스턴트에서 RAG 걷어내고 가상 파일시스템으로 교체 — 세션 생성 46초→100ms

• Mintlify가 AI 문서 어시스턴트의 RAG를 들어내고 가상 파일시스템(ChromaFs)으로 교체했음
  • 핵심 발상은 단순함 — 에이전트한테 진짜 파일시스템이 필요한 게 아니라 "파일시스템처럼 보이는 것"만 있으면 됨
  • 문서가 이미 Chroma DB에 인덱싱되어 있으니, UNIX 명령어를 DB 쿼리로 번역하는 레이어를 얹은 것

왜 샌드박스를 버렸나

• 기존에는 격리된 샌드박스를 띄우고 GitHub 레포를 클론하는 방식이었음
  • 백그라운드 에이전트라면 괜찮은데, 프론트엔드 어시스턴트에서는 유저가 로딩 스피너를 멍하니 쳐다보는 상황이 됨
  • 샌드박스 1개당 vCPU 1개 + 2GiB RAM + 5분 세션 기준으로 계산하면, 월 85만 대화에 연간 약 $70,000이 날아감

ChromaFs 구조

• Vercel Labs의 just-bash (bash의 TypeScript 재구현) 위에 구축함

  • grep, cat, ls, find, cd를 지원하고, 파싱과 파이핑은 just-bash가 처리
  • ChromaFs는 IFileSystem 인터페이스만 구현해서 파일시스템 호출을 Chroma 쿼리로 변환

• 디렉토리 트리는 gzip 압축된 JSON 문서(__path_tree__) 하나로 저장됨

  • 초기화 시 이걸 풀어서 Set<string> (파일 경로)과 Map<string, string[]> (디렉토리→자식) 두 개의 인메모리 구조로 올림
  • ls, cd, find는 네트워크 콜 없이 로컬에서 바로 처리 — 후속 세션엔 캐시까지 적용

• 접근 제어도 깔끔하게 해결함

  • 각 경로에 isPublic과 groups 필드가 있어서, 세션 토큰 기반으로 트리 빌드 전에 가지치기
  • chmod나 Linux 유저 그룹, 티어별 컨테이너 이미지 같은 건 필요 없음 — 코드 레벨에서 필터링

페이지 재조립과 grep 최적화

• cat /auth/oauth.mdx 실행 시, Chroma에서 해당 청크들을 전부 가져와 인덱스 순서로 정렬 후 합침

  • 결과는 캐시되어 반복 조회 방지
  • 대용량 파일(S3에 올린 OpenAPI 스펙 등)은 lazy 포인터로 접근 시에만 로드
  • 쓰기 연산은 전부 EROFS(Read-Only File System) 에러 반환 — 에이전트 간 오염 방지

• grep 최적화가 특히 인상적임 — 재귀 grep이 밀리초 단위로 끝남

  • 1단계(Coarse Filter): Chroma의 $contains/$regex로 매칭 가능한 파일 목록을 먼저 추림
  • 2단계(Fine Filter): 매칭된 청크를 Redis에 벌크 프리페치 → grep을 해당 파일만 대상으로 재작성 → just-bash에서 로컬 실행

sequenceDiagram
    participant 에이전트
    participant ChromaFs
    participant ChromaDB
    participant Redis
    participant JustBash

    에이전트->>ChromaFs: grep -r "OAuth" /docs
    ChromaFs->>ChromaDB: $contains 쿼리로 후보 파일 필터
    ChromaDB-->>ChromaFs: 매칭 파일 목록 반환
    ChromaFs->>Redis: 매칭 청크 벌크 프리페치
    Redis-->>ChromaFs: 캐시된 청크 반환
    ChromaFs->>JustBash: 대상 파일만으로 grep 재작성 실행
    JustBash-->>에이전트: 로컬 grep 결과 반환

운영 결과

• 현재 3만 건 이상의 일일 대화를 처리하고 있고, 수십만 유저가 사용 중
  • 세션 생성 즉시 완료, 추가 컴퓨팅 비용 제로, 별도 인프라 없이 RBAC까지 내장

기술 맥락

• RAG가 AI 어시스턴트의 표준 패턴으로 자리 잡았지만, "문서 탐색"이라는 유스케이스에서는 생각보다 비효율적이에요. 유저가 물어볼 때마다 임베딩 검색을 돌리는 것보다, 에이전트가 직접 ls와 grep으로 문서 구조를 탐색하는 게 더 자연스러운 패턴이거든요
• 여기서 핵심은 "진짜 파일시스템이 필요하냐?"라는 질문이에요. 샌드박스를 띄우면 격리성은 확보되지만, 문서 어시스턴트는 읽기만 하면 되니까 EROFS로 쓰기를 막아버리면 가상 FS로도 충분해요
• just-bash를 기반으로 한 것도 영리한 선택이에요. bash 파싱과 파이핑이라는 복잡한 부분을 이미 검증된 구현체에 위임하고, ChromaFs는 파일시스템 인터페이스만 구현하면 되니까 코드량이 최소화돼요
• grep 최적화의 2단계 필터 전략은 검색 엔진에서 흔히 쓰이는 패턴인데, 여기선 Chroma의 메타데이터 필터를 coarse filter로, Redis 캐시를 fine filter의 데이터 소스로 활용한 점이 깔끔해요. 전체 문서를 스캔하지 않으니 재귀 grep도 밀리초 단위로 끝나는 거예요