A memória do Claude é um índice, não um diário

O Claude Code vem anotando coisas sobre os seus projetos, e quase ninguém abriu essas anotações. Elas ficam em ~/.claude/projects/<project>/memory/. E tem um detalhe que deveria definir como você usa essa pasta: só as 200 primeiras linhas do MEMORY.md, ou os primeiros 25KB — o que vier primeiro —, carregam no início de cada sessão. Nada mais no diretório carrega.

Encare isso como restrição de projeto, não como limite de tamanho. A linha 201 não "carrega depois" — ela é descartada. Ou seja: o MEMORY.md não pode ser onde o conhecimento mora. Ele tem que ser o índice que diz ao Claude qual arquivo abrir.

A Anthropic leva isso a sério o suficiente pra ter criado um erro só pra esse caso. Depois que o Claude escreve no MEMORY.md, o Claude Code mede o arquivo — e se a escrita passou do teto, aparece this write left the memory index at MEMORY.md at ..., over its ... read limit. A documentação explica o motivo em uma frase: o limite de leitura existe pra preservar espaço da context window pro trabalho de verdade.

O layout

~/.claude/projects/<project>/memory/
├── MEMORY.md          # o índice — carrega toda sessão, ≤200 linhas
├── build.md           # lido só quando precisa
├── auth-gotchas.md
└── deploy.md

Os arquivos de tópico nunca carregam na largada. O Claude abre cada um com as ferramentas normais de arquivo quando o índice indica que ele é relevante — e é exatamente por isso que cada entrada do índice precisa descrever o arquivo bem o bastante pra essa decisão acontecer.

Um MEMORY.md que funciona parece uma tabela de roteamento:

# Memory Index

- [Build](build.md) — workspaces pnpm 11; `db` migra antes do `web` passar no typecheck
- [Auth](auth-gotchas.md) — sessão no banco; campos do adapter não podem ser renomeados
- [Deploy](deploy.md) — Vercel + Railway, matriz de env muda por plataforma
- Postgres roda em Docker local, não no Neon — `pnpm db:up` antes de qualquer teste

São dois tipos de entrada, e a diferença é onde está o ofício: um ponteiro (o link mais descrição suficiente pra decidir se vale abrir) ou um fato tão curto que o ponteiro custaria mais caro que o próprio fato. Se a entrada precisa de uma segunda linha, ela é um arquivo de tópico.

O que merece virar memória

Nenhuma ferramenta decide isso pra você — e é aqui que todo sistema de memória que eu vi dá errado. A pegadinha: a memória automática é local da máquina. O caminho <project> é derivado do repositório git, então todos os worktrees e subdiretórios do mesmo repositório compartilham uma pasta de memória — mas essa pasta nunca vai pro commit, nunca sincroniza e não existe num ambiente na nuvem. Três semanas de aprendizado suado em debug e um notebook novo começa do zero.

Então o roteamento tem três caminhos, não dois:

1. Fato que um colega precisa → CLAUDE.md ou um documento no repositório.
2. Preferência descoberta ou peculiaridade da sua máquina → memória automática.
3. Conhecimento que um papel acumula → memória de subagent, com escopo project.

A terceira opção é a mais subestimada. Coloque memory: project no frontmatter de um subagent e o diretório de memória dele passa a ser .claude/agent-memory/<name>/ — dentro do repositório, no controle de versão. A documentação chama project de escopo padrão recomendado justamente por isso: é o que torna o conhecimento do subagent compartilhável via controle de versão.

---
name: code-reviewer
description: Reviews a diff for quality, conventions and recurring issues.
memory: project
---

Check your memory before reviewing. When you finish, record each new pattern,
convention or recurring issue as ONE line in MEMORY.md, with the detail in a
topic file. Keep MEMORY.md under 200 lines — prune stale entries as you go.

Isso é um revisor que fica melhor no seu código e entrega essa melhora pro seu time num git commit. O mesmo teto vale lá dentro: as 200 primeiras linhas ou 25KB do MEMORY.md dele entram no system prompt do subagent.

Se você quer que a sua memória pessoal sobreviva a uma troca de máquina, aponte ela pra um lugar com backup:

{
  "autoMemoryDirectory": "~/Dropbox/claude-memory"
}

O valor precisa ser um caminho absoluto ou começar com ~/, e ele é lido de qualquer escopo de configuração. Eu deixo a minha numa pasta sincronizada e espelho o índice no Notion — assim nenhum notebook é a única cópia.

Curar é o trabalho de verdade

A pasta de memória de um agente apodrece igualzinho a wiki de time. Dois hábitos seguram isso:

• Confie nas datas. Quando um arquivo de memória começa com frontmatter YAML, o Claude Code grava um campo modified com data e hora em ISO 8601 a cada escrita (v2.1.214 pra frente). Esse é o seu sinal de que a informação envelheceu — e o do Claude também, quando ele reler o arquivo meses depois.
• Poda no calendário, não no erro. Se você esperar o erro de limite, é o Claude que decide o que cortar sob pressão. Faça você mesmo, uma vez por mês, com uma pergunta por linha: isso ainda é verdade?

A Anthropic embute essa mesma disciplina como prompt no lado da API. Habilite a memory tool e o system prompt ganha automaticamente IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE, seguido de ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory. Ou seja: projete pra ser interrompido. Aí a memória deixa de ser um luxo e passa a ser o único lugar onde o progresso realmente existe.

Faça isso hoje

Rode /memory, abra a pasta de memória automática e leia cada linha que o Claude salvou sobre o seu repositório mais ativo. Depois faça uma passada com três pilhas: vai pro repositório (um colega precisa disso → mova pro CLAUDE.md), fica (fato real da sua máquina → deixa, em uma linha), apaga (você já não consegue confirmar). Então conte o que sobrou. Se o MEMORY.md passar de 200 linhas, você vinha guardando conhecimento num arquivo que é cortado no meio — transforme o excedente em arquivos de tópico e deixe ponteiros no lugar. O meu tinha aprendido coisas sobre o meu build que eu nunca escrevi em lugar nenhum, e também guardava um "fato" que parou de ser verdade dois meses atrás.

Fontes

• Claude Code docs — How Claude remembers your project
• Claude Code docs — Memory-related errors
• Claude Code docs — Enable persistent memory for subagents
• Claude docs — Memory tool