Contexto: por que seu agente esquece e como resolver

Na maior parte das vezes em que o agente parece esquecido, a informação que você espera dele nunca chegou ao contexto daquele turno.

Isso muda o diagnóstico. "Ele esqueceu" trata tudo como um problema só, e existem três mecanismos distintos por trás do sintoma: a conversa foi resumida, o arquivo foi lido uma vez no início da sessão, ou a regra depende de um gatilho que não disparou. Cada um tem correção própria, e aplicar a errada gasta tempo sem resolver.

O sintoma é sempre o mesmo: você repete algo que já tinha dito. O que muda é a causa.

Os dois do meio são os que mais custam tempo, porque parecem falha do modelo e são comportamento documentado.

A compactação não é uma faxina indiscriminada. Ela tem ordem: o Claude Code limpa primeiro as saídas de ferramenta mais antigas e só resume a conversa se ainda precisar de espaço. Seus pedidos e os trechos de código relevantes ficam. Instruções detalhadas do começo da conversa são as que mais correm risco.

Depois do resumo, cada mecanismo de instrução tem um destino diferente:

Dois detalhes dessa tabela mudam como você escreve os arquivos.

O primeiro: a truncagem de skill preserva o início do arquivo. Instrução importante enterrada no fim do SKILL.md é a primeira a sumir numa sessão longa. Escreva de cima para baixo, com o que mais importa nas primeiras linhas.

O segundo: a listagem de skills não é reinjetada depois da compactação. Só as que você de fato invocou voltam. Numa sessão longa, o agente perde a lista do que poderia invocar sozinho, o que explica por que ele para de sugerir skills que sugeria no começo.

Para dirigir o resumo em vez de torcer, existem duas alavancas. A primeira é uma seção Compact Instructions no CLAUDE.md, que vale para toda compactação automática:

## Compact Instructions

Ao resumir, preserve sempre:
- O contrato de dados que combinamos para a API de pedidos
- A decisão de manter o schema antigo até a migração terminar
- Nomes de arquivo já investigados e descartados, com o motivo

A segunda é o /compact com foco, que vale só para aquela passada:

/compact foque na migração do checkout, descarte a investigação do CSS

Esse é o caso que mais confunde, porque o comportamento parece um bug e está documentado como projeto.

Seu CLAUDE.md de raiz e o de usuário são lidos uma vez, na abertura da sessão, e ficam em memória. Editar qualquer um deles no meio da sessão não invalida o cache e também não aplica a mudança. O agente continua trabalhando com a versão que carregou quando você abriu o terminal. O conteúdo novo entra no próximo /clear, /compact ou reinício.

O mesmo vale para output style: parte do prompt de sistema, lido na abertura, trocado só na próxima sessão.

Já os arquivos que carregam depois se comportam ao contrário. CLAUDE.md de subpasta e regra com paths: entram no histórico quando o Claude lê o primeiro arquivo que casa. Editar antes disso funciona. Editar depois, não, porque o conteúdo já virou mensagem no histórico.

A regra prática que sai daí: se algo precisa valer sempre, precisa estar no CLAUDE.md da raiz e sem paths:. A anatomia do CLAUDE.md cobre a hierarquia inteira e onde cada escopo faz sentido.

Antes da primeira palavra, a sessão já carregou prompt de sistema, CLAUDE.md, memória automática, informações de ambiente, nomes de ferramentas MCP e descrições das skills disponíveis.

A memória automática entra limitada: as primeiras 200 linhas ou 25 KB do MEMORY.md, o que vier primeiro. Arquivo de memória que cresceu sem poda perde a parte de baixo em silêncio.

Ferramentas MCP são o item que mais varia. Por padrão, nos modelos compatíveis, só os nomes entram, e os esquemas completos ficam adiados até serem necessários. Com ENABLE_TOOL_SEARCH=auto, os esquemas carregam adiantados se couberem em 10% da janela de contexto. Com false, tudo carrega. A diferença entre as duas configurações, num setup com vários servidores, é a diferença entre começar a sessão com folga ou já apertado. O post sobre MCP na prática detalha o custo por servidor.

Para ver a distribuição real da sua sessão em vez de estimativa, /context mostra a quebra por categoria, inclusive quais arquivos de CLAUDE.md e de memória carregaram. /mcp mostra o custo por servidor.

1. Delegar leitura grande a subagente. A maior economia disponível. O subagente lê no contexto dele e devolve só o texto final mais um rodapé curto de metadados. Na simulação da própria documentação, um subagente lê 6.100 tokens de arquivos e devolve 420. Quando delegar e quando não vale está em subagentes: quando delegar.

2. /clear entre tarefas não relacionadas. Conversa velha não fica de graça: ela é reenviada em toda mensagem seguinte e disputa espaço com os arquivos de que você precisa agora. A medição de custo em 46 mil turnos reais mostra o tamanho dessa conta.

3. /compact com foco, no intervalo certo. Rodar entre tarefas coloca o custo onde você escolheu. Esperar a compactação automática coloca no meio do trabalho.

4. Ajustar a janela de compactação. Define o quão cheio o contexto chega antes da passada automática. O comando e a flag aceitam de 100K a 1M, em três formatos equivalentes:

/autocompact 500k          # sufixo k ou M
/autocompact 200000        # contagem simples
/autocompact 200           # numero puro de 100 a 1000, em milhares
/autocompact auto          # volta para a janela ajustada ao modelo

claude --autocompact 500k  # so este lancamento, sem salvar

O /autocompact salva em autoCompactWindow nas suas configurações. Em script ou ambiente de nuvem, a variável CLAUDE_CODE_AUTO_COMPACT_WINDOW tem precedência sobre o comando, a flag e a configuração.

5. Esconder skill que você só invoca na mão. disable-model-invocation: true tira a skill da listagem inicial, e ela fica fora do contexto até você digitar /nome. Para skills que você não escreveu, skillOverrides faz o mesmo pelas configurações. O passo a passo de escrita está em como escrever a sua primeira Agent Skill.

Sobre janela maior: Fable 5, Sonnet 5, Opus 4.6 em diante e Sonnet 4.6 suportam 1 milhão de tokens, com disponibilidade variando por plano. Na API, o Sonnet 5 roda sempre em 1M e compacta por volta de 967 mil tokens. Janela maior adia o problema, não muda o mecanismo.

Essa parte não é sobre esquecimento e explica boa parte da conta.

O modelo não guarda nada entre requisições. O Claude Code reenvia o contexto inteiro toda vez, e o que evita reprocessar tudo é o cache de prefixo. A comparação é exata e do início: uma mudança em qualquer ponto do prefixo recomputa tudo que vem depois. Não existe cache por arquivo nem por trecho.

Por isso a requisição é montada em camadas, do que muda menos para o que muda mais:

Token lido do cache é cobrado a cerca de 10% da taxa normal de entrada. É uma diferença grande o bastante para valer conhecer as oito ações que jogam essa economia fora: trocar de modelo, mudar o nível de esforço, ligar o fast mode, conectar ou desconectar um servidor MCP com ferramentas no prefixo, habilitar ou desabilitar plugin que traga MCP, negar uma ferramenta inteira por regra de permissão, compactar, e atualizar o Claude Code.

Duas delas surpreendem. Modelo e nível de esforço não são texto do prompt, e mesmo assim entram na chave do cache: trocar qualquer um recomputa a conversa inteira com conteúdo idêntico. E opusplan alterna entre Opus e Sonnet ao entrar e sair do plan mode, o que faz de cada alternância uma troca de modelo.

Do outro lado, ações que mantêm o cache: editar arquivo do repositório, editar o CLAUDE.md no meio da sessão, trocar de modo de permissão, invocar skill ou comando, rodar /recap e criar subagente.

O /rewind merece parágrafo próprio. Quando você quer abandonar um caminho inteiro, ele trunca a conversa de volta a um ponto anterior, e esse prefixo já está no cache. Compactar, na mesma situação, constrói um prefixo novo. Para descartar trabalho ruim, rebobinar sai mais barato que resumir.

E o custo do /compact depende do momento: com cache quente, a chamada de resumo lê o prefixo do cache e custa uma fração do que o tamanho do contexto sugere. Depois de uma pausa longa, o cache expirou e o resumo reprocessa o histórico inteiro. É por isso que compactar ao retomar uma sessão antiga costuma ser a requisição mais cara do dia.

Um detalhe de escopo que pega quem usa worktrees: o cache é, na prática, por máquina e por diretório, porque o prompt de sistema embute o diretório de trabalho. Duas worktrees do mesmo repositório constroem prefixos diferentes e não aproveitam o cache uma da outra.

Existe um caso em que nenhuma alavanca acima ajuda: um único arquivo ou saída de ferramenta grande o suficiente para encher o contexto de novo logo depois de cada resumo.

O Claude Code detecta o ciclo. Depois de algumas tentativas, ele para de compactar sozinho e mostra um erro em vez de entrar em laço. A saída é reduzir a entrada: ler o arquivo em pedaços, filtrar a saída do comando antes de mandar, ou empurrar a leitura para um subagente.

O padrão vale como diagnóstico geral. Quando o contexto enche rápido demais, o problema quase nunca é o tamanho da janela. Quase sempre é uma leitura que não precisava ser inteira. O guia de Claude Code em produção trata isso como restrição de projeto, não de configuração.

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

/clear descarta a conversa e começa do zero, recarregando CLAUDE.md e memória do disco. /compact substitui a conversa por um resumo estruturado e mantém a linha do trabalho. Use /clear ao trocar para algo não relacionado, e /compact para continuar a mesma tarefa com menos peso.

Por que o agente ignorou a regra que acabei de adicionar no CLAUDE.md?

Porque o CLAUDE.md da raiz é lido uma vez, na abertura da sessão. A edição não invalida o cache e também não entra em vigor. O conteúdo novo carrega no próximo /clear, /compact ou reinício do Claude Code.

Sessão nova começa sabendo o que foi feito na anterior?

Não. Cada sessão abre com uma janela de contexto limpa, sem o histórico da anterior. O que atravessa são os arquivos: CLAUDE.md e a memória automática, limitada às primeiras 200 linhas ou 25 KB do MEMORY.md. Para retomar a conversa em si, use --continue ou --resume.

Subagente aproveita o cache da sessão principal?

Subagente comum, não: ele começa com prompt de sistema e conjunto de ferramentas próprios, e aquece o cache dele. Fork é diferente, porque herda prompt, ferramentas e histórico do pai e já lê o cache dele na primeira requisição. Subagente usa TTL de cinco minutos mesmo em assinatura, onde a conversa principal usa uma hora.

• Anthropic — Claude Code Docs: Explore the context window. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude Code uses prompt caching. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Model configuration. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude Code works. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) mudarem os tetos de reinjeção de skill (5.000 por skill, 25.000 no total), (b) o limiar de compactação automática do Sonnet 5 sair dos 967 mil tokens, ou (c) a lista de ações que invalidam o cache ganhar ou perder item.