MEMORY.md: o caderno de campo que sua IA escreve sozinha

“Não havíamos decidido isso ontem?”

Eu estava migrando meu email para fora do Google. Já tinham sido duas sessões no Claude Code trabalhando nisso: issues no Linear, decisões tomadas, scripts executados. Abro uma terceira sessão e pergunto “o que ainda está pendente do degoogle?”

Silêncio. Amnésia total.

É como trabalhar com um colega brilhante que toda manhã chega ao escritório sem se lembrar de absolutamente nada do que vocês fizeram no dia anterior. Nem as decisões, nem os erros, nem as descobertas. Cada sessão é uma tela em branco.

E acontece que existe um arquivo que resolve exatamente esse problema. Está lá há meses. E quase ninguém o conhece.

CLAUDE.md vs MEMORY.md: o manual e o caderno

Se você usa Claude Code, provavelmente já conhece o CLAUDE.md. É o arquivo onde você diz à IA como trabalhar: que idioma usar, que ferramentas você tem, suas convenções de código.

CLAUDE.md é seu manual de instruções. Você escreve. Você mantém.

MEMORY.md é outra coisa. É um caderno de campo que a IA escreve sozinha. Anota o que aprende enquanto trabalha com você: erros que cometeu, decisões que vocês tomaram, padrões do projeto, coisas que tentou e não funcionaram.

Dito de forma clara:

Se CLAUDE.md é o contrato que você dá ao estagiário no primeiro dia, MEMORY.md são as notas que o estagiário vai anotando em seu caderno enquanto trabalha.

Onde fica

~/.claude/projects/<hash-do-diretorio>/memory/MEMORY.md

Cada diretório de projeto tem seu próprio arquivo de memória. Se você trabalha em ~/code/projeto-a, tem um MEMORY.md. Se abrir Claude Code em ~/code/projeto-b, tem outro diferente. Não se misturam.

O arquivo é carregado automaticamente no contexto no início de cada sessão. Você não precisa fazer nada.

Não existe um MEMORY.md global?

Não. Apenas por projeto. E isso é um problema.

Hoje criei um wrapper de op (o CLI do 1Password) que cacheia segredos durante uma hora. É útil em todos os meus projetos, não só no que eu estava trabalhando. Mas MEMORY.md anotou isso apenas na memória desse diretório.

CLAUDE.md sim tem uma versão global (~/.claude/CLAUDE.md), que é carregada em todas as sessões. MEMORY.md não tem equivalente. Se a IA aprender algo que se aplica a todo seu ambiente (um alias, uma peculiaridade do seu sistema, uma preferência), tem que anotar em cada projeto separadamente. Ou não anota.

Na prática, o que faço é colocar esse tipo de conhecimento transversal no meu CLAUDE.md global manualmente. Não é ideal, mas funciona.

Se deletar o projeto, a memória é deletada?

Não. A memória fica em ~/.claude/projects/, não no seu diretório de código. Se você deletar ~/code/meu-projeto/, o MEMORY.md continua lá, órfão, ocupando espaço e sem ninguém para lê-lo.

Alguém faz limpeza? Que nada. Não há nenhum garbage collector que detecte diretórios de projeto eliminados. Com o tempo, ~/.claude/projects/ acumulará memórias de projetos que não existem mais.

Se você é daqueles que deleta projetos com frequência, de vez em quando convém dar uma olhada:

1

ls ~/.claude/projects/

E deletar os diretórios que você não reconheça mais. Nada de ruim vai acontecer — o pior que pode ocorrer é a IA começar do zero na próxima vez.

Como é a cara dele

Este é um exemplo real. Hoje, depois de uma sessão migrando meu email para fora do Google Workspace, meu MEMORY.md ficou assim:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Memory - f@frr.dev

## Degoogle f@frr.dev — COMPLETADO (2026-02-12)

- Email: migrado para iCloud+ custom domain (plano 200 GB, custo 0€)
- ChatGPT: passkey configurada (iCloud Keychain)
- Linear: passkey web + API token funcionam
- Google Workspace: cancelado após Takeout

## Wrapper op (cache do 1Password CLI)

- Localização: ~/.local/bin/op
- Cacheia `op read` durante 1h, o resto passa direto
- Por quê: Claude Code lança um processo novo para cada comando Bash

## Lições técnicas

- `stat` é GNU neste Mac (coreutils via Homebrew). Usar `stat -c %Y`
- Linear API: `issueCreate` requer UUID do team, não o key

Nada de filosofia. Fatos concretos. Na próxima vez que abrir uma sessão aqui, Claude já sabe que o degoogle está feito, que tenho um wrapper de op, e que stat é GNU no meu Mac.

O problema real que resolve

Não é só “lembrar coisas”. É evitar que a IA repita erros.

Hoje, a primeira vez que escrevi o wrapper de op, usei stat -f %m (sintaxe BSD). Falhou porque meu Mac tem GNU coreutils via Homebrew. Corrigi com stat -c %Y.

Sem MEMORY.md, na próxima vez que precisar de stat neste projeto, tentará stat -f %m de novo. Com MEMORY.md, já sabe que não deve fazer isso.

É a diferença entre um colega que anota as coisas e um que confia na memória. Quem anota não repete erros.

Como evitar que vire uma bagunça

Aqui vem a pergunta óbvia: se a IA escreve o que quer, não vai acabar virando um depósito de notas irrelevantes?

Existem várias salvaguardas:

1. Limite de 200 linhas. Tudo que passar da linha 200 é truncado ao carregar. Isso força a ser conciso.

2. Organização por temas. Podem ser criados arquivos separados (debugging.md, patterns.md) e linkados do MEMORY.md. O arquivo principal é um índice, não um monte de coisa jogada.

3. Você tem a última palavra. É um arquivo de texto no seu disco. Você pode editá-lo, deletá-lo, ou dizer ao Claude “limpe MEMORY.md, isso não é mais relevante”.

4. A IA se autocorrige. As instruções do sistema dizem para ela atualizar ou eliminar memórias que acabem se mostrando erradas ou desatualizadas.

Na prática, funciona surpreendentemente bem. A IA tende a ser mais disciplinada que muitos humanos anotando coisas — provavelmente porque não tem ego nem apego às próprias ideias.

Por que ninguém conhece

Boa pergunta. Está há meses no Claude Code, funciona por padrão, e não me lembro de ter visto destacado em nenhum changelog ou blogpost da Anthropic.

Minha teoria: é uma funcionalidade que nasceu como infraestrutura interna para melhorar a experiência entre sessões, não como um feature voltado ao usuário. Não tem UI, não tem toggle, não tem painel de configuração. É um arquivo de texto em um diretório oculto.

E aí está o problema. As funcionalidades mais úteis costumam ser as mais invisíveis, porque ninguém as procura se não sabe que existem.

A quarta camada de memória

Se você leu meu post sobre Linear, Beads e Tasks, MEMORY.md encaixa como uma quarta camada que complementa as demais:

As três primeiras são sobre trabalho: o que fazer, em que ordem, quem faz. MEMORY.md é sobre conhecimento: o que aprendemos fazendo.

E aí está a chave. Beads e Tasks são efêmeros por design: uma task se completa e fecha, uma issue se resolve e é arquivada. MEMORY.md é o que fica depois. As lições, não os deveres.

Um exemplo concreto de como se complementam: hoje usei Linear para trackear as issues do degoogle (PER-16 a PER-28). Tasks para seguir os passos dentro de cada issue. E MEMORY.md para anotar que a API do Linear precisa de UUIDs para os teams, não os keys. As issues se fecharam. As Tasks desapareceram. A lição dos UUIDs continua lá para a próxima vez.

Como começar a usar

Não precisa ativar nada. Já está funcionando.

A única coisa que você tem que fazer é dizer ao Claude “anote isso na sua memória” quando acontecer algo que vale a pena lembrar:

• Decisões técnicas (“escolhemos iCloud+ para o email”)
• Erros e soluções ("stat é GNU, usar -c não -f")
• Contexto do projeto (“o degoogle está completado”)
• Preferências descobertas (“o usuário prefere X sobre Y”)

E de vez em quando, revisar ~/.claude/projects/*/memory/MEMORY.md para ver o que anotou e podar o que sobrar.

O caderno do bom aprendiz

Existe uma frase do Feynman que vem a calhar: “The first principle is that you must not fool yourself — and you are the easiest person to fool.”

Um LLM não se engana porque não tem ego. Não pensa “já vou me lembrar” nem “isso é óbvio demais para anotar”. Se você diz para anotar algo, ele anota. Se descobre que uma nota está incorreta, corrige.

De certa forma, é melhor anotando coisas do que a maioria de nós jamais será. Só faltava um lugar onde guardá-las.

Agora tem.