Memória do Agente

1. Visão Geral da Conceito e Problema Sistêmico

Sem memória sistêmica, cada execução de um agente autônomo é totalmente isolada (stateless). O modelo está limitado ao tamanho físico da janela de contexto (Context Window Limit) e, após o encerramento da sessão, perde todas as conclusões extraídas, erros corrigidos e configurações do usuário.

A tentativa de resolver isso "na marra" — enviando todo o histórico antes de cada prompt — leva a três becos sem saída de engenharia críticos:

1. Crescimento exponencial dos custos com tokens e latência (Time to First Token).
2. Degradação da atenção do modelo (Lost-in-the-Middle): um contexto inflado dispersa o mecanismo Self-Attention, provocando a omissão de instruções críticas.
3. Ausência de aprendizado com erros: o agente reincide nos mesmos bugs da base de código que já havia resolvido em sessões anteriores.

A arquitetura Agent Memory separa a persistência de estado em níveis especializados, fornecendo ao agente memória de longo prazo com uso mínimo de tokens.

2. Taxonomia Arquitetural e Modelo Mental

Na engenharia agêntica moderna, a memória é padronizada em quatro camadas funcionais:

• 1. Curto Prazo (Working / Scratchpad Memory): Buffer operacional da iteração atual (loop ReAct). Armazena pensamentos intermediários (thoughts), argumentos de chamadas de ferramentas (tool calls) e respostas do ambiente do sistema. Vive apenas durante o ciclo de vida da tarefa atual (em memória do processo ou Redis).
• 2. Episódica (Episodic Memory): Crônica da experiência passada do agente: sequência de ações, tentativas de execução de tarefas, causas de falhas em testes e fixes encontrados. Permite ao agente lembrar: "Já tentei executar essa migração por este método ontem e ocorreu um deadlock — vou escolher outro caminho".
• 3. Semântica (Semantic Memory): Base de conhecimento extraído, fatos e entidades sobre o mundo externo, o usuário e o repositório. Implementada como uma base estruturada de fatos (Knowledge Graph) ou banco de dados vetorial com embeddings.
• 4. Procedural (Procedural Memory): A "memória muscular" do agente: algoritmos, workflows fixos, sintaxe de ferramentas customizadas, regras de formatação de código e instruções do sistema (incluindo .agents/skills e .agents/rules do repositório).

3. Pipeline Técnico e Mecânica Interna

O ciclo de vida da memória de um agente autônomo é implementado através de um pipeline de 4 etapas:

1. Extraction & Filtering (Extração de Fatos): Um parser LLM leve em background ou extrator heurístico analisa o diálogo concluído ou passo da ferramenta. Ele filtra o ruído comunicacional ("obrigado", "entendido") e extrai fatos atômicos (Atomic Facts).
2. Hybrid Indexing (Indexação Híbrida): As entidades obtidas são gravadas em um armazenamento com índice duplo: vetores densos (Dense Embeddings) para busca semântica + índice BM25/full-text para correspondência exata de identificadores, funções e constantes.
3. Context-Aware Retrieval (Recuperação Seletiva): Antes de gerar a próxima resposta, o ranker calcula uma pontuação integral de relevância da memória pela fórmula: Score = w1 * Relevance + w2 * Recency (decaimento exponencial) + w3 * Importance (importância). Apenas os top-$K$ fragmentos mais importantes são carregados no prompt de trabalho.
4. Memory Compaction & Consolidation (Compactação e Esquecimento): Um processo periódico resume cadeias episódicas antigas em conclusões de alto nível (Recursive Summarization), liberando recursos da base de conhecimento.

4. Cenários Práticos de Engenharia em Produção

01. Contexto Personalizado do Desenvolvedor

O agente registra e armazena automaticamente as regras específicas do desenvolvedor: por exemplo, uso de TypeScript strict, especificidade no tratamento de erros via Result<T, E>, aversão a ver any ou preferência por certas bibliotecas de estado, eliminando a necessidade de repetir isso em cada chat.

02. Contexto Arquitetural da Base de Código

Preservação de decisões tomadas semanas atrás: "Por que o módulo de billing usa uma fila Redis Streams em vez de uma chamada HTTP direta". O agente consulta a memória semântica do repositório antes de sugerir um refactoring perigoso.

03. Sincronização de Estado entre Subagentes

Em arquiteturas Multi-Agent (por exemplo, orquestrador -> coder -> tester), a memória de estado compartilhada permite que o agente-tester recupere instantaneamente todas as hipóteses do agente-arquiteto sem transmitir logs brutos completos.

5. Armadilhas, Erros Comuns e Segurança

• Context Poisoning (Envenenamento da Memória): Se o agente registrar uma alucinação como conhecimento verdadeiro, ele repetirá esse erro em todas as sessões futuras. Proteção: validação de fatos através de uma etapa separada de crítica (Verification Step) e capacidade explícita de deletar memórias falsas via UI/comando.
• Retrieval Dilution (Diluição da Atenção): Um limiar de similaridade (similarity threshold) muito baixo resulta no carregamento de dezenas de memórias irrelevantes, deslocando as instruções atuais do usuário.
• Secret Leakage (Vazamento de Segredos): Armazenamento em repositórios de longo prazo de dados sensíveis (chaves de API, senhas de logs, tokens). Proteção: camada obrigatória de sanitização (Secret Redaction Regex/Entropy detection) no nível do hook pre-save da memória.