Em cada novo encontro, Neo a reconhece. Lembra de tudo que aconteceu. Retoma de onde pararam. O agente sem memory é um Neo que esquece da Trinity todo dia.
O que é Memory?
Quatro características que separam memória persistente de um simples contexto de sessão que se perde.
Persiste entre sessões
Você fecha o terminal, abre amanhã, e o agente continua sabendo quem você é, em que está trabalhando e o que decidiu.
Tipos múltiplos
Quatro categorias: perfil do usuário, feedback de comportamento, contexto de projeto e referência externa. Cada uma com papel específico.
Indexado
Um arquivo MEMORY.md é índice. Cada memória mora num .md separado, carregado sob demanda.
Auto-gerenciado
O agente lê e escreve sozinho. Você só diz "lembra disso" quando algo merece virar regra permanente.
Memory · CLAUDE.md · Contexto
Três formas de informação viver com o agente. Confundir as três é receita para perder contexto ou poluir o token budget.
Os quatro tipos de memória
Cada memória declara seu tipo no frontmatter. Cada tipo tem propósito, formato e ciclo de vida diferentes.
Perfil do usuário
Quem você é, sua função, expertise técnica, idioma, tom preferido na conversa.
Regras de comportamento
Correções que você fez. Padrões que devem se repetir. O "não faça assim" e o "faça sempre assim".
Contexto de iniciativa
Decisões da iniciativa, prazos, stakeholders, restrições, vocabulário interno do projeto.
Ponteiro externo
Link para Linear, Slack, Notion, dashboards. A memória aponta, o conteúdo vive fora.
Anatomia de uma memória
Frontmatter no topo, corpo no meio, linkagem entre memórias com sintaxe de wiki.
--- name: feedback_no_em_dash description: Nunca usar travessao em texto LaTeX metadata: type: feedback --- # Proibido usar travessao Nunca usar travessao (em dash triplo) no texto LaTeX. Substituir por virgula, ponto e virgula ou dois-pontos. **Why:** O autor padronizou o livro sem travessoes para manter ritmo de leitura mais direto. **How to apply:** - Se o usuario digitar travessao, reescrever a frase - Validar antes de qualquer commit em [[feedback_latex_titles]] Veja tambem: [[feedback_subsection_asterisk]]
frontmatter
Identidade da memória: nome, descrição, tipo
corpo Markdown
Regra + Why: + How to apply:
[[linkagem]]
Wiki-style entre memórias relacionadas
Ciclo
A jornada de uma memória
Você diz algo, o agente decide salvar, cria um arquivo .md, atualiza o índice. Na próxima sessão, tudo está lá.
Onde a memória mora
Tudo num diretório memory/ dentro do hash do projeto. Markdown puro, versionável, auditável.
~/.claude/
└── projects/
└── C---MEUS-LIVROS-ENG-SOFTWARE/ # hash do projeto
└── memory/
├── MEMORY.md # indice, sempre no contexto
├── user_profile.md # tipo: user
├── feedback_no_em_dash.md # tipo: feedback
├── feedback_latex_titles.md # tipo: feedback
├── project_book_deadline.md # tipo: project
└── reference_overleaf.md # tipo: reference
MEMORY.md = índice
Uma linha por memória. Sempre carregado no contexto inicial.
Arquivos individuais = conteúdo
Lidos sob demanda, só quando o índice aponta relevância.
Um exemplo real de cada tipo
Quatro memórias, quatro propósitos. Veja como cada tipo se materializa em poucas linhas.
--- name: user_profile metadata: type: user --- # Perfil Sandeco, professor de IA aplicada, escreve livros tecnicos em portugues. Prefere comunicacao direta, exemplos concretos e zero floreio.
--- name: feedback_terminology metadata: type: feedback --- # Vibe coding x AI Engineering vibe coding = problema (IA sem processo) AI Engineering = solucao (IA com processo) **Why:** consistencia narrativa do livro. **How:** corrigir sempre que aparecer.
--- name: project_book_deadline metadata: type: project --- # Prazo do livro Deadline de submissao: 15/jun/2026. Editor: Casa do Codigo. Capitulos faltando: 5, 6, 7. **Why:** orientar priorizacao do dia.
--- name: reference_overleaf metadata: type: reference --- # Overleaf do livro Projeto principal: https://overleaf.com/project/abc123 Branch sincronizado com o repo Git toda manha as 09h00 via webhook.
O que não salvar em memory
Memory é caro: ocupa contexto, polui o índice, fica stale. Use para o que repete e orienta, não para o que muda toda hora.
Código fonte ou trechos de implementação
Use o repositório. Memory não é cache de função.
Log de Git ou histórico de commits
git log resolve. Memória não é replay de versionamento.
Soluções pontuais de bug
Bug que apareceu uma vez vira ruído. Só se for padrão recorrente.
Documentação que já existe
README, docs internas, ADR. Aponte via reference, não duplique.
Regra de ouro: memória decai. Antes de agir, o agente deve verificar se a memória ainda reflete a realidade. Memórias stale são piores que memórias ausentes.
Sua primeira memória: "lembra disso"
Você não precisa abrir editor nenhum. Diga ao agente. Ele decide a categoria, escreve o arquivo, atualiza o índice.
para escrever LaTeX, nunca use
travessao. Substitua por virgula
ou ponto e virgula.
Vou aplicar a partir de agora,
inclusive nas sessões futuras.
---
name: feedback_no_em_dash
description: Proibido usar travessao em LaTeX
metadata:
type: feedback
---
# Proibido travessao em LaTeX
Nunca usar travessao (em dash triplo)
em texto LaTeX.
**Why:** o usuario padronizou o livro
sem travessoes, prefere virgula
ou ponto e virgula.
**How to apply:**
- Substituir por virgula
- Ou por ponto e virgula
- Ou reescrever a frase
O índice MEMORY.md ganha uma linha nova apontando para este arquivo.
Diga a frase mágica
"lembra disso: ..." dispara a captura.
Agente classifica
Escolhe entre user, feedback, project ou reference.
Próxima sessão lê tudo
Você abre o terminal amanhã e a regra está ativa.
Como o agente cita a memória
Toda vez que uma memória influencia uma resposta, o agente deve referenciar. Isso vira rastro: você sabe por que ele decidiu daquele jeito.
Errado
Sem rastro de memória
Você não consegue auditar. Não sabe se ele usou memória correta. Não sabe corrigir o que está errado.
Certo
Cita a memória usada
Rastro completo. Se algo veio errado, você ataca a memória, não o output.
Cinco memórias que vão fazer diferença
Cinco arquivos. Cinco regras. Um agente que para de te perguntar as mesmas coisas.
Memória 1 · user_profile
Perfil do usuário
Sua função, expertise, idioma e tom. O agente para de te tratar como estranho a partir da primeira sessão e nunca mais te trata como tutorial de iniciante.
--- name: user_profile description: Quem e o usuario metadata: type: user --- # Perfil - **Funcao:** engenheiro de software senior - **Stack:** Python, FastAPI, Postgres - **Expertise:** alta em backend, media em ML - **Idioma:** portugues brasileiro - **Tom preferido:** direto, sem floreio, com exemplo concreto antes de teoria Nao explique conceitos basicos como HTTP, REST, OOP. Va direto ao ponto que e novo ou contraintuitivo.
Vou direto ao ponto que costuma confundir: decorator com argumentos e a diferenca entre @cache e @functools.lru_cache.
Quer ver o caso de classmethod decorator?
Ganho prático: zero "Aqui está uma introdução a..." quando você é sênior na área. O agente respeita seu nível.
Memória 2 · feedback_pr_rules
Regras de revisão de PR
Cada vez que você corrige um PR, vira regra. Não é sobre lembrar; é sobre não repetir o mesmo apontamento toda semana.
--- name: feedback_pr_rules description: Como revisar pull requests metadata: type: feedback --- # Revisao de PR Quando eu pedir review de PR, sempre: 1. Apontar testes faltantes no caminho feliz 2. Apontar testes faltantes no caminho erro 3. Verificar se ha migration sem rollback 4. Conferir logs com dados sensiveis 5. Conferir se variaveis de ambiente estao no .env.example **Why:** sao os 5 apontamentos que mais repito em todo PR do time. **How:** so liberar approve quando os 5 forem verificados.
Aponto 3 bloqueios antes do approve.
Ganho prático: seu checklist mental vira checklist do agente. Reviews ganham consistência sem virar processo burocrático.
Memória 3 · feedback_test_pytest
Sempre usar pytest
Convenção de teste do projeto. O agente nunca mais vai propor unittest, doctest ou qualquer outra coisa. Pytest sempre, com fixtures e parametrize.
--- name: feedback_test_pytest description: Sempre usar pytest com fixtures metadata: type: feedback --- # Pytest e padrao Todo teste novo deve ser: - pytest, nunca unittest - Usar fixtures em conftest.py - Usar parametrize para variantes - Nomear arquivo como test_*.py - Nomear funcao como test_*() **Why:** alinhamento com o resto do projeto, evita duas frameworks competindo no mesmo repo. **How:** se eu sugerir unittest, me corrija e reescreva em pytest.
Ganho prático: padrão de teste do projeto vive na memória, não no Wiki que ninguém lê. O agente cumpre desde a primeira sessão.
Memória 4 · project_deadline
Contexto de projeto
Deadline, stakeholders, restrições. O agente priorizar tarefas sabendo o prazo que está em jogo. Não precisa adivinhar urgência.
--- name: project_deadline description: Prazos e stakeholders do projeto metadata: type: project --- # Projeto AuthService v2 - **Deadline:** 30/jun/2026 - **Stakeholders:** Maria (PM), Carlos (CTO) - **Hard requirement:** zero downtime - **Soft requirement:** rollback em 2 min ## Decisoes ja tomadas - JWT com refresh token de 7 dias - Rate limit 100 req/min por usuario - Postgres como source of truth ## A decidir - Cache: Redis ou Memcached? - Migracao: blue-green ou canary?
Critico: decidir entre Redis e Memcached. Trava o desenho do cache layer.
Urgente: escolher estrategia de migracao (blue-green vs canary).
Sugiro pauta com Carlos ainda esta semana.
Ganho prático: priorização com contexto. O agente não sugere refactor cosmético quando o deadline aperta.
Memória 5 · reference_notion
Referência externa
Ponteiro para sistemas externos: Linear, Notion, Slack, dashboards. A memória aponta, não duplica. O conteúdo vive na fonte de verdade.
--- name: reference_notion description: Doc principal de arquitetura metadata: type: reference --- # Arquitetura no Notion ADRs do projeto: https://notion.so/team/adrs-auth Roadmap trimestral: https://linear.app/team/roadmap-q2 Canal de incidentes: slack://channel/incidents-auth ## Quando consultar - Antes de propor mudanca arquitetural - Quando o usuario citar "ADR-N" - Em duvidas sobre prioridade
Resumo da pagina:
· Stateless escala melhor
· Reduz dependencia de Redis
· Trade-off: revocation mais complexa (mitigado com blacklist de 24h)
Link completo: notion.so/.../adr-007
Ganho prático: contexto sempre fresco. Você atualiza no Notion, o agente lê o link, ninguém precisa sincronizar manualmente.
As cinco memórias lado a lado
Resumo do conjunto mínimo que transforma um assistente em colaborador de verdade.
| Memória | Tipo | O que captura | Ganho | |
|---|---|---|---|---|
| user_profile | user | Função, expertise, tom preferido | Sem tutorial básico | |
| feedback_pr_rules | feedback | Checklist de revisão de PR | Reviews consistentes | |
| feedback_test_pytest | feedback | Pytest com fixtures e parametrize | Padrão de teste vivo | |
| project_deadline | project | Deadline, stakeholders, decisões | Priorização contextual | |
| reference_notion | reference | Links para ADR, Linear, Slack | Sempre fonte fresca |
Cinco arquivos. Menos de cem linhas no total. E o agente para de ser estranho a partir da segunda sessão.
Quer dominar cada peça?
O livro Engenharia de Software para Agentes Inteligentes destrincha memory, commands, hooks, skills, MCP, subagents e tudo que faz o agente trabalhar a seu favor.
·
@canalsandeco
Sem memory, cada sessão é o reinício do Matrix Resurrections. Com memory, Neo reconhece a Trinity e segue a luta de onde pararam.
Memory é o que separa um assistente que executa de um colaborador que cresce com você. A diferença entre repetir explicações e ser entendido na primeira frase.