Memória do Claude Code

Problema: Cada nova sessão começa em branco. Você digita o mesmo contexto de novo. Framework, convenções, foco atual, estrutura de arquivos. O agente não tem memória de ontem.

Ganho rápido: Crie o arquivo de memória em 30 segundos:

cd your-project
claude
/init

Claude lê seu repositório e cria um CLAUDE.md inicial ao lado dele. Esse arquivo vira contexto permanente do projeto, carregado no topo de cada sessão futura.

O Que o CLAUDE.md Realmente É

O arquivo de memória é o CLAUDE.md. Ele fica no disco, então sobrevive a tudo. O histórico de chat morre quando a sessão termina. Esse arquivo não morre. Claude o lê na inicialização e o trata como autoritativo.

Aqui está a parte importante. Texto dentro do CLAUDE.md recebe um slot de alta prioridade na janela de contexto. Claude o segue mais rigorosamente do que mensagens de chat e mais rigorosamente do que arquivos que ele puxa no meio da sessão. Trate-o como configuração, não como documentação.

Essa diferença de prioridade molda como você estrutura tudo o mais. A hierarquia de prioridade explica tudo em detalhes.

Estruture o Arquivo para Retenção

Divida o arquivo em duas metades. O que nunca muda fica no topo. O que se move fica na parte de baixo.

# Project Context
 
- Framework: Next.js 14 with App Router
- Database: Supabase with Row Level Security
- Testing: Vitest for unit tests
 
## Key Directories
 
- `src/app/` - Route handlers and pages
- `src/lib/` - Shared utilities
- `src/components/` - React components
 
## Standards
 
- TypeScript strict mode required
- All API routes need error handling
- Run `npm test` before committing
 
## Current Focus
 
- Building user authentication flow
- Priority: Login and password reset

O bloco Current Focus é seu rascunho. Sobrescreva a cada poucos dias. Deixe o resto em paz.

Memória Hierárquica na Árvore

Arquivos CLAUDE.md se aninham. Claude sobe a árvore de diretórios e carrega cada um que encontra:

~/projects/CLAUDE.md          <- Universal defaults
~/projects/my-app/CLAUDE.md   <- Project-specific
~/projects/my-app/api/CLAUDE.md <- Component-specific

Monorepo? Subpastas diferentes com stacks diferentes? Aqui é onde isso se paga. Mantenha os arquivos de nível superior curtos. Cada camada é carregada em cada inicialização.

@import: Memória Composável

Um arquivo pode puxar outros. A sintaxe é @caminho/para/importar. Sua configuração de memória para de ser um único arquivo e começa a parecer um pequeno grafo.

See @README for project overview and @package.json for available npm commands.
 
# Additional Instructions
 
- git workflow @docs/git-instructions.md

Caminhos relativos e absolutos funcionam. Caminhos relativos resolvem em relação ao arquivo que está importando, não ao seu diretório de trabalho. Você pode apontar para qualquer coisa na sua máquina:

# Pull in shared team standards
 
- @docs/coding-standards.md
- @docs/api-conventions.md
 
# Reference external files with absolute paths
 
- @~/.claude/my-preferences.md

Aprovação na primeira vez. Na primeira vez que um projeto importa um arquivo de fora de si mesmo, Claude Code exibe um diálogo de aprovação listando os caminhos exatos. Aprove para carregar. Recuse para pular. A escolha é lembrada por projeto. Uma recusa é permanente até você desfazê-la, e o diálogo não vai aparecer de novo.

Segurança em blocos de código. Importações dentro de código cercado ou spans de código inline são ignoradas. Escrever @caminho/para/arquivo em um exemplo é seguro.

Importações recursivas. Arquivos importados podem importar os próprios arquivos. Profundidade máxima de 5 saltos. Use isso para empilhar conjuntos de instruções sem enfiar tudo em um lugar só.

Dica para git worktree. CLAUDE.local.md só existe em um worktree de cada vez. Se você alterna entre worktrees, coloque instruções pessoais no seu diretório home e importe-as:

# Individual Preferences
 
- @~/.claude/my-project-instructions.md

CLAUDE.local.md: Memória Privada

Algum contexto é seu, não da equipe. URLs de sandbox local. Fixtures de teste. Um hábito de nomenclatura de branch. Coloque esses em CLAUDE.local.md. Claude Code adiciona esse arquivo ao .gitignore automaticamente, então ele nunca vaza para o repositório.

# CLAUDE.local.md
 
## My Local Setup
 
- Dev server: http://localhost:3001
- Test database: local-dev-db
- Preferred branch naming: feature/[initials]-[description]

Carrega junto com CLAUDE.md na mesma prioridade alta. Suas notas pessoais ficam pessoais. O arquivo compartilhado fica limpo.

/memory: Inspecionar e Editar ao Vivo

Execute /memory dentro de uma sessão para ver todos os arquivos de memória carregados no momento e abrir qualquer um no seu editor. Cobre três trabalhos:

• Verificar quais arquivos CLAUDE.md, regras e importações estão ativos
• Editar a memória sem sair da sessão
• Depurar quando uma instrução parece estar sendo ignorada

Regras Modulares: Memória com Escopo de Caminho

Quer mais controle? O diretório .claude/rules/ permite dividir instruções em muitos arquivos pequenos, cada um com escopo para um padrão de caminho:

.claude/rules/
├── api-guidelines.md     # paths: src/api/**/*
├── react-patterns.md     # paths: src/components/**/*
└── testing-rules.md      # paths: **/*.test.*

Crítico: Arquivos de regras ficam na mesma prioridade alta que o CLAUDE.md. O que muda é o escopo. O alvo por caminho decide quando essa prioridade entra em ação.

Isso resolve o problema do "CLAUDE.md monolítico". Enfie tudo em um arquivo e cada instrução briga por atenção, incluindo as que não têm nada a ver com o que você está trabalhando agora. Com regras, sua orientação de API só compete quando Claude está realmente editando código de API.

Regras em nível de usuário. Regras pessoais que cobrem todos os projetos ficam em ~/.claude/rules/. Carregam antes das regras do projeto, então as regras do projeto ganham em caso de empate.

Expansão de chaves. Padrões de caminho aceitam expansão de chaves para múltiplas extensões ou pastas: src/**/*.{ts,tsx} ou {src,lib}/**/*.ts.

Symlinks. A pasta .claude/rules/ segue symlinks, o que permite reutilizar conjuntos de regras entre projetos. Symlinks circulares são detectados e pulados.

O guia do Diretório de Regras tem a sintaxe completa de padrões de caminho, a ordem de prioridade e notas de migração.

Os Cinco Locais de Memória

Claude Code tem cinco slots de memória distintos. Cada um serve a um trabalho:

Caminhos de política gerenciada mudam por sistema operacional:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Slots mais altos carregam primeiro e definem o piso. Arquivos mais específicos se empilham por cima.

Descoberta em Subárvore: Carregamento Preguiçoso

Claude sobe a árvore na inicialização. Ele também percebe arquivos CLAUDE.md em pastas abaixo da que você iniciou.

A diferença principal: esses arquivos de subárvore não são carregados na inicialização. Carregam no momento em que Claude lê um arquivo dentro dessa subpasta. A inicialização fica barata, e as regras localizadas ainda aparecem quando importam.

Então se packages/auth/CLAUDE.md tiver instruções exclusivas de auth, elas ficam dormentes até Claude abrir um arquivo em packages/auth/.

Versione Seu Arquivo de Memória

Coloque CLAUDE.md sob controle de versão e ele vira uma memória com checkpoints:

# Before experimenting with instructions
git add CLAUDE.md && git commit -m "working context state"
 
# Try new instructions, then restore if needed
git checkout CLAUDE.md

Rollback instantâneo quando uma edição dá errado.

Memória Automática: As Próprias Notas do Claude

Você escreve CLAUDE.md. Claude também escreve o próprio caderno. Esse arquivo fica em ~/.claude/projects/<project>/memory/ e se preenche com observações de depuração, padrões de build e notas de arquitetura. As primeiras 200 linhas do arquivo principal MEMORY.md são carregadas na inicialização junto com seus arquivos CLAUDE.md. O guia completo de memória automática cobre a estrutura de armazenamento e configuração.

Memória de Sessão: Resumo Contínuo

Claude Code agora mantém um resumo contínuo da sessão atual que atualiza a cada mensagem. O arquivo de resumo fica em ~/.claude/projects/[project]/[session]/session_memory e rastreia:

• Título da sessão. Descrição gerada automaticamente do seu trabalho
• Status atual. Itens concluídos, pontos de discussão, perguntas abertas
• Resultados principais. Resultados importantes e aprendizados
• Log de trabalho. Registro cronológico de ações tomadas

Esse feed alimenta a compactação instantânea. Execute /compact e Claude coloca o resumo em um novo contexto imediatamente. Sem espera de dois minutos.

Pergunte ao Claude "onde está armazenada sua memória de sessão?" e ele vai imprimir o caminho exato da sessão atual.

Contexto Fresco Sob Demanda

Sessões longas se enchem de ruído. Redefina com /clear:

/clear

Isso apaga o buffer de conversa e mantém CLAUDE.md no lugar. O ruído vai. Sua memória fica.

Para um reset completo, saia e reinicie:

exit
claude

Contextos Isolados por Tarefa

Quer memória totalmente separada para uma branch? Crie uma pasta:

mkdir feature-auth && cd feature-auth
cp ../CLAUDE.md CLAUDE.md
echo "## Focus: Authentication only" >> CLAUDE.md
claude

Cada pasta carrega seu próprio CLAUDE.md. Os contextos ficam isolados. Ótimo para branches de feature e trabalho experimental.

Quando as Coisas Dão Errado

O contexto parece obsoleto. O histórico de conversa acumulou lixo.

• Correção: Execute /clear. O chat vai, CLAUDE.md fica.

Projetos vazando um para o outro. Instruções de um repositório estão aparecendo em outro.

• Correção: Todo projeto precisa do próprio CLAUDE.md na raiz do projeto.

Instruções sendo ignoradas. O arquivo cresceu demais ou perdeu a forma.

• Correção: Mantenha CLAUDE.md abaixo de 400 linhas. Mova detalhes específicos de domínio para regras com escopo de caminho, para que só recebam alta prioridade quando o caminho combinar.

Próximos Passos

• Trate CLAUDE.md como um sistema operacional para padrões de orquestração mais pesados
• Leia o guia de memória automática para as próprias notas de projeto do Claude
• Estude gerenciamento de contexto para manter os tokens enxutos
• Confira os modos de planejamento para trabalho estruturado
• Configure integração com git para checkpoints de memória
• Veja como a memória se encaixa em context engineering para sistemas de agentes em produção

Lembre-se: CLAUDE.md não é documentação do projeto. É o sistema operacional do seu agente. Estruture bem, e cada sessão pega exatamente de onde a última parou.