785 artigos para agentes, não para humanos. Uma base de conhecimento sem busca vetorial

Quando um agente começa a trabalhar num projeto desconhecido, ele gasta os primeiros 30 a 40% dos seus tokens descobrindo o que está acontecendo ao redor. Não trabalhando, se orientando. Este post descreve o Happyin Knowledge Space, uma biblioteca de cards de referência que escrevo para agentes, e não para pessoas: por que o formato dos cards é como é, por que domínios que mudam rápido têm um limite de atualidade, por que ligo os cards à mão em vez de guardá-los num banco vetorial e como pesquisas feitas em conversas de várias contas chegam até lá sem nenhum copiar e colar. Em 22 de abril de 2026, quando saiu o original em russo, ele tinha 785 cards em 26 domínios.

Dois problemas com a forma como um agente aprende um projeto

Um README explica a motivação, um tutorial dá a mão ao leitor, uma referência de API lista parâmetros. Nenhum deles responde à pergunta com que o agente de fato chegou: aqui está minha tarefa, qual padrão eu copio e onde estão as armadilhas?

O segundo problema é mais profundo e leva mais tempo para ser percebido. Um modelo sabe "tudo", mas esse tudo está distribuído de forma desigual pelos dados de treinamento. Quanto mais tempo uma tecnologia está na internet, mais posts, respostas do Stack Overflow e tutoriais existem sobre ela, e mais peso aquela abordagem carrega dentro do modelo. Quando peço ao Claude para treinar um LoRA, a primeira coisa que ele oferece é uma receita de cinco anos atrás. Não porque seja melhor, mas porque há mais dela. Para tecnologias estáveis, tudo bem. Para qualquer coisa que se move rápido, como treinamento de modelos, ferramentas de agentes ou segurança, isso significa que o agente me puxa discretamente para o passado.

A cura óbvia é rodar uma pesquisa profunda toda vez e trazer contexto atual. Eu faço isso. Mas pesquisa profunda é cara: várias centenas de dólares por mês em assinaturas, e os limites ainda acabam quase de imediato. Pior, cada pesquisa desaparece junto com a sessão. Amanhã vou rodar a mesma busca sobre o mesmo tema e gastar os mesmos tokens com o que eu já descobri.

Dessa situação saíram duas ideias. Pesquisa deve se acumular, não evaporar. E o formato deve mostrar ao agente o que é atual agora, de modo que abrir um projeto o coloque imediatamente em "é assim que se faz aqui".

O formato: um card, não um artigo

Cada card tem o mesmo esqueleto. No topo, o tema e uma definição em uma frase, para que o agente saiba na hora se caiu no lugar certo. Depois, Key Facts: afirmações curtas com números, como versões, limites e dependências. Em seguida, Patterns: código copiável, com tag de linguagem. No fim, as armadilhas (gotchas), cada uma como um par do que quebra e do que conserta.

Nada de introduções do tipo "vamos dar uma olhada" e nada de finais do tipo "neste artigo examinamos". O card sobre a arquitetura de brokers do Kafka é uma tabela ZooKeeper versus KRaft, uma configuração comentada, métricas JMX com limites de alerta e uma migração passo a passo. Não se lê de forma fluida. Mas um agente faz grep por "KRaft migration" e recebe uma receita funcional em três passos.

O último bloco é o mais valioso. Uma linha, "min.insync.replicas only takes effect with acks=all", economiza meia hora de depuração. O agente leu, não cometeu o erro e não gastou um ciclo de nova tentativa para corrigi-lo.

26 domínios, crescidos do trabalho

Em abril, o maior domínio era Geração de Imagens, com 58 cards, seguido de perto por Agentes LLM, com 57, depois Data Science e Segurança, com 56 cada (Segurança cresceu por meio de uma pasta separada sobre classes CWE). Depois vinham Kafka, com 43, DevOps com 38, Frontend Web com 36, Engenharia de Dados com 34, e quatro domínios com 33: Python, SQL, Arquitetura e Algoritmos. Catorze domínios menores completavam o total: iOS, Linux CLI, C++, Java Spring, Testes e QA, BI, SEO, Rust, Node.js, PHP, Memória de LLM, Áudio e voz, Escrita e Go.

Isso não é um plano. É um mapa de onde meu tempo realmente vai quando trabalho com agentes: treinar LoRAs, depurar plugins em C++, pesquisa. Cada área reuniu sua própria lista de lugares onde algo quebrou para mim, e essas listas viraram o esqueleto.

O conhecimento não envelhece no mesmo ritmo

Algoritmos e matemática são estáveis: um card sobre análise amortizada ou fluxo em redes escrito três anos atrás continua correto. Treinamento de difusão, otimização de inferência e nós do ComfyUI mudam a cada poucos meses, e o que funcionava no outono já foi superado na primavera. O tiling de difusão em fotos muito grandes, sobre o qual escrevi em Por que a difusão desenha costuras em fotos de 40 megapixels, é um desses temas que se movem rápido.

Por isso, cada domínio tem seu próprio limite de atualidade. Domínios estáveis não têm nenhum. Em domínios rápidos, um card com mais de 60 dias é marcado para revisão, e um hook que roda uma vez por dia o coloca numa lista de "conferir e atualizar". Não é um alerta de exclusão. É um lembrete de que o tema provavelmente se moveu e de que o card precisa ser conferido com o que é verdade agora. Cards desatualizados entram em revisão por conta própria, em vez de enganar o agente em silêncio.

Links em vez de vetores

A arquitetura óbvia para isso é um banco vetorial com RAG por cima. Ele encontra texto semanticamente próximo com rapidez e funciona bem em produção. Deliberadamente não usei um, por três motivos.

Um vector store não é legível por humanos. Markdown eu consigo abrir num editor de texto, buscar com grep, comparar no git, colar num e-mail ou imprimir e pendurar na parede. Isso funciona hoje e vai funcionar daqui a dez anos em qualquer computador, sem ferramentas especiais. Um vector store é um binário que só o próprio cliente entende. Troque de fornecedor, perca o serviço, quebre a API, e os dados viram uma pilha de números que ninguém consegue ler. Eu queria que a base de conhecimento sobrevivesse a uma troca de ferramentas, e não que dependesse delas.

Vetorizar é quase irreversível. Um embedding é uma compressão com perdas e de mão única. Sem os chunks originais guardados ao lado, um arquivo de embeddings é inútil, porque recuperar um texto legível é quase impossível. Existe pesquisa sobre inversão de embeddings, mas ela funciona em fragmentos muito curtos, precisa do mesmo modelo de embedding e de um decodificador treinado à parte. Além disso, ela prende você a um único modelo de embedding: troque de modelo por uma qualidade melhor e precisará reindexar tudo, porque os vetores antigos não significam nada no novo espaço.

E o que mais me importa: um grafo de links registra quais tópicos são adjacentes, não quais textos são parecidos. A similaridade vetorial encontra tópicos que se sobrepõem em vocabulário e conceitos. No trabalho real, os links valiosos muitas vezes ligam tópicos muito distantes entre si. O card de replicação do Kafka que escrevi liga-se a um card de profiling de memória, não porque os temas sejam parecidos, mas porque ajustar um consumer revelou um vazamento de memória, e a experiência os tornou vizinhos. No espaço de embeddings, "replicação em uma fila distribuída" e "profiling de memória em Python" ficam muito longe um do outro, e a busca semântica não vai construir essa ponte. Um wiki-link escrito à mão constrói, e agora um agente que lê sobre Kafka está a um passo do profiling de memória.

O mecanismo é simples. Os cards se referenciam como [[flux-klein-9b-inference]], [[two-phase-commit]], [[saga-pattern]]. Na hora do build, um hook em Python resolve cada slug para um caminho relativo. Se um slug não for encontrado, o log recebe um aviso, e no modo estrito o build falha, para que um link quebrado nunca chegue ao site no ar. Em abril havia mais de 2.100 desses links. Esse é o grafo de conhecimento inteiro: sem embeddings, sem banco vetorial, sem RAG. Markdown e grep. Um agente abre o card sobre transações distribuídas, vê os tópicos vizinhos em See Also, segue um deles e continua. Três passos do ponto de entrada até um padrão funcional.

É a mesma ideia dos links [[filename]] na memória dos meus agentes, descrita em Meu CLAUDE.md tem 582 linhas.

O site é um build do repositório

Tudo em happyin.space é um site estático gerado a partir de Markdown num repositório aberto. Sem banco de dados, sem backend, sem camada escondida. O arquivo docs/kafka/broker-architecture.md se torna a página happyin.space/kafka/broker-architecture/ depois do build, e esse é todo o mecanismo.

Isso significa que qualquer um pode fazer um fork e rodar localmente em cerca de cinco minutos:

git clone https://github.com/AnastasiyaW/knowledge-space.git
cd knowledge-space
pip install -r requirements.txt
mkdocs serve        # then open http://localhost:8000

Isso dá uma cópia local com todos os cards, busca completa e o grafo de links. A partir daí você pode apagar meus domínios, adicionar os seus e apontar seus agentes para o build local em vez do site público. É assim que eu mesma uso: na maior parte do tempo o build local está aberto, e o site público é um espelho.

Um rebuild completo levou cerca de cinco segundos, tão rápido num notebook antigo quanto numa estação de trabalho, porque por baixo está o tipo de gerador de site estático que a indústria usa há quinze anos. Um agente que trabalha com uma cópia local não gasta tokens com ida e volta de rede nem esperando um deploy: rebuild, abre o card, pega a receita.

O mesmo passo de build mantém os links honestos. Ele percorre cada [[slug]], encontra o card correspondente e escreve o caminho relativo, e se não encontrar nada, o build falha. Eu vejo isso localmente antes de fazer commit, e o CI roda a mesma checagem no modo estrito, em que qualquer link quebrado bloqueia o deploy. Em abril, isso significava mais de 2.100 links e nenhum quebrado. E como o site é o repositório, tudo está no git: dá para ver como um card mudou, quais fatos chegaram depois de qual rodada de pesquisa e quando ele foi tocado pela última vez. Para uma base organizada pela velocidade com que seu conhecimento envelhece, esse histórico importa.

Como a pesquisa entra

A rotina está montada de modo que eu nunca mova dados à mão. Tenho várias contas do Claude, cada uma com várias conversas abertas, e em qualquer uma delas uma pesquisa profunda pode começar a qualquer momento: novos modelos, otimizações, bugs, qualquer coisa. Antes, o resultado vivia até o fim da conversa. Agora cada uma dessas conversas segue a mesma regra permanente: quando uma rodada de pesquisa termina, uma cópia do resultado vai para um único lugar central.

Esse lugar é um projeto do Claude Code vinculado ao repositório knowledge-space, com sua própria pasta research/inbox/, que reúne os dumps brutos de cada conversa em cada conta. Sem copiar e colar, apenas uma regra que cada conversa lê no início e segue quando sua pesquisa termina.

Depois vem uma segunda passada. Uma sessão separada sobre o projeto knowledge-space percorre a inbox: lê cada dump bruto, extrai os fatos concretos e as armadilhas, reempacota tudo no formato de card e confere com o que já existe naquele domínio, para que duplicatas enriqueçam cards existentes em vez de se multiplicar. Depois confere os wiki-links, roda o build, lê o diff e faz push. Uma sessão dessas costuma gerar de 20 a 40 cards novos ou enriquecidos em algumas horas.

A escolha de modelo por nível sai daqui diretamente, e foi aqui que finalmente encontrei uso para o Sonnet. Para mim ele ficava entre "esperto demais para coisas simples" e "simples demais para qualquer coisa interessante". Mas "ler um dump bruto de pesquisa, extrair os fatos, reempacotar no formato de card, comparar com os vizinhos da pasta" é exatamente o tipo de trabalho dele: mecânico, mas com linguagem envolvida. O Sonnet reempacota texto tão bem quanto o modelo maior e custa bem menos, então as conversas de pesquisa e a passada pela inbox rodam nele. Conferir os wiki-links, decidir se dois cards devem ser fundidos ou resolver um conflito entre duas fontes é trabalho de entender-decidir-projetar, e isso vai para o modelo mais forte. A diferença de custo é de múltiplos, sem perda de qualidade.

O resultado é um fluxo. Faço meu trabalho principal, rodo pesquisas em conversas diferentes ao longo do caminho, e a base se enche sem que eu mova ou formate nada.

Usando e contribuindo

A forma mais simples de usar é apontar seu agente para happyin.space/llms.txt e deixá-lo buscar cards conforme precisar. Só isso já reduz a primeira terça parte dos tokens que antes iam para a orientação.

O próximo nível é contribuir. O repositório tem dois arquivos escritos para isso: CONTRIBUTING.md, um guia geral para preparar páginas e enviar alterações, e AGENTS.md, instruções para o seu agente. Eles descrevem o formato dos cards, quão denso o texto deve ser, o que pertence às Gotchas, como escrever wiki-links e como abrir um pull request com um card novo ou uma correção. Entregue ao seu agente o guia e um resultado de pesquisa recente, e ele monta o card sozinho. Sua pesquisa entra na base, você deixa de pagar por ela de novo, e todos também deixam. O README declara licença MIT.

Quanto mais pesquisa estiver na base, menos dela alguém precisa refazer. Quanto mais pessoas e agentes enviarem cards, mais pontes inesperadas aparecem entre domínios, e são elas as valiosas. A página do projeto neste site é happyin.space.

O que mudou depois de abril

Atualização, setembro de 2026. O README do repositório agora informa mais de 1.287 artigos em 28 domínios e mais de 3.139 referências cruzadas. A maior parte do crescimento vem de dois tipos novos de página: projects/, com 388 páginas, uma por ferramenta, modelo ou produto que um pipeline de notícias acompanha, e organizations/, com 45 páginas, uma por empresa ou laboratório. A regra de atualidade agora é um ciclo de quatro etapas no README: estável, anual, a cada seis meses e mensal, com geração de imagens e frameworks de agentes no grupo mensal.

Os números de abril acima (785 cards, 26 domínios, mais de 2.100 links, o limite de 60 dias, um build de cinco segundos) eram verdadeiros no dia da publicação, e eu os deixei como estavam. A mesma preferência por arquivos simples em vez de um serviço, aplicada a várias sessões de agentes trabalhando ao mesmo tempo, está em Vários Claudes num repo.