Porque é que o Claude Code se esquece entre sessões e como o nosso se lembra

O Claude Code esquece o contexto entre sessões porque cada sessão começa com uma janela de contexto vazia. Dentro de uma sessão, uma janela cheia é compactada: os turnos mais antigos passam a resumo. Entre sessões, nada passa para a seguinte além do que ficou escrito.

A memória entre sessões é uma rotina que leva um agente de programação com IA a consultar decisões anteriores antes de trabalhar e a guardar as novas depois, para que uma janela de contexto nova comece informada. Usamo-la como um ciclo no Claude Code, imposto por um hook Stop (um script que o Claude Code executa sempre que termina uma resposta). O OpenCode e o Kimi Code partilham as mesmas regras e o mesmo repositório de memória.

Dentro de uma sessão, os turnos mais antigos são compactados; entre sessões, a nova janela começa vazia e só as notas guardadas passam para o outro lado.

Porque é que o Claude Code se esquece e o que faz o nosso ciclo de memória

O Claude Code não se esquece por acidente. Cada sessão começa vazia de propósito, por isso a solução é uma rotina, não um ficheiro maior.

Documentação da Anthropic(abre num novo separador), 2026: «Cada sessão do Claude Code começa com uma janela de contexto nova.» Duas funcionalidades nativas dão ao Claude Code memória entre sessões:

O contexto é algo que o agente pondera, não um passo que tenha de dar. Por isso acrescentámos um ciclo por cima, com um repositório de memória partilhado a que o agente chega por MCP:

O repositório de memória é o cérebro da nossa empresa; a forma como as notas são organizadas é a camada 1 do nosso sistema que se melhora a si próprio.

A versão para copiar (hook, entrada nas definições e teste) está em Construa o seu próprio ciclo.

Porque o criámos: uma regra escrita acaba ignorada

Escrevemos a regra e o agente ignorou-a. Uma regra que depende de o agente se lembrar de a cumprir é uma sugestão.

A regra estava no ficheiro de instruções: consultar antes de explorar, guardar depois. As sessões saltavam a consulta e voltavam a ler código que uma sessão anterior já tinha mapeado. As sessões editavam ficheiros e terminavam sem nada escrito, e a seguinte voltava a descobrir a mesma resposta.

A memória existia e as ferramentas funcionavam. Faltava um momento em que saltar o passo tivesse um custo. Uma pessoa aprova o trabalho que importa (o nosso modelo de governação), mas ninguém acompanha o fim de cada sessão.

Veja como o ConvOps dá a cada agente uma memória única que ele consulta antes de trabalhar(abre num novo separador), e guarda as notas que cada sessão deixa.

Como funciona o ciclo de memória

Consultar custa uma chamada. Guardar custa uma chamada. A única parte cara é garantir que ambas acontecem sempre, e foi essa a tarefa que demos ao hook.

Em cada paragem verificada, edições sem nada guardado mandam o agente de volta para guardar; caso contrário, a sessão termina.

Como decide um hook Stop. Lê a transcrição (o ficheiro onde o Claude Code regista cada mensagem e cada chamada a ferramentas) e termina com um código de saída, um número que diz ao Claude Code o que fazer a seguir. O código 0 deixa a sessão terminar. O código 2 «impede o Claude de parar e continua a conversa» (Anthropic, hooks(abre num novo separador), 2026), e o agente lê a mensagem do hook. A nossa proteção contra eliminações usa o mesmo código de saída nas chamadas a ferramentas.

O que verifica o hook Stop de memória

Cada limiar aqui é o que o nosso hook usa.

Cada regra violada acrescenta uma mensagem, o bloqueio termina com This is mandatory. e o hook sai com o código 2.

O que o hook não vê

Confiamos mais no hook porque sabemos exatamente onde é cego.

• Conta as chamadas a ferramentas pelo nome. Nunca lê o que uma consulta devolveu nem se um registo tinha qualidade.
• Só memory_store conta como registo. Uma sessão que escreve apenas notas context= e edita ficheiros continua a ser mandada de volta.
• As edições pela shell não são vistas. Um sed ou um heredoc não é uma edição para o hook; só as quatro ferramentas de edição nativas o são.
• A transcrição pode chegar atrasada. A documentação de hooks(abre num novo separador) da Anthropic diz que é escrita de forma assíncrona, por isso um registo de última hora é contado na verificação seguinte.
• Só corre no Claude Code; veja as secções do OpenCode e do Kimi Code.

Os hooks guardam as regras que nunca podem depender da memória (a camada de hooks). Este obriga às chamadas, não à memória.

Como o Claude Code se lembra entre sessões

O momento útil não é o registo. É a manhã seguinte, quando uma sessão que nunca viu o trabalho de segunda-feira abre com a lição de segunda-feira.

A Copperfern é uma loja online fictícia de artigos para a casa; os nomes, ficheiros e notas são inventados, e os limiares e as mensagens são reais.

Segunda-feira. A Maya, que gere as operações, abre uma tarefa: «As encomendas espanholas ficam com um cêntimo de diferença na finalização da compra.» O agente de programação executa context_query("spanish vat checkout rounding") e não encontra nada sobre arredondamentos. Lê shop/checkout/tax.py, vê que o IVA é arredondado uma única vez sobre o total da encomenda, edita o ficheiro e o respetivo teste para arredondar por linha e tenta parar.

O hook corre: 5 chamadas a ferramentas, entradas novas suficientes desde a última verificação. Houve uma consulta, por isso só dispara a verificação de edições:

KNOWLEDGE CHECK: Modified 2 file(s) but stored nothing. memory_store() the change/decision (supersede if updating). If you explored files, create_route()/update_route() in ConvOps. This is mandatory.

Código 2. O agente guarda uma memória da categoria gotchas, importância 7, etiquetas shop, checkout, vat. A nota diz: «O IVA espanhol arredonda por linha, não pelo total da encomenda; arredondar o total dá um cêntimo de diferença em encomendas com vários artigos.» Regista uma rota: «O arredondamento do IVA está em shop/checkout/tax.py». Volta a tentar parar. stop_hook_active é verdadeiro e a sessão termina.

A sessão de segunda-feira corrige o arredondamento, é mandada de volta uma vez e guarda o porquê antes de terminar.

Terça-feira. Uma nova tarefa: «Acrescentar IVA à linha do embrulho para oferta.» Nova sessão, janela vazia: nada de segunda-feira está lá. O agente executa context_query("vat gift wrap checkout"), e a nota de segunda-feira e a rota aparecem. Abre diretamente shop/checkout/tax.py e arredonda o IVA do embrulho na sua própria linha.

Afinal, os portes de envio também são uma linha à parte. O agente guarda a nota refinada, «O IVA espanhol arredonda por linha; o embrulho para oferta e os portes contam cada um como linha própria.», e depois esquece o registo de segunda-feira com memory_forget, uma eliminação lógica reversível. Na paragem, a consulta veio antes do registo e a edição tem um registo: código 0. Só a nota refinada responde à consulta seguinte.

A sessão de terça-feira nunca viu a de segunda-feira, mas a sua primeira consulta devolve a lição de segunda-feira; guarda a nota refinada e esquece a antiga.

O que o ciclo deixa para trás

Uma memória vale exatamente o que a sessão seguinte consegue usar sem perguntar: um facto, o motivo, um tipo e uma importância honesta.

Um registo de memória, tal como o agente o guarda:

content:    Spanish VAT rounds per line, not per order total; rounding the
            total is off by a cent on multi-item orders.
category:   gotchas
importance: 7
tags:       shop, checkout, vat
task_id:    cf-131

O conteúdo guarda o facto e o motivo. A importância mede quanto perde a sessão seguinte se não vir a nota: a maioria fica entre 4 e 6, e esta é um 7 porque um total errado chega aos clientes. Duas a cinco etiquetas tornam-na fácil de encontrar.

Uma rota diz onde algo está:

title:       VAT rounding
description: VAT rounding lives in shop/checkout/tax.py
paths:       shop/checkout/tax.py, tests/test_tax.py

Uma nota context=, escrita na mesma chamada que uma atualização de tarefa, guardada como uma memória ligada à tarefa (importância 4 por omissão; abaixo de 40 caracteres não é guardada):

Rounded VAT per line, not per order; Spanish totals were a cent off on
multi-item orders.

Nenhum campo substitui um registo. O agente guarda a nota nova e esquece a antiga. Uma pessoa também pode substituir uma nota na página do cérebro, que liga o registo novo ao antigo e retira o antigo das consultas.

O que corre mal num hook de memória

A nossa imposição falhou duas vezes, em sentidos opostos: uma vez deixou passar edições em silêncio, outra vez bloqueou para sempre. Verifique o seu hook para os dois casos.

Deixou passar edições. A única verificação de «não guardou nada» esperava que a sessão ultrapassasse um comprimento mínimo. Uma sessão curta da Copperfern edita o modelo da etiqueta de envio e termina sem problemas, sem nada escrito; a sessão seguinte repete a mesma investigação. A regra que daí resultou: as edições sem registo são assinaladas na verificação seguinte, sem essa espera. O mínimo de 3 chamadas e o intervalo continuam a aplicar-se.

Bloqueou para sempre. A verificação de registo antes da consulta comparava o primeiro registo com a primeira consulta em toda a sessão. Uma sessão guarda uma nota antes da primeira consulta, depois consulta corretamente, e continua a ser mandada de volta em cada paragem até ser abandonada. A regra que daí resultou: cada verificação olha só para o que aconteceu desde a anterior, por isso um deslize inicial é reportado na verificação que o cobre, não em todas as paragens seguintes.

O comentário no nosso código explica porquê: «um alerta que nenhum comportamento posterior consegue satisfazer é um incómodo, não uma proteção.» Essa regra tem agora um teste que corre o hook real com uma transcrição sintética, um registo de sessão falso.

Antes da correção, um registo feito cedo bloqueava todas as paragens seguintes; agora cada verificação olha só para o que aconteceu desde a anterior, por isso o deslize é reportado na sua própria janela.

Estreitámos a regra de consulta. Antes aplicava-se a todas as mensagens. Agora aplica-se antes de explorar ou trabalhar em algo que ainda não se conhece; guardar depois de cada ação continua a ser obrigatório. Uma sessão a quem perguntam «que horas são em Madrid» não faz consulta; uma sessão prestes a ler o código da finalização da compra faz sempre.

Construa o seu próprio ciclo de memória no Claude Code

Comece por uma regra que o hook consiga contar: se uma sessão alterou ficheiros, escreve o quê e porquê antes de terminar.

Primeiro, ligue o repositório de memória. Usamos o ConvOps; um comando acrescenta-o ao Claude Code:

claude mcp add --transport http convops https://mcp.convops.app/

Depois acrescente estas duas linhas ao seu CLAUDE.md. Mantenha esse ficheiro curto (o que cortar num CLAUDE.md demasiado longo): o hook trata da imposição, o ficheiro trata do hábito.

Before exploring or working on anything you don't already know, query the memory store first. Known answers and chat skip the lookup.
After every action, store what you learned and why, with a type, an honest importance and two to five tags. To replace a note, store the new one, then forget the old one.

Esta versão reduzida do nosso hook (Claude Code 2.1.301) mantém a proteção contra ciclos, o mínimo de 3 chamadas, o intervalo, a verificação de edições e a consulta na primeira verificação. Guarde-a como ~/.claude/hooks/memory-gate.py:

"""Stop hook: send the agent back when it edited files and stored nothing."""
import json, os, sys, tempfile

MIN_TOOL_CALLS = 3
INTERVAL = 2
EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")

hook = json.load(sys.stdin)
if hook.get("stop_hook_active"):
    sys.exit(0)  # the retry after a block is not checked
names, entries = [], 0
with open(hook["transcript_path"]) as f:
    for line in f:
        entry = json.loads(line)
        if entry.get("type") != "assistant":
            continue
        entries += 1
        for block in entry.get("message", {}).get("content", []):
            if isinstance(block, dict) and block.get("type") == "tool_use":
                names.append(block["name"])

if len(names) < MIN_TOOL_CALLS:
    sys.exit(0)
counter = os.path.join(tempfile.gettempdir(), f"memory_gate_{hook['session_id']}")
last = int(open(counter).read()) if os.path.exists(counter) else 0
if entries - last < INTERVAL:
    sys.exit(0)
open(counter, "w").write(str(entries))
edits = sum(n in EDIT_TOOLS for n in names)
stores = sum("memory_store" in n for n in names)
lookups = sum("context_query" in n or "route_query" in n for n in names)
problems = []
if edits and not stores:
    problems.append(f"Modified {edits} file(s) but stored nothing. Store the change and why.")
if last == 0 and not lookups:
    problems.append("No lookup at the first check. Query the memory store first.")
if problems:
    print("KNOWLEDGE CHECK: " + " | ".join(problems) + " This is mandatory.", file=sys.stderr)
    sys.exit(2)

Registe-o em Stop no .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "python3 ~/.claude/hooks/memory-gate.py", "timeout": 15 }
        ]
      }
    ]
  }
}

Teste-o com uma transcrição sintética antes de confiar nele. Esta tem uma consulta e duas edições, por isso o resultado esperado é o código 2:

printf '%s\n' \
  '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"context_query"}]}}' \
  '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit"}]}}' \
  '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit"}]}}' \
  > copperfern-test.jsonl
echo '{"session_id":"test-001","transcript_path":"copperfern-test.jsonl"}' \
  | python3 ~/.claude/hooks/memory-gate.py; echo "exit $?"

Use um session_id novo em cada execução, porque o ficheiro contador guarda a última verificação. Depois acrescente uma linha memory_store e o resultado esperado passa a ser o código 0.

Memória do OpenCode entre sessões

As sessões do OpenCode 1.18.31 também começam vazias. Damos-lhes o mesmo texto e o mesmo repositório de memória.

Os nossos ficheiros AGENTS.md são symlinks para o CLAUDE.md, por isso o OpenCode lê as mesmas regras de consulta e de registo (um ficheiro para os dois). O nosso opencode.json aponta o bloco mcp para o mesmo repositório de memória do ConvOps, por isso uma nota guardada a partir do Claude Code aparece numa consulta do OpenCode. Não usamos nenhum hook de memória no OpenCode. Os plugins do OpenCode(abre num novo separador) permitem criar um, e a nossa proteção contra eliminações mostra o formato.

Memória do Kimi Code entre sessões

O Kimi Code 0.31.1 recebe o mesmo texto e o mesmo repositório de memória. Lê o AGENTS.md que é um symlink para o CLAUDE.md, e o nosso .kimi-code/mcp.json lista o mesmo servidor ConvOps, por isso as suas consultas devolvem o que o Claude Code e o OpenCode guardaram. Não usamos nenhum hook de memória no Kimi Code. Aceita entradas [[hooks]] na configuração do utilizador (hooks do Kimi Code(abre num novo separador)), e o guia da proteção contra eliminações mostra uma.

Crie uma conta gratuita no ConvOps e ligue o Claude Code, o OpenCode ou o Kimi Code a uma memória única(abre num novo separador) e, depois, acrescente a regra de consulta, a regra de registo e o hook Stop.