Agentes de programação precisam preservar decisões, progresso e pendências para continuar tarefas entre sessões sem repetir investigações ou perder informações importantes.

A estratégia é separar o conhecimento permanente do projeto do estado temporário das tarefas, utilizando checkpoints, handoffs e resumos estruturados.

O objetivo não é armazenar todo o histórico das conversas, mas garantir que um agente consiga retomar o trabalho com o contexto necessário, verificando o que já foi feito e o que ainda precisa ser concluído.

1. Diferentes tipos de memória

Nem toda informação produzida durante o desenvolvimento precisa ser armazenada da mesma maneira. É importante distinguir três categorias:

Tipo Conteúdo Onde armazenar
Conhecimento do projeto Arquitetura, contratos, convenções e decisões permanentes AGENTS.md, CHAOS ou documentação técnica
Estado da tarefa Progresso, decisões específicas, bloqueios e próximos passos Checkpoints, tickets ou arquivos de estado
Histórico de execução Comandos, tentativas, erros e resultados intermediários Logs, registros de execução ou histórico da sessão

Essa separação evita que informações temporárias sejam incorporadas à documentação permanente ou que um agente precise consultar históricos extensos para descobrir o estado atual de uma tarefa.

A organização do conhecimento do projeto já foi abordada no artigo Arquitetura, engenharia e documentação de contexto. Aqui o foco é a continuidade operacional.

Leitura adicional: OpenAI Codex — AGENTS.md. CHAOS.

2. Continuidade entre sessões

Ao iniciar uma nova sessão, o agente deve recuperar o estado da tarefa antes de executar novas alterações.

  1. Identificar a tarefa em andamento.
  2. Consultar o checkpoint mais recente.
  3. Recuperar decisões e dependências relevantes.
  4. Conferir o estado atual do repositório.
  5. Identificar pendências e continuar a execução.

Exemplo de instrução:

Antes de continuar uma tarefa existente:

1. Leia o estado registrado da tarefa.
2. Identifique decisões, alterações e pendências.
3. Confira se o registro corresponde ao
   estado atual do repositório.
4. Verifique bloqueios e dependências.
5. Continue a partir da próxima etapa pendente.

Não repita investigações já concluídas,
exceto quando houver inconsistências.

O ponto importante é não confiar exclusivamente no resumo anterior. Um checkpoint pode estar desatualizado ou registrar uma alteração que não foi efetivamente aplicada. Por isso, o agente deve confrontá-lo com os arquivos e o estado real do projeto.

3. Checkpoints durante a execução

Em tarefas longas, depender apenas do contexto da conversa aumenta o risco de perder informações quando a sessão termina ou o histórico é compactado. Checkpoints permitem preservar o estado necessário para continuar o trabalho.

Eles podem ser criados:

  • Após concluir uma etapa relevante.
  • Antes de mudanças com impacto significativo.
  • Quando uma decisão técnica altera o planejamento.
  • Ao encontrar um bloqueio.
  • Antes de encerrar ou transferir uma sessão.

Não é necessário gerar um checkpoint a cada comando ou pequena alteração. O registro deve representar o progresso da tarefa, não reproduzir todo o histórico da execução.

Exemplo de arquivo task-state.md:

# Task: Order API Integration

Status: In progress

## Completed
- API endpoint implemented
- Request validation added
- Response contract preserved

## Decisions
- Reuse existing authentication middleware
- Keep the current response structure

## Pending
- Frontend integration
- Integration verification

## Modified Files
- src/routes/orders.ts
- src/services/orders.ts

## Blockers
- None

## Next Step
Implement frontend integration.

Esse arquivo pode ser atualizado durante a execução e utilizado por qualquer agente autorizado a continuar a tarefa.

4. Handoff entre agentes

Quando uma tarefa é transferida para outro agente, o objetivo é fornecer contexto suficiente para continuar o trabalho sem exigir a leitura de toda a conversa anterior.

Um handoff pode conter:

  • Objetivo e estado atual da tarefa.
  • Alterações realizadas e arquivos envolvidos.
  • Decisões técnicas relevantes.
  • Contratos e restrições que precisam ser preservados.
  • Pendências e bloqueios.
  • Próxima ação recomendada.

O agente que recebe o trabalho deve conferir as informações antes de continuar.

Exemplo de instrução para handoff

Prepare um handoff para outro agente
continuar esta tarefa.

Inclua:
- Objetivo e progresso atual.
- Decisões técnicas relevantes.
- Arquivos modificados.
- Restrições e contratos existentes.
- Pendências e bloqueios.
- Próxima etapa recomendada.

Seja objetivo.
Não reproduza o histórico completo da sessão.

Checkpoints e handoffs podem compartilhar o mesmo formato. A diferença está na finalidade: o checkpoint registra o estado, enquanto o handoff organiza as informações necessárias para transferir a responsabilidade pela execução.

5. Compactação e eficiência do contexto

Manter todo o histórico de uma tarefa no contexto do modelo pode aumentar o consumo de tokens e dificultar a identificação das informações relevantes.

Uma estratégia é substituir históricos extensos por resumos estruturados, preservando apenas o que influencia as próximas decisões.

O resumo deve manter:

  • Decisões aprovadas e suas justificativas relevantes.
  • Contratos e restrições.
  • Resultados confirmados.
  • Problemas ainda não resolvidos.
  • Referências para arquivos e evidências.
  • Próximas ações.

Tentativas descartadas, discussões repetitivas e detalhes que não influenciam a continuidade geralmente não precisam permanecer no contexto ativo.

Entretanto, compactação não deve significar perda de informações importantes. Quando um resultado depende de evidências extensas, é preferível armazená-las em arquivos separados e incluir referências no resumo, em vez de reproduzi-las integralmente.

A estratégia é preservar decisões e referências, não todas as interações que levaram até elas.

6. Persistência e recuperação

A memória operacional pode ser mantida utilizando arquivos Markdown, JSON, tickets ou mecanismos específicos de orquestração.

Para muitos projetos, arquivos estruturados no próprio workspace são suficientes.

.tasks/
  TASK-101/
    state.md
    decisions.md
    findings.md

Essa organização é apenas uma possibilidade. Não é necessário criar uma estrutura complexa para tarefas simples.

O importante é que os agentes saibam:

  • Onde encontrar o estado atual.
  • Quais informações precisam atualizar.
  • Como identificar a versão mais recente.
  • Quais registros pertencem à tarefa.
  • Quando consultar a documentação permanente.

Em fluxos com múltiplos agentes, também é necessário evitar que execuções concorrentes sobrescrevam o mesmo arquivo de estado. Isso pode ser resolvido com responsabilidades definidas, controle de versões ou mecanismos próprios do orquestrador.

Para projetos que já utilizam CHAOS ou outra estrutura de contexto, os registros operacionais podem ser integrados à organização existente, sem duplicar documentação.

Leitura adicional: Git — documentação oficial. CHAOS.

Persistência em bancos de dados e memória compartilhada

Em esteiras com múltiplos agentes, especialmente quando as execuções acontecem em máquinas ou containers diferentes, pode ser útil manter o estado e o histórico em um serviço externo compartilhado.

Um banco de dados pode registrar checkpoints, andamento das tarefas, decisões e resultados de execuções anteriores. Isso permite que outro agente retome um trabalho ou consulte uma solução já encontrada, sem depender de arquivos locais ou do histórico completo da conversa.

Armazenamento Aplicação possível
PostgreSQL ou MySQL Estado atual, checkpoints, decisões e histórico estruturado de tarefas
Redis Cache, filas e coordenação temporária entre execuções
Banco vetorial Busca semântica por problemas, decisões e soluções anteriores
Armazenamento de objetos Logs extensos, relatórios e evidências de execução

Não é necessário adotar todos esses componentes. Em muitos casos, um banco relacional é suficiente; a busca semântica só se justifica quando traz benefícios concretos à recuperação das informações.

É importante distinguir estado atual, histórico de execução e memória reutilizável. O estado atual orienta a continuidade de uma tarefa; o histórico registra o que aconteceu; a memória reutilizável reúne conhecimentos confirmados que podem ajudar em trabalhos futuros.

Por exemplo, ao encontrar um erro de integração, um agente pode consultar incidentes semelhantes e recuperar a causa identificada e a solução aplicada anteriormente. Esses registros servem como referência, mas precisam ser conferidos contra a versão atual do projeto antes de serem reutilizados.

O valor da memória compartilhada está na recuperação de informações relevantes e verificadas, não no armazenamento indiscriminado de todas as conversas.

7. Atualização e confiabilidade da memória

Informações persistidas podem ficar desatualizadas conforme o projeto evolui. Uma decisão registrada anteriormente pode ter sido substituída, uma tarefa pode ter sido concluída ou uma dependência pode ter mudado.

Por isso, os agentes devem atualizar o estado sempre que ocorrerem alterações relevantes.

  • Manter um registro atual da tarefa.
  • Identificar decisões substituídas.
  • Evitar múltiplos arquivos com estados contraditórios.
  • Confirmar informações importantes antes de reutilizá-las.
  • Remover ou arquivar estados que não são mais necessários.
  • Atualizar a documentação permanente quando decisões alterarem a arquitetura ou os contratos.

A atualização deve ocorrer na fonte apropriada. Uma mudança arquitetural confirmada pertence à documentação do projeto. Já o andamento de uma implementação pertence ao estado da tarefa.

Também é importante tratar resumos produzidos por agentes como registros sujeitos a verificação, não como fontes automaticamente confiáveis.

Em bancos externos, históricos também devem registrar origem, data e contexto da execução, permitindo identificar informações obsoletas e aplicar regras de retenção e acesso. Uma solução antiga não deve substituir o estado atual ou uma decisão arquitetural vigente.

A memória deve refletir o estado real do trabalho, e não apenas aquilo que um agente afirmou ter realizado.

Conclusão

A continuidade do desenvolvimento com agentes depende de preservar as informações certas, no lugar adequado e no momento necessário.

Separar conhecimento permanente, estado da tarefa e histórico de execução permite recuperar contexto com menos tokens e menor risco de repetir trabalho.

Checkpoints, handoffs e resumos estruturados ajudam diferentes agentes a continuar tarefas, enquanto a verificação do estado real do projeto mantém a confiabilidade do processo.

O objetivo não é fazer o agente lembrar de tudo, mas garantir que ele consiga recuperar o que precisa para continuar trabalhando corretamente.

Leituras adicionais

Artigos relacionados

CHAOS.