Memória do agente de IA entre sessões: arquivo de progresso, diário de decisões, git e script de init

Por que o agente não lembra de nada

O modelo não guarda estado entre execuções. Tudo o que o agente "sabe" sobre a sua tarefa está na janela de contexto da sessão atual: arquivos lidos, saída de comandos, o diálogo com você. A sessão se encerra ou o contexto transborda, e a nova começa do zero, vendo apenas o que foi gravado em disco.

Um modelo útil: um engenheiro brilhante que chega ao trabalho toda manhã com a memória completamente apagada. Ele entende o código rapidamente, mas não se lembra de qual arquitetura foi escolhida ontem, por que as outras foram descartadas e em que estado estão os testes. Sem anotações, gasta de quinze a vinte minutos de reconhecimento e, com boa probabilidade, refaz o que você já havia descartado de propósito.

Por isso a memória do agente de IA não é uma propriedade do modelo, e sim parte do harness: um conjunto de arquivos e regras que você mesmo projeta. A boa notícia é que não são necessários bancos vetoriais nem serviços especiais. Bastam alguns arquivos Markdown, o git e disciplina.

Por que uma janela de contexto grande não resolve

Parece que basta esperar um modelo com uma janela maior. Mas uma tarefa complexa enche qualquer janela: o agente lê a base de código, acumula o histórico de decisões, recebe saídas longas de testes e mantém o diálogo inteiro. As necessidades crescem junto com a janela. É um problema de arquitetura, não de volume.

Há também um segundo efeito. Perto do limite da janela, muitos modelos começam a ter pressa de terminar: pulam verificações e escolhem a solução simples em vez da correta. A Anthropic descreve essa observação para os próprios modelos, e a intensidade do efeito varia de modelo para modelo. Uma sessão longa no limite do contexto não é apenas um risco de perder informação, mas também um risco de piorar a qualidade do trabalho.

Compactação: o que é preservado e o que se perde

Compactação é a condensação do início do diálogo em um resumo curto, para liberar espaço na mesma sessão. No Claude Code isso é feito pelo comando /compact, e a compactação também acontece automaticamente quando se aproxima do limite. Já o comando /clear apaga o histórico e recomeça a conversa.

O problema da compactação é que o resumo costuma preservar o "o quê" e perder o "por quê". O código pronto continua nos arquivos, mas o raciocínio — por que foi escolhida a variante B, por que não se usou a biblioteca, por que a otimização foi deliberadamente deixada de lado — encolhe a duas palavras ou desaparece. O próximo passo do agente "melhora" uma decisão consciente, porque já não vê os motivos.

Uma regra prática, sem métricas complexas: quando a tarefa já ocupou cerca de 60% da janela, pare de escrever código e prepare a passagem de trabalho. Se o contexto está em 40% e o fim da tarefa está próximo, a compactação basta.

Quatro artefatos que formam a memória do agente

Em vez de confiar na memória do modelo, crie um diário de bordo. Ele tem quatro partes, cada uma com um papel próprio.

1. PROGRESS.md — onde estamos agora.
2. DECISIONS.md — por que foi feito assim e não de outra forma.
3. Commits do git — checkpoints de estado sem custo.
4. Protocolo de troca de turno no AGENTS.md — o que fazer ao chegar e ao sair.

PROGRESS.md: arquivo de progresso

Responde a uma só pergunta: em que estado o projeto está neste momento. O agente o lê primeiro no início da sessão e o atualiza por último, antes de sair. O arquivo é curto e é reescrito, não acrescentado indefinidamente: o histórico fica no git.

# PROGRESS.md

## Objetivo atual
Busca no catálogo de produtos (funcionalidade search-01)

## Estado
- HEAD: 4f2a9c1
- make check: verde, 142/142 testes
- Feito: índice no PostgreSQL (tsvector), endpoint GET /search
- Verificado: testes unitários + consulta manual com curl em 3 buscas

## Bloqueios
- Não há dados de morfologia para o cazaque — aguardando decisão

## Próximo passo
Adicionar paginação em GET /search, critério: teste da 2ª página

Repare nos quatro campos suficientes para passar o trabalho adiante: hash do commit, proporção de testes passando, bloqueios e próximo passo. Se uma sessão nova não consegue continuar sem ambiguidade com base nesse arquivo, o modelo está faltando um campo.

DECISIONS.md: diário de decisões

Guarda justamente o "por quê" que se perde na compactação. Formato de cada registro: a decisão, o motivo, o que foi descartado e por quê, e as restrições.

## 2026-03-14 — Cache das configurações do usuário no Redis
- Decisão: Redis, TTL de 5 minutos, invalidação ativa na gravação.
- Motivo: é lido em cada requisição, o volume de dados é pequeno.
- Descartado: materialized view no PostgreSQL — mudanças muito frequentes,
  a manutenção não compensa.
- Restrição: não armazenar em cache as configurações de pagamento.

A linha mais valiosa aqui é "Descartado". É ela que impede a sessão seguinte de "otimizar" a decisão de volta para uma variante que já foi considerada e rejeitada. Diferentemente do arquivo de progresso, o diário de decisões só cresce: os registros antigos não são apagados, são marcados como substituídos pelos novos.

Histórico do git como checkpoints

Os commits já são snapshots versionados do estado, integrados ao trabalho. O agente pode ler git log e git diff e reconstruir o que foi alterado. Para que o histórico funcione como memória, a mensagem do commit deve explicar a intenção, e não repetir o diff.

# ruim
git commit -m "update search.py"

# bom
git commit -m "search: índice tsvector em vez de LIKE

LIKE '%q%' não usa índice; com 200k produtos a consulta leva 1.8 s.
A paginação ainda não está feita, ver PROGRESS.md."

Commits pequenos e frequentes, feitos após cada execução verde dos testes, também oferecem um ponto de retorno. Se a sessão saiu do rumo, é mais simples voltar ao último estado verificado do que desembaraçar edições pela metade.

Protocolo de troca de turno no AGENTS.md

Os arquivos de estado são inúteis se o agente não sabe que existem. Por isso, no arquivo de instruções de entrada (AGENTS.md ou CLAUDE.md), escreve-se um protocolo curto: o que fazer ao chegar e ao sair.

## Ao assumir o turno
1. Ler PROGRESS.md e DECISIONS.md.
2. Encontrar a tarefa ativa em .agent/feature_list.json.
3. Rodar make check — confirmar que o repositório está consistente.
4. Continuar do "Próximo passo", sem reabrir o que já foi decidido.

## Ao encerrar o turno
1. Rodar make check, commitar o estado verde.
2. Atualizar PROGRESS.md: HEAD, testes, bloqueios, próximo passo.
3. Acrescentar as novas decisões em DECISIONS.md.
4. Não deixar nada pela metade na árvore de trabalho.

É melhor manter o protocolo curto: são algumas linhas no arquivo de entrada, e não um texto longo à parte.

Script de init: como acelerar o início da sessão

Para que o agente não precise montar o quadro manualmente, dê a ele um único script que verifica o ambiente e imprime o estado. O script deve ser idempotente — pode ser executado quantas vezes for preciso — e terminar com uma mensagem explícita de que está pronto.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Ambiente =="
command -v uv >/dev/null || { echo "FAIL: uv não instalado"; exit 1; }
uv sync --frozen

echo "== 2. Repositório =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: árvore de trabalho suja"
else
  echo "OK: limpo"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Verificação =="
make check

echo "== 4. Estado =="
cat PROGRESS.md

echo "Pronto para trabalhar"

No protocolo de entrada basta, então, uma linha: "execute scripts/init.sh". No Claude Code essa execução pode ser automatizada com um hook de início de sessão (evento SessionStart), mas, mesmo sem o hook, o agente executa o script seguindo a instrução do arquivo.

O que colocar na memória do agente e o que não colocar

O erro principal é transformar a memória em um depósito. Cada linha que o agente lê no início ocupa espaço no contexto, e o excesso dilui o que é importante.

Separe também por tempo de vida. As regras do projeto mudam raramente e valem para todas as tarefas: o lugar delas é o arquivo de instruções de entrada. O estado muda a cada sessão: o lugar dele é o arquivo de progresso. Se misturar os dois, o arquivo de entrada logo fica inchado de anotações obsoletas.

Primeira sessão: a inicialização como fase separada

A memória entre sessões não ajuda se a primeira sessão terminou em caos. Quadro típico: você escreve, em um repositório limpo, "adicione busca", e meia hora depois descobre que o framework de testes está mal configurado e o formato das migrações não é o esperado. A busca apareceu, mas a base está torta.

A causa é que implementação e inicialização otimizam coisas diferentes: a primeira, o número de funcionalidades prontas nesta sessão; a segunda, a velocidade e a confiabilidade de todas as sessões seguintes. O agente tende ao resultado visível, ou seja, ao código. Por isso vale separar a inicialização em uma sessão própria, com um critério de pronto de quatro condições.

• Executar: make setup e make dev funcionam a partir de um clone limpo.
• Verificar-se: existe make test e pelo menos um teste real que passa.
• Enxergar o progresso: o arquivo de estado existe e pode ser lido.
• Retomar o trabalho: existe uma lista de tarefas com critérios de aceitação.

Se você inicia projetos novos com frequência, crie um template de repositório: Makefile, framework de testes, esqueleto do AGENTS.md, pasta .agent/, scripts/init.sh, linter e CI. Assim, a inicialização se resume à especificidade de cada projeto.

Como verificar se a memória funciona

A métrica mais honesta é o tempo entre o início de uma sessão nova e a primeira alteração de código com sentido. Sem artefatos, costuma ser de quinze a vinte minutos de reconhecimento; com uma boa passagem de trabalho, de dois a três. Meça uma vez antes e uma vez depois, e você verá se a disciplina compensa.

Um segundo método é o teste de partida a frio. Abra uma sessão nova, escreva "continue" e faça cinco perguntas: qual é o objetivo atual, em que estado estão os testes, qual decisão foi tomada sobre o tema-chave e por quê, o que está bloqueando, qual é o próximo passo. Se o agente responde às cinco com base nos arquivos, sem adivinhar, a memória está bem estruturada. Cada resposta insegura aponta um campo que falta no template.

Erros típicos

• O arquivo de progresso só cresce. Depois de um mês, tem centenas de linhas de histórico. Reescreva-o para o estado atual; o histórico fica no git.
• Falta a linha "descartado". Um diário de decisões sem as alternativas rejeitadas não protege contra discussões repetidas.
• O agente atualiza o estado "de olho". Escreva como foi verificado: comando e resultado, e não "tudo funciona".
• Passagem de trabalho no limite da janela. Perto do limite do contexto o agente já está com pressa; comece o handoff antes, por volta de 60%.
• Árvore de trabalho suja ao final. Edições pela metade sem commit confundem a sessão seguinte.

Resumindo

A memória do agente de IA entre sessões é construída não sobre o modelo, e sim sobre arquivos: o PROGRESS.md guarda o estado atual, o DECISIONS.md guarda os motivos e as alternativas descartadas, os commits do git são checkpoints com a explicação da intenção, e o protocolo de troca de turno no AGENTS.md obriga a ler e atualizar tudo isso. O script de init reduz o início a um único comando, e o teste de partida a frio mostra se os registros são suficientes. O diário de bordo do agente e o contrato de bootstrap são explicados na prática no curso de engenharia de harness.