Membangun sistem file virtual sebagai pengganti RAG untuk asisten dokumen AI

• Untuk mengatasi keterbatasan pencarian berbasis RAG yang ada, pendekatannya diubah ke struktur sistem file virtual yang menyusun dokumen sebagai file dan direktori
• Diimplementasikan ChromaFs berbasis database Chroma yang dapat menjalankan perintah grep, cat, ls, find tanpa menyalin file sungguhan
• Dengan pendekatan ini, waktu pembuatan sesi dipangkas dari 46 detik menjadi 100 milidetik, dan biaya komputasi tambahan turun hingga mendekati 0 dolar
• Kontrol akses ditangani dengan filtering RBAC pada metadata path file, sehingga tidak perlu kontainer terpisah atau pengelolaan grup pengguna
• Hasilnya, asisten dokumen Mintlify dapat dioperasikan sebagai layanan skala besar dengan respons instan, biaya rendah, dan arsitektur stateless

---

Pendekatan sistem file virtual yang melampaui keterbatasan RAG

• Pencarian dokumen berbasis RAG sebelumnya hanya mengembalikan potongan teks yang cocok dengan kueri, sehingga sulit menjawab pertanyaan lintas banyak halaman atau melakukan pencarian frasa secara akurat
• Untuk mengatasinya, struktur dokumen diubah menjadi bentuk yang bisa dijelajahi seperti sistem file, dengan setiap halaman dokumen dipetakan sebagai file dan setiap section sebagai direktori
• Agen dapat menjelajahi dokumen secara langsung melalui perintah grep, cat, ls, find, sehingga dirancang agar pencarian dokumen terasa seperti developer menangani codebase

Masalah bottleneck kontainer

• Pendekatan umum adalah memberi agen lingkungan sandbox terisolasi dengan sistem file nyata dan menyalin repositori ke dalamnya
• Namun pada asisten frontend, latensi pembuatan sesi menjadi masalah serius, dengan waktu pembuatan sesi p90 sekitar 46 detik
• Dengan 850 ribu percakapan per bulan, bahkan pada konfigurasi minimum (1 vCPU, 2GiB RAM, sesi dipertahankan 5 menit), biaya infrastruktur tahunan bisa melebihi 70 ribu dolar
• Untuk menghilangkan bottleneck ini, dibutuhkan sistem file virtual yang merespons instan dan berjalan dengan biaya rendah

Implementasi shell virtual — ChromaFs

• Alih-alih sistem file nyata, yang disediakan hanya ilusi sistem file virtual
• Karena data dokumen yang ada sudah diindeks di database Chroma, maka dibangunlah ChromaFs di atasnya
• ChromaFs mencegat perintah UNIX lalu mengubahnya menjadi kueri Chroma
• Hasilnya, waktu pembuatan sesi turun dari 46 detik menjadi 100 milidetik, sementara biaya komputasi tambahan menjadi mendekati 0 dolar

Metric	Sandbox	ChromaFs
P90 Boot Time	~46 detik	~100ms
Marginal Compute Cost	~$0.0137/percakapan	~$0
Search Mechanism	pemindaian disk	kueri metadata DB
Infrastructure	sandbox eksternal seperti Daytona	memakai ulang DB yang ada

• Diimplementasikan berbasis just-bash (Vercel Labs), dengan dukungan perintah grep, cat, ls, find, cd
• Dengan memanfaatkan interface IFileSystem milik just-bash, pemrosesan pipe dan logika flag tetap dipertahankan sambil mengubah panggilan akses file menjadi kueri Chroma

Bootstrapping pohon direktori

• Karena ChromaFs perlu mengetahui file apa saja yang ada sebelum dijalankan, seluruh pohon file disimpan di koleksi Chroma dalam bentuk JSON terkompresi (__path_tree__)
• Saat inisialisasi server, data ini diambil lalu dipulihkan menjadi dua struktur memori
  • Set<string> untuk path file
  • Map<string, string[]> untuk daftar anak pada tiap direktori
• Setelah itu, perintah ls, cd, find diproses secara instan di memori lokal tanpa panggilan jaringan, dan sesi berikutnya pada situs yang sama menggunakan ulang pohon yang sudah di-cache

Kontrol akses

• Pohon path mencakup field isPublic dan groups, lalu hanya menyisakan file yang dapat diakses berdasarkan token sesi pengguna
• File tanpa izin akses dihapus sepenuhnya dari pohon, sehingga agen tidak dapat mengenali path tersebut
• Pada sandbox konvensional, ini biasanya memerlukan pengelolaan grup pengguna Linux, chmod, atau pemisahan kontainer, tetapi di ChromaFs RBAC dapat diimplementasikan hanya dengan logika filtering sederhana

Path	Access	Visible
/auth/oauth.mdx	public	✓
/auth/api-keys.mdx	public	✓
/internal/billing.mdx	admin, billing	✗
/api-reference/users.mdx	public	✓
/api-reference/payments.mdx	billing	✗

Penyusunan ulang potongan dokumen

• Dokumen yang disimpan di Chroma dipecah menjadi beberapa chunk untuk embedding
• Saat cat /auth/oauth.mdx dijalankan, semua chunk dengan slug page yang sama diambil, diurutkan berdasarkan chunk_index, lalu digabungkan
• Hasilnya di-cache sehingga pada workflow grep berulang tidak perlu melakukan kueri ulang ke DB
• OpenAPI spec berukuran besar dan semacamnya didaftarkan sebagai lazy file pointer, sehingga hanya diambil dari S3 saat benar-benar diakses
• Semua operasi tulis mengembalikan error EROFS (read-only filesystem), sehingga menjaga arsitektur yang aman dan stateless

Optimasi grep

• Karena perintah grep -r akan sangat lambat jika hanya melakukan pemindaian jaringan, proses ini dioptimalkan dengan struktur filtering dua tahap
  • Tahap 1: memilih file kandidat menggunakan kueri Chroma ($contains, $regex)
  • Tahap 2: data diambil lebih dulu ke cache Redis, lalu dilakukan filtering presisi di memori dalam just-bash
• Dengan cara ini, pencarian rekursif skala besar pun dapat selesai dalam hitungan milidetik

Kesimpulan

• ChromaFs menjalankan asisten dokumen Mintlify yang digunakan lebih dari 30 ribu kali per hari oleh ratusan ribu pengguna
• Dengan menggantikan sandbox, tercapai pembuatan sesi instan, biaya tambahan nyaris 0, RBAC bawaan, dan arsitektur stateless
• Dapat digunakan langsung di semua situs dokumentasi Mintlify (mintlify.com/docs)

[GN⁺]

Komentar Hacker News

• Alasan pencarian berbasis sistem file kembali mendapat perhatian adalah karena orang sedang menemukan kembali bentuk pencarian semantik yang bukan berbasis embedding
  Seperti pustakawan yang menyusun buku di rak berdasarkan topik, cara mengatur file per domain lebih mudah diinterpretasikan
  Ini memang metode pencarian yang sudah ada sejak lama, tetapi baru sekarang nilainya kembali disadari
  Tulisan blog terkait

  • Ilmu perpustakaan tradisional sebenarnya sudah lama menangkap pola mendalam dalam struktur informasi
    Konsep ini juga tergambar dengan baik dalam Ralph Wrecks The Internet dari Pixar
    Tweet referensi 1, Tweet referensi 2
  • Saya sedang bekerja pada codebase dengan lebih dari 400 file Python, dan RAG berbasis embedding sering mengambil potongan kode yang meleset hanya karena kata-katanya mirip
    Ketika agen dibiarkan menelusuri pohon direktori secara langsung, dalam 30 detik ia mulai memahami struktur modul dan meminta file yang tepat
    Saya lupa bahwa hierarki direktori itu sendiri sudah merupakan graf pengetahuan buatan manusia
  • Saat membangun sistem pencarian LLM, pada akhirnya saya malah menemukan kembali indeks terbalik (concordance)
    Ini adalah konsep yang sama dengan inverted index milik Google, jadi sebenarnya bukan sesuatu yang benar-benar baru
  • Seseorang berasumsi bahwa RAG harus memakai pencarian vektor, dan tampaknya semua orang ikut arus itu
  • Asisten AI pada akhirnya adalah tokoh virtual yang diautocomplete oleh LLM, jadi mekanisme yang bisa diinterpretasikan seperti interaksi bahasa manusia lebih menguntungkan

• Bagi saya, RAG tidak memberi cara untuk membaca isi secara langsung
  Jadi sekarang saya menyatukan pengetahuan ke dalam halaman statis berbasis Markdown, lalu setelah diedit saya membangun file JSON agar agen bisa melakukan kueri terhadap sumber ini
  Tautan penjelasan

• Klaim bahwa pencarian sistem file lebih baik daripada RAG terasa membingungkan
  Pencarian kata kunci seperti grep adalah cara lama, sedangkan RAG memakai pencarian vektor
  Namun di database, konten bisa diindeks dengan hierarki, tag, atau struktur arbitrer
  Pencarian juga bisa memakai berbagai kombinasi seperti kata kunci, vektor, tf-idf, BM25, dan lainnya
  Kembali ke sistem file terasa seperti mundur ke teknologi era 1960-an

  • Itu benar, tetapi dalam praktiknya kinerja lebih baik ketika agen bekerja berbasis file
    Agen coding berbasis CLI bertindak jauh lebih cerdas saat diberi akses file
  • Saya mendapat hasil bagus dengan agentic search berbasis database
    Intinya adalah agen bisa menjalankan berbagai kueri ad-hoc sendiri secara langsung
    Di DB yang mendukung embedding dan full-text search sekaligus, agen tetap cukup agentic jika bebas melakukan kueri
  • Sebenarnya sebagian besar sistem file juga secara internal memakai struktur database
    Menggunakan sistem file seperti DB bukanlah hal baru
  • Saya rasa pendekatan yang dibahas artikel itu pada akhirnya memang ini juga
  • Menurut saya, membiarkan agen menjelajah langsung ke berbagai sumber data itu lebih baik

• Perhitungan bahwa 850 ribu percakapan per bulan menghabiskan lebih dari 70 ribu dolar per tahun terdengar aneh
  Saya penasaran CPU dan memori dipakai untuk apa sebanyak itu, dan ternyata penyebabnya adalah ChromaFs berbasis just-bash dari Vercel Labs

  • Jika tiap agen diberi container terisolasi, memori akan terus terpakai meskipun tidak ada yang dilakukan, sehingga biayanya membesar

• Saya menikmati kebangkitan aplikasi CLI
  Saya membuat sistem file virtual yang mencerminkan sistem file nyata di Mac dengan FUSE, lalu membatasi agen hanya di dalam tree tersebut
  Untuk tiap repo saya menjalankan agen jangka panjang, dan izin dikendalikan lewat sistem file virtual
  Proyek bashguard

• Kami memakai virtual file system (VFS) dan RAG sekaligus
  Inti RAG ada pada kualitas data: dokumen dipecah berdasarkan unit makna dan dibuatkan metadata serta tautan
  Tiap chunk di-embedding bersama dokumennya menggunakan voyage contextual embedding
  Saat pencarian, agen bisa mengikuti tautan atau menganalisis teks asli
  Kualitas reranking sangat memengaruhi performa

  • VFS kami berbasis Postgres dan diproyeksikan dalam bentuk file/direktori
    Mendukung grep, bm25, jq, alat pratinjau, dan berjalan di atas Pydantic AI

• Mengemulasikan shell POSIX di TypeScript untuk melakukan pencarian hierarkis terlihat seperti overengineering
  Setiap kali menjalankan ls atau grep, siklus inferensi bertambah sehingga latency ikut naik

  • Jika FUSE dipasang di atas chunk, sepertinya emulasi shell tidak diperlukan

• Saya tidak terlalu paham tech stack-nya, tetapi saya penasaran kenapa harus membuat shell palsu
  Solusi FUSE terlihat lebih alami

  • Mereka memang mempertimbangkan adaptor FUSE, tetapi terlalu lambat
    Mereka tidak butuh kompatibilitas POSIX penuh, hanya penjelajahan dokumen read-only
    Karena itu, pendekatan yang hanya mendukung sebagian perintah bash menjadi lebih sederhana

• Dalam konteks membuat dokumen bisa diakses dengan alat sistem file, AI SDK dari Vercel menarik
  Dengan menyertakan dokumen .mdx di root paket npm, agen diarahkan untuk lebih dulu melakukan grep pada dokumentasi lokal
  Contoh SKILL.md

• Ini pendekatan yang bagus untuk startup seperti Mintlify, tetapi di organisasi kompleks bisa jadi kurang praktis
  Di lingkungan dengan struktur non-hierarkis atau dokumen yang bercampur, RAG lebih berguna

  • Di sini ada use case pencarian kode yang jelas, sehingga lebih sederhana
    RAG bukan solusi serba bisa, dan tim Claude Code juga sampai pada kesimpulan yang sama
  • Karena teknologi OCR sudah cukup maju, jika dokumen bisa di-OCR maka pendekatan ini juga dapat digeneralisasi
  • Jika VFS ditumpangkan di atas organisasi dokumen yang kompleks, pada akhirnya itu hanya variasi dari pengindeks; tanpa kontrol akses, masalah keamanan akan muncul