CLAUDE.md e memória do Claude Code
VPS Agêntica
Uma VPS para os seus agentes trabalharem dia e noite
Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.
Link de parceiro da Promovaweb.
Black Friday até 30/11
30%off
nos 2 primeiros meses do plano mensal da VPS
- Backup diário grátis para sempre
- Servidores em São Paulo no datacenter da Ascenty
- Datacenter Tier III manutenção sem parada
- Acesso root com disco SSD NVMe
- Réplica do backup em Ashburn, nos EUA
O CLAUDE.md é um arquivo Markdown que você escreve com as convenções do projeto e que o Claude Code carrega no começo de toda sessão. A auto memory é o outro lado: notas que o próprio agente grava durante o trabalho com as suas correções e preferências, também lidas quando uma sessão nova começa.
Sumário da página
Cada sessão começa do zero
Toda sessão nova do Claude Code abre com a janela de contexto vazia. Ontem você explicou que os testes rodam com npm run test:unit e que os handlers da API ficam em src/api/handlers/. Essa conversa não chega à sessão de hoje. Sem um registro escrito, você repete as mesmas instruções e o agente volta a procurar as mesmas pastas.
O Claude Code resolve isso com dois sistemas que se completam. O CLAUDE.md é escrito por você e guarda instruções e convenções. A auto memory é escrita pelo Claude e guarda aprendizados. Os dois carregam no início de cada conversa. A documentação deixa claro que ambos entram como informação para o modelo, não como configuração imposta. Para barrar uma ação de qualquer jeito, o caminho é uma entrada deny nas permissões ou um hook PreToolUse.
Onde o CLAUDE.md pode ficar
O arquivo existe em quatro escopos, carregados do mais amplo para o mais específico. A instrução do projeto aparece depois da instrução pessoal, então é lida por último.
/etc/claude-code/CLAUDE.mdPolítica da organização no Linux e no WSL, distribuída pela área de TI.~/.claude/CLAUDE.mdSuas preferências pessoais, válidas em todos os projetos.projeto/Raiz do repositório.CLAUDE.mdConvenções do projeto, versionadas no Git. Também aceito em .claude/CLAUDE.md.CLAUDE.local.mdAjustes pessoais daquele projeto, fora do Git..claude/rules/Instruções por assunto, que podem valer só para alguns caminhos.
No macOS, a política da organização fica em /Library/Application Support/ClaudeCode/CLAUDE.md. No Windows, em C:\Program Files\ClaudeCode\CLAUDE.md. O comando /init gera um CLAUDE.md inicial a partir da leitura do projeto. O /memory abre os arquivos carregados para você conferir e editar.
O agente lê o CLAUDE.md e o CLAUDE.local.md da pasta onde você abriu a sessão e de todas as pastas acima dela. Os arquivos não se sobrepõem: eles são concatenados, da raiz do disco até a pasta atual. Arquivos em subpastas carregam sob demanda, quando o agente lê ou edita algo naquela subpasta. Num monorepo, cada pacote pode ter o próprio CLAUDE.md sem pesar nas sessões dos outros pacotes.
Instruções que o agente consegue seguir
A documentação recomenda instruções concretas o bastante para serem conferidas. “Use indentação de dois espaços” funciona melhor que “formate o código direito”. “Rode npm test antes do commit” funciona melhor que “teste as mudanças”. “Os handlers da API ficam em src/api/handlers/” funciona melhor que “mantenha os arquivos organizados”.
O tamanho também pesa. A recomendação é ficar abaixo de 200 linhas por arquivo, porque um arquivo longo ocupa mais janela de contexto e reduz a aderência às instruções. Instruções que só interessam a uma parte do código vão para .claude/rules/, com o campo paths no frontmatter. Esses arquivos só carregam quando o agente trabalha com arquivos que casam com o padrão. Duas instruções que se contradizem fazem o modelo escolher uma delas de forma imprevisível. Por isso vale revisar os arquivos de tempos em tempos.
O CLAUDE.md aceita importar outros arquivos com a sintaxe @caminho/do/arquivo, com até quatro níveis de importação. O import divide um arquivo longo em partes, mas não reduz o custo, porque o arquivo importado carrega junto. Comentários HTML em bloco são removidos antes de o conteúdo chegar ao modelo, o que permite deixar notas para os colegas do projeto sem gastar janela de contexto.
AGENTS.md e outros agentes
Se o repositório já tem um AGENTS.md para outros agentes de código, o Claude Code lê esse arquivo como instrução do projeto quando não existe CLAUDE.md na pasta nem acima dela. Com os dois arquivos presentes, ele lê só o CLAUDE.md. Para manter um arquivo único entre ferramentas, o CLAUDE.md pode importar o AGENTS.md. A leitura direta do AGENTS.md exige a versão 2.1.277 ou posterior.
A memória que o agente grava sozinho
A auto memory funciona sem você escrever nada. Durante o trabalho, o Claude anota quatro tipos de nota: o seu papel e a sua forma de trabalhar, as correções que você faz e as abordagens que confirma, o andamento do projeto que não aparece no código nem no histórico do Git e onde encontrar informação fora do repositório, como um quadro de tarefas ou um painel. Ele pula o que consegue tirar do código e o que o CLAUDE.md já diz.
Cada projeto tem a própria pasta de memória em ~/.claude/projects/<projeto>/memory/, compartilhada entre os worktrees do mesmo repositório. O arquivo MEMORY.md funciona como índice. As primeiras 200 linhas ou os primeiros 25 KB, o que vier primeiro, carregam em toda sessão. Notas detalhadas ficam em arquivos de tópico que o agente lê só quando o assunto aparece. Quando a interface mostra mensagens como “Saved 2 memories”, o agente está gravando nessa pasta.
O que fica de fora
Instruções não substituem permissões. Uma instrução escrita orienta o comportamento, mas o modelo pode deixar de seguir uma frase ambígua ou perdida no meio de um arquivo grande. Depois de uma compactação longa, o que foi dito no começo da conversa pode sair do resumo. O CLAUDE.md da raiz volta a ser lido, por isso as instruções permanentes moram nele e não na conversa. Procedimentos longos, que só valem para uma tarefa, ficam melhor numa skill, assunto do próximo hub.