Construção de um sistema de arquivos virtual para substituir RAG em um assistente de documentação com IA

• Para superar as limitações da busca baseada em RAG tradicional, a estrutura dos documentos foi convertida para um sistema de arquivos virtual composto por arquivos e diretórios
• Foi implementado o ChromaFs, que permite executar comandos grep, cat, ls e find com base no banco de dados Chroma, sem copiar arquivos reais
• Com essa abordagem, o tempo de criação de sessão foi reduzido de 46 segundos para 100 milissegundos, e o custo computacional adicional caiu para próximo de 0 dólar
• O controle de acesso é tratado com filtragem RBAC nos metadados de caminho dos arquivos, eliminando a necessidade de contêineres separados ou gestão de grupos de usuários
• Como resultado, o assistente de documentação da Mintlify pode operar em grande escala com uma arquitetura de resposta imediata, baixo custo e sem estado

---

Uma abordagem de sistema de arquivos virtual além dos limites do RAG

• A busca de documentos baseada em RAG tradicional retornava apenas trechos de texto compatíveis com a consulta, dificultando respostas que atravessam várias páginas ou buscas exatas por padrões
• Para resolver isso, a estrutura dos documentos foi transformada em um formato navegável como um sistema de arquivos, mapeando cada página de documentação como um arquivo e cada seção como um diretório
• O agente pode explorar diretamente os documentos com os comandos grep, cat, ls e find, em uma estrutura projetada para pesquisar a documentação como um desenvolvedor navega em uma base de código

O problema do gargalo com contêineres

• A abordagem comum consiste em criar um ambiente sandbox isolado e clonar o repositório para fornecer ao agente um sistema de arquivos real
• Porém, em assistentes no frontend, a latência de criação de sessão se torna um problema grave, com tempo p90 de criação de sessão em cerca de 46 segundos
• Considerando 850 mil conversas por mês, mesmo em uma configuração mínima (1 vCPU, 2 GiB de RAM, sessão mantida por 5 minutos), o custo anual de infraestrutura ultrapassa 70 mil dólares
• Para eliminar esse gargalo, era necessário um sistema de arquivos virtual que respondesse instantaneamente e operasse com baixo custo

Implementação do shell virtual — ChromaFs

• Em vez de um sistema de arquivos real, é fornecida apenas a ilusão de um sistema de arquivos virtual
• Como os dados de documentação já estavam indexados no banco de dados Chroma, o ChromaFs foi construído sobre essa base
• O ChromaFs intercepta comandos UNIX e os converte em consultas ao Chroma
• Como resultado, o tempo de criação de sessão foi reduzido de 46 segundos para 100 ms, e o custo computacional adicional caiu para próximo de 0 dólar

Metric	Sandbox	ChromaFs
P90 Boot Time	~46 s	~100ms
Marginal Compute Cost	~$0.0137/conversa	~$0
Search Mechanism	varredura em disco	consulta de metadados no BD
Infrastructure	sandbox externo como Daytona	reutilização do BD existente

• Implementado com base no just-bash (Vercel Labs), com suporte aos comandos grep, cat, ls, find e cd
• Aproveitando a interface IFileSystem do just-bash, a lógica de pipes e flags foi mantida, enquanto as chamadas de acesso a arquivos foram convertidas em consultas ao Chroma

Bootstrapping da árvore de diretórios

• Como o ChromaFs precisa saber quais arquivos existem antes de executar, a árvore completa de arquivos é armazenada em uma coleção do Chroma na forma de JSON compactado (__path_tree__)
• Na inicialização do servidor, isso é carregado e restaurado em duas estruturas de memória
  • Set<string> com os caminhos dos arquivos
  • Map<string, string[]> com a lista de filhos por diretório
• Depois disso, os comandos ls, cd e find são processados instantaneamente na memória local, sem chamadas de rede, e sessões subsequentes do mesmo site reutilizam a árvore em cache

Controle de acesso

• A árvore de caminhos inclui os campos isPublic e groups, mantendo apenas os arquivos acessíveis com base no token de sessão do usuário
• Arquivos sem permissão de acesso são completamente removidos da árvore, de modo que o agente nem sequer reconhece esses caminhos
• Nos sandboxes tradicionais, isso exigiria gerenciar grupos de usuários no Linux, chmod, separação por contêiner etc., mas no ChromaFs o RBAC é implementado apenas com uma lógica simples de filtragem

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	✗

Recombinação de fragmentos de documentos

• Os documentos armazenados no Chroma são divididos em vários fragmentos para embedding
• Ao executar cat /auth/oauth.mdx, todos os fragmentos com o mesmo slug de page são recuperados, ordenados por chunk_index e então mesclados
• O resultado é armazenado em cache, evitando novas consultas ao BD mesmo em fluxos repetidos com grep
• Itens como grandes especificações OpenAPI são registrados como lazy file pointer, sendo carregados do S3 apenas no momento do acesso
• Todas as operações de escrita retornam erro EROFS (sistema de arquivos somente leitura), preservando uma arquitetura segura e sem estado

Otimização do Grep

• Como o comando grep -r fica muito lento com varreduras simples pela rede, ele foi otimizado com uma estrutura de filtragem em duas etapas
  • Etapa 1: uso de consultas do Chroma ($contains, $regex) para selecionar os arquivos candidatos
  • Etapa 2: pré-carregamento no cache Redis e filtragem precisa em memória no just-bash
• Com isso, até buscas recursivas em larga escala podem ser concluídas em milissegundos

Conclusão

• O ChromaFs opera o assistente de documentação da Mintlify, usado mais de 30 mil vezes por dia por centenas de milhares de usuários
• Ao substituir os sandboxes, ele alcança criação instantânea de sessões, custo adicional próximo de zero, RBAC embutido e arquitetura sem estado
• Pode ser usado diretamente em todos os sites de documentação da Mintlify (mintlify.com/docs)

[GN⁺]

Comentários do Hacker News

• O motivo para voltar a dar atenção à busca baseada em sistema de arquivos é que estamos redescobrindo uma forma de busca semântica que não é baseada em embeddings
  Assim como um bibliotecário organiza livros por assunto nas prateleiras, estruturar arquivos por domínio é mais interpretável
  É uma forma de busca que existe há muito tempo, mas só agora estamos percebendo novamente seu valor
  Post de blog relacionado

  • A biblioteconomia tradicional já havia capturado padrões profundos da estrutura da informação
    Esse conceito também foi bem representado em Ralph Wrecks The Internet, da Pixar
    Tweet de referência 1, Tweet de referência 2
  • Estou trabalhando em uma base de código com mais de 400 arquivos Python, e o RAG baseado em embeddings frequentemente trazia trechos de código errados com palavras parecidas
    Em vez disso, ao deixar o agente explorar diretamente a árvore de diretórios, ele passou a entender a estrutura dos módulos em 30 segundos e a pedir os arquivos corretos
    Eu tinha esquecido que a própria hierarquia de diretórios já era um grafo de conhecimento criado por humanos
  • Ao construir um sistema de busca com LLM, acabei reinventando o índice invertido (concordance)
    Isso é o mesmo conceito do inverted index do Google, ou seja, não é exatamente algo novo
  • Alguém presumiu que RAG necessariamente teria de usar busca vetorial, e parece que todo mundo seguiu essa linha
  • Assistentes de IA são, no fim das contas, personagens virtuais autocompletados por LLMs, então mecanismos interpretáveis, como na interação linguística humana, são mais vantajosos

• Para mim, o RAG não oferecia um jeito de ler o conteúdo diretamente
  Então agora estou consolidando o conhecimento em páginas estáticas baseadas em Markdown, e depois das edições gero um arquivo JSON para que o agente consulte essa fonte
  Link explicativo

• A afirmação de que busca em sistema de arquivos é melhor que RAG é confusa
  Busca por palavra-chave, como grep, é um método antigo, e o RAG usa busca vetorial
  Mas em bancos de dados é possível indexar conteúdo com hierarquias, tags e estruturas arbitrárias
  A busca pode combinar palavra-chave, vetores, tf-idf, BM25 e outros métodos
  Voltar ao sistema de arquivos dá a sensação de regredir para tecnologia dos anos 60

  • É verdade, mas na prática o desempenho é melhor quando o agente trabalha com base em arquivos
    Agentes de programação baseados em CLI se comportam de forma muito mais inteligente ao acessar arquivos
  • Eu obtive bons resultados com agentic search baseada em banco de dados
    O ponto principal é que o agente pode executar por conta própria várias consultas ad-hoc
    Se o agente puder consultar livremente um banco que suporte embeddings e busca full-text, isso já é suficientemente agentic
  • Na verdade, a maioria dos sistemas de arquivos também usa internamente estruturas de banco de dados
    Usar sistema de arquivos como se fosse um DB não tem nada de novo
  • Suspeito que a abordagem descrita no artigo seja isso no fim das contas
  • Acho melhor deixar o agente explorar diretamente várias fontes de dados

• A conta de que 850 mil conversas por mês custariam mais de 70 mil dólares por ano parece estranha
  Eu estava me perguntando onde CPU e memória estavam sendo tão consumidas, e a resposta era o ChromaFs baseado em just-bash da Vercel Labs

  • Se você dá a cada agente um container isolado, a memória continua ocupada mesmo sem fazer nada, e isso encarece bastante

• Estou curtindo o renascimento das aplicações CLI
  Criei um sistema de arquivos virtual com FUSE que espelha o sistema de arquivos real do Mac, restringindo o agente a operar apenas dentro daquela árvore
  Mantenho um agente de longa duração por repositório, e as permissões são controladas pelo sistema de arquivos virtual
  Projeto bashguard

• Nós usamos tanto sistema de arquivos virtual (VFS) quanto RAG
  O ponto central do RAG é a qualidade dos dados: dividimos documentos em unidades semânticas e geramos metadados e links
  Fazemos embedding de cada chunk junto com o documento usando voyage contextual embedding
  Na busca, o agente pode seguir os links ou analisar o texto original
  A qualidade do reranking afeta muito o desempenho

  • Nosso VFS é baseado em Postgres e projetado na forma de arquivos/diretórios
    Ele suporta grep, bm25, jq, ferramentas de preview etc., e roda sobre Pydantic AI

• Emular um shell POSIX em TypeScript para fazer busca hierárquica parece overengineering
  Cada execução de ls ou grep aumenta os ciclos de inferência e, com isso, a latência

  • Se a abordagem for colocar FUSE sobre os chunks, talvez nem seja necessário emular shell

• Não conheço bem a stack técnica, mas fiquei me perguntando por que criar um shell falso
  Uma solução com FUSE parece mais natural

  • Na prática, eles consideraram um adaptador FUSE, mas ele era lento demais
    Não havia necessidade de compatibilidade POSIX completa, apenas de navegação em documentos somente leitura
    Por isso foi mais simples suportar apenas parte dos comandos bash

• No contexto de tornar documentos acessíveis por ferramentas de sistema de arquivos, o AI SDK da Vercel é interessante
  Eles incluem documentos .mdx na raiz do pacote npm para induzir o agente a usar grep primeiro na documentação local
  Exemplo de SKILL.md

• É uma boa abordagem para startups como a Mintlify, mas em organizações complexas pode ser pouco prática
  Em ambientes com estrutura não hierárquica ou documentação misturada, o RAG pode ser mais útil

  • Aqui existe um caso de uso claro de busca em código, então a simplicidade funciona
    RAG não é solução para tudo, e a equipe do Claude Code chegou à mesma conclusão
  • Como a tecnologia de OCR avançou bastante, se a documentação puder passar por OCR essa abordagem também pode ser generalizada
  • Se você sobrepõe um VFS a uma organização documental complexa, isso no fim acaba sendo apenas uma variação de indexador, e sem controle de acesso surgem problemas de segurança