Memória automática no código Claude

Problema: Seu CLAUDE.md está no lugar com as regras do projeto, mas o Claude continua perguntando as mesmas coisas sobre comandos de compilação, convenções de teste e peculiaridades estranhas de depuração. 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.

**Vitória Rápida: Veja se a memória automática já está em execução. Dentro de qualquer sessão do Claude Code, execute /memory. Um seletor é aberto mostrando seus arquivos CLAUDE.md e uma opção de auto-memória. A alternância está ativada por padrão, o que significa que o Claude tem tomado notas do projeto silenciosamente para você.

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

Ver diretórios listados? O Claude tem notas à espera. Continue lendo para saber o que há neles, como trabalhar com eles, e como eles ficam ao lado do seu sistema CLAUDE.md. Se os seus ficheiros de memória se sentirem inchados após muitas sessões, veja o Auto Dream, a funcionalidade de consolidação que limpa e reorganiza tudo o que o Auto Memory escreve.

O que a Memória Automática realmente é

A memória automática é uma pasta persistente onde o Claude regista as aprendizagens, os padrões e os conhecimentos enquanto trabalha. Aqui está a divisão chave: **CLAUDE.md são suas instruções para o Claude. MEMORY.md são as notas do Claude para ele 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: "o comando de construção é pnpm build, os testes estão em __tests__/, a API usa Express com middleware em src/middleware/"

Não confunda isso com a Memória de Sessão, que armazena resumos em nível de conversação para recuperação entre sessões. A memória automática funciona num nível mais profundo. Ela mantém o conhecimento durável do projeto que permanece, não importando qual conversa o criou.

Três sistemas de memória, lado a lado

O Claude Code tem agora três sistemas de memória separados. Saber qual deles utilizar evita que se faça o mesmo trabalho duas vezes ou que se escolha a ferramenta errada.

A melhor configuração executa todos os três juntos. CLAUDE.md estabelece as regras. A memória automática regista o que o Claude aprende ao longo do caminho. A Memória de Sessão guarda o thread entre as sessões.

Onde os arquivos vivem

Cada projeto tem a 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 pormenores 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. Execute o Claude a partir de src/api/ e você terá a mesma memória que teria se executasse a partir da raiz do repo.
• As árvores de trabalho do Git têm cada uma sua própria pasta. Isso é proposital. Diferentes worktrees geralmente possuem diferentes branches em diferentes estados.
• Fora de um repositório git, o diretório de trabalho desempenha o papel da raiz do repositório.

O que é escrito

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

Padrões do projeto: comandos de compilação, convenções de teste, escolhas de estilo de código. Execute seu conjunto de testes uma vez e o Claude grava o comando mais quaisquer sinalizadores especiais necessários.

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

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

As suas preferências: como comunica, os seus hábitos de fluxo de trabalho, as suas escolhas de ferramentas. O Claude repara nos padrões em que se apoia.

o MEMORY.md funciona como um pequeno índice. À medida que as notas se acumulam, o Claude move os detalhes para arquivos de tópicos como debugging.md ou patterns.md. Isso mantém o arquivo principal com menos de 200 linhas, já que apenas as primeiras 200 linhas são carregadas na inicialização.

Como usá-lo

Apenas deixe-o rodar

O caminho mais fácil: deixá-lo em paz. A memória automática está ativada por padrão. O Claude lê e escreve ficheiros de memória em segundo plano enquanto trabalha. Você notará isso durante as sessões quando o Claude tocar nos arquivos dentro da pasta de memória.

Salvar algo específico

Dizer ao Claude o que deve ser guardado:

"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-os imediatamente no ficheiro de memória correto.

Navegar e editar

Durante qualquer sessão, execute /memory para abrir o seletor de arquivos de memória. Isto lista todos os arquivos de memória (CLAUDE.md, auto memory, local config) e permite que você abra qualquer um deles no seu editor de sistema.

Você também pode lê-los a partir 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

Estes são ficheiros markdown simples. Edite-os sempre que quiser. Elimine entradas que tenham ficado obsoletas. Reorganizar à medida que o projeto cresce.

Configuração e Controlo

A memória automática vem activada por defeito. Aqui estão todos os botões que pode rodar:

Alternância por sessão

Execute /memory e alterne o botão de auto-memória. É a maneira mais rápida de ativar ou desativar a memória para o seu fluxo de trabalho atual.

Desligue-o para cada projeto

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

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

Projeto Kill It For One

Coloque isso nas configurações do projeto:

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

Substituição da variável de ambiente

CLAUDE_CODE_DISABLE_AUTO_MEMORY supera todas as outras configurações. É a escolha certa para pipelines de CI, automação e implantações gerenciadas:

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

Isso anula tanto a alternância /memory quanto settings.json, então funciona como um hard kill switch.

Quando usar o quê

Três sistemas de memória, uma estrutura de decisão:

Procure CLAUDE.md quando você quer regras rígidas. Padrões de codificação, chamadas de arquitetura, comandos necessários, convenções de equipa. CLAUDE.md carrega completamente na inicialização e fica em alta prioridade. Se quiser que um padrão seja sempre seguido, ele vai para aqui.

Procure a memória automática quando quiser que o Claude pegue nas coisas à medida que avança. Padrões que surgem durante o trabalho real, correções de depuração, preferências silenciosas. Não é necessário planear tudo com antecedência.

Recorre à Memória de Sessão quando precisas de continuidade da conversa. A Memória de Sessão mantém o fio condutor do que foi discutido e decidido em cada sessão. É a camada "o que fizemos ontem".

Procure o diretório de regras quando o seu CLAUDE.md tiver ultrapassado o tamanho de um ficheiro. Divida suas instruções em arquivos focados em .claude/rules/ para uma estrutura mais limpa sem perder a prioridade.

A sobreposição é proposital. A memória automática pega as coisas que você esqueceu de colocar no CLAUDE.md. A Memória de Sessão carrega o contexto que as notas de nível de projeto não conseguem. Empilhe-as e terá uma memória em camadas cobrindo regras, conhecimento do projeto e histórico de conversas.

Melhores práticas

**Mantenha o MEMORY.md com menos de 200 linhas. Apenas as primeiras 200 linhas são carregadas na inicialização. O Claude é instruído a permanecer conciso, colocando detalhes em arquivos de tópicos. Se você editar à mão, respeite o mesmo limite.

Reveja seus arquivos de memória de vez em quando. Como qualquer nota, eles ficam obsoletos. Depois de um grande refactor ou mudança de arquitetura, passe os olhos pelos ficheiros e apague o que já não é verdade.

Não duplique entre CLAUDE.md e auto memory. Se algo precisa ser uma regra, coloque-a em CLAUDE.md. Se for um padrão que pode mudar, deixe que a memória automática o leve.

**Quando você descobrir um bug desagradável ou bloquear uma grande chamada de arquitetura, diga ao Claude para se lembrar disso. Não aposte que o Claude vai apanhar tudo sozinho.

Desligue a memória automática no CI. A automação não precisa que o Claude empilhe notas sobre sua caixa de construção. Defina CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 na sua configuração de CI.

**A memória automática é uma camada de uma estratégia maior de engenharia de contexto. Quanto mais cuidado você colocar no que o Claude sabe na inicialização, mais cada sessão retribui.

Próximos passos

• Configure seu sistema de memória CLAUDE.md para instruções persistentes do projeto
• Entenda a memória de sessão para a continuidade de conversas entre sessões
• Aprender estratégias de gestão de contexto para trabalhar dentro dos limites do token
• Explorar o diretório de regras para instruções de projeto modulares
• Leia sobre engenharia de contexto para sistemas de memória de IA de produção

A memória automática preenche a lacuna entre o que diz ao Claude e o que o Claude resolve por si próprio. CLAUDE.md possui as regras "faça desta forma". A memória automática possui o conhecimento "reparei nisto no seu projeto". Se os utilizar em conjunto, explica-se menos e envia-se mais.