Segunda-feira de manhã. Você abre o Claude Code num bug complexo que tinha deixado pela metade na sexta. O Claude não lembra de nada. Você explica o contexto de novo, descreve a arquitetura de novo, lista de novo tudo o que já foi tentado. Quinze minutos perdidos antes de conseguir voltar ao ponto em que estava.

É exatamente esse o problema que a memória de sessão resolve — e foi isso que o OpenClaw resolveu primeiro.

O que é o OpenClaw?

O OpenClaw é um framework open source feito para o Claude Code. O objetivo dele: transformar o Claude de um assistente sem memória num agente autônomo persistente, capaz de lembrar o que fez, o que foi decidido e o que ainda falta fazer.

O OpenClaw funciona inteiramente em Markdown e Python, sem banco de dados, sem dependência externa. A filosofia dele: arquivos planos, versionáveis e legíveis por um humano são a melhor memória de longo prazo.

A arquitetura de memória dele se apoia em três níveis: - Memória imediata — o contexto carregado na sessão atual - Logs diários — o que aconteceu hoje (e ontem) - Memória de longo prazo — os fatos duráveis, condensados e mantidos atualizados

Adaptei essa arquitetura para os meus projetos no Claude Code: um Stop hook que roda automaticamente depois de cada troca, dois arquivos Markdown por projeto (long_memory.md + um log por dia) e duas skills para carregar e consolidar a memória. Veja como funciona e como montar.

Por que isso é um ganho real em relação ao Claude padrão

O Claude Code tem sim uma memória automática nativa — mas ela tem duas limitações importantes:

O CLAUDE.md é outra solução, mas é um arquivo de regras estáticas — não um diário de atividade. Ele não registra o que foi feito, os problemas encontrados nem as decisões tomadas ao longo da sessão.

A memória de sessão preenche essa lacuna: ela captura automaticamente, a cada troca, o que aconteceu. Sem que você precise pensar nisso.

Arquitetura

O sistema se apoia em dois tipos de arquivo Markdown, um hook Stop e um modelo Haiku que faz a extração.

Estrutura dos arquivos

projeto/
  memory_sessions/
    long_memory.md          ← memória de longo prazo (condensado permanente)
    logs/
      2026-03-22.md         ← log diário estruturado por seções
      2026-03-21.md
      archives/             ← logs com mais de 30 dias
      .debug/               ← JSON bruto do Haiku (no gitignore)

Num workspace com vários projetos, cada subprojeto tem o seu próprio diretório memory_sessions/ — a memória do cmms_doc não se mistura com a do competitors.

Template 1 — O log diário (logs/2026-03-22.md)

Um arquivo por dia, estruturado em seções fixas. O Haiku adiciona bullets nele a cada troca — sem nunca duplicar o que já existe.

# Log de sessão — 2026-03-22

## Contexto
- Reformulação do sistema de memória de sessão para o workspace PRODUCT_AGENTS.

## Objetivo
- Testar o novo formato JSON estruturado retornado pelo Haiku.

## Problemas encontrados
- A extração do transcript falhava: mensagens tool_result filtradas de forma incorreta.

## Conhecimentos adquiridos
- O transcript JSONL contém muitas mensagens de conteúdo vazio (tool_use, thinking) — filtrar por `content[].type == "text"`.

## Trabalho produzido
- Reescrita do parser de transcript no memory-session.sh.
- Adição do diretório .debug/ para inspecionar o JSON bruto do Haiku.

## Decisões tomadas
- Chamar o `claude` a partir de `/tmp` para evitar que o CLAUDE.md do projeto interfira.

## A acompanhar
- Validar que a descoberta das skills funciona depois do patch.

## Finalizado
- ✅ Validar que a descoberta das skills funciona depois do patch.

Cada seção tem um papel específico. A seção Finalizado recebe os pontos resolvidos de "A acompanhar" — disparados quando você envia OK-done ao Claude.

Template 2 — A memória de longo prazo (long_memory.md)

Um condensado permanente, limitado a 300 linhas. Não é um log — é o que o Haiku julga durável: fatos técnicos, regras de negócio, decisões estruturantes.

# Memória de longo prazo — cmms_doc

## 2026-03-09
- O hook memory-session.sh precisa chamar o `claude` a partir de /tmp (não do projeto) para evitar a injeção do CLAUDE.md hospedeiro na resposta do Haiku.
- Formato intermediário escolhido: JSON estruturado por seções → o Python formata o Markdown.
- Deduplicação feita pelo Haiku, que relê o log existente antes de escrever.

Quando o long_memory.md passa de 300 linhas, a skill /memory_promotion consolida e arquiva as entradas mais antigas.

O mecanismo: o log diário alimenta a memória de longo prazo

Troca com o Claude
    ↓
Haiku analisa: o que reter no log do dia?
    ↓
Log diário atualizado (seções em append, deduplicação)
    ↓
Se um fato durável for detectado → long_memory.md atualizado
    ↓
/memory_promotion (semanal/mensal) → arquiva os logs antigos,
    consolida o long_memory.md se passar de 300 linhas

O fluxo do hook (versão simplificada)

O gatilho central é um Stop hook — um script Shell que o Claude Code executa automaticamente ao final de cada turno de conversa.

Claude responde
    ↓
Stop hook disparado (settings.json)
    ↓
[Anti-loop] stop_hook_active = true? → exit 0
    ↓
Fazer o parse do transcript JSONL → extrair a última troca humano + assistente
    ↓
Ler os logs existentes do dia (para não duplicar)
    ↓
Chamar o Haiku a partir de /tmp com o prompt estruturado
    ↓
Haiku retorna um JSON por seções (objetivo, problemas, trabalho…)
    ↓
Python funde tudo no log Markdown do dia
    ↓
exit 0

O anti-loop merece uma explicação: quando o hook chama o claude, essa invocação termina e dispara o Stop hook de novo. Aí o Claude Code injeta stop_hook_active: true no JSON de stdin. O hook detecta essa flag primeiro e sai na hora, sem processamento.

Por que chamar o claude a partir de /tmp? Se o hook roda a partir do diretório do projeto, o CLAUDE.md do projeto é injetado no contexto do Haiku. Resultado: o Haiku segue as suas regras de negócio em vez de retornar JSON puro. Chamar a partir de /tmp neutraliza esse efeito.

Como montar o sistema

1. As skills de memória

Duas skills completam o hook:

• /memory_load [projeto] — para chamar no início da sessão. Lê o long_memory.md + os logs do dia e da véspera. Mostra um resumo consolidado. Esse carregamento é manual — a memória é gravada automaticamente, mas não se recarrega sozinha.
• /memory_promotion [projeto] — consolida os logs recentes para o long_memory.md e arquiva os logs com mais de 30 dias. Rode manualmente, uma vez por semana ou por mês, conforme a sua atividade.

As skills são arquivos Markdown em .claude/skills/{nome}/SKILL.md. O Claude Code as reconhece como comandos /nome.

2. Conectar o hook Stop

O hook Stop é declarado em .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-session.sh" }
        ]
      }
    ]
  }
}

Quando o Stop hook dispara? O Claude Code dispara o Stop ao final de cada turno — ou seja, depois de cada resposta completa do Claude, seja ela simples (uma frase) ou complexa (com chamadas de ferramentas). Isso é diferente do fim de sessão: o hook roda depois de cada troca, não só quando você fecha o Claude Code.

3. Ajustar a lista de projetos

No hook, uma variável PROJECT_PATHS lista os diretórios de memória de cada subprojeto:

PROJECT_PATHS = {
    "root": "memory_sessions",
    "cmms_doc": "projects/cmms_doc/memory_sessions",
    "competitors": "projects/competitors/memory_sessions",
}

O Haiku analisa a troca e determina quais projetos estão envolvidos — depois escreve nos arquivos certos.

4. Custo

O Haiku 4.5 foi escolhido de propósito: rápido (~1-2 segundos) e econômico. Com um uso intenso de 20 trocas por dia, o custo fica abaixo de US$ 1 por mês. É desprezível para o que ele entrega.

O que isso muda na prática

Com esse sistema montado:

• Retomada depois do fim de semana: /memory_load no início da sessão → o Claude sabe o estado do bug, as decisões tomadas, o que ainda faltava fazer.
• Vários projetos: cada subprojeto tem a sua própria memória. Trabalhar no cmms_doc e depois no competitors na mesma sessão → os logs ficam separados.
• Rastreabilidade: o histórico das decisões técnicas fica no repositório. git log memory_sessions/ conta a evolução do projeto.
• Portabilidade: clone o repositório em outra máquina e a memória está lá.

Limitação principal

O /memory_load é manual. A memória é capturada automaticamente no fim do turno, mas não se recarrega sozinha no início de uma nova sessão. Você precisa lembrar de rodar o /memory_load no começo da sessão para aproveitá-la.

É uma escolha deliberada — forçar o carregamento automático correria o risco de poluir o contexto de sessões curtas ou sem relação com o projeto.

Anexos

A especificação técnica completa (código completo do hook, formato JSON, escolhas de implementação, bugs conhecidos) está disponível em anexo:

→ spec_session_memory.md

Exemplo concreto — log diário real: o arquivo abaixo é o log de sessão gerado automaticamente no dia em que este artigo foi escrito. Ele mostra o que o sistema captura de fato a cada troca: contexto, trabalho produzido, decisões tomadas, pontos a acompanhar.

→ session-log-exemple.md

Para saber mais

Do arquivo único ao sistema de contextos: por que a memória de um LLM não cabe em um só documento Um arquivo, algumas diretrizes, e o Claude faz o resto — como estruturei 500 e-mails sem esforço