Memória Permanente no Claude Code: o Hook que Resolve o Esquecimento

Se você usa o Claude Code no dia a dia, já passou por isso. E a resposta que todo mundo dá — "usa o CLAUDE.md" — resolve pela metade, por um motivo que quase ninguém explica.

Neste artigo eu mostro por que o CLAUDE.md falha justamente quando você mais precisa, e o hook de 40 linhas que faz o Claude carregar tudo sozinho, antes da sua primeira palavra, venha a sessão de onde vier. O código está pronto para copiar.

Por que o CLAUDE.md não é suficiente

O CLAUDE.md é o arquivo de contexto do projeto. Você escreve nele o que o Claude precisa saber e ele carrega no começo da sessão. Funciona — quando o terminal abre na pasta certa.

E é aí que mora o problema. Ninguém abre o terminal na pasta certa toda vez. Você abre onde parou ontem, ou clica num atalho, ou o editor abre por você numa subpasta. O arquivo existe, está bem escrito, e simplesmente não carrega.

Cansado de decidir campanha no achismo? As 10 ferramentas da Central Ads — calculadoras, diagnósticos e simuladores — fazem a conta por você.

O dia que eu perdi por causa de um ponto

Descobri isso do jeito mais caro possível. Passei um dia inteiro construindo um sistema de agendamento de posts para o Instagram: fila de aprovação, publicador via API, guia de credenciais, exportação de arquivos.

No fim do dia descobri que eu já tinha esse app pronto. Funcionando, no ar, conectado havia semanas.

O Claude não sabia que existia porque a sessão tinha aberto em Documents/.claude — com um ponto na frente — em vez de Documents/claude. Duas pastas, duas memórias. A que ele leu tinha 9 notas; a real tinha 42.

E o pior nem foi o app. Quando fui olhar a memória certa, todos os erros daquele dia já estavam documentados lá dentro: a regra de usar o app próprio, o checklist de automação, até o detalhe de que o sistema já normaliza acentos. Um dia inteiro redescobrindo, na marra, o que já estava escrito.

A solução: um hook que roda sempre

O Claude Code tem um evento chamado SessionStart. Ele dispara quando a sessão começa, antes da sua primeira mensagem — e, ao contrário do CLAUDE.md, não depende do diretório.

Um script conectado nesse evento lê os arquivos que você quiser e injeta o conteúdo direto no contexto. O resultado é este, abrindo de qualquer pasta:

Você não digita nada. Não escolhe pasta. Não confere.

O código do hook

Salve como ~/.claude/hooks/contexto.py. A única coisa que você precisa mexer é o bloco CONFIGURE AQUI, apontando para os seus arquivos.

# -*- coding: utf-8 -*-
import io, json, os, sys

# O stdout do Windows e cp1252 e quebra em emoji. Sem isto o hook
# morre calado e a sessao comeca sem contexto.
try:
    sys.stdout.reconfigure(encoding="utf-8")
except Exception:
    pass

# ===================== CONFIGURE AQUI =====================
BASE    = os.path.expanduser("~/meu-projeto")
MEMORIA = os.path.expanduser("~/meu-projeto/memoria")

# (rotulo, caminho, limite de caracteres)
FONTES = [
    ("COMO TRABALHAR",       os.path.join(BASE, "PRINCIPIOS.md"), 6000),
    ("INDICE DO QUE EU SEI", os.path.join(MEMORIA, "INDICE.md"),  8000),
    ("CONTEXTO DO PROJETO",  os.path.join(BASE, "CONTEXTO.md"),   9000),
]
# ==========================================================

def ler(caminho, limite):
    try:
        with io.open(caminho, encoding="utf-8") as f:
            txt = f.read().strip()
    except Exception:
        return None
    if len(txt) > limite:
        txt = txt[:limite] + "\n\n[...truncado]"
    return txt

def main():
    partes, faltando = [], []
    for rotulo, caminho, limite in FONTES:
        txt = ler(caminho, limite)
        if txt is None:
            faltando.append(os.path.basename(caminho))
            continue
        partes.append("=" * 70 + "\n" + rotulo + "\n" + "=" * 70 + "\n\n" + txt)

    if not partes:
        sys.exit(0)   # nada a injetar: sai limpo, sem quebrar a sessao

    contexto = ("CONTEXTO CARREGADO AUTOMATICAMENTE - leia antes de "
                "responder ou construir qualquer coisa.\n\n" + "\n\n".join(partes))

    aviso = "OK Contexto carregado (%d de %d fontes)." % (len(partes), len(FONTES))
    if faltando:
        aviso += "  Nao encontrei: " + ", ".join(faltando)

    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "SessionStart",
            "additionalContext": contexto,
        },
        "systemMessage": aviso,
        "suppressOutput": True,
    }, ensure_ascii=False))

if __name__ == "__main__":
    main()

Como instalar em 3 passos

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"C:\\Users\\SEU_USUARIO\\.claude\\hooks\\contexto.py\"",
            "timeout": 15,
            "statusMessage": "Carregando contexto..."
          }
        ]
      }
    ]
  }
}

No Mac e no Linux, troque o comando por python3 ~/.claude/hooks/contexto.py. Feche o terminal, abra de novo, e a mensagem de contexto carregado deve aparecer.

A outra metade do problema: a escrita

O hook resolve a leitura. Mas as memórias que o Claude cria durante a sessão continuam sendo gravadas na pasta de onde você abriu — ou seja, a armadilha continua de pé, só que ao contrário.

A correção é uma linha no mesmo settings.json:

"autoMemoryDirectory": "C:\\Users\\SEU_USUARIO\\meu-projeto\\memoria"

Com o caminho absoluto, ele lê e escreve sempre no mesmo lugar. O diretório de onde você abre deixa de importar — que era o problema inteiro.

O que colocar em cada arquivo

Perguntas frequentes

Isso não gasta muito contexto? Cerca de 4 mil tokens por sessão. Você gasta mais que isso explicando tudo de novo — e explicando pior, porque esquece metade.

Funciona em projeto grande? Sim, por causa dos limites por arquivo. Um índice enxuto apontando para notas completas funciona melhor do que despejar tudo de uma vez.

E se um arquivo não existir? O hook avisa quais faltaram e carrega o resto. Ele nunca quebra a abertura da sessão.

Preciso digitar algum comando? Não. É exatamente esse o ponto: se você precisasse lembrar de digitar, o problema continuaria de pé.

Serve para outros assistentes de código? O evento SessionStart é específico do Claude Code. A ideia — carregar contexto por gancho em vez de depender do diretório — vale para qualquer ferramenta que tenha eventos de ciclo de vida.

O que muda no dia a dia

Depois de instalado, a diferença aparece no primeiro pedido. Em vez de explicar o projeto antes de qualquer coisa, você já começa pedindo o que precisa — e ele responde sabendo o que existe, o que já foi decidido e o que deu errado antes.

No meu caso, o teste real foi abrir de propósito na pasta errada, a mesma que tinha me custado um dia. As 42 memórias carregaram do mesmo jeito.