Se você já construiu um chatbot de documentação usando RAG, provavelmente já ficou frustrado com uma pergunta simples recebendo uma resposta completamente errada — não porque o modelo é burro, mas porque os chunks recuperados não tinham contexto suficiente. A Mintlify chegou no mesmo limite e fez uma aposta diferente: jogar fora o pipeline de recuperação vetorial e deixar o agente navegar a documentação como um desenvolvedor navegaria um projeto no terminal.

O resultado? Tempo de inicialização caindo de 46 segundos para 100 milissegundos. Custo de infraestrutura eliminado quase por completo. E um assistente que consegue responder perguntas que o RAG nunca conseguia.

Esse artigo é uma análise técnica do que está acontecendo, por que funciona, e quando faz sentido substituir RAG por um filesystem virtual.

O Problema Real com RAG

Antes de falar sobre filesystem virtual, precisa ficar claro o que exatamente quebra no RAG convencional — porque muita gente acha que RAG “não funciona” sem saber por quê.

O pipeline clássico é esse:

1. Você quebra seus documentos em chunks (pedaços de ~500 tokens)
2. Converte cada chunk em um vetor numérico usando um modelo de embedding
3. Armazena no banco vetorial (Pinecone, Chroma, Weaviate, pgvector…)
4. Na hora da query, converte a pergunta em vetor e busca os K chunks mais similares
5. Injeta esses chunks no prompt e deixa o LLM responder

Parece razoável. Na prática, tem três problemas sérios.

Chunking destrói estrutura. Um documento de documentação técnica tem hierarquia: página > seção > subseção > exemplo de código. Quando você quebra em chunks de 512 tokens, você está destruindo essa hierarquia. Um chunk pode conter a metade de um exemplo de código, sem o setup que vem antes. Outro chunk pode conter a conclusão de uma seção sem a premissa.

Top-K é arbitrário. Você define k=5 (recupera os 5 chunks mais relevantes) mas a resposta para uma determinada pergunta pode estar espalhada por 8 pedaços diferentes. Você não tem como saber isso com antecedência. Se você aumentar K demais, enche o contexto com ruído. Se mantiver baixo, perde informação.

O agente não sabe o que não sabe. Numa busca vetorial, o modelo recebe os chunks e precisa responder. Ele não pode dizer “espera, deixa eu checar a página ao lado”. Não há navegação, não há exploração. É uma foto, não um mapa.

# O pipeline RAG que todo mundo constrói
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

# O problema: e se a resposta precisar de 8 chunks?
# E se os 5 recuperados tiverem contexto insuficiente?
docs = retriever.get_relevant_documents("Como configurar OAuth com JWT refresh tokens?")

Um estudo da Vectara apresentado na NAACL 2025 mostrou que a estratégia de chunking tem tanta ou mais influência na qualidade do sistema quanto a escolha do modelo de embedding. Ou seja: você pode ter o melhor embedding model do mercado e ainda ter um sistema ruim porque quebrou os documentos errado.

O Insight da Mintlify: Agentes Já Sabem Usar Terminal

A Mintlify é uma plataforma de documentação técnica. Eles tinham um assistente de IA que deveria ajudar desenvolvedores a navegar a documentação dos clientes deles. O RAG funcionava para perguntas simples, mas quebrava em perguntas que exigiam navegar por múltiplas páginas ou encontrar sintaxe exata em exemplos de código.

A sacada deles foi perceber algo óbvio que todo mundo ignora: LLMs são treinados em quantidades absurdas de código bash e interações de terminal. Eles sabem usar grep, cat, ls, find. Sabem que grep -r "keyword" . busca recursivamente. Sabem que cat arquivo.md mostra o conteúdo. Sabem que ls src/ lista um diretório.

Em vez de criar uma API de recuperação nova para o agente aprender, eles criaram a ilusão de um sistema de arquivos. O agente usa comandos Unix normais. Por baixo, esses comandos são traduzidos para queries no banco de dados vetorial.

Agente AI
  ↓ grep -r "webhook" docs/
  ↓
ChromaFs (intercepta o comando)
  ↓
Chroma Vector Database (executa a query real)
  ↓
Retorna resultados formatados como saída de grep

Isso se chama ChromaFs — um filesystem virtual sobre o Chroma existente.

Como o ChromaFs Funciona Tecnicamente

A implementação usa o just-bash, uma reimplementação TypeScript do bash feita pela Vercel Labs. O ChromaFs implementa uma interface IFileSystem que intercepta os comandos e os redireciona.

A árvore de diretórios é armazenada como um único documento JSON comprimido dentro do próprio Chroma:

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

Esse JSON descomprime em memória como duas estruturas:

• Um Set<string> com todos os caminhos de arquivo
• Um Map<string, string[]> mapeando diretórios para seus filhos

Operações como ls, cd e find rodam localmente com zero chamadas de rede. Só quando você faz um cat ou grep é que vai ao banco.

O grep em dois estágios é a parte mais inteligente:

1. Filtro grosso: O Chroma identifica quais arquivos provavelmente contêm o match (busca vetorial normal)
2. Filtro fino: Regex em memória sobre os chunks pré-carregados, com cache no Redis

Isso combina o melhor dos dois mundos: velocidade da busca vetorial para pré-filtrar, precisão do regex para confirmar.

Controle de acesso é elegante: a árvore de caminhos inclui campos isPublic e groups. Antes de inicializar, o ChromaFs poda os caminhos inacessíveis com base no token de sessão do usuário. O agente literalmente não vê arquivos para os quais não tem permissão.

Os Números que Convencem

A redução de 46 segundos para 100ms não é otimização — é mudança de paradigma. Um sandbox real (que era o que eles usavam antes) precisa provisionar um ambiente, montar volumes, inicializar processos. Um filesystem virtual que existe em memória não precisa de nada disso.

“O agente não precisa de um sistema de arquivos real. Só precisa da ilusão de um.”
— Equipe da Mintlify

RAG Está Morto? Não, Mas Evoluiu

Título clickbait à parte, RAG não morreu. Ele virou infraestrutura. A questão é que “RAG” em 2026 não significa mais o pipeline ingênuo de chunk-embed-retrieve.

GraphRAG: Quando as Relações Importam

A Microsoft publicou pesquisa open-source chamada GraphRAG que, em vez de chunks isolados, constrói um grafo de conhecimento a partir dos documentos. Extrai entidades e relacionamentos automaticamente.

GraphRAG não ganha em tudo. Mas em domínios onde as relações entre entidades são o que importa — compliance, org charts, análise financeira — ele brilha onde o RAG vetorial simplesmente falha.

Agentic RAG: O Agente Decide a Estratégia

A evolução mais adotada hoje é deixar o LLM escolher dinamicamente qual estratégia de recuperação usar. Em vez de um pipeline fixo, o agente tem acesso a múltiplas ferramentas:

# LlamaIndex - Recuperação Agêntica
from llama_index.core import LlamaParseIndex

# O agente escolhe entre chunk-based, metadata, ou content-driven
nodes = financial_index.as_retriever(
    retrieval_mode="auto_routed"
).retrieve(query)

A Contextual AI testou isso com Claude Sonnet 3.5 e encontrou um ganho de +7.62 pontos percentuais de acurácia simplesmente adicionando uma ferramenta de busca por metadados ao lado do RAG vetorial convencional.

OpenViking: Filesystem como Padrão Universal

Em janeiro de 2026, a ByteDance lançou o OpenViking — um banco de dados de contexto open-source para agentes que organiza tudo através de um paradigma de filesystem. Usa o protocolo viking:// para endereçar contextos:

• Memórias em /memory/
• Recursos em /resources/
• Skills em /skills/

Em poucas semanas acumulou mais de 15.000 estrelas no GitHub. Não é coincidência: Claude Code usa ~/.claude/, Cursor usa arquivos de projeto, OpenViking usa viking://. Todos convergiram independentemente para o mesmo padrão sem coordenação.

Quando Usar Cada Abordagem

A resposta honesta é: depende do seu caso de uso.

Use RAG vetorial convencional quando:

• Corpus grande e não estruturado (emails, relatórios, PDFs variados)
• Usuários fazem perguntas em linguagem natural variada
• Você precisa de algo funcionando rápido sem engenharia complexa
• Os documentos não têm hierarquia clara

Use Filesystem Virtual quando:

• Documentação técnica bem estruturada (APIs, tutoriais, referências)
• Agente precisa navegar por múltiplas páginas para responder
• Controle de acesso granular é requisito (permissões por grupo/rota)
• Custo de sandbox/ambiente é um problema real
• Performance de inicialização importa (produtos de alta escala)

Use GraphRAG quando:

• Dados com relações explícitas entre entidades (organigramas, grafos de compliance)
• Perguntas que exigem raciocínio multi-hop
• Qualidade supera custo como prioridade (latência 2.4x maior é aceitável)

Use Agentic RAG quando:

• Você quer a melhor acurácia para o seu caso específico
• Tem recursos para adicionar ferramentas especializadas ao agente
• Está construindo para o longo prazo

Context Engineering: O Frame que Une Tudo

O campo está convergindo para um conceito mais amplo chamado Context Engineering — a ideia de que a qualidade do sistema não é determinada pelo modelo de LLM, mas pela qualidade e relevância do contexto que você monta para ele.

Com janelas de contexto chegando a 10 milhões de tokens (Llama 4 Scout), a pergunta deixou de ser “como recuperar o trecho certo” e virou “como compor contexto de alta qualidade para cada query”.

Nesse framework, RAG, filesystem virtual, GraphRAG e Agentic RAG são todos estratégias de composição de contexto, não arquiteturas concorrentes. O sistema ideal provavelmente usa todas elas.

Context Engine
├── Knowledge Retrieval (RAG vetorial para docs gerais)
├── Structured Navigation (Filesystem virtual para docs técnicas)
├── Graph Traversal (GraphRAG para relações entre entidades)
├── Tool Selection (Qual API/ferramenta usar para essa query)
└── Memory Retrieval (Interações históricas relevantes)

O Que Fica de Lição

A história da Mintlify é um estudo de caso sobre restrições que liberam criatividade. Eles não inventaram um novo paradigma de IA. Eles observaram que o modelo já sabia usar terminal, e que a documentação já tinha estrutura hierárquica — e construíram a ponte mais simples possível entre os dois.

O RAG clássico tem 46 problemas de chunking, 31 problemas de top-K, e um custo de $70.000 por ano em sandbox. O filesystem virtual tem uma linha de arquivo JSON e um grep em dois estágios.

Às vezes a melhor solução de engenharia não é a mais sofisticada. É a que usa o que já existe de forma mais inteligente.

Se você está construindo um assistente para documentação técnica estruturada, vale seriamente considerar essa abordagem antes de investir semanas em fine-tuning de embeddings e otimização de chunking. A estrutura que você está destruindo no processo de indexação é exatamente a que o agente precisa para navegar bem.

Fonte de inspiração: We replaced RAG with a virtual filesystem for our AI documentation assistant — Mintlify Engineering Blog