Cómo construir un sistema de archivos virtual que reemplaza RAG para un asistente de documentación con IA

• Para superar las limitaciones de la búsqueda basada en RAG existente, se cambió a una estructura de sistema de archivos virtual compuesta por documentos organizados como archivos y directorios
• Se implementó ChromaFs, que permite ejecutar comandos grep, cat, ls y find sobre una base de datos Chroma sin copiar archivos reales
• Con este enfoque, el tiempo de creación de sesión se redujo de 46 segundos a 100 milisegundos, y el costo computacional adicional bajó prácticamente a 0 dólares
• El control de acceso se resuelve con filtrado RBAC sobre los metadatos de rutas de archivo, por lo que no se requieren contenedores separados ni gestión de grupos de usuarios
• Como resultado, el asistente de documentación de Mintlify puede operar como un servicio a gran escala con respuesta inmediata, bajo costo y arquitectura sin estado

---

Un enfoque de sistema de archivos virtual más allá de las limitaciones de RAG

• La recuperación de documentos basada en RAG tradicional solo devolvía fragmentos de texto que coincidían con la consulta, lo que dificultaba responder preguntas que abarcaban varias páginas o hacer búsquedas exactas de frases
• Para resolverlo, la estructura de la documentación se transformó en una forma navegable como un sistema de archivos: cada página de documentación se mapea como un archivo y cada sección como un directorio
• El agente puede explorar la documentación directamente con los comandos grep, cat, ls y find, por lo que se diseñó una estructura donde se puede buscar en la documentación igual que un desarrollador trabaja con una base de código

El problema del cuello de botella de los contenedores

• El enfoque habitual consiste en crear un entorno sandbox aislado y clonar el repositorio para ofrecerle al agente un sistema de archivos real
• Sin embargo, en un asistente de frontend la latencia al crear sesiones se vuelve un problema serio, y el tiempo p90 de creación de sesión llega a unos 46 segundos
• Con una base de 850 mil conversaciones mensuales, incluso con una configuración mínima (1 vCPU, 2 GiB de RAM y sesiones de 5 minutos), el costo de infraestructura supera los 70 mil dólares anuales
• Para eliminar este cuello de botella, se necesitaba un sistema de archivos virtual que respondiera al instante y funcionara con bajo costo

Implementación del shell virtual — ChromaFs

• En lugar de un sistema de archivos real, solo se proporciona la ilusión de un sistema de archivos virtual
• Como los datos de documentación existentes ya estaban indexados en una base de datos Chroma, se construyó ChromaFs sobre esa base
• ChromaFs intercepta comandos UNIX y los convierte en consultas a Chroma
• Como resultado, el tiempo de creación de sesión se redujo de 46 segundos a 100 ms, y el costo computacional adicional bajó prácticamente a 0 dólares

Metric	Sandbox	ChromaFs
P90 Boot Time	~46 segundos	~100ms
Marginal Compute Cost	~$0.0137/conversación	~$0
Search Mechanism	escaneo de disco	consulta de metadatos en la BD
Infrastructure	sandbox externo como Daytona	reutilización de la BD existente

• Se implementó sobre just-bash (Vercel Labs) y soporta los comandos grep, cat, ls, find y cd
• Usando la interfaz IFileSystem de just-bash, se conserva la lógica de pipes y flags tal como está, mientras que las llamadas de acceso a archivos se convierten en consultas a Chroma

Bootstrapping del árbol de directorios

• Como ChromaFs necesita saber qué archivos existen antes de ejecutarse, el árbol completo de archivos se guarda en la colección de Chroma en forma de JSON comprimido (__path_tree__)
• Al inicializar el servidor, esto se recupera y se reconstruye en dos estructuras en memoria
  • Un Set<string> con las rutas de archivo
  • Un Map<string, string[]> con la lista de hijos por directorio
• Después, los comandos ls, cd y find se resuelven al instante en memoria local, sin llamadas de red, y las sesiones posteriores del mismo sitio reutilizan el árbol cacheado

Control de acceso

• El árbol de rutas incluye los campos isPublic y groups, y solo se conservan los archivos accesibles según el token de sesión del usuario
• Los archivos sin permisos de acceso se eliminan por completo del árbol, de modo que el agente ni siquiera puede reconocer que esa ruta existe
• En los sandboxes tradicionales esto requería gestionar grupos de usuarios de Linux, chmod, aislamiento por contenedor, etc., pero en ChromaFs el RBAC se implementa solo con una lógica simple de filtrado

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	✗

Reensamblado de fragmentos de documentación

• Los documentos almacenados en Chroma están divididos en varios fragmentos para generar embeddings
• Cuando se ejecuta cat /auth/oauth.mdx, se obtienen todos los fragmentos con el mismo slug page, luego se ordenan por chunk_index y se combinan
• El resultado se cachea, por lo que incluso en flujos repetidos con grep no se vuelve a consultar la BD
• Elementos como especificaciones OpenAPI grandes se registran como lazy file pointer, y solo se traen desde S3 cuando se accede a ellos
• Todas las operaciones de escritura devuelven el error EROFS (sistema de archivos de solo lectura), lo que mantiene una arquitectura segura y sin estado

Optimización de Grep

• Como el comando grep -r puede ser muy lento si se hace con simples escaneos por red, se optimizó con una estructura de filtrado en dos etapas
  • Etapa 1: se seleccionan archivos candidatos usando consultas de Chroma ($contains, $regex)
  • Etapa 2: tras precargarlos en caché de Redis, just-bash realiza un filtrado preciso en memoria
• Gracias a esto, incluso las búsquedas recursivas a gran escala pueden completarse en milisegundos

Conclusión

• ChromaFs impulsa el asistente de documentación de Mintlify, usado por más de 30 mil veces al día y por cientos de miles de usuarios
• Al reemplazar los sandboxes, logra creación instantánea de sesiones, costo adicional cercano a 0, RBAC integrado y arquitectura sin estado
• Puede usarse directamente en todos los sitios de documentación de Mintlify (mintlify.com/docs)

[GN⁺]

Comentarios en Hacker News

• La razón para volver a poner atención en la búsqueda basada en sistema de archivos es que estamos redescubriendo una forma de búsqueda semántica que no depende de embeddings
  Así como un bibliotecario organiza los libros por tema en los estantes, estructurar los archivos por dominio resulta más interpretable
  Es una forma de búsqueda que existe desde hace mucho tiempo, pero apenas ahora estamos volviendo a apreciar su valor
  Entrada de blog relacionada

  • La bibliotecología tradicional ya había capturado patrones profundos de la estructura de la información
    Pixar también expresó bien esta idea en Ralph Wrecks The Internet
    Tuit de referencia 1, Tuit de referencia 2
  • Estoy trabajando en una base de código con más de 400 archivos Python, y el RAG basado en embeddings solía traer con frecuencia fragmentos de código equivocados solo porque tenían palabras parecidas
    En cambio, al dejar que el agente explorara directamente el árbol de directorios, en 30 segundos empezó a entender la estructura de los módulos y a pedir los archivos correctos
    Había olvidado que la propia jerarquía de directorios ya era un grafo de conocimiento creado por humanos
  • Al construir un sistema de búsqueda para LLM, terminé reinventando un índice invertido (concordance)
    Es el mismo concepto que el inverted index de Google, así que en realidad no es algo completamente nuevo
  • Alguien asumió que RAG necesariamente tenía que usar búsqueda vectorial, y parece que todos siguieron esa corriente
  • Los asistentes de IA son, al final, personajes virtuales que el LLM autocompleta, así que un mecanismo interpretable, parecido a la interacción lingüística humana, resulta más ventajoso

• RAG no me daba una forma de leer directamente el contenido
  Así que ahora integro el conocimiento en páginas estáticas basadas en Markdown, y después de editarlas construyo archivos JSON para que el agente consulte esa fuente
  Enlace con explicación

• La afirmación de que la búsqueda por sistema de archivos es mejor que RAG me parece confusa
  La búsqueda por palabras clave tipo grep es un método antiguo, y RAG usa búsqueda vectorial
  Pero en una base de datos se puede indexar el contenido con jerarquías, etiquetas o estructuras arbitrarias
  La búsqueda puede combinar palabras clave, vectores, tf-idf, BM25 y otras técnicas
  Volver al sistema de archivos da la sensación de regresar a una tecnología de los años 60

  • Es cierto, pero en la práctica el rendimiento es mejor cuando el agente trabaja sobre archivos
    Los agentes de programación basados en CLI se comportan de forma mucho más inteligente cuando tienen acceso a archivos
  • Yo he tenido buenos resultados con agentic search basado en base de datos
    La clave es que el agente pueda ejecutar por sí mismo distintas consultas ad-hoc
    Si el agente puede consultar libremente una DB que soporte embeddings y búsqueda de texto completo, eso ya es suficientemente agentic
  • De hecho, la mayoría de los sistemas de archivos también usan internamente estructuras de base de datos
    Usar el sistema de archivos como si fuera una DB no tiene nada de nuevo
  • Me da la impresión de que el enfoque del artículo al final es justamente eso
  • Creo que es mejor dejar que el agente explore directamente múltiples fuentes de datos

• Suena extraña la cuenta de que 850 mil conversaciones al mes cuesten más de 70 mil dólares al año
  Me preguntaba en qué se estaba yendo tanto CPU y memoria, y resultó ser por ChromaFs de Vercel Labs basado en just-bash

  • Si le das a cada agente un contenedor aislado, la memoria sigue ocupada incluso cuando no hace nada, y eso eleva los costos

• Estoy disfrutando este renacimiento de las aplicaciones CLI
  Construí un sistema de archivos virtual con FUSE que refleja el sistema de archivos real de Mac, y limito al agente para que solo opere dentro de ese árbol
  Tengo un agente de larga duración por cada repo, y los permisos se controlan con el sistema de archivos virtual
  Proyecto bashguard

• Nosotros usamos tanto sistema de archivos virtual (VFS) como RAG
  La clave de RAG es la calidad de los datos: dividimos los documentos en unidades semánticas y generamos metadatos y enlaces
  Usamos voyage contextual embedding para generar embeddings de cada chunk junto con su documento
  Durante la búsqueda, el agente puede seguir enlaces o analizar el texto original
  La calidad del reranking tiene un gran impacto en el rendimiento

  • Nuestro VFS está basado en Postgres y se proyecta en forma de archivos/directorios
    Soporta grep, bm25, jq, herramientas de vista previa y más, y funciona sobre Pydantic AI

• Emular un shell POSIX en TypeScript para hacer búsqueda jerárquica parece una sobreingeniería
  Cada vez que se ejecuta ls o grep, aumenta el ciclo de inferencia y sube la latencia

  • Si el enfoque fuera montar FUSE sobre los chunks, parecería que ni siquiera haría falta emular un shell

• No conozco bien el stack técnico, pero me preguntaba por qué hicieron un shell falso a propósito
  Una solución con FUSE parece más natural

  • En realidad sí consideraron un adaptador FUSE, pero era demasiado lento
    No necesitaban compatibilidad completa con POSIX, solo navegación de documentos en modo lectura
    Por eso fue más simple soportar solo una parte de los comandos de bash

• En el contexto de hacer que los documentos sean accesibles mediante herramientas de sistema de archivos, el AI SDK de Vercel resulta interesante
  Incluyen documentos .mdx en la raíz del paquete npm, para inducir a que el agente primero haga grep sobre documentación local
  Ejemplo de SKILL.md

• Es un buen enfoque para startups como Mintlify, pero en organizaciones complejas podría ser poco práctico
  En entornos con estructuras no jerárquicas o documentos mezclados, RAG puede ser más útil

  • Aquí hay un caso de uso claro, que es la búsqueda de código, así que todo es más simple
    RAG no sirve para todo, y el equipo de Claude Code llegó a la misma conclusión
  • Como la tecnología de OCR ha avanzado lo suficiente, si los documentos son aptos para OCR este enfoque también podría generalizarse
  • Si se superpone un VFS sobre una organización documental compleja, al final no deja de ser una variante de indexador, y sin control de acceso pueden aparecer problemas de seguridad