O problema não é esquecer uma frase

Quando uma sessão de agente termina, o que costuma se perder não é apenas texto. Somem as decisões: por que uma biblioteca foi escolhida, qual hipótese já falhou, onde está o risco e qual é o próximo passo. Sem isso, a próxima sessão reabre o mesmo labirinto.

Memória útil é um sistema de recuperação, não um depósito infinito de conversas.

Três camadas simples

1. Estado atual: o que está acontecendo agora, quais arquivos mudaram e qual tarefa está em andamento.

2. Decisões: escolhas estáveis e seus motivos, como o formato de uma API ou a política de cache.

3. Histórico pesquisável: experimentos, erros e referências que podem voltar a ser relevantes.

No meu fluxo, o estado fica curto e próximo do projeto; decisões viram Markdown versionado; histórico vai para uma busca que consiga apontar trechos, não apenas documentos inteiros.

Handoff precisa terminar em ação

Um handoff bom responde quatro perguntas: onde parei, o que descobri, o que ainda não sei e qual comando ou arquivo abre o próximo passo. "Continue daqui" não é handoff, é um pedido para outra pessoa adivinhar.

Uma nota pequena como esta costuma ser suficiente:

Objetivo: publicar a home do blog
Feito: API responde 200 e build passa
Risco: cache antigo no domínio customizado
Próximo passo: verificar três rotas após o deploy

Não confunda contexto com autoridade

Memória também pode carregar uma decisão errada. Por isso, o agente deve tratar notas como contexto verificável, não como permissão para apagar dados, alterar produção ou expor segredo. A memória explica o caminho; as políticas continuam mandando.

Um começo leve

Você não precisa montar uma plataforma complexa no primeiro dia. Comece com um arquivo DECISIONS.md, um TASK.md por tarefa e um script para buscar palavras-chave no histórico. Quando o volume crescer, adicione SQLite, embeddings ou MCP. A estrutura conceitual vem antes da tecnologia.

O projeto ai-memory, citado pelo Akita, explora uma direção parecida ao conectar sessões e ferramentas em uma memória que pode ser versionada. A lição que eu levaria para qualquer equipe é simples: documente decisões enquanto elas ainda estão frescas.

Leitura relacionada: ai-memory 2.0 — AkitaOnRails.