Gerenciando contexto e memória no Claude Code: /compact, CLAUDE.md e orçamento de tokens (2026)

Se você já usou o Claude Code em sessões longas e com muitos arquivos, provavelmente já passou por isto: tudo vai bem, e de repente o Claude começa a "esquecer" uma decisão que você fechou 20 minutos atrás, ou o terminal avisa que o contexto está quase cheio. Neste artigo eu junto as três peças que a maioria dos guias mantém separadas — contexto na sessão, memória entre sessões e orçamento de tokens — em um único fluxo de trabalho prático. Se você é totalmente iniciante, leia primeiro um guia introdutório; mas, se você roda sessões com vários arquivos todos os dias, este texto é para você.

Contexto vs. memória no Claude Code: qual é a diferença?

Essas duas palavras são usadas como sinônimos, mas são coisas completamente diferentes — e confundir uma com a outra é a raiz da maioria dos problemas quando o assunto é gerenciar contexto no Claude Code. O contexto (a janela de contexto) é a memória de curto prazo que o Claude consegue "ver" agora: a sua pergunta, o conteúdo dos arquivos que ele leu, o histórico da conversa, os resultados das ferramentas que ele rodou, além do CLAUDE.md que foi carregado no início da sessão. Ela é finita e some quando você encerra a sessão ou digita /clear.

A memória (a memória persistente do Claude Code) vive entre as sessões. Existem dois tipos: o CLAUDE.md — o arquivo que você escreve para orientar o Claude sobre o seu projeto — e a memória automática — onde o Claude guarda o que aprende sozinho. O ponto-chave: a memória não fica dentro do contexto, ela é recarregada no contexto toda vez que uma nova sessão começa.

Aqui vai uma frase para você nunca mais confundir: contexto é o que o Claude está pensando agora, memória é o que o Claude sempre sabe.

Por que toda sessão do Claude Code começa com o contexto vazio?

Muita gente presume, caladinha, que o Claude "lembra" da conversa de ontem do jeito que um colega lembraria. Ele não lembra. No fundo, um modelo de linguagem não tem memória de longo prazo embutida — o Claude não lembra de verdade da conversa. Toda nova sessão é uma janela de contexto limpa e em branco. A sensação de que "ele lembra do meu projeto" na verdade vem de o Claude Code recarregar automaticamente a memória (CLAUDE.md e memória automática) no início de cada sessão, e não de o modelo recordar algo.

É exatamente por isso que a memória existe: ela é a ponte que compensa uma janela de contexto que "perde a memória" depois de cada reinício. Depois que você entende isso, para de esperar que o Claude lembre sozinho e passa a anotar de propósito o que precisa ser lembrado. Esse comportamento de janela de contexto nova a cada sessão está descrito na documentação oficial do Claude Code sobre a janela de contexto (acesso em 2026-08-20).

A consequência prática: qualquer decisão que vive só no chat, sem ser escrita em um arquivo, corre o risco de evaporar — quando a sessão termina, ou até antes, se o contexto for compactado. Voltaremos a isso na seção do /compact.

Meça o contexto com /context e o estado dos tokens

Você não consegue gerenciar o que não consegue medir. O primeiro comando para gravar na cabeça é /context. Digite-o durante uma sessão e o Claude Code lista os Memory files carregados no momento (quais arquivos CLAUDE.md entraram no contexto) e a porcentagem da janela de contexto em uso.

/context

Essa é a forma mais confiável de verificar se o seu CLAUDE.md realmente entrou no contexto — não chute, olhe a lista de Memory files. Além disso, a linha de status no seu terminal mostra a porcentagem de tokens em uso em tempo real. Quando o contexto atinge um limite alto, o Claude Code compacta automaticamente (auto-compact) para a sessão não travar.

O limite do auto-compact fica em torno de 80-83%, segundo a documentação oficial do Claude Code (acesso em 2026-08-20), mas esse número pode mudar entre versões.

/compact — compactando o contexto do jeito certo

Este é o comando mais importante do artigo. O /compact lê a conversa atual inteira, produz um resumo condensado e então substitui a conversa antiga por esse resumo. O resultado: libera a maior parte dos tokens mantendo o fio do trabalho intacto — o Claude continua sabendo o que você está fazendo, só que de forma comprimida.

# automatic compaction
/compact

# compact with instructions on what to keep
/compact keep the DB schema decisions and the files I edited, drop the debug logs

Quando você deve compactar? Minha regra prática: seja proativa por volta dos 60%, não espere chegar aos 90%. Compactar cedo, enquanto a conversa ainda está "limpa", gera um resumo muito melhor do que forçar uma compactação com o contexto já entupido — nesse ponto o Claude precisa descartar muita coisa e o resumo tende a perder detalhes. Usar /compact <instructions> para deixar claro o que manter é um grande ganho de qualidade.

⚠️ Observação importante sobre limites: a compactação tem perdas. Qualquer coisa que vive só na conversa e não foi escrita em um arquivo pode se perder de vez depois de uma compactação. Esse é um problema real que faz as pessoas "perderem" decisões no meio da tarefa. A tabela abaixo mostra o que sobrevive e o que não sobrevive:

O recado, em resumo: antes de compactar, peça ao Claude para "escrever as decisões importantes no CLAUDE.md" — e então rode o /compact. O que está no disco está seguro.

/clear vs. /compact — qual você deve usar?

Esses dois comandos são fáceis de confundir, mas servem a situações bem diferentes. Versão curta: /compact quando você está continuando o mesmo trabalho, /clear quando você está mudando para outra coisa.

O que vale lembrar: seja com /clear ou /compact, a memória entre sessões (CLAUDE.md e memória automática) continua sendo recarregada — então você não perde o "conhecimento de base" do seu projeto, só a conversa temporária. Quando trocar de tarefa, não hesite em usar /clear: segurar uma conversa antiga sem relação só queima tokens e distrai o Claude.

CLAUDE.md — a memória de longo prazo que você mesma escreve

O CLAUDE.md é a ferramenta de memória mais poderosa que você controla diretamente. Ele carrega automaticamente no contexto a cada sessão, na ordem do escopo mais amplo para o mais estreito. O Claude Code lê vários níveis de CLAUDE.md e os mescla:

A ordem de carregamento do amplo para o específico significa que os níveis mais estreitos (projeto, local) podem complementar os mais amplos. O jeito mais rápido de começar: rode /init — o Claude Code vai escanear seu código e montar um CLAUDE.md inicial para o projeto.

/init

Escrevendo um CLAUDE.md eficaz: mantenha-o curto — abaixo de cerca de 200 linhas. Um arquivo mais longo não só custa contexto a cada sessão como também reduz a aderência (o Claude tem dificuldade de priorizar quando há instruções demais). Existe uma análise com medições sobre por que arquivos de contexto inchados custam 20% a mais. Escreva coisas específicas e verificáveis: "use indentação de 2 espaços" é melhor que "formate bonitinho". Para conteúdo longo, use @path para importar outros arquivos, e coloque convenções específicas de contexto em .claude/rules/ com escopo de caminho (carregadas só quando você abre um arquivo que casa com o glob) para economizar contexto. Para se aprofundar em como estruturar esse arquivo, veja o guia sobre escrever um arquivo CLAUDE.md decente — esse conteúdo cuida dos detalhes, então não vou repeti-los aqui.

Um exemplo rápido de regra com escopo de caminho: um arquivo em .claude/rules/api-conventions.md com um frontmatter YAML que limita quando ele carrega:

---
paths:
  - "src/api/**/*.ts"
---
Use camelCase for function names; always validate input with Zod.

Uma regra sem o campo paths: (sem escopo) carrega a cada sessão com a mesma prioridade do CLAUDE.md raiz; uma regra com escopo só carrega quando você abre um arquivo que casa com o glob — é por isso que ela economiza mais contexto do que enfiar tudo no CLAUDE.md. Para a configuração completa do .claude/rules/ (layout de pastas, regras no nível do usuário, prioridade de carregamento), veja o guia do CLAUDE.md.

Memória automática — quando o Claude lembra entre sessões por conta própria

Esta é uma novidade relativamente recente (2026) que muitos guias antigos pulam. Além do CLAUDE.md que você escreve, o Claude Code pode ele mesmo salvar o que aprende enquanto trabalha em uma pasta de memória específica do projeto: ~/.claude/projects/<project>/memory/.

Lá dentro, o MEMORY.md funciona como índice: as primeiras 200 linhas ou os primeiros 25KB do arquivo — o que vier primeiro — são carregados a cada sessão; os outros arquivos de tópico carregam sob demanda, só quando necessário. Esse recurso vem ligado por padrão; você o gerencia com o comando /memory (alterna pela opção autoMemoryEnabled), e vai ver avisos como "Saved N memories" / "Recalled N memories" quando o Claude escreve ou relembra aprendizados.

/memory

Para deixar a distinção clara: o CLAUDE.md é o que você escreve (instruções — como você quer que o Claude trabalhe), enquanto a memória automática é o que o Claude escreve (aprendizados — o que ele captou). Os dois se complementam. O mecanismo da memória automática e seus limites de carregamento estão detalhados na documentação oficial de memória do Claude Code (acesso em 2026-08-20).

Orçamento de tokens — trabalhando de forma mais barata e sustentável

Esta é a parte que os concorrentes deixam quase totalmente em branco. Os modelos mais novos são conscientes do contexto: eles acompanham quantos tokens restam e passam automaticamente a responder de forma mais concisa, usando ferramentas com mais parcimônia conforme o contexto diminui. Mas não deixe tudo por conta da sorte — as seis regras abaixo mantêm suas sessões baratas e estáveis:

A regra 3 merece destaque: quando você precisa que o Claude leia um diretório grande ou um log longo, entregue isso a um subagent em vez de ler direto na sessão principal. O subagent trabalha em um contexto separado e devolve só a conclusão — seu contexto principal fica leve. Essa forma de organizar o trabalho é detalhada no artigo sobre usar subagents para isolar o contexto. Quanto aos comentários da regra 6, notas humanas no CLAUDE.md envolvidas em <!-- --> nunca chegam ao contexto do Claude, então você pode anotar à vontade sem gastar tokens.

O fluxo de gerenciamento de contexto e memória (checklist prático)

Juntando tudo em uma rotina de seis passos que você pode rodar todo dia:

1. Gere o CLAUDE.md: rode /init para gerar um arquivo inicial a partir do código.
2. Enxugue o CLAUDE.md: mantenha abaixo de 200 linhas, específico e verificável; mova convenções específicas de contexto para .claude/rules/.
3. Monitore: digite /context periodicamente durante sessões longas e fique de olho na % de tokens na linha de status.
4. Compacte cedo: /compact por volta dos 60%, com instruções sobre o que manter (por exemplo, manter decisões + arquivos editados).
5. Reinicie ao trocar de tarefa: use /clear ao mudar para uma tarefa sem relação.
6. Fixe as decisões: peça ao Claude para "atualizar o CLAUDE.md com esta decisão" antes de compactar ou encerrar a sessão, para nada se perder na compactação.

Ganhe velocidade com um kit pronto (AgentKit)

Escrever um CLAUDE.md, um .claude/rules/ e a configuração de subagents decentes para cada projeto dá um bom trabalho. Se você quer andar mais rápido, alguns kits prontos como o bundle AgentKit — agora US$ 149 (de US$ 198) já vêm com CLAUDE.md/rules de exemplo, além de subagents que têm o próprio contexto — o que combina exatamente com os princípios de orçamento de tokens acima. Eu dou uma olhada mais de perto em o que é o AgentKit e se ele vale a pena caso você queira pesar os prós e contras; mas, para gerenciamento de contexto, os comandos /context, /compact e /clear acima seguem sendo a base, use você um kit ou não.

Erros comuns e como evitá-los

Sendo sincera, esses são os pontos em que eu — e muita gente — mais tropeço:

• Perder decisões depois do /compact: porque foram apenas ditas no chat, nunca escritas em um arquivo -> sempre escreva as decisões importantes no CLAUDE.md antes de compactar.
• Um CLAUDE.md inchado: um arquivo longo demais desperdiça tokens e reduz a aderência -> separe as coisas em .claude/rules/ com escopo de caminho.
• Regras / CLAUDE.md aninhado não recarregam sozinhos após a compactação: regras com escopo de caminho e CLAUDE.md de subpasta não se recarregam sozinhos -> reabra o arquivo que casa com o glob para reativá-los.
• Instruções conflitantes entre vários arquivos CLAUDE.md: quando os níveis se contradizem, o Claude pode escolher de um jeito que você não pretendia -> revise a consistência entre usuário/projeto/local.

Se você esbarrar em outros perrengues, veja a coletânea sobre corrigir os erros comuns do Claude Code. E, para entender o quadro maior de como o Claude Code encaixa suas peças, confira o artigo sobre a diferença entre skills, subagents, hooks e MCP.

Perguntas frequentes (FAQ)

Qual a diferença entre /compact e /clear?

O /compact comprime a conversa em um resumo condensado e mantém o fio do trabalho — use quando estiver continuando a mesma tarefa, mas com o contexto cheio. O /clear apaga a conversa por completo e começa um contexto vazio — use quando trocar para uma tarefa diferente. Os dois continuam recarregando o CLAUDE.md e a memória automática.

Em que % o auto-compact dispara?

Segundo a documentação oficial, o auto-compact entra em ação quando o uso do contexto está por volta de 80-83%. Ainda assim, é melhor você usar /compact de forma proativa mais cedo, perto dos 60%, para um resumo de mais qualidade e com menos perda. O limite exato pode mudar entre versões.

O CLAUDE.md sobrevive ao /compact?

Sim. O CLAUDE.md na raiz do seu projeto é reinjetado do disco, então ele está sempre lá depois de uma compactação. Mas CLAUDE.md aninhado em subpastas e regras com escopo de caminho não recarregam sozinhos — você precisa reabrir o arquivo correspondente para reativá-los.

Quando eu devo usar o /compact?

De forma proativa, quando o uso do contexto está por volta dos 60% — não espere chegar aos 90%. Compactar cedo, enquanto a conversa ainda está "limpa", dá um resumo melhor. Adicione instruções também, por exemplo /compact keep the schema decisions and edited files, para o Claude reter exatamente o que você precisa.

Onde a memória automática fica guardada?

O Claude Code salva os aprendizados em uma pasta de memória específica do projeto (~/.claude/projects/<project>/memory/), com o MEMORY.md como índice: as primeiras 200 linhas ou 25KB dele, o que vier primeiro, carregam a cada sessão. Vem ligado por padrão; alterne e inspecione com o comando /memory. Confira o caminho exato ao vivo, conforme a versão.

Como eu reduzo tokens no Claude Code?

Compacte cedo com /compact em ~60%, mantenha o CLAUDE.md enxuto (< 200 linhas), delegue leituras pesadas a um subagent para não comer o contexto principal, divida tarefas em fases e use /clear quando trocar de trabalho. Essas são as alavancas de orçamento de tokens mais eficazes.

Conclusão + próximos passos

O fluxo inteiro em uma linha: meça com /context -> compacte cedo com /compact em ~60% -> use /clear ao trocar de tarefa -> fixe as decisões no CLAUDE.md, e deixe a memória automática cuidar dos aprendizados. Domine as três peças — contexto, memória e orçamento de tokens — e suas sessões longas param de "esquecer" e ficam visivelmente mais baratas. Próximo passo: aprenda a escrever um arquivo CLAUDE.md decente para a sua memória realmente valer a pena, e mergulhe mais fundo em o que é engenharia de contexto quando você quiser otimizar no nível arquitetural.