TL;DR: Claude Code tem três camadas de memória. A maioria dos devs usa só uma. Li o artigo do Artem Zhutov que explica as três, mas ao invés de implementar tudo do zero, descobri que já tinha 90% do sistema montado. Só faltava conectar as peças. Aqui está exatamente o que eu fiz.
Eu estava no meio de uma sessão de code review quando o Claude me perguntou pela terceira vez na semana se eu preferia testify/mock ou uber-go/mock.
Eu já tinha corrigido isso. Duas vezes. Em sessões diferentes.
O problema não era o Claude. Era eu, tratando ele como uma ferramenta que reseta toda vez, em vez de um colaborador que aprende. Então fui entender melhor como funciona a memória do Claude Code. E aí encontrei o artigo do Artem, que documentou algo que a maioria dos devs não sabe que existe.
As três camadas de memória
Camada 1: CLAUDE.md
Você escreve, você mantém. Regras fixas, contexto do projeto, stack, pessoas-chave. O problema: cresce rápido, fica defasado mais rápido ainda. O meu tinha chegado em 180 linhas. O Claude claramente não estava lendo por completo.
Camada 2: Auto-memory
O Claude escreve suas próprias preferências. Você corrige uma vez, ele salva em ~/.claude/memory/ e carrega nas sessões seguintes. Cada arquivo captura um padrão ou preferência específica.
Para ativar:
claude # abre o Claude Code
/memory # abre o menu de configurações de memória
# -> toggle "Auto-memory" ON
Camada 3: Auto-dream
Roda em background a cada 24h. Lê os transcripts de conversa locais, consolida memórias, remove as defasadas, converte datas relativas em absolutas. É um VACUUM no banco de dados do seu agente. Você ativa e esquece.
Para ativar: mesmo menu /memory, toggle "Auto-dream" ON.
O auto-dream não exige configuração. Roda à meia-noite, limpa o que ficou defasado, e na manhã seguinte o contexto está mais preciso.
O que o auto-dream faz na prática
Aqui está o que acontece quando o auto-dream roda.
Ele lê os arquivos de memória do projeto em ~/.claude/projects/<projeto>/memory/ e faz quatro coisas:
- Mescla entradas redundantes: se você corrigiu o mesmo comportamento duas vezes em sessões diferentes, o auto-dream consolida as duas notas em uma.
- Remove contexto defasado: se você finalizou uma migração, a memória "migração em andamento" some. O Claude para de mencionar algo que já não existe.
- Converte datas relativas em absolutas: "ontem decidimos X" vira "2026-04-05: decidimos X". Fundamental para que as memórias façam sentido depois de semanas.
- Reorganiza para facilitar a busca: entradas soltas viram arquivos organizados por tema.
O efeito prático: cada sessão começa com um contexto mais limpo. Sem aquele ruído acumulado de decisões antigas que já foram revertidas, ou de contexto de projeto que mudou há duas semanas.
Um exemplo concreto: imagine que você está migrando o hash de senhas de MD5 para bcrypt. Durante três sessões, o Claude carrega o contexto "migration in progress: replace MD5 with bcrypt across user service". Na quarta sessão, você finaliza e faz o merge. O auto-dream lê que a tarefa foi concluída e substitui a memória por "bcrypt migration completed 2026-04-03, MD5 fully removed from user service". Na quinta sessão, o Claude já sabe que a migração terminou, sem você precisar mencionar.
Gotcha: O auto-dream tem dois gatilhos: tempo suficiente passado e sessões suficientes acumuladas. Ele não roda depois de uma única sessão longa, nem depois de dez sessões rápidas em duas horas. Se você quiser disparar manualmente, use o comando
/dreamno Claude Code.
O que eu já tinha e não sabia
Aqui está a parte que o artigo do Artem não cobre, porque é específica da minha configuração.
Eu já tinha um diretório ~/.claude/rules/common/ com 11 arquivos organizados por tema:
~/.claude/rules/common/
├── coding-style.md <- imutabilidade, organização de arquivos
├── testing.md <- TDD, cobertura, tipos de teste
├── git-workflow.md <- formato de commit, processo de PR
├── security.md <- checklist de segurança
├── performance.md <- seleção de modelo, contexto
├── patterns.md <- Repository Pattern, API response format
├── agents.md <- orquestração de agentes
├── hooks.md <- tipos de hook, boas práticas de auto-accept
├── open-pr.md <- checklist de PR, sempre draft
├── development-workflow.md
└── always-works.md <- TDD + coverage gate + verificação
Esses arquivos já eram minha Camada 1, só que melhor organizada que um CLAUDE.md monolítico. Cada sessão carregava o contexto relevante com alta coesão e baixo acoplamento.
O que estava faltando: uma forma de alimentar esses arquivos com o que acontecia nas sessões, sem fazer isso manualmente.
A solução: o /retro simplificado
O Artem propõe um skill de retrospectiva que cria arquivos novos de memória a cada sessão. O que eu fiz foi diferente: adaptei o /retro para classificar o que aprendeu na sessão e decidir onde salva. Memória de projeto ou regras globais que já existem.
O skill em ~/.claude/skills/retro/SKILL.md (estrutura simplificada):
# Session Retrospective
Reviews the session and does two things:
1. Proposes memory updates (corrections, preferences, decisions)
2. Exports a session summary to the Obsidian vault
## Step 1: Extract signals
Categorize findings:
- Corrections: what the user corrected and what they wanted instead
- Confirmed patterns: what worked on the first try
- Redos: what had to be redone and why
- New decisions: architecture or workflow choices
## Step 2: Classify scope
For each signal, decide where to save:
Project memory: specific to this codebase
-> ~/.claude/projects/<project>/memory/
Global rule: applies to ALL projects
-> append to ~/.claude/rules/common/<relevant-file>.md
-> never create a new file. Only update existing ones.
## Step 3: Present and wait for approval
Show findings table and wait for approval before writing.
| # | Type | Finding | Proposed action | Scope |
|---|------------|-------------------------------------------|-----------------|----------------------|
| 1 | correction | Used testify/mock instead of uber-go/mock | Update rule | global: testing.md |
| 2 | decision | Chose Redis Streams for queues | Create memory | project: minha-api |
| 3 | confirmed | Commit format was correct | No action | - |
## Step 4: Export session to vault
Writes to:
~/Documents/rflpazini/sessions/YYYY-MM-DD-<project>-<topic>.md
O ponto central: ao invés de criar uma nova camada de arquivos, o /retro alimenta o knowledge base que já existe. Correções de comportamento global vão para testing.md, coding-style.md ou git-workflow.md, dependendo do assunto. Decisões específicas vão para a memória do projeto.
A observabilidade pelo Obsidian
Aqui entra o obsidian-mind: um projeto open-source que transforma seu vault Obsidian num segundo cérebro para o Claude Code, com CLAUDE.md configurado, hooks, slash commands e uma estrutura pensada para capturar contexto de trabalho.
Ao setup padrão eu adicionei três coisas:
1. Pasta sessions/ para histórico cross-project
Cada sessão vira um arquivo com: objetivo, o que foi feito, decisões, aprendizados, próximos passos. O /retro escreve isso automaticamente. Exemplo de como fica:
---
title: "Session: minha-api - kafka-consumer"
date: 2026-04-05
tags: [session, minha-api]
project: "[[minha-api]]"
---
## Goal
Implementar o consumer Kafka async com DLQ imediato, sem retry.
## What Got Done
- Consumer async configurado com ack-mode RECORD
- DLQ publishing manual implementado no error handler
- Testes de integração passando
## Decisions Made
- AbortPolicy + DLQ imediato: CallerRunsPolicy bloqueava o poll thread do Kafka
- ack-mode RECORD, não BATCH: BATCH commita offsets antes das tasks completarem
## Learnings
- Container-level error handler e DLQ manual ativos ao mesmo tempo causam duplicação
- Testar com consumer group real antes de fazer PR
## Next Steps
- [ ] Revisar configuração de timeout do executor
- [ ] Abrir PR após code review
2. Symlink das memórias de projeto no vault
#!/bin/bash
# ~/.claude/scripts/sync-memories-to-vault.sh
# Cria symlinks de ~/.claude/projects/*/memory/ para o vault Obsidian
# Roda automaticamente após o /retro
VAULT_MEMORY_DIR="$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/rflpazini/claude/memories"
CLAUDE_PROJECTS="$HOME/.claude/projects"
mkdir -p "$VAULT_MEMORY_DIR"
clean_name() {
local raw="$1"
case "$raw" in
*-minha-api*) echo "minha-api" ;;
*-outro-projeto*) echo "outro-projeto" ;;
*-obsidian-mind*) echo "obsidian-mind" ;;
*)
echo "$raw" \
| sed 's/^-Users-seuusuario-//' \
| sed 's/^Documents-Development-//' \
| tr '[:upper:]' '[:lower:]' \
| sed 's/^-//'
;;
esac
}
created=0
skipped=0
for memory_dir in "$CLAUDE_PROJECTS"/*/memory; do
[ -d "$memory_dir" ] || continue
project_dir=$(dirname "$memory_dir" | xargs basename)
name=$(clean_name "$project_dir")
link_path="$VAULT_MEMORY_DIR/$name"
if [ -L "$link_path" ] || [ -d "$link_path" ]; then
skipped=$((skipped + 1))
else
ln -s "$memory_dir" "$link_path"
created=$((created + 1))
fi
done
echo "done. created=$created skipped=$skipped"
Cada memória de projeto aparece como arquivo navegável no Obsidian. Você vê, edita ou apaga direto pelo painel lateral, sem precisar abrir o terminal.
3. Base view Sessions.base
Uma view Obsidian que lista todas as sessões por projeto, ordenadas por data. Quando começo uma sessão nova, abro essa view e vejo em 10 segundos o contexto da última vez que trabalhei naquele projeto.
O que não implementei (e por quê)
O artigo do Artem sugere mais coisas: QMD para busca semântica, dashboards por área de vida, session auto-export hooks, LLM Wiki.
Não implementei nenhuma. O vault tinha 50 arquivos no momento. QMD resolve um problema de busca que ainda não existe. Dashboards adicionam fricção de manutenção antes de gerar valor.
A regra que usei: cada adição foi avaliada pela fricção que criava, não pelo potencial teórico. Se não resolvia um problema que eu tinha hoje, ficou de fora.
Gotcha: Auto-memory é estritamente scoped por projeto. Não existe auto-memory global. Preferências que devem valer em todos os projetos precisam ir para
~/.claude/rules/common/, via/retroou manualmente. O artigo original não deixa isso claro.
Como fica o loop na prática
Segunda-feira de manhã. Abro o terminal, claude, começo a trabalhar.
O hook SessionStart injeta automaticamente: data de hoje, objetivos atuais, projetos ativos, listagem de arquivos do vault. Não preciso explicar contexto nenhum.
Trabalho a sessão. No final: /retro.
O Claude monta a tabela de achados com escopo sugerido e aguarda minha aprovação. Aprovo: ele faz append em testing.md para a regra de mock, cria arquivo em ~/.claude/projects/minha-api/memory/ para o contexto específico, e escreve o resumo em rflpazini/sessions/.
Encerro o terminal. De noite, o auto-dream consolida, remove o que ficou defasado.
Na manhã seguinte, o Claude começa sabendo exatamente onde paramos.
E esse é o resultado no Obsidian:
Como começar
Mínimo viável (30 minutos):
- Instale o obsidian-mind ou abra o Claude Code dentro do seu vault Obsidian existente
- Ative auto-memory:
claude->/memory-> toggle ON - Ative auto-dream: mesmo menu -> toggle ON
- Execute
/retroao final das próximas 3 sessões
Para o setup completo:
- Organize seu CLAUDE.md em arquivos separados por tema em
~/.claude/rules/common/ - Crie o skill
/retrocom a estrutura acima - Crie a pasta
sessions/no vault para histórico cross-project - Configure o script
sync-memories-to-vault.shpara visibilidade das memórias no Obsidian
O Claude não vai parar de errar do dia para a noite. Mas cada correção que você faz uma vez não vai precisar ser repetida. Esse é o investimento: tempo decrescente de alinhamento, qualidade crescente de colaboração.
Três semanas depois de configurar isso, as sessões começam sem aqueles 15 minutos de "deixa eu te explicar o contexto". O Claude chega sabendo.
Crédito ao Artem Zhutov pela documentação das três camadas. O que eu fiz foi simplificar a implementação aproveitando o que já existia.
e também ao Brenno Ferrari pelo obsidian-mind
Testa, roda o /retro nas próximas sessões, e me conta o que apareceu na tabela de achados.
Nos próximos dias, vou publicar as skills que utilizo no github :)
Top comments (0)