Como organizo o MEMORY.md do Claude Code — estrutura real, com exemplos

Escrevi este post enquanto ele mesmo estava sendo decidido. Perguntei ao Claude Code “o que podemos escrever hoje no blog” e ele foi puxar sugestões no meu backlog de pautas — e uma das que sobrou foi justamente essa: como funciona o sistema de memória que ele estava usando pra ter esse contexto todo em mãos. Achei bom demais pra não registrar no calor da hora.

O problema que isso resolve

Toda sessão de IA tem um limite de contexto. Quando a conversa cresce demais, ela é resumida ou, pior, você fecha o terminal e no dia seguinte tem que reexplicar quem você é, o que já foi decidido, o que já foi tentado. Isso é o maior atrito de usar IA no dia a dia: repetir contexto vira trabalho.

O Claude Code resolve isso com um sistema de memória por projeto, baseado em arquivos markdown de verdade, que sobrevive entre conversas diferentes. Não é context window, não é cache — é um diretório real em disco que ele lê e escreve sozinho.

Onde isso mora

Cada projeto tem sua própria pasta de memória:

~/.claude/projects/<hash-do-projeto>/memory/
├── MEMORY.md              ← índice, sempre carregado
├── user_role.md
├── feedback_testing.md
└── project_algo.md

MEMORY.md é só um índice — uma linha por memória, carregada em todo início de conversa. As memórias de verdade ficam em arquivos separados, e só são lidas quando relevantes pro que está sendo discutido.

Os quatro tipos de memória

Isso é a parte que eu achei mais bem pensada. Não é “salva tudo” — tem uma taxonomia clara, cada tipo com uma função diferente:

• user — quem eu sou, meu papel, minha stack, meu nível de conhecimento. Serve pra calibrar explicação (não me trata como iniciante, não assume que eu sei tudo de frontend se eu só faço backend há dez anos).
• feedback — correções e confirmações que eu já dei. Se eu falei “não mocka o banco nesse teste” uma vez, não quero repetir isso pra sempre. Se eu confirmei que uma decisão estranha foi a certa, ele também guarda isso — pra não regredir pra abordagem “óbvia” da próxima vez.
• project — decisões, contexto e estado de um projeto específico que não dá pra inferir só lendo o código. Prazo, motivação de negócio, quem pediu o quê.
• reference — ponteiro pra onde a informação de verdade mora fora do projeto. Não duplica o dado, só lembra “isso tá no Linear, projeto X” ou “isso tá documentado ali”.

Um exemplo real, sem inventar nada

Peguei dois arquivos de memória reais deste projeto (o pablo-blog) pra mostrar o formato de verdade, sem sanitizar nada porque não tem nada sensível:

---
name: reference-blog-draft-rule
description: Regra de publicação de posts no Vault Obsidian /Blog via frontmatter draft
metadata:
  type: reference
---

No Vault Obsidian, pasta `/Blog`, cada post tem frontmatter com o campo `draft`:
- `draft: false` → post publicado
- `draft: true` → post não publicado (rascunho)

O arquivo `_Índice de Posts.md` deve **sempre** manter `draft: "true"`.

**How to apply:** ao criar, editar ou revisar posts, nunca alterar o `draft`
do `_Índice de Posts.md` para `false`.

Isso é uma memória reference — não repete a lógica do script de sync, só registra a regra de negócio que não tá óbvia lendo o Hugo isoladamente. E uma project:

---
name: project-blog-publish-pipeline
description: Pipeline automatizado Obsidian Vault -> Hugo content/posts -> git push -> Vercel
metadata:
  type: project
---

O blog tem publicação ponta a ponta automatizada a partir do Obsidian: um
LaunchAgent observa `~/Vault/Blog`, converte frontmatter/slug pro formato Hugo,
outro LaunchAgent faz commit + push a cada hora se houver mudança.

**Gotcha:** `~/Vault` fica sob `~/Documents`, protegido por TCC no macOS — se o
sync parar sem erro aparente, checar Full Disk Access do `/bin/bash` primeiro.

**How to apply:** ao investigar por que um post não subiu, checar nessa ordem:
LaunchAgent carregado, logs em `/tmp/`, Full Disk Access, `draft: false` no post.

Isso é o tipo de coisa que eu só quero explicar uma vez. Da próxima vez que eu abrir uma sessão nesse projeto e o sync parecer quebrado, ele já sabe por onde começar a procurar — sem eu precisar recontar a história do TCC do macOS de novo.

O que ele explicitamente NÃO guarda

Isso é tão importante quanto o que guarda. Fica de fora:

• Padrão de código, arquitetura, estrutura de pasta — isso o código já mostra.
• Histórico de git, quem mudou o quê — git log/git blame são a fonte da verdade.
• Solução de bug pontual — o fix já tá no código, o commit já tem o contexto.
• Qualquer coisa que já esteja documentada no CLAUDE.md.

Isso evita a armadilha óbvia: memória virando um segundo repositório desatualizado do que já existe em outro lugar. Memória é pra contexto que não dá pra derivar olhando o estado atual do projeto.

Memória tem data de validade

Cada memória carrega quando foi escrita, e o próprio sistema me lembra: “isso é uma observação de um momento no tempo, não estado ao vivo — confira contra o código atual antes de tratar como fato”. Faz sentido — se uma memória cita uma função ou um arquivo, ela é uma aposta de que aquilo existia quando foi escrita. Pode ter sido renomeado ou removido depois. Antes de agir em cima de uma recomendação vinda de memória, ele confere se ainda é verdade.

Por que isso muda o dia a dia

Eu trabalho em vários projetos diferentes (Viajaflux, Andrinno, projetos do Grupo Fly) e cada um tem seu contexto próprio. Sem isso, cada sessão nova era voltar ao zero: reexplicar que projeto é esse, quais são minhas preferências, o que já tentamos e não funcionou. Com memória por projeto, cada um mantém sua própria história — e eu só preciso corrigir uma vez, não repetir a correção pra sempre.

A diferença pro CLAUDE.md é essa: CLAUDE.md é o que eu escrevo à mão, preferência fixa, regra que eu decido de propósito. Memória é o que o próprio Claude observa e escreve sozinho, conversa após conversa, sem eu precisar manter nada manualmente. Os dois se complementam — um é estático e deliberado, o outro é vivo e cresce com o uso.