A Estratégia da Base de Conhecimento: Dando aos Agentes de IA Uma Memória que Compõe

Todo agente de IA de codificação tem a mesma fraqueza fundamental: ele não tem memória do seu sistema.

Você pode apontá-lo para o seu código-fonte. Ele pode ler seus arquivos, fazer grep nos seus símbolos, rastrear seus imports. Mas ele não conhece seu sistema. Ele não sabe por que você escolheu aquele banco de dados, o que as três tentativas fracassadas de migração ensinaram, qual módulo está prestes a ser descontinuado, ou que o refactor "simples" que o estagiário sugeriu no mês passado na verdade quebra um invariante sutil no pipeline de faturamento.

Esse conhecimento vive na cabeça dos membros da sua equipe, espalhado por threads antigas no Slack, páginas de Confluence desatualizadas e mensagens de commit de engenheiros que saíram há dois anos. Quando você pede a um agente de IA para planejar uma nova feature ou desenhar uma migração, ele está trabalhando sem nenhum desse contexto. E isso aparece — os planos são tecnicamente plausíveis, mas arquiteturalmente ingênuos. Eles resolvem o problema que o agente consegue ver enquanto ignoram as restrições que ele não consegue.

Existe uma solução para isso. Não é RAG. Não é fine-tuning. É uma base de conhecimento estruturada, mantida por LLM, que fica ao lado do seu código e dá aos seus agentes uma memória persistente e cumulativa da sua arquitetura, decisões e conhecimento de domínio.

Venho construindo e usando esse padrão no último ano, e abri o código de um template para que você também possa fazer isso: knowledge-base-template.

O problema: agentes sem memória produzem planos sem sabedoria

Aqui está um cenário que toda equipe de engenharia já vivenciou com agentes de IA:

Você pede ao agente para planejar uma migração do seu sistema de autenticação. O agente lê o código do módulo de autenticação, rastreia os pontos de chamada e produz um plano. O plano está sintaticamente correto. Ele lida com os casos óbvios. Ele até inclui uma estratégia de rollback.

Mas o plano está errado, porque:

Ele não sabe que a migração de autenticação do ano passado falhou por causa de uma race condition no tratamento de sessões que só se manifesta sob carga — e o código atual tem um workaround que parece um bug mas na verdade é crítico
Ele não sabe que o serviço de faturamento tem uma dependência não documentada no formato do token de autenticação que não é visível no grafo de imports
Ele não sabe que sua equipe decidiu há seis meses avançar em direção a um padrão específico de autenticação, e o plano deveria estar alinhado com essa trajetória
Ele não sabe que o engenheiro sênior que construiu o sistema de autenticação está em licença-paternidade e ninguém mais entende totalmente o mecanismo de rotação de tokens

Nada disso está no código. O agente fez o melhor que pôde com o que tinha. O problema não é o raciocínio do agente — é o contexto do agente.

Essa é a lacuna de memória. E jogar mais código no agente não fecha essa lacuna. Você precisa de conhecimento estruturado sobre seu sistema — o porquê, a história, as restrições, as decisões — não apenas o quê do código atual.

A ideia central: pare de re-derivar, comece a compilar

A ideia central vem do padrão LLM Wiki de Andrej Karpathy: em vez de fazer um LLM recuperar de documentos brutos e re-derivar entendimento toda vez (a abordagem RAG), fazer com que ele construa e mantenha um wiki persistente. O LLM lê suas fontes, extrai as informações-chave e as integra em uma base de conhecimento em evolução, com referências cruzadas. O conhecimento se acumula ao longo do tempo, em vez de ser descartado após cada conversa.

Peguei essa ideia e a apliquei a um domínio específico: equipes de engenharia e seus códigos-fonte.

A base de conhecimento se torna a memória de longo prazo do agente sobre o seu sistema. Não um banco de dados vetorial que você consulta. Não um embedding que você afina. Um wiki — legível por humanos, versionado, e mantido pelos mesmos agentes LLM que o utilizam.

Como funciona: a arquitetura de três camadas

O knowledge-base-template implementa uma arquitetura de três camadas:

Camada 1: Fontes brutas (imutáveis)

Seus documentos-fonte. Registros de decisão arquitetural. Notas de reunião. Relatórios de postmortem. Documentos de RFC. Docs de design. Contratos de API. Guias de onboarding. Qualquer coisa que contenha conhecimento institucional sobre seu sistema. Coloque-os ali, nunca os modifique. Essa é sua verdade absoluta.

Camada 2: O wiki (gerado por LLM)

É aqui que a mágica acontece. O LLM lê as fontes brutas e constrói um wiki estruturado: páginas de conceitos, páginas de entidades, registros de decisão, páginas de projetos, páginas de ferramentas — todas com referências cruzadas via wikilinks, marcadas com metadados e pontuadas com níveis de confiança. Um único documento-fonte pode afetar de 10 a 15 páginas do wiki quando ingerido.

O wiki não é um depósito. Ele é organizado:

Conceitos — padrões arquiteturais, princípios de design, ideias específicas de domínio usadas em seu sistema
Entidades — serviços, bancos de dados, sistemas de terceiros, equipes, pessoas-chave
Projetos — iniciativas em andamento, seu status, decisões, bloqueios e aprendizados
Fontes — uma página de resumo por documento ingerido, ligada a todas as entidades e conceitos que ela menciona
Ferramentas — tecnologias na sua stack, como estão configuradas, por que foram escolhidas

Toda página tem frontmatter YAML com metadados estruturados — tipo, tags, data de criação, pontuação de confiança, fontes. Isso torna o wiki consultável: "mostre-me todas as decisões de arquitetura dos últimos 6 meses com confiança abaixo de 0,7" é uma consulta válida.

Camada 3: O esquema (regras e convenções)

Um arquivo de configuração (eu uso CLAUDE.md para o Claude Code, mas funciona com qualquer agente) que diz ao LLM como manter o wiki. Quais tipos de páginas existem, quais são as convenções de nomenclatura, como tratar conflitos, quando criar vs. atualizar uma página, como manter o índice. Essa é a diferença entre um wiki que permanece organizado e um que degenera em caos. O esquema evolui com as necessidades da sua equipe.

O que entra: o conhecimento que um agente precisa para bons planos

Aqui está o que eu coloco na base de conhecimento de um código-fonte em produção, e por que cada parte importa para os planos de desenvolvimento gerados por agentes:

Registros de Decisão Arquitetural (ADRs)

O quê: Documentos registrando por que escolhas técnicas específicas foram feitas. "Escolhemos PostgreSQL em vez de MongoDB porque..." ou "Decidimos manter o serviço de autenticação monolítico porque dividi-lo introduzia um problema de transação distribuída que não estávamos prontos para resolver."

Por que importa para agentes: Sem ADRs, um agente sugerirá o que parece ótimo isoladamente. Com ADRs, o agente entende as restrições que moldaram o sistema atual e evita re-propor soluções que já foram consideradas e rejeitadas. Essa é a categoria de conhecimento com maior impacto na qualidade dos planos.

Topologia de serviços e sistemas

O quê: Páginas descrevendo cada serviço, suas responsabilidades, suas dependências, seus armazenamentos de dados, suas características de deployment. Não apenas o código — a realidade operacional.

Por que importa: Um agente lendo código pode inferir o call graph. Mas ele não pode inferir que o Serviço A é sensível à latência e roda em instâncias dedicadas, enquanto o Serviço B é orientado a lote e compartilha computação. Ele não pode inferir que o pool de conexões com o Banco de Dados C é o gargalo durante o tráfego de pico. Esses fatos operacionais mudam o que um "bom" plano parece.

Postmortems e padrões de falha

O quê: Resumos de incidentes passados. O que quebrou, por quê, o que foi aprendido, o que foi mudado.

Por que importa: Postmortems são conhecimento negativo — coisas que o sistema não pode fazer ou não deveria tentar. Um agente sem conhecimento de postmortems alegremente reintroduzirá exatamente o padrão que causou uma queda há seis meses. Com conhecimento de postmortems, os planos do agente ativamente evitam modos de falha conhecidos.

Conceitos de domínio e regras de negócio

O quê: Definições de termos de domínio, invariantes de negócio, requisitos de conformidade. "Uma 'liquidação' é final e nunca pode ser revertida." "Todos os dados pessoais (PII) devem ser criptografados em repouso e ter acesso registrado conforme o Artigo 30 do GDPR."

Por que importa: Agentes tendem a soluções ótimas de engenharia por padrão. Regras de negócio adicionam restrições que mudam o que "ótimo" significa. Um agente que sabe que "liquidações são irreversíveis" projetará um plano de migração com uma etapa de validação antes do ponto sem retorno, em vez de uma estratégia de rollback genérica que não se aplica.

Projetos em andamento e mudanças próximas

O quê: O que está sendo trabalhado neste momento. Quais módulos estão prestes a mudar. O que está descontinuado mas ainda não foi removido.

Por que importa: Um agente sem esse contexto pode planejar uma feature que se baseia em um módulo que será removido no próximo trimestre, ou desenhar um sistema que duplica um trabalho que outra equipe já está fazendo. O contexto de projetos atuais transforma planos de "tecnicamente corretos" em "estrategicamente alinhados."

O efeito cumulativo: como os agentes ficam mais inteligentes ao longo do tempo

A base de conhecimento não apenas armazena informação. Ela a compõe.

Quando você ingere um postmortem de uma falha de migração de banco de dados, o LLM não apenas arquiva um resumo. Ele atualiza a página de entidade do banco de dados com o padrão de falha. Ele adiciona um aviso à página do conceito de migração. Ele liga o postmortem à página de projeto em andamento para a próxima migração planejada. Ele eleva a confiança na afirmação "este banco de dados não lida bem com mudanças de schema sob carga" de 0,5 (observação única) para 0,8 (confirmado por incidente).

Seis meses depois, quando um agente estiver planejando uma nova migração, todo esse contexto estará aguardando no wiki. O agente lê as páginas relevantes e produz um plano que considera a sensibilidade à carga, evita o padrão de falha e referencia a abordagem de migração estabelecida pela equipe. Não porque o agente esteja mais inteligente. Porque a base de conhecimento está mais rica.

Este é o efeito cumulativo. Cada fonte que você ingere, cada pergunta que você faz, cada postmortem que você arquiva torna cada plano futuro ligeiramente melhor. RAG não faz isso. RAG recupera fragmentos. Uma base de conhecimento constrói síntese.

O ciclo de vida do conhecimento

Nem todo conhecimento permanece igualmente válido para sempre. O knowledge-base-template implementa um modelo de ciclo de vida:

Pontuação de confiança — toda afirmação carrega uma pontuação (0,0-1,0) com base em quantas fontes a apoiam e quão recentemente foi confirmada. A confiança decai com o tempo e se fortalece quando novas evidências a confirmam.
Supersessão — quando nova informação contradiz uma afirmação antiga, a nova página explicitamente supera a antiga. O conteúdo antigo é preservado para o histórico, mas marcado como obsoleto.
Camadas de consolidação — observações brutas são promovidas através de camadas conforme as evidências se acumulam. Um padrão visto uma vez permanece em um resumo de fonte. Um padrão visto em três postmortems ganha sua própria página de conceito. Um padrão que molda como a equipe trabalha se torna conhecimento procedural.

Esse ciclo de vida significa que os agentes trabalham com conhecimento ponderado pela confiabilidade. Uma decisão arquitetural bem fundamentada e recentemente confirmada carrega mais peso do que uma observação especulativa de uma nota de reunião de um ano atrás.

Fluxo prático: mantendo a base de conhecimento

O fluxo de trabalho diário tem três operações:

Ingestão

Coloque um documento-fonte no diretório raw e diga ao agente para processá-lo. O agente lê a fonte, extrai entidades e conceitos, cria ou atualiza páginas do wiki, sinaliza contradições com conhecimento existente, e atualiza o índice e o log. Um único ADR pode criar uma página de resumo de fonte e atualizar cinco páginas de entidade/conceito.

Eu ingiro fontes uma de cada vez e permaneço envolvido — reviso os resumos, verifico as referências cruzadas e oriento o agente sobre o que importa. Mas você também pode ingerir em lote com menos supervisão se as fontes forem bem estruturadas.

Consulta

Faça perguntas ao wiki. "Quais são os riscos de migrar o Serviço X para um novo banco de dados?" O agente pesquisa no wiki, lê páginas relevantes (a página de entidade do serviço, a página de ferramenta do banco de dados, postmortems relacionados, status do projeto atual) e sintetiza uma resposta com citações. Respostas substanciais podem ser arquivadas de volta como novas páginas do wiki — então suas explorações se acumulam na base de conhecimento da mesma forma que fontes ingeridas.

Lint

Periodicamente faça um check-up de saúde do wiki. Encontre páginas órfãs sem links de entrada. Sinalize afirmações obsoletas onde a confiança decaiu. Detecte referências cruzadas ausentes. Identifique conceitos que são mencionados frequentemente, mas ainda não têm sua própria página. O agente corrige o que pode automaticamente e sinaliza o resto para revisão humana.

Antes e depois: o que muda na prática

Aqui está a diferença concreta que observei na qualidade dos planos quando os agentes trabalham com vs. sem uma base de conhecimento:

Sem a base de conhecimento

O agente lê o código, produz um plano que:

Resolve o problema como enunciado, ignorando restrições que não são visíveis no código
Re-propõe abordagens que a equipe já tentou e rejeitou
Ignora trabalhos em andamento que afetam os mesmos módulos
Trata todos os componentes como igualmente modificáveis (não sabe sobre módulos congelados, invariantes frágeis ou depreciações próximas)
Produz estratégias genéricas de migração/rollback em vez de estratégias adaptadas aos modos de falha reais do seu sistema

Com a base de conhecimento

O agente lê o código e as páginas relevantes do wiki, produz um plano que:

Referencia decisões arquiteturais específicas e explica como o plano se alinha com elas
Evita padrões que causaram incidentes passados (citando o postmortem relevante)
Leva em conta projetos em andamento que tocam as mesmas áreas
Trata componentes de forma diferente com base em suas características operacionais e estabilidade
Inclui mitigações de risco adaptadas aos modos de falha conhecidos do seu sistema

A diferença é a diferença entre um plano de um contratado inteligente que acabou de ler o código-fonte e um plano de um engenheiro sênior que está na equipe há um ano. A base de conhecimento fornece o contexto "está na equipe há um ano" que o código sozinho não pode.

Por que um wiki supera o RAG para isso

A pergunta óbvia: por que não usar apenas RAG (Retrieval-Augmented Generation) — jogar seus documentos em um banco de dados vetorial e deixar o agente recuperar trechos relevantes?

RAG funciona para recuperação factual simples. "Qual é o endpoint da API do serviço de pagamento?" — RAG lida bem com isso.

Mas o RAG falha exatamente naquilo que torna os planos bons: síntese entre múltiplas fontes. Quando um agente precisa entender por que o sistema de autenticação é projetado da forma como é, ele precisa sintetizar informações de um ADR, dois postmortems, um doc de design e o status do projeto atual. RAG recupera fragmentos. Ele não os sintetiza. Cada consulta começa do zero, re-derivando conexões que foram estabelecidas na semana passada.

Um wiki pré-computa a síntese. A página do sistema de autenticação já tem a racionalidade de design, o histórico de falhas, as restrições atuais e os links relevantes. O agente lê uma página e obtém a imagem integrada. A síntese foi feita de forma incremental, toda vez que uma nova fonte foi ingerida, e foi mantida ao longo do tempo. RAG não consegue fazer isso.

Dito isso, as duas abordagens não são mutuamente exclusivas. RAG é ótimo para pesquisar em um grande corpus de documentos. Um wiki é ótimo para manter conhecimento sintetizado e estruturado. Em escala, você quer ambos — RAG para descoberta, wiki para entendimento.

Começando

Abri o código do template que eu uso: bmentges/knowledge-base-template

Ele foi projetado para funcionar com qualquer agente LLM de codificação (Claude Code, Codex, Cursor, Windsurf, ou qualquer um que possa ler/escrever arquivos) e usa o Obsidian como visualizador. A configuração leva cerca de 15 minutos:

Clone o template
Abra seu agente LLM no diretório
Diga a ele seu caso de uso e deixe-o configurar o esquema
Abra o diretório como um cofre do Obsidian
Comece a ingerir suas primeiras fontes

O template inclui o documento original do padrão LLM Wiki de Karpathy, além de uma extensão v2 com gerenciamento de ciclo de vida (pontuação de confiança, supersessão, camadas de consolidação) e padrões de escala para quando seu wiki crescer além de algumas centenas de páginas.

Comece pelos documentos que contêm o maior conhecimento institucional: registros de decisão arquitetural, postmortems e documentos de topologia de sistema. Três bons ADRs no wiki melhorarão a qualidade dos planos do agente mais do que cinquenta arquivos de código brutos.

O quadro maior: agentes precisam de infraestrutura de memória

Estamos nos primeiros dias do uso de agentes de IA para trabalho de engenharia real. A maioria das equipes está focada no próprio agente — qual modelo usar, como fazer o prompt, que ferramentas dar a ele. Isso importa, mas não é o gargalo.

O gargalo é o contexto. Um agente sem memória institucional é como um contratado brilhante em seu primeiro dia — tecnicamente habilidoso mas arquiteturalmente ingênuo. A solução não é um contratado mais inteligente. É dar a ele acesso ao conhecimento acumulado da equipe em uma forma que ele realmente possa usar.

Uma base de conhecimento estruturada e mantida por LLM é infraestrutura de memória para agentes de IA. É a camada que transforma inteligência genérica na inteligência da sua equipe. E, ao contrário do próprio agente, que você obtém de um fornecedor, a base de conhecimento é sua vantagem competitiva — é a sabedoria acumulada da sua equipe, organizada para consumo por máquinas.

As equipes que construírem essa infraestrutura agora terão agentes que produzem trabalho significativamente melhor do que as equipes que não a construírem. Não porque seus agentes sejam mais inteligentes, mas porque seus agentes sabem mais.