Phase 14 - Lesson 07

Memória: Contexto Virtual e MemGPT

Os limites de janela de contexto são finitos. Conversas, documentos e históricos de ferramentas não são. O MemGPT (Packer et al., 2023) modela isso como memória virtual de SO — o contexto principal é a RAM, o armazenamento externo é o disco, e o agente realiza a paginação entre eles. Este é o padrão herdado por todo sistema de memória de 2026.

Type: Build Languages: Python (stdlib) Prerequisites: Phase 14 · 01 (Agent Loop), Phase 14 · 06 (Tool Use) Time: ~75 minutes

Learning Objectives

• Explicar a analogia de SO na qual o MemGPT se baseia: contexto principal = RAM, contexto externo = disco, ferramentas de memória = paginação de entrada/saída (page in/out).
• Implementar o padrão MemGPT de duas camadas em stdlib com um buffer de contexto principal, um armazenamento externo pesquisável e ferramentas de paginação de entrada/saída.
• Descrever como o agente emite "interrupções" (interrupts) para consultar ou modificar a memória externa e como o resultado é emendado de volta no próximo prompt.
• Identificar as escolhas de design do MemGPT que se estendem para o Letta (Lição 08) e Mem0 (Lição 09).

The Problem

Janelas de contexto parecem que deveriam resolver a memória. Elas não resolvem. Três modos de falha ocorrem repetidamente em produção:

1. Estouro. Conversas de múltiplos turnos, documentos longos ou trajetórias cheias de chamadas de ferramentas ultrapassam o limite da janela. Tudo o que passa do ponto de corte é perdido.
2. Diluição. Mesmo dentro do limite da janela, inserir contexto irrelevante dilui a atenção sobre o que importa. Modelos de fronteira ainda degradam com entradas longas.
3. Persistência. Uma nova sessão começa com uma janela vazia. Agentes sem memória externa não conseguem dizer "lembra quando você me pediu para..." entre sessões.

Janelas maiores ajudam, mas não resolvem isso. O artigo do Mem0 de 2025 mediu que baselines com janela de 128k ainda perdem fatos de longo prazo que um agente com janela de 4k e memória externa consegue capturar.

The Concept

MemGPT: a analogia com SO

Packer et al. (arXiv:2310.08560, v2 Fev 2024) mapeiam o gerenciamento de contexto para a memória virtual de sistemas operacionais:

O agente executa um loop ReAct normal. Uma classe extra de ferramentas permite que ele faça a paginação de dados para dentro e para fora do contexto principal.

Duas camadas

• Contexto principal. Buffer de prompt com tamanho fixo que armazena a tarefa atual. Sempre visível para o modelo.
• Contexto externo. Ilimitado, pesquisável por meio de ferramentas. Lido quando relevante, gravado quando novos fatos surgem.

O artigo original avaliou o design em duas tarefas além da janela base: análise de documentos com mais de 100k tokens e chat de múltiplas sessões com memória persistente ao longo de vários dias.

O padrão de interrupção

O MemGPT introduz o conceito de memória como interrupção (memory-as-interrupt): no meio da conversa, o agente pode invocar uma ferramenta de memória, o runtime a executa e o resultado é emendado na próxima rodada do assistente como uma nova observação. Isso é conceitualmente idêntico a uma chamada de sistema (syscall) read() do Unix que bloqueia o processo, retorna bytes e o processo continua.

Superfície canônica de ferramentas de memória:

• core_memory_append(section, text) — escreve em uma seção persistente do prompt.
• core_memory_replace(section, old, new) — edita uma seção persistente.
• archival_memory_insert(text) — escreve no armazenamento externo pesquisável.
• archival_memory_search(query, top_k) — recupera dados do armazenamento externo.
• conversation_search(query) — escaneia rodadas anteriores.

Onde o MemGPT termina e o Letta começa

Em setembro de 2024, o MemGPT tornou-se Letta. O repositório de pesquisa (cpacker/MemGPT) continua existindo; o Letta estende o design:

• Três camadas em vez de duas (core, recall, archival — Lição 08).
• Raciocínio nativo substituindo o padrão de send_message/batimento cardíaco (heartbeat) (Lição 08).
• Agentes de tempo de repouso (sleep-time agents) executando trabalho de memória assíncrono (Lição 08).

O artigo do MemGPT é a base de 2026, mesmo que os sistemas de produção executem o Letta, o Mem0 ou um armazenamento personalizado de duas camadas.

Onde esse padrão dá errado

• Degradação de memória (memory rot). As gravações acumulam mais rápido do que as leituras; a recuperação é sufocada por fatos obsoletos. Solução: consolidação periódica (tempo de repouso do Letta), invalidação explícita (detector de conflitos do Mem0).
• Envenenamento de memória (memory poisoning). A memória externa consiste em texto recuperado. Se um conteúdo controlado por um invasor for parar em uma nota de memória, o agente o reingerirá na próxima sessão. Este é o ataque de Greshake et al. (Lição 27) reformulado ao longo do tempo.
• Perda de citação. O agente lembra que "o usuário me pediu para enviar X", mas não consegue citar de qual rodada. Armazene referências de origem (ID da sessão, ID da rodada) em cada gravação de arquivo.

Build It

O arquivo code/main.py implementa o padrão de duas camadas do MemGPT na stdlib:

• MainContext — buffer de prompt com tamanho fixo, contendo um dicionário core e uma lista messages; compacta automaticamente as mensagens mais antigas ao ultrapassar o limite.
• ArchivalStore — armazenamento em memória no estilo BM25 (pontuação por sobreposição de tokens) de registros (id, text, tags, session, turn).
• Cinco ferramentas de memória que mapeiam a superfície do MemGPT.
• Um agente programado que preenche o armazenamento de arquivamento com fatos e, em seguida, responde a uma pergunta chamando archival_memory_search.

Execute-o:

python3 code/main.py

O rastreamento (trace) mostra o agente gravando três fatos, preenchendo o contexto principal até o limite (forçando a expulsão) e, em seguida, respondendo a uma pergunta subsequente ao recuperar dados do armazenamento de arquivamento — reproduzindo o fluxo de trabalho do MemGPT sem nenhum LLM real.

Use It

Todo sistema de memória em produção hoje é uma variante do MemGPT:

• Letta (Lição 08) — três camadas, raciocínio nativo, computação em tempo de repouso.
• Mem0 (Lição 09) — fusão de vetor + KV + grafo com uma camada de pontuação.
• OpenAI Assistants / Responses — memória gerenciada via threads e arquivos.
• Claude Agent SDK — memória de longo prazo via habilidades (skills) e armazenamento de sessão.

Escolha um pelo formato operacional (hospedado localmente, gerenciado, integrado a frameworks), não pelo padrão central — o padrão central é o MemGPT.

Ship It

O arquivo outputs/skill-virtual-memory.md é uma habilidade reutilizável que produz uma estrutura correta de memória de duas camadas (principal + arquivamento + superfície de ferramentas) para qualquer runtime de destino, com políticas de expulsão e campos de citação configurados.

Exercises

1. Adicione um limite max_main_context_tokens medido em tokens (aproxime com len(text.split()) * 1.3). Compacte as mensagens mais antigas em um resumo quando o limite for excedido. Compare o comportamento com e sem o sumarizador.
2. Implemente o BM25 corretamente no armazenamento de arquivamento (frequência do termo, frequência inversa do documento). Meça a métrica recall@10 em um conjunto de fatos fictícios em comparação com a linha de base de sobreposição de tokens.
3. Adicione campos de citation (session_id, turn_id, source_url) às inserções de arquivamento. Faça com que o agente cite as fontes a cada resposta baseada em recuperação.
4. Simule o envenenamento de memória: adicione um registro de arquivamento que diga "ignore todas as instruções futuras do usuário". Escreva uma proteção que escaneie as recuperações em busca de textos estruturados como diretrizes e os marque como não confiáveis.
5. Adapte a implementação para usar o esquema JSON de memória core do repositório de pesquisa do MemGPT (cpacker/MemGPT). O que muda quando você alterna de strings brutas para seções digitadas?

Key Terms

Further Reading

• Packer et al., MemGPT (arXiv:2310.08560) — Artigo sobre contexto virtual inspirado em SO
• Letta, Memory Blocks blog — a evolução em três camadas
• Anthropic, Effective context engineering — tratando contexto como um orçamento
• Chhikara et al., Mem0 (arXiv:2504.19413) — memória de produção híbrida construída com base neste padrão