Source: https://aiprimetech.io/pt/blog/claude-code-persistent-memory-across-sessions/ Jul 11, 2026 · 6 min · Engenharia # Memória persistente para Claude Code: como o contexto entre sessões realmente funciona A Por [AI Prime Tech](https://aiprimetech.io/pt/) · Com auxílio de IA Você fecha o notebook na sexta-feira depois de uma sessão de três horas em que o Claude Code refatorou seu módulo de autenticação, aprendeu que sua equipe usa um wrapper personalizado de Result em vez de lançar exceções, e finalmente entendeu por que UserService não pode importar de billing/. Na segunda-feira, você abre uma nova sessão e Claude, confiante, envolve uma nova função em um try/catch e importa o módulo proibido. Tudo o que ele aprendeu se perdeu. Este é o problema central de ergonomia das ferramentas de programação agêntica: o modelo não tem memória episódica. Cada sessão começa do zero, acrescida apenas do que você anotou manualmente. Vamos resolver isso com engenharia — com honestidade, incluindo as partes que não funcionam. ## 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: | Hook | Executado quando | Usar para | SessionStart | Uma sessão começa | Injetar memória | SessionEnd | Uma sessão termina | Acionar a captura | PostToolUse | Após qualquer chamada de ferramenta | Transmitir atividade granular | Stop | O agente termina de responder | Criar um ponto de verificaçã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: | Abordagem | Custo de configuração | Tokens recorrentes | Risco de desatualização | Ideal para | CLAUDE.md apenas | Minutos | Baixo, determinístico | Você controla | A maioria dos projetos | Ferramentas MCP com escopo definido | Horas | Apenas sob demanda | Baixo | Estado atual do sistema | Camada completa de memória | Dias | Mais alto, por sessão | Alto | Trabalho longo e exploratório ## 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, 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. [Programação](/pt/blog/tag/coding/)[Claude](/pt/blog/tag/claude/) A [AI Prime Tech](https://aiprimetech.io/pt/) A AI Prime Tech publica este blog. Os artigos são redigidos com assistência de IA; confira detalhes específicos de cada versão, como IDs de modelos, preços e limites, na documentação oficial antes de se basear neles. Obtenha acesso mais barato à API do Claude Uma única chave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, além de GPT-6 modelos. Pague conforme o uso, sem assinatura. [Obtenha Sua Chave de API →](/register) A AI Prime Tech é um gateway de API independente de terceiros. Claude™ e Anthropic® são marcas comerciais da Anthropic, PBC. Não há afiliação nem endosso implícitos.