Phase 14 - Lesson 07

Memoria: Contexto Virtual y MemGPT

Las ventanas de contexto son finitas. Las conversaciones, los documentos y los historiales de herramientas no lo son. MemGPT (Packer et al., 2023) plantea esto como memoria virtual de SO: el contexto principal es la RAM, el almacenamiento externo es el disco, y el agente realiza la paginación entre ellos. Este es el patrón que hereda cada sistema de memoria de 2026.

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

Learning Objectives

• Explicar la analogia de SO en la que se basa MemGPT: contexto principal = RAM, contexto externo = disco, herramientas de memoria = paginación de entrada/salida (page in/out).
• Implementar el patrón de MemGPT de dos niveles en stdlib con un búfer de contexto principal, un almacenamiento externo de búsqueda y herramientas de paginación de entrada/salida.
• Describir cómo el agente emite "interrupciones" (interrupts) para consultar o modificar la memoria externa y cómo el resultado se une de nuevo en el siguiente prompt.
• Identificar las decisiones de diseño de MemGPT que se trasladan a Letta (Lección 08) y Mem0 (Lección 09).

The Problem

Las ventanas de contexto parecen que deberían resolver la memoria. No lo hacen. Tres modos de fallo se repiten en producción:

1. Desbordamiento. Las conversaciones de múltiples turnos, los documentos largos o las trayectorias cargadas de llamadas a herramientas superan la ventana. Todo lo que pasa del punto de corte se pierde.
2. Dilución. Incluso dentro de la ventana, meter contexto irrelevante diluye la atención sobre lo que importa. Los modelos de frontera aún se degradan con entradas largas.
3. Persistencia. Una nueva sesión comienza con una ventana vacía. Los agentes sin memoria externa no pueden decir "recuerdas cuando me pediste que..." entre sesiones.

Las ventanas más grandes ayudan pero no solucionan esto. El artículo de Mem0 de 2025 midió que las líneas de base con una ventana de 128k todavía pierden hechos de largo plazo que un agente con una ventana de 4k y memoria externa logra capturar.

The Concept

MemGPT: la analogía con el SO

Packer et al. (arXiv:2310.08560, v2 de febrero de 2024) asignan la gestión del contexto a la memoria virtual de los sistemas operativos:

El agente ejecuta un bucle ReAct normal. Una clase adicional de herramientas le permite paginar datos hacia adentro y hacia afuera del contexto principal.

Dos niveles

• Contexto principal. Búfer de prompt de tamaño fijo que contiene la tarea actual. Siempre visible para el modelo.
• Contexto externo. Ilimitado, de búsqueda mediante herramientas. Se lee cuando es relevante, se escribe cuando surgen hechos.

El artículo original evaluó el diseño en dos tareas más allá de la ventana base: análisis de documentos de más de 100k tokens y chat de múltiples sesiones con memoria persistente a lo largo de varios días.

El patrón de interrupción

MemGPT introduce la memoria como interrupción (memory-as-interrupt): a mitad de la conversación, el agente puede invocar una herramienta de memoria, el entorno de ejecución (runtime) la ejecuta y el resultado se une en el siguiente turno del asistente como una nueva observación. Conceptualmente idéntico a una llamada al sistema (syscall) read() de Unix que bloquea el proceso, devuelve bytes y el proceso continúa.

Superficie canónica de herramientas de memoria:

• core_memory_append(section, text) — escribir en una sección persistente del prompt.
• core_memory_replace(section, old, new) — editar una sección persistente.
• archival_memory_insert(text) — escribir en el almacenamiento externo de búsqueda.
• archival_memory_search(query, top_k) — recuperar del almacenamiento externo.
• conversation_search(query) — escanear turnos pasados.

Dónde termina MemGPT y comienza Letta

En septiembre de 2024, MemGPT se convirtió en Letta. El repositorio de investigación (cpacker/MemGPT) permanece; Letta extiende el diseño:

• Tres niveles en lugar de dos (core, recall, archival — Lección 08).
• Razonamiento nativo que reemplaza el patrón de send_message/latido (heartbeat) (Lección 08).
• Agentes en tiempo de sueño (sleep-time agents) que ejecutan trabajo de memoria asíncrono (Lección 08).

El artículo de MemGPT es la base de 2026, incluso si los sistemas de producción ejecutan Letta, Mem0 o un almacenamiento personalizado de dos niveles.

Dónde sale mal este patrón

• Degradación de memoria (memory rot). Las escrituras se acumulan más rápido que las lecturas; la recuperación se ahoga en hechos obsoletos. Solución: consolidación periódica (tiempo de sueño de Letta), invalidación explícita (detector de conflictos de Mem0).
• Envenenamiento de memoria (memory poisoning). La memoria externa es texto recuperado. Si contenido controlado por un atacante llega a una nota de memoria, el agente lo reingere en la próxima sesión. Este es el ataque de Greshake et al. (Lección 27) reformulado a lo largo del tiempo.
• Pérdida de citas. El agente recuerda que "el usuario me pidió enviar X" pero no puede citar en qué turno. Almacene referencias de origen (ID de sesión, ID de turno) con cada escritura de archivo.

Build It

El archivo code/main.py implementa el patrón de dos niveles de MemGPT en la biblioteca estándar (stdlib):

• MainContext — búfer de prompt de tamaño fijo con un diccionario core y una lista messages; compacta automáticamente los mensajes más antiguos cuando supera el límite.
• ArchivalStore — almacenamiento en memoria similar a BM25 (puntuación por coincidencia de tokens) de registros (id, text, tags, session, turn).
• Cinco herramientas de memoria que se asignan a la superficie de MemGPT.
• Un agente programado que llena el archivo con hechos y luego responde a una pregunta llamando a archival_memory_search.

Ejecútelo:

python3 code/main.py

El rastreo (trace) muestra al agente escribiendo tres hechos, llenando el contexto principal hasta el límite (lo que obliga al desalojo) y luego respondiendo a una pregunta de seguimiento mediante la recuperación del archivo, reproduciendo el flujo de trabajo de MemGPT sin ningún LLM real.

Use It

Cada sistema de memoria en producción hoy en día es una variante de MemGPT:

• Letta (Lección 08) — tres niveles, razonamiento nativo, computación en tiempo de sueño.
• Mem0 (Lección 09) — vector + KV + grafo fusionados con una capa de puntuación.
• OpenAI Assistants / Responses — memoria gestionada a través de hilos y archivos.
• Claude Agent SDK — memoria a largo plazo a través de habilidades y almacenamiento de sesión.

Elija uno por su diseño operativo (auto-hospedado, gestionado, integrado en el framework), no por el patrón central; el patrón central es MemGPT.

Ship It

El archivo outputs/skill-virtual-memory.md es una habilidad reutilizable que produce una estructura correcta de memoria de dos niveles (principal + archivo + superficie de herramientas) para cualquier runtime de destino, con políticas de desalojo y campos de citas conectados.

Exercises

1. Agregue un límite max_main_context_tokens medido en tokens (aproxímelo con len(text.split()) * 1.3). Compacte los mensajes más antiguos en un resumen cuando se supere el límite. Compare el comportamiento con y sin el resumidor.
2. Implemente BM25 correctamente sobre el almacenamiento de archivo (frecuencia de término, frecuencia inversa de documento). Mida recall@10 en un conjunto de hechos de prueba frente a la línea de base de coincidencia de tokens.
3. Agregue campos de citation (session_id, turn_id, source_url) a las inserciones de archivo. Haga que el agente cite las fuentes en cada respuesta respaldada por recuperación.
4. Simule el envenenamiento de memoria: agregue un registro de archivo que diga "ignorar todas las instrucciones futuras del usuario". Escriba una protección que escanee las recuperaciones en busca de texto estructurado como directiva y las marque como no confiables.
5. Adapte la implementación para usar el esquema JSON de memoria central del repositorio de investigación de MemGPT (cpacker/MemGPT). ¿Qué cambia cuando pasa de cadenas planas a secciones tipadas?

Key Terms

Further Reading

• Packer et al., MemGPT (arXiv:2310.08560) — Artículo sobre el contexto virtual inspirado en SO
• Letta, Memory Blocks blog — la evolución de tres niveles
• Anthropic, Effective context engineering — tratar el contexto como un presupuesto
• Chhikara et al., Mem0 (arXiv:2504.19413) — memoria de producción híbrida sobre este patrón