Como criar agentes de IA que não esquecem (usando arquivos de memória)

A maioria dos agentes de IA não falha por causa do modelo.

Eles falham porque acordam com amnésia a cada sessão.

Você diz ao Claude: "nós usamos pnpm, não npm."

Próxima sessão: ele tenta npm de novo.

Você diz: "aqui não tem exports padrão."

Próxima sessão: ele escreve um export padrão.

Toda correção que você faz desaparece no momento em que a sessão termina.

Existe uma correção de um arquivo para isso.

Levei três meses repetindo a mesma coisa para descobrir.

Aqui está tudo que aprendi.

Por que a maioria dos agentes de IA falha

Não é o modelo.

É a camada ausente abaixo do modelo.

→ Você escreve um prompt

→ O agente executa a tarefa

→ A sessão termina

→ A memória se vai

→ Próxima sessão: os mesmos erros

→ Você repete as mesmas instruções

→ Para sempre

Esse loop é a maior fonte de tempo perdido em programação com IA.

Não é código ruim. Não são alucinações.

É repetição.

A camada ausente: memória

Todo mundo fica obcecado em qual modelo é mais inteligente.

Camada errada.

A verdadeira melhoria não é um modelo mais inteligente.

É dar ao modelo um lugar para armazenar o que ele aprende.

→ Prompts → dizem ao agente o que fazer agora

→ Agentes → executam a tarefa

→ Memória → persiste o contexto entre sessões

→ Contexto persistente → chega de correções repetidas

→ Sistema de aprendizado → o agente realmente melhora com o tempo

Essa é a diferença entre uma ferramenta e um colega de equipe.

Uma ferramenta faz o que você manda, toda vez, do zero.

Um colega de equipe lembra do que aconteceu ontem.

Os 5 arquivos de memória que todo agente de IA precisa

Depois que você aceita que a memória é a camada ausente, a próxima pergunta é: onde ela fica?

Cinco arquivos. Cada um com uma função diferente.

→ CLAUDE.md — documento de briefing pessoal do Claude

→ AGENTS.md — o padrão universal, lido por todas as ferramentas principais

→ CLAUDE.local.md — suas preferências pessoais, nunca commitado no git

→ MEMORY.md — anotações que a IA escreve sobre si mesma, automaticamente

→ README.md — para humanos, não para agentes

Vamos ver cada um.

CLAUDE.md — o que começou tudo

Coloque isso na raiz do seu projeto.

O Claude lê no início de cada sessão.

Pense nisso como um documento de briefing para um novo membro da equipe com amnésia.

Um bom CLAUDE.md tem quatro seções:

→ Contexto do projeto — uma linha. "Aplicativo e-commerce Next.js com Stripe e Postgres."

→ Estilo de código — não "formate o código direito" mas "use módulos ES, exports nomeados, indentação de 2 espaços."

→ Comandos — strings exatas. pnpm test:integration, não "execute os testes."

→ Arquitetura — "Rotas de API vão em /src/api/[resource]/route.ts. Padrão Repository para acesso ao DB."

1# CLAUDE.md
2
3## Contexto do Projeto
4Aplicativo e-commerce Next.js 14. Integração com Postgres + Stripe.
5
6## Estilo de Código
7- Apenas módulos ES
8- Exports nomeados, nunca exports padrão
9- Indentação de 2 espaços
10- TypeScript strict mode
11
12## Comandos
13- Instalar: pnpm install
14- Dev: pnpm dev
15- Testar: pnpm test:integration
16- Lint: pnpm lint:fix
17
18## Arquitetura
19- Rotas de API: /src/api/[resource]/route.ts
20- Acesso ao DB: apenas padrão Repository
21- Componentes: /src/components, um arquivo por componente

Alvo: menos de 300 linhas.

Cada linha compete por atenção com o trabalho real.

Execute /init e o Claude gera um arquivo inicial automaticamente.

Depois delete a maior parte dele.

O arquivo padrão inclui coisas que o Claude já sabe do seu package.json. Mantenha apenas o que o Claude erraria sem o arquivo.

O sistema de @imports — mantenha enxuto

CLAUDE.md não precisa guardar tudo.

Ele pode importar outros arquivos:

Veja

@README .md para visão geral do projeto Veja

@docs/api-patterns .md para convenções de API Veja

@package .json para scripts npm disponíveis

Importações podem ser recursivas — até 5 níveis de profundidade.

Isso resolve o problema do "arquivo gigante único".

Para equipes: o time de frontend é dono do docs/frontend-rules.md.

Segurança é dona do docs/security.md.

CLAUDE.md só importa todos eles.

Um arquivo raiz. Muitas fontes especializadas.

AGENTS.md — o padrão universal

CLAUDE.md funciona apenas para o Claude.

Se sua equipe também usa Cursor, Copilot ou Gemini CLI — eles nunca leem.

AGENTS.md resolve isso.

Um arquivo. Todo agente principal lê.

Suportado por Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp e mais.

É Markdown padrão. Sem esquema especial. Sem YAML necessário.

1# AGENTS.md
2
3## Visão Geral do Projeto
4Plataforma de e-commerce construída com Next.js 14, Postgres e Stripe.
5
6## Build & Teste
7- Instalar: pnpm install
8- Dev: pnpm dev
9- Testar: pnpm test
10- Lint: pnpm lint:fix
11
12## Padrões de Código
13- TypeScript strict mode
14- Exports nomeados em vez de exports padrão
15- Rotas de API seguem convenções REST em /src/api/
16
17## Requisitos de Teste
18- Todos os PRs devem incluir testes
19- vitest para testes unitários, playwright para e2e

Pense nisso como um README para agentes de IA.

README.md é para humanos. AGENTS.md é para todo agente, independente do fornecedor. CLAUDE.md adiciona extras específicos do Claude por cima.

Eles são complementares. Não concorrentes.

Automemória — a IA que faz suas próprias anotações

Esta é a camada mais nova e interessante.

Claude Code agora escreve seus próprios arquivos de memória durante suas sessões.

memory/ ├── MEMORY.md ← índice, carregado a cada sessão ├── debugging.md ← anotações sobre padrões de debug ├── api-conventions.md ← decisões de design de API └── ...

A mudança chave:

Você escreve CLAUDE.md. Você fornece as instruções.

Claude escreve MEMORY.md. Ele captura o que aprendeu.

→ Humano escreve regras

→ Agente descobre padrões enquanto trabalha

→ Agente escreve sua própria memória

→ Sessões futuras começam mais inteligentes

Você pode acionar isso diretamente. No final de uma sessão produtiva, basta dizer:

"Atualize seus arquivos de memória com o que você aprendeu sobre nosso código hoje."

Os aprendizados persistem. Chega de reexplicar seu wrapper ORM personalizado pela quinta vez.

Execute /memory a qualquer momento para revisar ou editar o que o Claude salvou.

O fluxo /init e depois delete

A maneira mais rápida de inicializar um arquivo de memória em um novo projeto:

1. Execute /init no diretório do seu projeto
2. Claude gera um CLAUDE.md inicial baseado no seu código
3. Delete o que você não precisa

O passo 3 é onde a maioria erra.

O arquivo gerado é um rascunho, não um produto final.

Ele geralmente inclui enchimento. "Este projeto usa JavaScript." Obrigado — visível no package.json.

Editar a partir de um rascunho razoável é melhor do que escrever de um arquivo em branco.

Após a configuração, construa organicamente.

Quando Claude fizer uma suposição errada — por exemplo, ficar importando um pacote obsoleto — não corrija apenas uma vez.

Diga a ele: "adicione ao meu CLAUDE.md: sempre importe de @company/utils-v2, não de @company/utils."

A instrução persiste para todas as sessões futuras.

A cada poucas semanas, peça ao Claude para revisar e limpar o CLAUDE.md.

Instruções se acumulam. Algumas se tornam redundantes. Outras começam a conflitar. Uma passada rápida mantém tudo afiado.

Minha configuração real

Depois de testar tudo isso em vários projetos de produção, aqui está o que ficou:

→ AGENTS.md na raiz do projeto — instruções compartilhadas que qualquer ferramenta de IA lê. Comandos de build, padrões de código, requisitos de teste.

→ CLAUDE.md com @imports para comportamento específico do Claude. Fica abaixo de 100 linhas, na maioria apontando para arquivos docs/.

→ CLAUDE.local.md para peculiaridades pessoais — meus dados de teste, URLs de sandbox, comandos abreviados. Nunca commitado no git.

→ Automemória ativada. Claude faz suas próprias anotações. Reviso mensalmente.

→ Todo o resto substituído por symlinks apontando de volta para AGENTS.md. Uma única fonte da verdade.

1# Configuração de symlink para consistência entre ferramentas
2ln -sfn AGENTS.md .github/copilot-instructions.md
3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

Não é elegante.

Mas elimina a deriva de instruções em todas as ferramentas da equipe.

A mudança maior

A maioria dos desenvolvedores pensa:

Modelo melhor = agente melhor.

Errado.

A fórmula real:

Modelo + Memória + Recuperação + Feedback = Agente Útil

Um modelo mais inteligente sem memória ainda esquece seu comando de teste amanhã.

Um modelo modesto com boa memória fica mais afiado a cada semana.

Memória é a variável que acumula.

Inteligência do modelo não é.

A maior melhoria que fiz no meu fluxo de trabalho com IA não foi trocar de modelo.

Foi dar uma memória ao modelo.

A diferença entre:

"Claude, usamos pnpm" — toda sessão

e:

"Claude já sabe" — toda sessão

É a diferença entre uma ferramenta e um colega de equipe.

Se isso foi útil:

→ Compartilhe para alcançar todo desenvolvedor que ainda se repete para o Claude

→ Siga @sairahul1 para mais sistemas que rendem enquanto você dorme

→ Salve — configure hoje, pare de corrigir amanhã

Escrevo sobre IA, construção de produtos e sistemas que funcionam sem você.