Como dar memória a agentes de IA que funcione com qualquer modelo?

O jeito mais simples é guardar a memória em arquivos Markdown no seu repositório, com um arquivo canônico que descreve o projeto e as regras, e fazer cada ferramenta apontar para ele. Assim a memória é sua, legível e versionada, e trocar de modelo ou de ferramenta não apaga o que foi aprendido. Montei isso para mim e deixei um modelo público no GitHub, o brain-template. O ponto frágil é a configuração de cada ferramenta, não os arquivos.

O problema

Toda ferramenta de IA para programar esquece: a janela de contexto acaba, a sessão expira, e o que você ensinou a um fornecedor fica preso nele. A documentação do Claude Code diz isso sem rodeio: cada sessão começa com a janela de contexto vazia, e dois mecanismos levam conhecimento de uma sessão para outra, os arquivos CLAUDE.md que você escreve e a memória automática que a ferramenta escreve sozinha. A segunda fica no formato e no lugar que a ferramenta escolhe. A primeira é um texto seu.

O que as ferramentas documentam

• O AGENTS.md é um formato aberto: um arquivo Markdown simples, sem campos obrigatórios, com instruções para agentes de código. A página do formato lista dezenas de ferramentas compatíveis, entre elas Codex, Gemini CLI, Cursor e opencode.
• O Claude Code lê o AGENTS.md do repositório, mas só quando não existe CLAUDE.md na pasta de trabalho nem acima dela. Se existem os dois, ele lê só o CLAUDE.md. Para ler ambos, a documentação manda o CLAUDE.md importar o AGENTS.md com a sintaxe @caminho. Imports aceitam caminho relativo ou absoluto e vão até quatro níveis. Um import que aponta para fora da pasta de trabalho pede aprovação na primeira vez.
• O opencode procura o AGENTS.md subindo a partir da pasta atual. Pelo campo instructions do arquivo de configuração, aceita caminhos e padrões com asterisco, e junta tudo com o AGENTS.md.

A própria documentação do Claude Code ressalva que essas instruções são contexto e não configuração imposta. Para impedir uma ação de verdade, ela indica um hook, um comando que roda sempre. Ou seja, memória em arquivo orienta, não obriga.

Como organizei

Na raiz do vault de anotações ficam:

• AGENTS.md: o contexto canônico, escrito uma vez. CLAUDE.md e os equivalentes são arquivos finos que só apontam para ele, para não haver duas versões do mesmo texto.
• GUARDRAILS.md: o protocolo de como trabalhar, em vez de o que saber. Evidência antes de afirmar, plano antes de implementar, prova antes de dizer "pronto". Existe uma versão condensada, com regras numeradas e imperativas, para modelos abertos.
• Memória/: um fato por arquivo, com o motivo e como aplicar, mais um índice de uma linha por fato.
• Um arquivo por tarefa longa, com onde parei e o que decidi e por quê, para continuar em outra ferramenta.

O brain-template é esse esqueleto sem o meu conteúdo. O README dele lista Claude Code, Gemini CLI e opencode como ferramentas pensadas para o modelo, e a licença é MIT.

Onde quebrou

Em 16 de agosto de 2026 descobri que minha própria nota dizia uma coisa que não era verdade. Eu registrara que o opencode carregava o protocolo por um link simbólico e que a configuração tinha regras de permissão. Medi: o arquivo de configuração tinha 50 bytes, só o cabeçalho, e a pasta do link não existia. Durante todo esse período, os modelos abertos rodaram sem protocolo nenhum.

Reconstruí no mesmo dia usando o campo instructions com caminho absoluto. Testei: um dos modelos devolveu a regra 6 palavra por palavra sem abrir arquivo. Que o caminho absoluto fora do repositório funciona eu medi, a página do opencode que li não detalha isso.

No mesmo dia, uma atualização do pacote do opencode deixou o programa fora do PATH, a lista de pastas onde o sistema procura comandos.

Também vale uma divergência. Anotei antes que o import de CLAUDE.md não saía da árvore do projeto. A documentação de hoje diz que sai, com aprovação na primeira vez. Sigo a documentação.

O que fazer

1. Escreva o contexto em um arquivo canônico e faça os outros apontarem para ele.
2. Guarde fatos um por arquivo, com o motivo, e versione no git.
3. Não registre estado momentâneo na memória. Isso vai no arquivo da tarefa.
4. Depois de configurar cada ferramenta, pergunte a ela uma regra pelo número. Se não souber, o arquivo não está sendo lido.
5. Para o que não pode falhar, use hook ou permissão, não só texto.

Para montar isso no seu time: agentes de IA em produção.