Por padrão, o Claude Code apaga as sessões que ficaram mais de 30 dias sem uso. Uma linha no settings.json muda esse prazo e mantém seu histórico disponível no /resume por meses ou anos.
Isso importa em projetos longos. Você passa uma tarde inteira com o Claude investigando um sistema legado, descompilando código ou mapeando um banco de dados. Volta ao assunto dois meses depois e a sessão não aparece mais: todo o raciocínio, as decisões e os comandos daquela conversa sumiram.
Para que serve o cleanupPeriodDays
O cleanupPeriodDays define quantos dias o Claude Code guarda as transcrições das sessões antes de apagá-las. O padrão é 30 dias e o mínimo é 1.
Cada conversa é gravada localmente, em texto puro, em ~/.claude/projects/<projeto>/<sessão>.jsonl. No Windows, ~ é C:\Users\<seu-usuário>. É desse arquivo que o /resume (ou claude --resume) lê para retomar uma conversa.
Logo após uma sessão iniciar, o Claude Code roda em segundo plano uma limpeza que apaga, sem aviso, tudo o que passou do prazo. Além das transcrições, a mesma regra vale para:
- transcrições de subagentes e saídas grandes de ferramentas da sessão;
- snapshots de arquivos usados para desfazer edições (checkpoints);
- planos do plan mode, listas de tarefas e logs de debug.
A memória automática do projeto (projects/<projeto>/memory/) e o histórico de prompts (history.jsonl) não entram nessa limpeza.
Como configurar
Basta adicionar a chave ao seu settings.json de usuário, que vale para todos os projetos.
- Abra (ou crie) o arquivo de configurações:
- Windows:
C:\Users\<seu-usuário>\.claude\settings.json - macOS e Linux:
~/.claude/settings.json
- Windows:
- Adicione a chave
cleanupPeriodDayscom o número de dias desejado. Se o arquivo já tiver outras chaves, mantenha-as e acrescente esta, separada por vírgula:
{
"cleanupPeriodDays": 3650
}- Salve o arquivo e abra uma nova sessão do Claude Code. A limpeza seguinte já usa o novo prazo.
- Confira com
/status. Se houver erro nosettings.json, ele avisa ali.
O valor 3650 equivale a cerca de dez anos e é o próprio exemplo da documentação oficial para retenção longa.
Cuidados importantes:
- Não use
0. Parece “nunca apagar”, mas o valor é rejeitado com erro de validação. O mínimo aceito é 1. - Sessões já apagadas não voltam. A configuração só protege o que ainda está no disco. Faça o ajuste o quanto antes.
- Também funciona por projeto, em
.claude/settings.json(compartilhado) ou.claude/settings.local.json(só você). Em empresas, uma configuração gerenciada pela organização tem prioridade sobre a sua.
Como conferir se deu certo
O jeito mais simples é pedir ao próprio Claude Code. Abra uma sessão nova e cole este prompt:
Confira se a minha configuração de retenção de sessões está funcionando:
1. Leia ~/.claude/settings.json e confirme se o JSON é válido e se a chave
"cleanupPeriodDays" existe, com um número inteiro maior ou igual a 1.
2. Verifique se .claude/settings.json ou .claude/settings.local.json do
projeto atual definem outro valor que sobrescreva o meu.
3. Liste a quantidade de sessões salvas em ~/.claude/projects (arquivos
.jsonl), o espaço total que ocupam e a data da sessão mais antiga.
4. Responda no final com "DEU CERTO" ou "NÃO DEU CERTO", o valor em vigor
e, se algo estiver errado, o que preciso corrigir.
Apenas leia os arquivos; não altere nada.Você também pode conferir à mão: rode /status e veja se não há aviso de erro nas configurações. Depois de 30 dias, o /resume deve continuar mostrando sessões mais antigas que isso, o que antes não acontecia.
Vale para o VS Code e para o Claude Desktop?
Sim, porque os dois usam o mesmo ~/.claude/settings.json. No VS Code (e no terminal), o cleanupPeriodDays vale normalmente. No Claude Desktop, as sessões de código e do Cowork já ficam guardadas sem prazo a partir da versão 2.1.248; para limitá-las, existe a chave desktopSessionCleanupPeriodDays.
As conversas normais do chat do Claude Desktop ficam na sua conta do claude.ai, não na sua máquina, e não são afetadas por essa configuração.
E o impacto?
No uso do dia a dia, nenhum. As sessões antigas são só arquivos parados no disco: o Claude Code não as lê nem as envia ao modelo, a menos que você retome uma delas pelo /resume.
| Aspecto | Muda algo? |
|---|---|
| Consumo de tokens e custo | Não. Sessões antigas não entram no contexto das novas. |
| Velocidade e qualidade das respostas | Não. O modelo só vê a conversa atual. |
| Limites de uso do plano | Não. Arquivo guardado não consome cota. |
| Espaço em disco | Sim, aos poucos. Na minha máquina, 134 sessões ocupam cerca de 205 MB (média de 1,5 MB cada). |
Lista do /resume | Fica mais longa, com mais sessões para escolher. |
Um ponto merece atenção: as transcrições ficam em texto puro, sem criptografia. Tudo o que passou por uma ferramenta fica gravado, inclusive o conteúdo de um .env ou uma senha impressa no terminal. Guardar por dez anos significa guardar isso por dez anos. Se o seu trabalho envolve dados sensíveis, use um prazo menor ou bloqueie a leitura de arquivos de credenciais nas regras de permissão.
Conclusão
Uma linha no settings.json transforma o Claude Code de uma ferramenta com memória de 30 dias em um histórico de trabalho de anos, sem custo extra de tokens nem perda de desempenho. Se você usa o Claude em projetos longos, configure "cleanupPeriodDays": 3650 hoje, antes que a próxima limpeza leve uma sessão importante.
Dica final: se uma sessão for realmente valiosa, não dependa só dela. Peça ao Claude para registrar as decisões e descobertas num arquivo do projeto (um CLAUDE.md ou um documento de notas). Assim o conhecimento sobrevive até a uma formatação da máquina.