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

A maioria dos agentes de IA não falha porque o modelo é ruim.

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

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

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

Você diz: "nada de exports padrão aqui."

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 solução de um arquivo para isso.

Levei três meses repetindo a mesma coisa para encontrá-la.

Aqui está tudo o que aprendi.

Por que a maioria dos agentes de IA falha

Não é o modelo.

É a camada que falta abaixo do modelo.

→ Você escreve um prompt

→ Agente executa a tarefa

→ Sessão termina

→ Memória se vai

→ Próxima sessão: mesmos erros

→ Você repete as mesmas instruções

→ Para sempre

Esse ciclo é 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 que falta: memória

Todo mundo se preocupa com qual modelo é o mais inteligente.

Camada errada.

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

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

→ Prompts → dizem ao agente o que fazer agora

→ Agentes → executam a tarefa

→ Memória → persiste contexto entre sessões

→ Contexto persistente → sem mais 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 se lembra do que aconteceu ontem.

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

Quando você aceita que a memória é a camada que falta, 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 deles.

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 corretamente", 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 BD."

1# CLAUDE.md
2
3## Contexto do Projeto
4Aplicativo e-commerce Next.js 14. Integração 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- Modo estrito do TypeScript
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 BD: apenas padrão Repository
21- Componentes: /src/components, um arquivo por componente

Meta: 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 @imports — mantenha enxuto

O CLAUDE.md não precisa conter tudo.

Ele pode importar outros arquivos:

Veja o

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

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

@package .json para scripts npm disponíveis

As 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.

O CLAUDE.md apenas importa todos eles.

Um arquivo raiz. Muitas fontes especializadas.

AGENTS.md — o padrão universal

O CLAUDE.md funciona apenas para o Claude.

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

O 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 e 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- Modo estrito do TypeScript
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.

Memória automática — a IA que faz suas próprias anotações

Esta é a camada mais nova e mais interessante.

O 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 o CLAUDE.md. Você fornece as instruções.

Claude escreve o 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. Sem precisar reexplicar seu wrapper ORM personalizado pela quinta vez.

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

O fluxo de trabalho /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 com base no seu código
3. Delete o que você não precisa

O passo 3 é onde a maioria das pessoas erra.

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

Ele geralmente inclui coisas genéricas. "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, continuar 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 funcionou:

→ 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 comportamentos específicos do Claude. Fica com menos de 100 linhas, apontando principalmente para arquivos em docs/.

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

→ Memória automática ativada. Claude faz suas próprias anotações. Eu reviso mensalmente.

→ Todo o resto substituído por symlinks apontando de volta para o 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 entre 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 vai esquecer seu comando de teste amanhã.

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

Memória é a variável que se 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 ao modelo uma memória.

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 todo desenvolvedor que ainda está se repetindo para o Claude

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

→ Salve — configure hoje à noite, pare de corrigir amanhã

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