O custo operacional da amnésia entre sessões
Quem usa agentes de código no trabalho diário reconhece rápido um padrão cansativo. Na segunda-feira você corrige o assistente porque ele usou uma dependência externa proibida pelo time, colocou lógica de rede na camada errada ou abriu um commit fora da convenção do repositório. Ele entende, corrige o código e entrega um pull request limpo. Na terça-feira, em uma sessão nova, o mesmo agente comete exatamente os mesmos três erros como se a conversa do dia anterior nunca tivesse existido.
Esse problema existe porque modelos de linguagem executam inferência sem estado persistente. Quando o processo fecha ou a conversa ultrapassa o limite da janela, todo o conhecimento construído durante a depuração evapora. Em equipes pequenas isso gera irritação; em times com dezenas de engenheiros trabalhando sobre a mesma base de código, vira retrabalho recorrente na revisão de código e degrada a confiança na automação.
A resposta intuitiva de muita gente é tentar resolver tudo com um banco vetorial gigantesco ou despejar 40 páginas de documentação no prompt de sistema. Os dois extremos costumam falhar. Um arquivo de instruções inchado desperdiça tokens a cada rodada e dilui o foco do modelo, problema analisado em detalhe no artigo sobre otimização de contexto e redução de tokens em LLMs. Já um banco vetorial sem curadoria devolve trechos antigos e contraditórios que confundem o agente mais do que ajudam.
Princípio de desenho: memória útil para agentes de software precisa separar regras invariantes, lições aprendidas por contexto de arquivo e procedimentos operacionais sob demanda. Nem tudo deve ser carregado sempre, e nada deve permanecer eternamente sem revisão.
Quatro camadas de memória para agentes de engenharia
Em vez de tratar "memória" como um depósito único de texto, arquiteturas maduras dividem o conhecimento em quatro camadas com ciclos de vida distintos. O diagrama abaixo mostra como essas camadas alimentam a janela ativa do agente sem sobrecarregá-la.
Cada camada responde a uma pergunta diferente e exige um formato de armazenamento adequado ao seu ritmo de mudança. Misturar regras de deploy permanentes com uma anotação temporária sobre um bug de compilação cria conflito difícil de depurar semanas depois.
| Camada | O que armazena | Onde fica | Quando carrega | Política de limpeza |
|---|---|---|---|---|
| Memória de trabalho | Plano atual, trechos de arquivo e saída recente de testes | Janela de contexto da sessão | Em tempo real durante o turno | Compactada ao fechar cada subtarefa |
| Memória semântica | Convenções imutáveis, arquitetura, limites de segurança e deploy | AGENTS.md ou CLAUDE.md no Git | Sempre no prefixo do prompt | Revisada em PR como código normal |
| Memória episódica | Correções específicas de bugs, pegadinhas de módulos e decisões pontuais | .ai/memory/learnings.jsonl | Sob demanda por filtro de pasta ou tag | TTL com revalidação após 90 dias sem uso |
| Memória procedural | Roteiros passo a passo, scripts de verificação e fluxos de release | .ai/skills/<nome>/SKILL.md | Apenas quando a tarefa casa com o gatilho | Atualizada junto com o processo operacional |
Estrutura versionada em Git sem depender de infraestrutura pesada
Para a maioria dos repositórios de produto, começar com arquivos de texto estruturados dentro do próprio Git funciona muito melhor do que subir um serviço separado de embeddings. Arquivos versionados passam por code review, acompanham branches de refatoração (se a arquitetura mudou na branch v2, a memória acompanha a branch sem contaminar a main) e podem ser inspecionados com git blame quando uma regra parece estranha.
Uma organização enxuta no repositório separa regras globais na raiz e escopos locais nas pastas dos módulos. Assim, um agente alterando o módulo de faturamento recebe automaticamente as restrições de arredondamento fiscal sem precisar carregar regras de animação da tela inicial.
.
├── AGENTS.md # Regras globais curtas (< 150 linhas)
├── Modules/
│ ├── Payments/
│ │ └── AGENTS.md # Regras locais apenas para o dominio de pagamentos
│ └── Networking/
│ └── AGENTS.md # Convencoes de retry, timeouts e certificados
└── .ai/
├── memory/
│ └── learnings.jsonl # Registro estruturado de correcoes verificadas
└── skills/
├── release-checklist/
│ └── SKILL.md # Procedimento completo de empacotamento e validacao
└── incident-triage/
└── SKILL.md # Passos para symbolication e leitura de crash logs Na memória episódica, cada linha de learnings.jsonl representa um fato atômico ligado a caminhos de arquivos (paths), tags, data da última confirmação e motivo da regra. Guardar o porquê é essencial: quando um desenvolvedor lê meses depois que "o módulo de cache não pode usar NSCache para chaves persistentes", ele sabe imediatamente se a restrição ainda faz sentido após uma mudança de requisito.
{"id":"mem-041","paths":["Modules/Payments/**"],"tags":["swift","currency","tests"],"rule":"Representar valores monetarios em centavos inteiros (Int64) nas camadas de dominio e telemetria; converter para Decimal apenas na formatacao visual.","evidence":"Corrigido no PR #814 apos divergencia de 1 centavo em parcelamento.","verified_at":"2026-09-10","confidence":0.95}
{"id":"mem-042","paths":["scripts/deploy.sh","public_html/**"],"tags":["deploy","cache"],"rule":"Nunca sincronizar arquivos direto via rsync manual na VPS; executar sempre scripts/deploy.sh para limpar Redis e purgar apenas as URLs alteradas na borda.","evidence":"Incidente de cache defasado em producao resolvido em 2026-08-22.","verified_at":"2026-09-18","confidence":1.0} Recuperação determinística com orçamento de tokens e decaimento
Se o arquivo learnings.jsonl chegar a 300 registros ao longo de um ano, injetá-lo inteiro na janela volta a causar poluição de contexto. O recuperador deve combinar filtragem por caminho de arquivo (matching de glob sobre os arquivos que o agente está editando), correspondência de tags e um fator simples de decaimento temporal para entradas antigas nunca reconfirmadas, respeitando um orçamento máximo em tokens (por exemplo, 1.200 tokens para memória episódica).
import fnmatch
import json
from datetime import date
from pathlib import Path
def select_episodic_memories(
jsonl_path: Path,
touched_files: list[str],
task_tags: set[str],
max_chars: int = 4000,
) -> list[dict]:
today = date.today()
scored: list[tuple[float, dict]] = []
for line in jsonl_path.read_text(encoding="utf-8").splitlines():
if not line.strip():
continue
item = json.loads(line)
path_hits = sum(
1
for f in touched_files
if any(fnmatch.fnmatch(f, pattern) for pattern in item.get("paths", []))
)
tag_hits = len(task_tags.intersection(item.get("tags", [])))
if path_hits == 0 and tag_hits == 0:
continue
verified = date.fromisoformat(item["verified_at"])
age_days = max(0, (today - verified).days)
recency_factor = 1.0 / (1.0 + age_days / 180.0)
score = (path_hits * 3.0 + tag_hits * 1.5) * item.get("confidence", 0.8) * recency_factor
scored.append((score, item))
scored.sort(key=lambda pair: pair[0], reverse=True)
selected: list[dict] = []
budget = 0
for _, item in scored:
entry_len = len(item["rule"]) + 80
if budget + entry_len > max_chars:
break
selected.append(item)
budget += entry_len
return selected Esse tipo de recuperação híbrida (regras por caminho de diretório antes de qualquer busca semântica difusa) tem uma vantagem prática grande: é completamente previsível. Se o agente ignorou uma regra, você roda a função localmente com os caminhos alterados e descobre em segundos se o registro não casou no glob, perdeu prioridade pelo decaimento ou estourou o limite de caracteres.
Também vale definir uma ordem clara de precedência para quando duas memórias entram em conflito. Em projetos reais, um módulo específico quase sempre tem exceções em relação à regra geral da empresa. A hierarquia mais limpa segue do mais específico para o mais amplo: instrução explícita do engenheiro na sessão atual vence qualquer registro anterior; regras do AGENTS.md dentro do subdiretório do módulo vencem o AGENTS.md da raiz; e entradas mais recentes em learnings.jsonl com evidência de pull request vencem notas antigas sem revisão. Sempre que uma entrada contradiz outra já gravada, o processo de atualização deve substituir ou arquivar o registro antigo em vez de empilhar os dois no mesmo arquivo.
Equipes maduras tratam essa camada de recuperação como código testável. Um teste simples em CI carrega o arquivo learnings.jsonl, valida o esquema JSON de cada linha (impedindo erros de sintaxe ou datas inválidas), verifica se todos os padrões de paths ainda apontam para diretórios existentes no repositório e roda consultas simuladas para os módulos mais críticos. Quando uma pasta inteira é renomeada em uma refatoração, o teste aponta na hora quais memórias ficaram órfãs e precisam ser atualizadas ou removidas.
Higiene de memória, prevenção de envenenamento e trabalho multiagente
Deixar um agente gravar livremente novas regras na memória permanente sem supervisão humana é uma receita conhecida para degradação progressiva. O modelo pode registrar uma hipótese errada durante uma sessão frustrada de depuração ("este teste sempre falha localmente, ignorar") e passar a repetir o atalho indevido em todas as tarefas futuras. Pior ainda: se o agente processar um issue externo ou um arquivo de terceiro com instruções maliciosas, um ataque de injeção de prompt indireta pode tentar gravar uma regra permanente de exfiltração dentro da memória persistente.
Para evitar esse envenenamento de memória, toda escrita em AGENTS.md ou em learnings.jsonl deve passar por revisão humana em pull request ou por uma etapa explícita de aprovação antes de ir para a branch principal. O agente pode sugerir a nova entrada ao final da sessão, já formatada em JSONL com referência ao erro corrigido, mas o engenheiro decide se ela entra no repositório. Regras de segurança críticas (como bloqueio de comandos destrutivos ou acesso a segredos) nunca devem depender apenas de texto na memória: elas precisam de validação determinística em código, assunto tratado em guardrails e segurança em automações com IA.
Outro ganho aparece quando o time adota múltiplos agentes especializados na mesma entrega, como um agente que implementa uma feature, outro que escreve testes e um terceiro que revisa o diff. Compartilhar a mesma base de memória semântica e episódica garante que o revisor cobre exatamente os padrões que o implementador recebeu no início. Quando o revisor aponta um desvio recorrente em três pull requests seguidos, o time transforma aquela correção em uma linha nova na memória do módulo ou em uma regra automatizada de linter, fechando o ciclo entre aprendizado humano e consistência contínua do código.
