Arquitetura de memória para times que adotaram IA

Legado desde o primeiro dia

Quando a helloo virou AI-first, o código funcionando começou a chegar mais rápido do que o time conseguia absorver. As features ficavam prontas e, depois de um tempo, ninguém mexia nelas com segurança, porque o raciocínio por trás tinha ficado numa sessão de chat já fechada. Chegamos num beco sem saída com código que funcionava.

Desacelerar era uma opção e não resolveria nada. O que resolveu foi fazer cada projeto se descrever sozinho: convenções escritas para os agentes, o porquê de cada decisão ao lado do código, documentação atualizada na mesma mudança que o código, e arquivos feitos para o agente ler primeiro quando abre o repositório. O teste que eu uso hoje é simples. Uma pessoa ou um modelo clona o repositório, lê o que está lá e continua o trabalho. Se isso não acontece, o projeto já é legado, mesmo que tenha sido escrito na semana passada.

Um projeto que só o agente original entende é legado desde o primeiro dia, e com agentes escrevendo a maior parte do código você chega lá muito mais rápido do que com gente.

Memória errada é pior que memória nenhuma

O perigo está numa assimetria. Falta de memória falha alto: o modelo pergunta, ou vai ler o código, e você vê o custo. Memória errada falha em silêncio. O modelo segue confiante, o erro parece conhecimento, e continua lá na sessão seguinte. Um modelo forte muitas vezes acha a resposta certa no fim, mas já gastou tempo e tokens dando volta, e se você não perceber, a anotação errada sobrevive.

O meu melhor exemplo não tem IA nenhuma. Um número sobre o meu próprio trabalho, 150 milhões de eventos por dia, esteve certo em algum momento. Envelheceu sem ninguém notar, foi copiado para 25 arquivos das minhas anotações, e durante meses eu usei um número 24% abaixo do real. A correção teve três partes: um arquivo-fonte de números com data em cada um, um script pequeno que confere todos os outros arquivos contra ele, e uma separação clara entre material vivo e registro histórico.

A estrutura

onde cada coisa mora

~/.claude/CLAUDE.md                 curto: quem eu sou, regras duras, um índice
projeto/CLAUDE.md                   status, comandos, portas, problemas conhecidos
projeto/CHANGELOG.md                o que mudou e quando
memory/<assunto>.md                 um fato por arquivo, com data e fonte
memory/MEMORY.md                    índice dos arquivos de memória, uma linha cada

O meu arquivo global é leve, no máximo um índice apontando para arquivos que o agente só carrega quando o assunto aparece. O do projeto segue a mesma ideia, menor. Decisão de reunião vai para um terceiro nível, e sempre escrita como evento: "em 26/08/2026 decidimos X". Nunca como regra do tipo "a empresa usa X", porque decisões mudam, outras pessoas mexem no código e a empresa muda de posição.

memory/dedup-e-rede.md

---
name: dedup-e-rede
description: o ReplacingMergeTree é a última camada de dedup; a de verdade fica antes do insert
type: project
---
Medido em 30/08/2026 em produção: fator de duplicação 1,11 uma hora depois da escrita.
Fonte: notas da investigação, seção "curva de convergência".
Por que importa: nunca ler dado fresco dessa tabela com count() cru.

O que mais me ajudou a pensar nisso foi a volatilidade, mais do que a profundidade. "Ele foi CTO por nove anos" não expira nunca. "A tabela usa ReplacingMergeTree" expira devagar. "O time decidiu X" pode já estar vencido no dia em que foi escrito. Fato com data e fonte nunca vira mentira, vira história. Sem a data, vira mentira no dia em que a realidade se mexe.

Onde o fato mora decide quanto tempo ele vive

Em 27/08/2026 eu perdi 5.794 caracteres de pesquisa. Uma ferramenta pequena minha guardava anotações curadas sobre empresas numa coluna do banco, e a rotina que revalida os registros sobrescreve essa coluna por desenho. Uma execução normal e ela ficou vazia. A correção foi uma coluna nova, que a rotina não toca. O dado estava certo o tempo todo; ele morava num lugar cuja regra de sobrescrita eu não conhecia.

Memória de agente funciona igual, então antes de salvar alguma coisa, saiba quem mais escreve naquele lugar.

Regra envelhece quando o leitor muda

Memória envelhece porque o mundo muda, e dá para auditar contra a fonte. Instrução envelhece porque o leitor muda, e não dá para auditar pela verdade, porque ela continua verdadeira. O meu arquivo global tinha uma tabela dizendo qual modelo usar para busca, qual para refatoração, qual para tarefa complexa. Foi escrita para uma geração de modelos que não existe mais. Parecia certa e passava em qualquer revisão.

Então eu audito regra com outra pergunta: o modelo ainda comete esse erro?

Dois casos do meu próprio trabalho de automação mostram os dois lados. Meu arquivo global tem uma regra antiga: verificar visualmente, não confiar só no status HTTP. Naquele dia o assistente ignorou a regra e passou três rodadas inspecionando o DOM para descobrir por que um campo de formulário parecia vazio. Um screenshot resolveu em dez segundos. A regra ainda corrige um erro vivo, então fica. Em outro trabalho, um seletor has-text("Male") casou com a opção "Female", porque uma string contém a outra. Ali a correção foi mais determinismo (comparação exata), porque para um agente automatizado preenchendo um formulário conhecido, determinismo é o produto. Para analisar ou explorar uma codebase grande é o contrário, e uma regra apertada só atrapalha.

Por isso eu separo as regras em três grupos, que envelhecem de jeitos diferentes:

Regras de erro vivo ficam enquanto o erro existir, e de tempos em tempos você confere.
Regras de escopo e autoridade não expiram, porque um modelo mais esperto não ganha mais permissão.
Muletas de capacidade podem sair quando o modelo não precisa mais delas. Num benchmark meu, o mesmo andaime levou um modelo local de 23,5% para 38,6% e piorou outro, a ponto de eu reverter.

Checklist

Deixe o arquivo de contexto da raiz como índice; os detalhes moram em arquivos que o agente carrega quando precisa.
Coloque data e fonte em todo fato, e escreva decisão como evento.
A documentação muda no mesmo commit que o código. O agente escreve, uma pessoa revisa.
Audite cada regra com "o modelo ainda comete esse erro?"
Uma vez por mês, abra uma sessão limpa e peça para o agente continuar uma tarefa usando só o que está no repositório. Onde ele se perder é o próximo documento a escrever.

Arquivado pelo problema que resolve