Auto Memory no Claude Code

Problema: Você tem o CLAUDE.md configurado com as regras do projeto, mas o Claude continua perguntando as mesmas coisas sobre comandos de build, convenções de teste e peculiaridades estranhas de debugging. As instruções cobrem o que você quer que o Claude faça. Elas perdem o que o Claude já aprendeu sobre o seu repositório.

Solução Rápida: Veja se o auto memory já está rodando. Dentro de qualquer sessão do Claude Code, rode /memory. Um seletor abre mostrando seus arquivos CLAUDE.md e um toggle de auto-memory. O toggle está ligado por padrão, o que significa que o Claude tem estado silenciosamente tomando notas do projeto para você.

# Find your project's auto memory directory
ls ~/.claude/projects/

Vê diretórios listados? O Claude tem notas esperando. Continue lendo para aprender o que vai neles, como trabalhar com eles, e como eles ficam ao lado do seu sistema CLAUDE.md. Se os seus arquivos de memória parecerem inchados depois de muitas sessões, olhe para o Auto Dream, a funcionalidade de consolidação que limpa e reorganiza o que o Auto Memory escreve.

O Que Auto Memory Realmente É

Auto memory é uma pasta persistente onde o Claude registra aprendizados, padrões e insights enquanto trabalha. Aqui está a divisão chave: CLAUDE.md é suas instruções para o Claude. MEMORY.md é as notas do Claude para si mesmo sobre o seu projeto.

CLAUDE.md é onde você escreve coisas como "use pnpm, não npm" ou "escreva testes antes do código." Auto memory é onde o Claude anota suas próprias observações: "comando de build é pnpm build, testes ficam em __tests__/, API usa Express com middleware em src/middleware/."

Não confunda isso com Session Memory, que armazena resumos de nível de conversa para recordação entre sessões. Auto memory trabalha um nível mais profundo. Ele mantém conhecimento durável do projeto que permanece não importa qual conversa o criou.

Três Sistemas de Memória, Lado a Lado

Claude Code agora roda três sistemas de memória separados. Saber qual usar evita que você faça o mesmo trabalho duas vezes ou escolha a ferramenta errada.

A melhor configuração roda os três juntos. CLAUDE.md estabelece as regras. Auto memory registra o que o Claude aprende ao longo do caminho. Session Memory mantém o fio entre sessões.

Onde Os Arquivos Ficam

Cada projeto tem sua própria pasta de memória, ancorada na raiz do repositório git:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Main index, loaded every session
├── debugging.md       # Detailed debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any topic files Claude creates

Alguns detalhes de armazenamento que vale a pena conhecer:

• A raiz do repositório git é o que define o caminho do projeto. Cada subdiretório dentro do mesmo repositório compartilha uma pasta de memória. Rode o Claude de src/api/ e você acessa a mesma memória que rodando da raiz do repositório.
• Git worktrees cada um recebe sua própria pasta. Isso é de propósito. Worktrees diferentes geralmente mantêm branches diferentes em estados diferentes.
• Fora de um repositório git, o diretório de trabalho desempenha o papel da raiz do repositório.

O Que É Anotado

Enquanto o Claude trabalha no seu projeto, ele arquiva notas em algumas categorias:

Padrões do projeto: comandos de build, convenções de teste, escolhas de estilo de código. Rode sua suíte de testes uma vez e o Claude registra o comando mais quaisquer flags especiais que precisou.

Insights de debugging: correções para bugs complicados e raízes de erros comuns. Passa tempo perseguindo um problema de CORS ou um nó de configuração webpack? O Claude escreve a solução.

Notas de arquitetura: arquivos-chave, como os módulos se relacionam, abstrações importantes. O Claude mapeia o território uma vez para não ter que redescobrir seu layout a cada sessão.

Suas preferências: como você se comunica, seus hábitos de workflow, suas escolhas de ferramentas. O Claude nota os padrões em que você se apoia.

MEMORY.md funciona como um índice curto. À medida que as notas se acumulam, o Claude move o detalhe para arquivos de tópico como debugging.md ou patterns.md. Isso mantém o arquivo principal abaixo de 200 linhas, já que apenas as primeiras 200 linhas carregam no início.

Como Usar

Apenas Deixe Rodar

O caminho mais fácil: deixe em paz. Auto memory está ligado por padrão. O Claude lê e escreve arquivos de memória em segundo plano enquanto você trabalha. Você vai notar durante as sessões quando o Claude toca em arquivos dentro da pasta de memória.

Salve Algo Específico

Diga ao Claude diretamente o que armazenar:

"remember that we use pnpm, not npm"
"save to memory that the API tests require a local Redis instance"
"note that the staging environment uses port 3001"

O Claude coloca isso no arquivo de memória certo imediatamente.

Navegue E Edite

Durante qualquer sessão, rode /memory para abrir o seletor de arquivos de memória. Isso lista cada arquivo de memória (CLAUDE.md, auto memory, configuração local) e permite que você abra qualquer um deles no seu editor do sistema.

Você também pode lê-los do shell:

# List all memory files for a project
ls ~/.claude/projects/<project>/memory/
 
# Read the main memory index
cat ~/.claude/projects/<project>/memory/MEMORY.md
 
# Read a specific topic file
cat ~/.claude/projects/<project>/memory/debugging.md

Esses são arquivos markdown simples. Edite-os quando quiser. Delete entradas que ficaram desatualizadas. Reorganize conforme o projeto cresce.

Configuração E Controle

Auto memory vem ligado por padrão. Aqui está cada controle que você pode ajustar:

Toggle Por Sessão

Rode /memory e vire o toggle de auto-memory. Forma mais rápida de ligar ou desligar para o seu workflow atual.

Desative Para Todos Os Projetos

Coloque isso nas suas configurações de usuário:

// ~/.claude/settings.json
{ "autoMemoryEnabled": false }

Desative Para Um Projeto

Coloque isso nas configurações do projeto:

// .claude/settings.json
{ "autoMemoryEnabled": false }

Variável de Ambiente Override

CLAUDE_CODE_DISABLE_AUTO_MEMORY vence todas as outras configurações. É a escolha certa para pipelines de CI, automação e deployments gerenciados:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # Force off
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # Force on

Isso anula tanto o toggle /memory quanto settings.json, então funciona como um interruptor de força.

Quando Usar O Quê

Três sistemas de memória, um framework de decisão:

Use CLAUDE.md quando você quer regras rígidas. Padrões de código, decisões de arquitetura, comandos obrigatórios, convenções da equipe. CLAUDE.md carrega completo no início e fica em alta prioridade. Se você quer um padrão seguido toda vez, vai aqui.

Use auto memory quando você quer que o Claude aprenda as coisas conforme avança. Padrões que surgem durante o trabalho real, correções de debugging, preferências silenciosas. Você não precisa planejar tudo com antecedência.

Use Session Memory quando você precisa de continuidade de conversa. Session Memory mantém o fio do que você discutiu e decidiu em cada sessão. É a camada "o que fizemos ontem".

Use o diretório rules quando seu CLAUDE.md cresceu demais para um arquivo. Divida suas instruções em arquivos focados em .claude/rules/ para uma estrutura mais limpa sem perder prioridade.

A sobreposição é de propósito. Auto memory captura as coisas que você esqueceu de colocar no CLAUDE.md. Session Memory carrega o contexto que notas de nível de projeto não podem. Empilhe-os e você tem memória em camadas cobrindo regras, conhecimento do projeto e histórico de conversa.

Melhores Práticas

Mantenha MEMORY.md abaixo de 200 linhas. Apenas as primeiras 200 linhas carregam no início. O Claude é instruído a permanecer conciso empurrando detalhes para arquivos de tópico. Se você editar manualmente, respeite o mesmo limite.

Revise seus arquivos de memória de vez em quando. Como qualquer nota, eles ficam desatualizados. Depois de um grande refactor ou mudança de arquitetura, passe os olhos nos arquivos e delete o que não é mais verdade.

Não duplique entre CLAUDE.md e auto memory. Se algo precisa ser uma regra, coloque no CLAUDE.md. Se é um padrão que pode mudar, deixe o auto memory carregar.

Salve o material crítico explicitamente. Quando você resolve um bug difícil ou fecha uma grande decisão de arquitetura, diga ao Claude para lembrar. Não aposte no Claude capturando tudo sozinho.

Desligue auto memory no CI. Automação não precisa do Claude empilhando notas sobre sua máquina de build. Configure CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 na sua configuração de CI.

Combine com engenharia de contexto. Auto memory é uma camada de uma estratégia maior de engenharia de contexto. Quanto mais cuidado você coloca no que o Claude sabe no início, mais cada sessão retorna.

Próximos Passos

• Configure seu sistema de memória CLAUDE.md para instruções persistentes do projeto
• Entenda Session Memory para continuidade de conversa entre sessões
• Aprenda estratégias de gerenciamento de contexto para trabalhar dentro dos limites de tokens
• Explore o diretório rules para instruções modulares de projeto
• Leia sobre engenharia de contexto para sistemas de memória AI em produção

Auto memory fecha a lacuna entre o que você diz ao Claude e o que o Claude descobre por conta própria. CLAUDE.md possui as regras "faça deste jeito". Auto memory possui o conhecimento "eu notei isso sobre o seu projeto". Rode-os juntos e você explica menos e entrega mais.