Memória persistente para Claude Code: como o contexto entre sessões realmente funciona

O problema central: as sessões não mantêm estado por definição

Uma sessão do Claude Code é uma conversa. Quando ela termina, a transcrição é arquivada e o contexto de trabalho — a compreensão acumulada ao longo de dezenas de chamadas de ferramentas — evapora. A sessão seguinte reconstrói o contexto a partir de três fontes:

• Seu CLAUDE.md files (project and user scope)
• Os arquivos que Claude lê durante a sessão
• O que você digita

Nenhuma dessas fontes captura conhecimento derivado : os caminhos sem saída que você já explorou, o motivo de existir uma solução alternativa estranha, o fato de que você tentou a abordagem A e ela quebrou a CI. Derivar esse conhecimento novamente custa tokens e tempo real em cada sessão.

O impulso é construir uma camada de memória — capturar o que aconteceu, comprimir essas informações e injetar a parte relevante de volta na inicialização. O projeto de código aberto claude-mem é uma implementação de referência clara exatamente desse padrão, e vale a pena estudá-lo, independentemente de você adotá-lo.

O padrão de arquitetura por trás da memória persistente do Claude Code

Toda abordagem séria de memória persistente no Claude Code segue o mesmo ciclo de três etapas. Entender cada etapa separadamente permite que você a implemente, compre uma solução ou a dispense.

Etapa 1: Capturar

Você precisa observar o que aconteceu em uma sessão. O Claude Code disponibiliza hooks de ciclo de vida — comandos de shell executados em resposta a eventos. Os relevantes são:

Um hook mínimo de captura em .claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/mem/capture.sh"
          }
        ]
      }
    ]
  }
}

O hook recebe JSON na entrada padrão descrevendo o evento. Para SessionEnd você recebe o ID da sessão e o caminho da transcrição, então capture.sh pode ler o registro completo da conversa:

#!/usr/bin/env bash
INPUT=$(cat)
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

# Hand the raw transcript to the compression stage
python3 "$CLAUDE_PROJECT_DIR/.claude/mem/compress.py" \
  --transcript "$TRANSCRIPT" \
  --session "$SESSION_ID"

Uma armadilha comum: os hooks têm um tempo limite de execução, e uma transcrição grande enviada de forma síncrona a um LLM vai ultrapassá-lo. Na prática, a captura deve ser disparada sem esperar sua conclusão — grave o caminho da transcrição em uma fila e processe-o em um worker em segundo plano, em vez de fazer isso dentro do hook.

Etapa 2: Comprimir

Transcrições brutas são inúteis como memória — são enormes e cheias de ruído (despejos de arquivos, excesso de saídas de ferramentas, seus erros de digitação). A etapa de compressão usa um LLM para extrair da sessão fatos duradouros. É aqui que você gasta com uma chamada ao Haiku 4.5, e não ao Opus — a sumarização é exatamente o tipo de tarefa de alto volume e baixo risco para o qual o Haiku tem preços adequados.

import anthropic

client = anthropic.Anthropic()

PROMPT = """You are a memory compressor. From this coding session
transcript, extract ONLY durable facts worth remembering next session:
- Architectural decisions and their rationale
- Conventions discovered (naming, error handling, imports)
- Dead ends already explored (so we don't repeat them)
- Unresolved TODOs

Output JSON: a list of {fact, category, files[], confidence}.
Omit anything transient. If nothing durable happened, output []."""

resp = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1500,
    system=PROMPT,
    messages=[{"role": "user", "content": transcript_text}],
)
memories = resp.content[0].text

Observe o campo confidence e a instrução explícita para gerar []. Ambos servem para limitar os danos do modo de falha que abordaremos adiante. Armazene a saída em algum lugar que permita consultas — SQLite com uma coluna de embeddings ou um banco vetorial com chaves por projeto e caminhos de arquivos.

Etapa 3: Injetar

No início da sessão, você recupera as memórias relevantes e as injeta. O hook SessionStart pode escrever na saída padrão, e essa saída é adicionada ao contexto do Claude:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/mem/inject.sh" }
        ]
      }
    ]
  }
}

A decisão crítica de engenharia é a filtragem por relevância. Injetar toda a memória é a abordagem ingênua e está errada — ela infla seu contexto e ofusca os fatos úteis. Melhor: recupere as memórias com base no provável assunto da sessão. Se ainda não for possível identificá-lo, injete apenas fatos de alta confiança que se apliquem ao projeto inteiro e disponibilize o restante por meio de um servidor MCP para que o Claude possa consultar a memória sob demanda:

# A tiny MCP tool the agent calls when it wants history
@mcp.tool()
def recall(query: str, files: list[str] = []) -> list[dict]:
    """Retrieve relevant memories about this codebase."""
    return memory_store.search(query, files=files, min_confidence=0.6)

Na prática, esse modelo de consulta sob demanda supera o modelo de envio antecipado. Em vez de adivinhar o que é relevante no início, você deixa o agente perguntar “já mexemos neste código de faturamento antes?” exatamente quando isso importa. O hook fornece um pequeno resumo sempre presente; o servidor MCP cuida da recuperação direcionada.

Onde isso falha — e falha mesmo

Uso camadas de memória há tempo suficiente para ser cético em relação a elas. Os modos de falha são reais e se acumulam.

A memória comprimida por IA alucina. O próprio compressor é um modelo de linguagem. Ocasionalmente, ele registra uma “decisão” que era, na verdade, uma ideia descartada, ou inverte a justificativa de uma escolha. Agora você tem uma memória falsa com aparência de autoridade injetada no início, e o agente confia nela mais do que deveria. Isso é pior do que não ter memória, porque ela está errada e transmite confiança. O campo confidence e a revisão humana do repositório de memórias são as únicas medidas reais de mitigação.

Contexto desatualizado é um assassino silencioso. Você refatora UserService na terça-feira. Sua memória de segunda-feira ainda diz “a autenticação fica em UserService.” Nada a invalida. As memórias perdem precisão no momento em que o código muda, e não há um sinal claro para expirá-las. Vincule as memórias a hashes de arquivos ou SHAs de commits e trate-as como suspeitas quando o arquivo subjacente for movido.

Os custos de tokens aumentam a cada sessão. A memória injetada é um contexto pelo qual você paga a cada turno, seja usado ou não. Uma camada de memória que injeta 4K tokens no início acrescenta essa quantidade ao seu custo de entrada durante toda a sessão. O modelo MCP baseado em consultas sob demanda ajuda, mas a captura e a compressão também geram gastos recorrentes.

Aqui está uma comparação honesta:

A verdade incômoda: você provavelmente não precisa disso

Antes de implementar qualquer uma dessas coisas, escreva um bom CLAUDE.md. Um arquivo organizado manualmente que diga “usamos Result<T>, nunca lance exceções; UserService não deve importar billing/; a autenticação foi movida para auth/ no segundo trimestre” resolve 80% do problema de memória com risco zero de alucinação e custo determinístico. Ele é escrito por uma pessoa, portanto é confiável por construção.

As camadas de memória justificam seu custo em um conjunto de situações mais restrito do que o entusiasmo sugere: trabalhos longos e exploratórios nos quais o conhecimento derivado (caminhos sem saída, investigações pela metade) realmente não pode ser registrado de antemão porque você ainda não o tem. Para o desenvolvimento rotineiro de funcionalidades, CLAUDE.md mais alguns servidores MCP com escopo definido atendem a mais necessidades do que um pipeline automatizado de memória, e nunca mentem para você.

Se você implementar o pipeline, a etapa de compressão é onde a sensibilidade ao custo mais importa — executar sumarizações frequentes com Haiku é barato, mas apenas se o preço por token já for razoável, o que é um dos motivos pelos quais as equipes encaminham esse tipo de trabalho de alto volume em segundo plano por provedores como a AI Prime Tech.

Recomendações práticas

• As sessões não mantêm estado. O conhecimento derivado — caminhos sem saída, justificativas, convenções — é o que realmente se perde, e reconstruí-lo custa caro.
• O padrão é capturar → comprimir → injetar. Conecte a captura e a injeção usando hooks de SessionEnd/SessionStart ; faça a captura de forma assíncrona para evitar os limites de tempo dos hooks.
• Prefira consultas sob demanda ao envio antecipado. Forneça um resumo mínimo no início e, em seguida, disponibilize uma ferramenta recall MCP para que o agente busque memórias apenas quando forem relevantes.
• Comprima com Haiku 4.5, marque cada memória com seu grau de confiança e os hashes dos arquivos de origem, e trate a memória como suspeita quando os arquivos mudarem.
• A memória automatizada pode mentir. Contexto alucinado e desatualizado é pior do que nenhum contexto, porque transmite autoridade. Mantenha uma pessoa envolvida na revisão do repositório de memórias.
• Experimente CLAUDE.md primeiro. Para a maioria dos projetos, um arquivo de contexto escrito manualmente e ferramentas com escopo definido superam uma camada completa de memória em custo, confiança e manutenção — recorra à persistência apenas quando seu trabalho for realmente longo e exploratório.