Vou te contar uma frustração que ouço toda semana nas minhas mentorias: “Thulio, eu gasto 20 minutos todo dia explicando pro Claude Code como meu projeto funciona. Toda vez que abro uma sessão nova, ele esquece tudo.”
Essa é a dor mais silenciosa de quem usa IA pra codar. Não é o preço dos tokens. Não é a velocidade do modelo. É a amnésia. Você explica a arquitetura, mostra os padrões, aponta os bugs conhecidos… e no dia seguinte, precisa fazer tudo de novo. É como treinar um estagiário que acorda toda manhã sem memória.
Só que a Anthropic finalmente resolveu isso. O Claude Code agora tem Auto-memory e ele lembra do seu projeto, dos seus padrões, das suas preferências, sem você precisar escrever uma única linha de configuração. E isso muda completamente o jogo pra quem roda uma software house.
O que é Auto-memory
Auto-memory é um sistema onde o Claude Code toma notas sozinho enquanto trabalha com você. Ele observa seus padrões, suas correções, suas decisões de arquitetura, e salva tudo em arquivos Markdown locais na sua máquina. Na próxima sessão, ele lê essas notas antes de começar.
Antes do Auto-memory, existia apenas o CLAUDE.md — um arquivo que você escrevia manualmente com instruções pro Claude. Funcionava bem, mas exigia disciplina. Quantos devs na sua software house realmente mantêm um CLAUDE.md atualizado? Na minha experiência com 300+ SHs, menos de 10%.
Agora existem dois sistemas que se complementam:
| CLAUDE.md | Auto-memory | |
|---|---|---|
| Quem escreve | Você | O Claude |
| O que contém | Instruções e regras | Aprendizados e padrões |
| Escopo | Projeto, usuário ou org | Por working tree |
| Carregado em | Toda sessão (completo) | Toda sessão (primeiras 200 linhas) |
| Use para | Padrões de código, workflows | Comandos de build, insights de debug, preferências |
O CLAUDE.md é o “manual de instruções” que você entrega pro Claude. O Auto-memory é o “caderno de anotações” que ele preenche sozinho. Juntos, eliminam aquela sensação de começar do zero toda vez.
Como funciona na prática
O Auto-memory vem habilitado por padrão desde a versão 2.1.59. Você não precisa configurar nada. Simplesmente comece a trabalhar.
Enquanto você interage com o Claude Code, ele identifica informações que seriam úteis em conversas futuras e salva em arquivos Markdown dentro de ~/.claude/projects/<projeto>/memory/. A estrutura fica assim:
~/.claude/projects/<projeto>/memory/
├── MEMORY.md # Índice — primeiras 200 linhas carregadas automaticamente
├── debugging.md # Padrões de debug que ele aprendeu
├── api-conventions.md # Decisões de design de API
└── ... # Outros tópicos conforme necessárioO MEMORY.md é o ponto de entrada. As primeiras 200 linhas são injetadas automaticamente no início de toda sessão. Arquivos de tópico como debugging.md são lidos sob demanda — quando o Claude percebe que precisa daquela informação.
O que o Claude aprende sozinho:
- Comandos de build:
npm run test,cargo build --release, seu script de deploy customizado - Padrões de debug: “quando o teste X falha, geralmente é porque o mock do Redis não foi inicializado”
- Preferências de código: indentação, naming conventions, patterns que você corrige repetidamente
- Arquitetura: “o módulo de billing fica em src/billing/ e usa o padrão CQRS”
- Gotchas do projeto: “a migration 047 tem um bug conhecido, rodar seed antes”
Gerenciando com /memory
O comando /memory dentro de uma sessão permite:
- Ver todos os arquivos CLAUDE.md e rules carregados
- Ligar/desligar o auto-memory
- Abrir a pasta de memória no seu editor
- Editar qualquer arquivo que o Claude salvou
Você também pode pedir diretamente: “Claude, lembra que a gente sempre usa pnpm, não npm” — e ele salva na auto-memory. Se quiser que vá pro CLAUDE.md em vez disso, basta dizer: “adiciona isso no CLAUDE.md”.
Configurações avançadas
Pra quem quer customizar:
// Desabilitar auto-memory
{ "autoMemoryEnabled": false }
// Diretório customizado
{ "autoMemoryDirectory": "~/my-custom-memory-dir" }
// Via variável de ambiente
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1Detalhe importante: todos os worktrees e subdiretórios do mesmo repositório git compartilham a mesma memória. Isso significa que se você usar claude --worktree pra trabalhar em branches isoladas, o contexto aprendido é preservado.
Por que isso importa para sua Software House
Vamos fazer uma conta simples. Cada dev na sua equipe gasta, em média, 15-30 minutos por dia re-explicando contexto pro Claude Code. Com uma equipe de 10 devs, são 2.5 a 5 horas de trabalho desperdiçadas por dia. Por mês, entre 50 e 100 horas. A custo médio de R$100/hora de dev, estamos falando de R$5.000 a R$10.000/mês jogados fora em re-explicações.
Auto-memory não elimina 100% disso — mas na minha experiência testando com times que mentoro, reduz em torno de 60-70% as re-explicações. Não é mágica. É um arquivo Markdown que o Claude lê antes de começar. Mas o efeito é transformador.
Cenários práticos para SHs:
1. Onboarding de devs novos
Dev novo entra no projeto. Em vez de gastar 2 dias lendo docs internos, ele abre o Claude Code e o Auto-memory já tem os padrões do projeto, os comandos de build, as decisões de arquitetura que outros devs ensinaram pro Claude. O onboarding acelera significativamente.
2. Projetos legados
Aquele projeto de 2019 que ninguém lembra como funciona? Se alguém já trabalhou nele com Claude Code, o Auto-memory tem notas sobre os gotchas, os bugs conhecidos, os patterns obscuros. É documentação viva que se escreve sozinha.
3. Consistência entre devs
Embora a auto-memory seja local por máquina, o CLAUDE.md é versionado no git. Combine CLAUDE.md com regras do projeto (.claude/rules/) e cada dev tem o mesmo ponto de partida. A auto-memory de cada um complementa com os aprendizados individuais.
4. Redução de custos com tokens
Menos re-explicação = menos tokens gastos em contexto repetitivo. Se cada sessão começa com o Claude já sabendo seu projeto, sobra mais janela de contexto pro trabalho real.
Dados e benchmarks
Segundo um teste publicado no Medium por Joe Njenga, que testou o Auto-memory extensivamente:
- Correções manuais caíram cerca de 40% em um projeto TypeScript de 50.000 linhas após o CLAUDE.md + Auto-memory estarem bem alimentados
- As primeiras sessões são as que mais geram aprendizados — depois de 5-10 sessões, o Claude já captura os padrões principais
- O
MEMORY.mdtipicamente estabiliza em 50-150 linhas para projetos médios
Um ponto importante levantado por Brent Peterson: Auto-memory não é “aprendizado” no sentido de machine learning. É um sistema de configuração que o modelo escreve pra si mesmo. Ele não fica mais inteligente — ele fica mais informado sobre o contexto. Essa distinção importa porque define expectativas corretas: não espere que o Claude aprenda a programar melhor, espere que ele lembre do seu projeto melhor.
O que eu penso
Auto-memory é daquelas features que parecem óbvias em retrospecto. “Claro que a IA deveria lembrar do meu projeto” — só que ninguém fazia isso direito até agora. GitHub Copilot não faz. Cursor tem algo similar mas menos estruturado. O Claude Code acertou na arquitetura: é Markdown puro, local, editável, sem vendor lock-in.
O que mais me impressiona é a simplicidade. Não é um banco de dados vetorial. Não é RAG sofisticado. São arquivos .md que o modelo lê no início da sessão. E funciona. Na minha experiência, funciona muito bem.
Mas vou ser honesto: o limite de 200 linhas no MEMORY.md pode ser restritivo pra projetos grandes. E a memória ser local por máquina significa que se você troca de computador, perde tudo. Seria bom ter uma opção de sync, talvez via git ou cloud. Aposto que vem nas próximas versões.
Pra software houses, a recomendação é clara: combine CLAUDE.md versionado no git (regras do time) com Auto-memory habilitado (aprendizado individual). Esse combo é o estado da arte hoje em produtividade com IA.
Conclusão
A era da IA amnésica acabou. Auto-memory transforma o Claude Code de um assistente descartável em um parceiro de projeto que realmente conhece seu código. Não é perfeito — tem limitações de escopo e localidade — mas é o maior salto em experiência de uso desde o lançamento do agent teams.
Se sua software house usa Claude Code e ainda não explorou o sistema de memória, comece hoje. Rode /memory numa sessão, veja o que o Claude já aprendeu sobre seu projeto, e adicione um CLAUDE.md com as regras do seu time. Em uma semana, você vai se perguntar como vivia sem isso.
Se você quer implementar IA com esse nível de maturidade na sua software house, com processos, padrões e resultados reais, a Imersão Software House 10x é onde a gente mergulha fundo nisso.
Sou Thulio, mentoro 300+ SHs desde 2016.
