Quando o Andrej Karpathy postou sobre o workflow de knowledge base com LLM dele em 3 de abril de 2026, quase toda a discussão tratou como sistema de produtividade pra pesquisa pessoal. Essa leitura é estreita demais. A arquitetura por baixo — acumular material bruto, compilar em markdown estruturado, consultar e manter com um LLM — mapeia direto num problema que qualquer um rodando agentes de código em escala de sessão já bateu: o reset de contexto.
Esse texto aplica o padrão do Karpathy a workflows de engenharia especificamente. Não gestão de conhecimento como hobby. Gestão de conhecimento como infraestrutura pra sessões de código multi-agente.
O que é, de fato, uma knowledge base com LLM (não é RAG)
O padrão Karpathy: Bruto → Compilar → Lint → Consultar
O sistema tem quatro fases que rodam em ciclo contínuo. Material bruto de fonte — no caso do Karpathy, artigos, papers e datasets; em contexto de código, docs de arquitetura, decisões logadas, contratos de API e comentários de código — cai num diretório raw/. Um LLM então "compila" isso num wiki estruturado: uma coleção de arquivos markdown organizados por conceito, com resumos, backlinks entre ideias relacionadas e arquivos de índice que ajudam o LLM a navegar na hora da consulta. O passo de compilação é a inovação arquitetural. O LLM não está só indexando — está sintetizando, categorizando e criando conexões que não existiam explicitamente na fonte.
Passadas de lint rodam periodicamente: o LLM varre o wiki em busca de informação desatualizada, inconsistências internas, links que faltam e novas oportunidades de conexão. O Karpathy descreve como health checks que "limpam o wiki incrementalmente e melhoram a integridade geral dos dados". Cada resultado de consulta, cada output gerado, volta arquivado pro wiki. O sistema acumula em vez de resetar.
Na escala que o Karpathy descreve — uns 100 artigos e cerca de 400.000 palavras — nenhum banco vetorial é necessário. Arquivos de índice e páginas de resumo, carregados na janela de contexto do LLM, dão conta da navegação. O LLM acha o que precisa por estrutura, não por similaridade de embedding.
Por que o RAG redescobre conhecimento do zero toda vez
O RAG padrão — como definido no paper fundacional do Lewis et al. em 2020 — quebra documentos em chunks, converte em embeddings vetoriais e roda busca por similaridade no momento da consulta. Os chunks não conhecem uns aos outros. Conexões entre uma decisão tomada em março e uma restrição documentada em janeiro não existem no índice a menos que as duas apareçam na mesma passada de retrieval. Toda consulta começa do zero.
A formulação do Karpathy é precisa: "o LLM está redescobrindo conhecimento do zero a cada pergunta. Não tem acúmulo." Pra knowledge bases pessoais e codebases de pequeno a médio porte, é a ferramenta errada. RAG foi desenhado pra escalar retrieval sobre milhões de documentos com padrões de acesso imprevisíveis — um tradeoff de design que pesquisa em Agentic RAG vem tentando endereçar embutindo agentes autônomos no pipeline de retrieval, mas ao custo de bem mais complexidade de infra. Um wiki compilado em markdown não precisa de nenhuma das duas coisas.
A distinção importa pra agentes de código porque a arquitetura do seu projeto não muda arbitrariamente — ela evolui deliberadamente. Um sistema que acumula e refina conhecimento sobre seu codebase com o tempo é mais útil que um que re-deriva tudo dos arquivos brutos a cada invocação.
O problema real pros agentes de código: resets de contexto
O que acontece quando uma sessão multi-agente bate no limite de contexto
Num setup de código multi-agente — worktrees paralelos, subagents isolados cuidando de tarefas separadas — cada agente começa com o contexto que você dá e trabalha até completar ou bater na fronteira de contexto. Quando uma sessão compacta ou um agente novo sobe, o conhecimento do projeto que ele tinha some. O que sobrevive é só o que está em arquivo no disco.
A consequência prática: o próximo agente, ou a próxima sessão do mesmo agente, lê o codebase do zero. Consegue ler o código, mas não consegue ler o raciocínio. Por que o módulo de auth usa um formato de token customizado em vez de JWT? Por que o serviço de pagamento está isolado no próprio worktree em vez de morar no repo principal? Por que você decidiu contra a arquitetura descrita no doc design-v1.md que ainda está parado ali? Nada disso está no código. Estava na conversa.
Com um wiki compilado, está nos arquivos. O agente lê architecture/decisions/auth-token-format.md, entende os tradeoffs que foram avaliados e segue sem te pedir pra re-explicar.
Re-explicar arquitetura pro agente: o imposto invisível de token
Toda vez que você restabelece contexto pra uma sessão nova de agente, está gastando token em histórico em vez de em trabalho. Pra um projeto moderadamente complexo com três subsistemas ativos, uma stack não-trivial e algumas restrições arquiteturais que importam, essa passada de restabelecimento pode rodar 5.000–15.000 tokens antes de qualquer tarefa de fato começar. Multiplica isso por 10 sessões de agente por dia e o overhead vira coisa real — em custo e em latência.
O problema mais fundo é que re-explicação é com perda. Você resume de memória, perde o edge case em que trabalhou semana passada, o agente segue em contexto incompleto e produz algo sutilmente errado. Você corrige. Essa correção devia ser durável. Na maioria dos workflows de agente, não é.
Como uma knowledge base com LLM resolve o problema de contexto
Wiki markdown persistente como camada de memória do agente
O mecanismo é direto: um diretório de wiki que mora ao lado do seu codebase. O agente lê no início da sessão, atualiza conforme decisões são tomadas, e a próxima sessão pega de onde a última parou. Sem embeddings, sem índice vetorial, sem infra separada. Markdown simples, sob controle de versão, legível por humano e por agente.
O Claude Code suporta isso direto. Como a documentação oficial de memória do Claude Code explica, arquivos CLAUDE.md são carregados na janela de contexto no início da sessão automaticamente. Pra conteúdo detalhado demais pra morar no próprio CLAUDE.md, a sintaxe de import @path deixa você referenciar arquivos markdown externos — o CLAUDE.md funciona como sumário e as páginas do wiki carregam sob demanda. A documentação oficial do Claude Code recomenda manter o CLAUDE.md abaixo de 200 linhas e quebrar conjuntos maiores de instruções em arquivos no subdiretório .claude/rules/, cada um escopado pros caminhos de arquivo relevantes. Um wiki encaixa naturalmente nessa estrutura: conhecimento específico de domínio carrega só quando o agente está trabalhando na parte correspondente do codebase.
Ciclo Ingerir → Compilar → Consultar aplicado a um codebase
Adaptado pra contexto de engenharia, o ciclo fica assim:
Ingerir: Novas decisões arquiteturais, mudanças em contrato de API, atualizações de dependência, post-mortems e discussões de design vão pra raw/. Você pode usar comentários em commit message, descrição de PR ou um log diário leve. A camada raw é intencionalmente sem estrutura — o único requisito é que exista e seja datável.
Compilar: O agente lê as novas entradas raw e atualiza o wiki. Uma decisão de migrar de REST pra gRPC no serviço de dados vira uma atualização em architecture/protocols/grpc-migration.md, com backlinks pros serviços afetados e referência cruzada pros benchmarks de latência que motivaram a mudança. O agente escreve; você revisa.
Consultar: No início da sessão, o agente carrega as seções relevantes do wiki via imports do CLAUDE.md. Quando precisa entender por que o sistema de auth funciona do jeito que funciona, lê o wiki em vez de te perguntar. Outputs — propostas de refatoração, alternativas de design, hipóteses de debug — voltam arquivados como novas entradas raw ou direto como atualização do wiki.
Lint: Periodicamente, roda uma passada de manutenção. Pede pro agente varrer páginas de wiki que referenciam caminhos de código que não existem mais, sinalizar decisões cujo racional ficou obsoleto e identificar lacunas onde material raw novo ainda não foi compilado.
Onde isso bate o RAG e onde não bate
Esse padrão é melhor que RAG quando: seu corpus de conhecimento é limitado (centenas de documentos, não centenas de milhares), o conteúdo evolui deliberadamente e se beneficia de entendimento acumulado, e você precisa que agentes em múltiplas sessões compartilhem uma visão coerente do projeto.
É pior que RAG quando: o corpus é genuinamente grande (milhões de tokens, milhares de documentos com padrões de acesso heterogêneos), os requisitos de retrieval são imprevisíveis, ou o overhead de latência da busca baseada em embedding é aceitável em troca de escala. Organizações grandes de engenharia com múltiplos repos e centenas de serviços provavelmente precisam dos dois — uma camada RAG pra retrieval amplo e um wiki compilado pra contexto específico de projeto.
O problema de conteúdo desatualizado é real dos dois lados. Um wiki que não é mantido é pior que nenhum wiki — entrega informação errada com confiança pro agente. Passadas de lint ajudam, mas não substituem review humano de mudanças arquiteturais significativas.
Setup prático pra um projeto de código
Estrutura de diretório: raw/, wiki/, índice
Um setup mínimo:
project-root/
├── CLAUDE.md # Carrega o índice do wiki; fica abaixo de 200 linhas
├── .claude/
│ └── rules/
│ ├── backend.md # Escopado pra src/api/**
│ └── frontend.md # Escopado pra src/ui/**
└── wiki/
├── INDEX.md # Navegação top-level do wiki
├── architecture/
│ ├── overview.md
│ ├── decisions/ # ADRs — um arquivo por decisão
│ └── protocols/
├── domains/ # Glossário do domínio de negócio
├── ops/ # Deploy, ambiente, dependências
└── raw/ # Material de fonte não compiladoO CLAUDE.md contém @wiki/INDEX.md e convenções de nível de projeto. O arquivo de índice mapeia subsistemas pras seções correspondentes do wiki. O agente navega pela estrutura do mesmo jeito que um engenheiro humano faria.
Quais ferramentas encaixam: Obsidian, Claude Code, scripts locais
O Obsidian funciona bem como frontend pro humano: a graph view mostra densidade de link e revela páginas órfãs, o web clipper ingere referências externas direto como markdown, e renderiza o wiki localmente sem dependência de servidor. O Karpathy usa assim — como camada de leitura/navegação, não como camada de escrita. O agente faz a escrita.
O Claude Code é o motor de compilação e manutenção. Você aponta ele pra raw/ com um prompt tipo "compila qualquer entrada nova em raw/ no wiki, atualiza páginas de índice afetadas e cria backlinks onde fizer sentido". No setup de agente paralelo do Verdent, dá pra rodar manutenção do wiki como tarefa em background num worktree dedicado enquanto outros agentes seguem o trabalho de código em isolamento.
Scripts locais podem automatizar o lado da ingestão: um git hook que anexa descrição de PR significativas em raw/, um cron que puxa issues novas com tag arch-decision pra raw/, ou um CLI simples que deixa você logar uma nota rápida do terminal. Quanto menor a fricção de ingestão, mais consistentemente o wiki é alimentado.
O que vai pro wiki vs. o que fica no codebase
O wiki é pra raciocínio que não pertence ao código. O código documenta o que o sistema faz. O wiki documenta por que faz desse jeito, que alternativas foram consideradas e que restrições moldaram a decisão.
Wiki: Decisões arquiteturais e o racional. Terminologia do domínio e relações entre entidades. Notas sobre dependências externas (por que essa biblioteca, quais os limites conhecidos, quando reconsiderar). Restrições de ambiente e deploy que afetam decisões de desenvolvimento. Padrões recorrentes de debug pra problemas difíceis conhecidos.
Codebase: Contratos de API, definições de tipo, comentários inline explicando lógica não-óbvia, casos de teste, configuração. Tudo que um engenheiro novo deveria aprender do código em si.
Se você se pega adicionando contexto explicativo ao wiki que devia ser uma docstring ou comentário inline, o código precisa de melhor documentação, não de wiki melhor.
Limitações e tradeoffs pra saber antes de construir
Custo de manutenção: quem lintha o wiki?
Um wiki que não é mantido engana ativamente. A passada de lint ajuda — o agente consegue identificar inconsistência interna, link morto e referência pra caminho de código deprecado — mas não consegue saber quando uma suposição arquitetural que estava correta seis meses atrás agora está errada porque a restrição externa mudou. Isso exige julgamento humano.
Na prática, alguém do time precisa ser dono do wiki do mesmo jeito que alguém é dono da arquitetura. Não como trabalho full-time, mas como responsabilidade recorrente: revisar entradas compiladas, rodar passadas de lint depois de mudança significativa e ocasionalmente reescrever seções que se desviaram demais da realidade atual. Se ninguém é dono, degrada mais rápido do que acumula valor.
Teto de escala: o sweet spot é centenas, não milhões de docs
O Karpathy descreve o setup dele como uns 100 artigos e cerca de 400.000 palavras — a cobertura do VentureBeat sobre o post nota que nessa escala, a capacidade do LLM de navegar via resumo e arquivo de índice é "mais que suficiente" sem infra de banco vetorial. Nessa escala, arquivos de índice e janela de contexto do LLM dão conta de navegar sem infra de embedding.
Além disso — múltiplos repos grandes, anos de histórico de decisão, conhecimento entre times — a abordagem de janela de contexto começa a apertar. Navegação por resumo e índice funciona até o próprio índice ficar pesado. Não é falha do padrão; é fronteira de escopo. Pra codebases maiores, um wiki compilado cuidando do contexto mais recente e mais acessado, combinado com camada RAG pra retrieval mais amplo, é arquitetura mais realista.
Esse teto de escala é observação da comunidade, não benchmark publicado formalmente. A densidade de conhecimento específica do seu projeto, com que frequência seções do wiki são acessadas, e quão agressivamente você mantém o índice, tudo afeta onde o teto prático fica.
Não é substituto pra documentação adequada do codebase
O wiki não substitui documentação — opera ao lado. Um README bem estruturado, doc de API abrangente e comentários inline claros significam que o agente precisa de menos wiki pra entender o codebase. Um wiki cobrindo o que o código não consegue expressar significa que agentes e engenheiros gastam menos token em arqueologia.
Tentar usar o wiki como substituto pra documentação de código cria um problema de manutenção com duas peças móveis em vez de uma. Mantém a divisão de responsabilidade clara: código pro quê, wiki pro porquê.
FAQ
Qual a diferença entre uma knowledge base com LLM e RAG?
RAG faz retrieval de chunks relevantes de uma coleção de documentos no momento da consulta usando similaridade de embedding — cada consulta começa do zero, sem conhecimento acumulado. Uma knowledge base com LLM tem o LLM compilando ativamente fontes brutas em markdown estruturado e interligado, construindo entendimento incrementalmente ao longo do tempo. O wiki compilado reflete conhecimento sintetizado; o RAG reflete documentos indexados. Pra corpus limitado onde o contexto se constrói sobre si mesmo, a abordagem de wiki compilado produz comportamento de agente mais coerente. Pra conjuntos grandes e heterogêneos de documento onde qualquer documento pode ser relevante pra qualquer consulta, RAG é mais apropriado.
Isso funciona com Claude Code ou outros agentes de IA pra código?
Sim, direto. O sistema CLAUDE.md do Claude Code carrega arquivos markdown no início da sessão, e a sintaxe de import @path deixa o CLAUDE.md referenciar páginas do wiki sem embutir o conteúdo completo no arquivo principal. O diretório .claude/rules/ suporta regras escopadas por caminho que carregam só quando o agente trabalha em partes correspondentes do codebase — encaixe natural pra páginas de wiki específicas de subsistema. Agentes Verdent rodando em worktrees isolados podem compartilhar um diretório de wiki comum, dando a agentes paralelos uma visão consistente do contexto do projeto sem escritas conflitantes se o acesso de escrita for coordenado por um agente de compilação dedicado.
Quão grande um projeto precisa ser pra justificar esse setup?
O ponto de equilíbrio é mais ou menos quando re-explicar contexto do projeto no início da sessão leva mais tempo do que manter o wiki levaria. Pra dev solo num único projeto focado, um CLAUDE.md bem estruturado pode bastar. Pra projeto com múltiplos subsistemas, vários agentes ativos e mais de algumas semanas de decisões arquiteturais não-triviais, o custo acumulado de restabelecimento de contexto faz o wiki valer a pena. O overhead de setup é baixo — você está criando diretório e arquivo markdown, não fazendo deploy de infra. Começa pequeno: um diretório de decisões arquiteturais, um glossário de domínio e o CLAUDE.md apontando pra eles.
Múltiplos agentes podem compartilhar a mesma knowledge base?
Podem, com coordenação. O wiki é arquivo em disco — qualquer agente com acesso ao filesystem consegue ler. Acesso de escrita exige cuidado: passadas simultâneas de compilação de múltiplos agentes podem produzir edição conflitante. A abordagem prática é um agente de compilação designado que tem acesso de escrita no wiki, enquanto agentes de tarefa têm acesso só-leitura (ou acesso de escrita só em raw/, deixando a compilação como passo separado). Em setups com git worktree, o wiki pode morar no próprio worktree, garantindo que agentes de tarefa puxem leitura limpa sem interferir na compilação em andamento.
O que acontece quando o código muda mas o wiki não é atualizado?
O agente recebe contexto errado com confiança, o que é pior que nenhum contexto. Esse é o risco central de manutenção do padrão. Estratégias de mitigação: rodar passada de lint depois de mudança significativa de código, usando o agente pra sinalizar páginas de wiki que referenciam caminho de código modificado ou removido; escopar entradas do wiki pra decisão e racional em vez de detalhe de implementação (racional envelhece mais devagar que código); e tratar wiki desatualizado como custo real de manutenção quando avaliar se vale rodar o padrão pro seu projeto. Um wiki com dono claro e cadência regular de lint degrada com graça. Um wiki mantido só na empolgação degrada rápido.
