Arquitectura de memoria para AI Agent: checkpoints y vector stores

Viacheslav Dubrov

2026-02-14 · Actualizado 2026-08-01 · 22 min · Agentes de IA

Traducción automática Este artículo se tradujo automáticamente a partir de la versión original en inglés.

Un reasoning loop solo sobrevive a una petición si su estado se almacena fuera del worker. Sin memoria del agente, el agente no puede reanudar un plan pausado, recuperarse tras un fallo ni recordar una preferencia de una sesión anterior. La Parte 1 cubría el flujo de control. En este artículo se identifica qué estado necesita cada turno posterior y dónde debería residir.

Usaré el Market Analyst Agent —un agente pequeño de LangGraph que obtiene datos de mercado y redacta un informe de analista— como referencia para hablar de hot checkpoints. Las secciones sobre cold vectors y Markdown en bruto son diseños ilustrativos independientes que muestran extensiones que el proyecto actual todavía no implementa. Después explicaré cuándo tiene sentido usar PostgreSQL, Redis, Qdrant, key-value stores y archivos Markdown sin más.

Todos los stores que aparecen a continuación los lee el harness, el código que dirige el loop alrededor del modelo. El harness decide qué contenido llega a la ventana de contexto; los stores no. Este artículo trata sobre dónde reside ese estado antes de que el harness lo utilice. La Parte 3 y la Parte 4 explican qué hace después el harness con el prompt.

¿Qué es la memoria de un AI agent?

La memoria de un AI agent es la capa de estado que permite conservar el progreso de una tarea, recuperar conocimiento previo y actualizar lo que el agente sabe entre ejecuciones. En producción no es una única base de datos vectorial. Es una combinación de hot checkpoints, stores semánticos o estructurados en frío y document memory legible para las personas.

No empieces por la memoria porque suene inteligente. Empieza por el fallo visible para el usuario: perder el progreso, olvidar una preferencia, repetir una investigación o no reutilizar una convención del proyecto.

Fallos que requieren memoria

Un agente stateless puede responder a una pregunta aislada, pero olvida la petición en cuanto termina la llamada. Ese diseño falla cuando el producto necesita cualquiera de los siguientes comportamientos:

• Pausar y reanudar: un usuario inicia una tarea de investigación, cierra el portátil y vuelve al día siguiente. Sin estado checkpointed, el agente empieza desde cero.
• Coherencia multi-turn: durante una conversación larga, el agente debe recordar qué tools llamó, qué datos recopiló y qué pasos del plan completó.
• Personalización: un usuario que vuelve espera que el agente conozca su tolerancia al riesgo, el nivel de profundidad del análisis que prefiere y sus interacciones anteriores.
• Human-in-the-loop (HITL): el agente recopila pruebas y espera a que una persona apruebe el siguiente paso. El estado de «espera» debe sobrevivir a los reinicios del proceso.

En el Market Analyst Agent de la Parte 1, la petición «Analyze NVDA» genera un plan, cinco tool calls, datos recopilados y un borrador de informe. Cuando el usuario responde «looks good, but add competitor analysis», un checkpoint store permite cargar el estado del último paso completado y añadir el paso de análisis de competidores. Sin estado checkpointed, el agente no puede resolver a qué se refiere «looks good» y tiene que empezar de nuevo.

La memoria a largo plazo cubre un caso diferente. Si el usuario vuelve una semana después y pregunta «Update my NVDA analysis», quizá el agente deba recordar una preferencia por evaluaciones de riesgo conservadoras y su interés por las acciones de empresas de semiconductores. Un memory store respaldado por vectores puede recuperar esos hechos entre sesiones sin volver a preguntárselos.

Los ejemplos de implementación siguientes utilizan LangGraph, la librería open source de LangChain para crear agentes como grafos de estado explícitos; las fronteras de almacenamiento que establece se generalizan a cualquier framework. LangGraph separa la memoria por ámbito. Cada ejecución del grafo se realiza dentro de un thread, es decir, una conversación o tarea. El estado persistido dentro de ese thread es short-term memory. El estado compartido entre threads es long-term memory. A continuación, «thread» y «conversation» son intercambiables; evito «session» para ese ámbito porque la Parte 5 reserva ese término para el log durable de una ejecución, de las que varias pueden acumularse en un mismo thread. El contexto actual del modelo y las variables en proceso forman la capa de working memory por encima de ambos stores.

Taxonomía de la memoria de un AI agent

Antes de entrar en la implementación, resulta útil clasificar qué necesitan recordar los agentes. El framework CoALA —Cognitive Architectures for Language Agents (Sumers, Yao et al., 2023)— es una taxonomía muy citada basada en la ciencia cognitiva. Introduje el ámbito de la memoria en mi artículo sobre context engineering; aquí lo amplío a seis categorías:

La working memory es aquello con lo que el LLM está razonando activamente: variables de Python en la función actual, contenido de la ventana de contexto y argumentos de tool calls durante la ejecución. Es la capa más rápida y efímera. Nada persiste más allá del paso actual. La working memory está limitada por la ventana de contexto del modelo, lo que la convierte en el cuello de botella. Todo lo que el agente «sabe» en el momento de decidir debe caber aquí, ya proceda del checkpoint store, de una consulta vectorial o de la lectura de un archivo. Las demás capas existen para introducir la información adecuada en la working memory en el momento adecuado.

La short-term memory es el checkpoint que LangGraph escribe tras cada unidad de ejecución del grafo —un super-step, definido en la sección siguiente—. Las memorias episódica y semántica persisten entre threads. La document memory almacena notas del proyecto, resúmenes de investigación y convenciones aprendidas en archivos que pueden inspeccionar tanto las personas como los agentes. La procedural memory vive en las instrucciones del sistema y las definiciones de tools, en lugar de cambiar para cada usuario.

Para la implementación, cinco de esas seis categorías se agrupan en tres capas de almacenamiento. La short-term memory se convierte en hot memory, el checkpoint del thread actual. La memoria episódica y la semántica se convierten en cold memory, la recuperación entre threads. La document memory mantiene legible y editable directamente el conocimiento acumulado del proyecto. La working memory aparece agrupada con la hot tier en la taxonomía anterior, pero es la única que en realidad nunca se almacena: vive durante un único paso, en proceso, y es la ventana de contexto en la que cargan las tres capas de almacenamiento. La procedural memory queda fuera de las tres: vive en el system prompt y las definiciones de tools, por lo que se distribuye con el agente en lugar de almacenarse y recuperarse.

CoALA clasifica la memoria working, episódica, semántica y procedural. El estudio Memory in the Age of AI Agents pone el énfasis en los vector stores y los knowledge graphs, mientras que LangGraph documenta los checkpoints y su interfaz Store. El conocimiento de proyecto respaldado por archivos queda fuera de esas taxonomías, aunque Claude Code, Cursor y Devin Desktop cargan archivos de proyecto persistentes.

El mismo patrón de almacenamiento aparece en otros ámbitos. Un agente de Minecraft (Voyager) guarda skills reutilizables como librerías de código, equipos de una competición empresarial de document-QA iteran sobre documentos procedurales de prompts y los web agents inducen workflows de navegación reutilizables a partir de ejecuciones satisfactorias. Volveré más adelante sobre los tres casos; aquí, la idea es que los archivos hacen que ese conocimiento sea inspeccionable y versionable sin un servicio de embeddings separado.

La memoria gestionada por el agente también se diferencia de un pipeline RAG fijo por quién realiza la escritura. El agente o su harness selecciona qué almacenar, actualizar y eliminar, y más tarde decide cuándo recuperarlo.

El artículo Generative Agents (Park et al., 2023) mostró hasta dónde puede llegar este enfoque: los agentes simulados almacenaban, reflexionaban sobre y recuperaban sus propias memorias. Su memory stream clasificaba los candidatos por recencia, importancia y relevancia, un diseño que sigue siendo una referencia útil para la recuperación en sistemas de memoria de agentes.

Memoria a corto plazo del agente: el checkpoint store

Cada vez que LangGraph termina un super-step —un nodo o un conjunto de nodos ejecutados en paralelo—, el framework serializa el estado completo del grafo y lo escribe en un checkpoint store. Esta es la base de los workflows de pausa/reanudación, la depuración time-travel y los flujos HITL.

Un checkpoint contiene el estado del grafo necesario para reanudarlo: el AgentState de la Parte 1 —mensajes, identidad, perfil del usuario, pasos del plan, datos de investigación y modo de ejecución—. Además, LangGraph almacena su propia información de control: el ID y la marca temporal del checkpoint, una versión por canal (el nombre que LangGraph da a cada clave de estado individual) y un registro separado de las versiones de canal que ya ha visto cada nodo. El número de paso reside en los metadatos del checkpoint, no en el checkpoint propiamente dicho. Comparar ambos elementos permite al grafo determinar qué debe ejecutarse a continuación. Tras una interrupción HITL o un reinicio del proceso, el grafo carga el checkpoint escrito en el último límite completado y vuelve a entrar en el nodo siguiente. No continúa desde una línea de Python arbitraria. Un checkpoint también es diferente de un event log append-only o de una trace; la Parte 5 separa explícitamente esas superficies de observabilidad del runtime.

Cómo funciona el checkpointing en LangGraph

El BaseCheckpointSaver de LangGraph es una interfaz sencilla: put() escribe un checkpoint, get_tuple() lee el último para un thread y list() devuelve el historial. Cada checkpoint se identifica mediante (thread_id, checkpoint_ns, checkpoint_id), donde thread_id identifica la conversación, checkpoint_ns gestiona el namespacing de los subgrafos y checkpoint_id es una versión única.

La decisión importante es qué backend colocar detrás. PostgreSQL y Redis son dos opciones habituales en producción.

PostgreSQL frente a Redis

Los benchmarks genéricos de bases de datos no predicen el rendimiento de los checkpoints. Mide el tamaño del estado serializado, la frecuencia de escritura, la configuración de persistencia y la concurrencia de tu propio grafo.

PostgreSQL: el valor predeterminado durable

PostgreSQL es la opción predeterminada más segura para la mayoría de los equipos. Los checkpoints sobreviven a los fallos, obtienes semántica transaccional completa y el historial de checkpoints simplifica la depuración time-travel.

Una versión simplificada de la configuración del checkpoint en memory/hot.py. En producción, establece LANGGRAPH_STRICT_MSGPACK=true o configura una allowlist explícita de allowed_msgpack_modules para que la deserialización de checkpoints solo permita tipos seguros o declarados; el valor predeterminado permisivo avisa sobre tipos no registrados, pero los permite.

import asyncio
from contextlib import asynccontextmanager

from langchain_core.messages import HumanMessage
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

@asynccontextmanager
async def postgres_checkpointer(connection_string: str):
    """Yield a PostgreSQL-backed checkpoint store.

    PostgreSQL gives us ACID guarantees — if a checkpoint write succeeds,
    the state is durable even if the process crashes immediately after.
    `from_conn_string` is itself an async context manager: it owns the
    connection and closes it on exit, so the graph has to run inside it.
    """
    async with AsyncPostgresSaver.from_conn_string(connection_string) as checkpointer:
        # Create the checkpoint tables if they don't exist.
        # This is idempotent — safe to call on every startup.
        await checkpointer.setup()
        yield checkpointer

async def main() -> None:
    # The graph lives inside the context manager's scope.
    async with postgres_checkpointer(
        "postgresql://user:pass@localhost:5432/agent_memory"
    ) as checkpointer:
        graph = create_graph(checkpointer=checkpointer)

        # Every invoke/stream call now persists state automatically.
        config = {"configurable": {"thread_id": "user-123-session-1"}}
        result = await graph.ainvoke(
            {"messages": [HumanMessage(content="Analyze NVDA")]}, config
        )

        # Resume later on the same thread_id — loads the latest checkpoint.
        result = await graph.ainvoke(
            {"messages": [HumanMessage(content="approved")]}, config
        )

asyncio.run(main())

El AsyncPostgresSaver utiliza el paquete langgraph-checkpoint-postgres, que crea cuatro tablas: checkpoints (el estado serializado), checkpoint_blobs (datos binarios grandes), checkpoint_writes (escrituras pendientes para la recuperación tras fallos) y checkpoint_migrations (versión del esquema). Los escritores concurrentes se separan mediante la clave primaria (thread_id, checkpoint_ns, checkpoint_id) y upserts, no mediante bloqueos: dos workers sobre el mismo thread no se corromperán entre sí, pero tampoco se coordinarán.

Redis: cuando la latencia es el cuello de botella

Cuando la latencia de los checkpoints es el cuello de botella, Redis es una opción para el estado recuperable. Mide el tamaño del estado serializado, la configuración de persistencia y la concurrencia antes de elegirlo frente a PostgreSQL.

Una versión simplificada de la configuración del checkpoint en memory/hot.py:

import asyncio
from contextlib import asynccontextmanager

from langgraph.checkpoint.redis.aio import AsyncRedisSaver

@asynccontextmanager
async def redis_checkpointer(redis_url: str):
    """Yield a Redis-backed checkpoint store.

    Redis keeps checkpoints in memory for low-latency access.
    Trade-off: less durable than PostgreSQL unless you enable AOF,
    Redis's append-only log — snapshots alone lose recent writes on a crash.
    """
    async with AsyncRedisSaver.from_conn_string(redis_url) as checkpointer:
        # Initialize Redis data structures
        await checkpointer.asetup()
        yield checkpointer

async def main() -> None:
    # Same graph API, different backend.
    async with redis_checkpointer("redis://localhost:6379") as checkpointer:
        graph = create_graph(checkpointer=checkpointer)

asyncio.run(main())

El AsyncRedisSaver de langgraph-checkpoint-redis almacena cada checkpoint como un documento RedisJSON independiente, bajo la misma clave (thread_id, checkpoint_ns, checkpoint_id) que el saver de Postgres. El rediseño de la v0.1.0 sustituyó varias operaciones de búsqueda por una única llamada JSON.GET, reduciendo considerablemente la latencia. Redis 8.0+ incluye RedisJSON y RediSearch de forma predeterminada; no es necesario instalar módulos adicionales.

En despliegues limitados por memoria, ShallowRedisSaver almacena únicamente el último checkpoint de cada thread: no hay historial, pero el uso de RAM es mínimo. Úsalo cuando necesites pausar y reanudar, pero no la depuración time-travel.

Cuándo usar cada uno

Usa PostgreSQL cuando:

• Necesites el historial completo de checkpoints para depuración time-travel o reanudación reproducible.
• La durabilidad sea innegociable (servicios financieros, sanidad).
• Ya ejecutes PostgreSQL en tu stack.
• Tu agente ejecute tareas largas en las que perder el estado implique horas de recomputación.
• Quieras un unified data store: PostgreSQL con pgvector puede ser un único backend para checkpoints, memoria a largo plazo y búsqueda vectorial.

Usa Redis cuando:

• La latencia de los checkpoints sea tu cuello de botella (chat en tiempo real, UX de streaming).
• Estés creando voice bots o experiencias de streaming en las que el acceso al checkpoint esté en una ruta crítica cuya latencia se mida.
• Necesites escalar horizontalmente entre muchos threads concurrentes.
• Tengas patrones de fan-out con alta concurrencia en los que varios agentes compartan estado.
• Trabajes con sesiones de corta duración en las que perder un checkpoint sea recuperable.
• Quieras semantic caching para reducir llamadas redundantes al LLM (Redis LangCache almacena en caché consultas semánticamente similares para evitar llamadas repetidas al LLM).

Otras opciones: langgraph-checkpoint-sqlite funciona para desarrollo local y despliegues de un único proceso. En stacks nativos de AWS, langgraph-checkpoint-aws proporciona un DynamoDBSaver con offloading automático del payload: los checkpoints pequeños (<350 KB) permanecen en DynamoDB y los grandes se vuelcan a S3. El precio serverless y la ausencia de infraestructura que gestionar lo hacen atractivo para despliegues con carga variable.

Memoria a largo plazo: recordar entre sesiones

La hot memory gestiona la conversación actual. La memoria a largo plazo cubre al usuario que vuelve la semana siguiente: almacena hechos, preferencias e historial de interacciones que persisten entre threads.

LangGraph proporciona una interfaz Store para la memoria entre threads mediante su clase BaseStore. Cada elemento de memoria es un par (namespace, key) con un valor JSON y un embedding vectorial opcional. El namespace suele codificar el usuario o la organización: ("user", "user-123", "preferences").

Almacenamiento vectorial: recuperación semántica con Qdrant

Cuando el agente necesita recordar hechos no estructurados («¿Qué dijo el usuario sobre su horizonte de inversión?»), la búsqueda vectorial proporciona recuperación semántica. En lugar de buscar claves exactas, el agente consulta por significado.

Qdrant es una base de datos vectorial especializada escrita en Rust que gestiona el almacenamiento de embeddings, la indexación (Hierarchical Navigable Small World, o HNSW) y la búsqueda con filtros. Expliqué HNSW y sus contrapartidas en detalle en mi artículo sobre search ranking. Qdrant también ofrece un servidor MCP que actúa como capa de memoria semántica, útil si tu framework de agentes admite el Model Context Protocol.

El diseño de Qdrant siguiente es independiente e ilustrativo. No es una versión simplificada del memory/long.py actual. El proyecto actual almacena perfiles de usuario con filtrado exacto mediante user_id y un placeholder de vector cero. La integración real de embeddings queda para más adelante. El request handler debe autenticar la petición y construir principal a partir de la identidad verificada; el cliente nunca lo proporciona. El filtro de Qdrant define el ámbito de recuperación, no la autorización.

from qdrant_client import QdrantClient
from qdrant_client.models import (
    PointStruct, Distance, VectorParams, Filter, FieldCondition, MatchValue,
)
import hashlib
from dataclasses import dataclass

@dataclass(frozen=True)
class AuthenticatedPrincipal:
    """Created by the server after authentication, never from request JSON."""
    user_id: str

class UserMemoryStore:
    """Long-term memory backed by Qdrant vector search.

    Stores user facts as embedded vectors for semantic retrieval.
    Each fact is a short natural-language statement about the user.
    """

    def __init__(self, qdrant_url: str, collection_name: str = "user_memory"):
        self.client = QdrantClient(url=qdrant_url)
        self.collection_name = collection_name
        self._ensure_collection()

    def _ensure_collection(self):
        """Create the collection if it doesn't exist."""
        collections = [c.name for c in self.client.get_collections().collections]
        if self.collection_name not in collections:
            self.client.create_collection(
                collection_name=self.collection_name,
                vectors_config=VectorParams(
                    size=1536,  # text-embedding-3-small dimensions
                    distance=Distance.COSINE,
                ),
            )

    def store_fact(
        self, principal: AuthenticatedPrincipal, fact: str, embedding: list[float]
    ):
        """Store a user fact with its embedding."""
        point_id = hashlib.md5(f"{principal.user_id}:{fact}".encode()).hexdigest()
        self.client.upsert(
            collection_name=self.collection_name,
            points=[PointStruct(
                id=point_id,
                vector=embedding,
                payload={"user_id": principal.user_id, "fact": fact},
            )],
        )

    def recall(
        self,
        principal: AuthenticatedPrincipal,
        query_embedding: list[float],
        top_k: int = 5,
    ):
        """Retrieve the most relevant facts for a user given a query."""
        results = self.client.query_points(
            collection_name=self.collection_name,
            query=query_embedding,
            query_filter=Filter(
                must=[FieldCondition(
                    key="user_id", match=MatchValue(value=principal.user_id)
                )]
            ),
            limit=top_k,
        )
        return [hit.payload["fact"] for hit in results.points]

El flujo tiene tres pasos. En este diseño ilustrativo, un LLM extrae hechos clave de la interacción («el usuario tiene una tolerancia al riesgo alta», «al usuario le interesan las acciones de empresas de semiconductores»). Esos hechos se convierten en embeddings y se almacenan en Qdrant. Al inicio de la conversación siguiente, el servidor proporciona el principal autenticado y el agente consulta Qdrant con el nuevo mensaje del usuario para recuperar contexto relevante. El Market Analyst Agent actual todavía no implementa este flujo de extracción semántica y generación de embeddings.

Scoring de la recuperación: más allá de la similitud coseno

La similitud coseno en bruto es un punto de partida, pero los sistemas de memoria en producción necesitan una recuperación más rica. El artículo Generative Agents (Park et al., 2023) introdujo una función de scoring que combina tres señales:

• Recencia: decaimiento basado en reglas para que las memorias recientes obtengan una puntuación mayor. Una función de decaimiento exponencial hace que un hecho de ayer supere a un hecho equivalente de hace seis meses.
• Importancia: relevancia estimada por un LLM en una escala de 1 a 10. «La cartera del usuario ha caído un 40 %» obtiene más puntuación que «el usuario ha dicho hola».
• Relevancia: similitud coseno entre el embedding de la consulta y el hecho almacenado.

La puntuación final de recuperación es una suma ponderada: score = alpha * recency + beta * importance + gamma * relevance. Así se evita que los hechos recientes e importantes queden enterrados bajo otros obsoletos pero semánticamente similares. Para un agente como el Market Analyst Agent, empezaría con alpha = 0.3 para la recencia, beta = 0.2 para la importancia y gamma = 0.5 para la relevancia, porque la intención de la consulta actual del usuario es lo que más importa. Son pesos iniciales adaptados del artículo Generative Agents (que utilizaba pesos iguales); observé que dar más peso a la relevancia funcionaba mejor en consultas de análisis financiero, pero los valores se basan en la intuición, no en una optimización empírica.

Alternativas a la búsqueda vectorial

La búsqueda vectorial es potente, pero no siempre es la herramienta adecuada. Estas son las situaciones en las que conviene usar alternativas:

Los key-value stores funcionan bien con datos estructurados. Si tu memoria a largo plazo es un perfil de usuario —tolerancia al riesgo, horizonte de inversión y sectores preferidos—, un hash de Redis o una columna JSONB de PostgreSQL es más simple y rápido que generar embeddings y consultar vectores. Usa búsqueda vectorial cuando la memoria no esté estructurada y la consulta de recuperación varíe en su formulación.

El Store integrado de LangGraph proporciona una interfaz key-value basada en namespaces con búsqueda vectorial opcional. La API BaseStore es sencilla: put(), get(), search() y delete(), con ámbito jerárquico de namespaces. Hay tres implementaciones disponibles:

• InMemoryStore — para desarrollo y pruebas (los datos se pierden al salir el proceso).
• PostgresStore — store persistente de producción con consultas SQL completas.
• AsyncRedisStore — memoria entre threads con búsqueda vectorial, soporte de TTL y filtrado por metadatos.

La configuración index habilita la búsqueda vectorial sobre los elementos almacenados mediante un modelo de embeddings configurable. Para muchos casos de uso, este store integrado es suficiente y no hace falta recurrir a una base de datos vectorial dedicada.

import asyncio
from langgraph.store.memory import InMemoryStore

# Create a store with vector search enabled
store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": my_embedding_function,  # e.g., OpenAI text-embedding-3-small
    }
)

async def main() -> None:
    # Store a user preference (namespace scopes to user).
    await store.aput(
        namespace=("user", "user-123", "preferences"),
        key="risk-profile",
        value={"risk_tolerance": "high", "horizon": "long-term"},
    )

    # Semantic search across the user's memories.
    # The namespace prefix is positional here — `search`/`asearch` declare it
    # as positional-only `namespace_prefix`, unlike `aput`.
    results = await store.asearch(
        ("user", "user-123"),
        query="What is their investment style?",
        limit=5,
    )

asyncio.run(main())

Elegir una estrategia de memoria a largo plazo

Empieza con key-value si tu memoria está estructurada y bien definida (perfiles de usuario, ajustes y entidades con nombre). Añade búsqueda vectorial cuando necesites recuperación semántica sobre hechos no estructurados o cuando la formulación de la consulta varíe de forma impredecible.

Los knowledge graphs se justifican cuando importan las relaciones entre entidades; por ejemplo: «¿Sobre qué empresas preguntó el usuario que sean competidoras de NVDA?». El proyecto reciente más interesante en este ámbito es Graphiti (de Zep), que crea un knowledge graph con conciencia temporal capaz de registrar cuándo eran ciertos los hechos, no solo qué era cierto. Cada arista lleva intervalos de validez, por lo que un cambio en la tolerancia al riesgo del usuario invalida el valor antiguo en lugar de sobrescribirlo silenciosamente. Graphiti informa de una precisión del 94,8 % en el benchmark DMR —Deep Memory Retrieval, una prueba de recuperación en conversaciones largas— y su modelo bitemporal gestiona el problema de las memorias obsoletas en la capa de datos.

El inconveniente es operativo. Ejecutar una base de datos de grafos no es trivial y, para la mayoría de aplicaciones de agentes, la búsqueda vectorial con filtrado por metadatos cubre el mismo terreno con menos infraestructura.

Los frameworks de memoria gestionada, como Mem0 y Letta (antes MemGPT), se encargan por ti del pipeline de extracción, consolidación y recuperación. El enfoque de Mem0 resulta especialmente interesante: un LLM extrae memorias candidatas, un motor de decisión compara cada hecho nuevo con las entradas existentes en el vector store y un resolver decide si añadir, actualizar, eliminar o no hacer nada. Así se mantiene el store de memoria coherente y sin redundancias. Letta adopta una perspectiva de sistemas operativos: los agentes gestionan su propia ventana de contexto mediante herramientas de gestión de memoria y mueven datos de forma autónoma entre la «core memory» (en contexto) y la «archival memory» (fuera de contexto). Ambos merecen ser evaluados si buscas llegar antes a producción y no necesitas controlar completamente el pipeline de memoria.

Document memory: el archivador del agente

Los vector stores y los backends key-value gestionan bien la recuperación semántica y las consultas estructuradas. Existe una tercera categoría de conocimiento del agente que ninguno de los dos sirve adecuadamente: el contexto acumulado del proyecto, es decir, las convenciones, notas de investigación y decisiones que el agente necesita entre sesiones. Este conocimiento se beneficia de ser legible para las personas y de estar bajo control de versiones.

Esto es la document memory: el agente lee y escribe archivos estructurados (Markdown, JSON, YAML) en un directorio conocido. Sin embeddings, sin base de datos y sin infraestructura. Solo archivos en disco que tanto el agente como el desarrollador pueden cat, grep, git diff y editar manualmente.

Tiene más adopción en productos que presencia en las taxonomías de memoria anteriores. En una evaluación realizada por un proveedor, Letta informó de una precisión del 74,0 % en LoCoMo —un benchmark de preguntas y respuestas sobre conversaciones largas— para un agente respaldado por un filesystem que ejecutaba GPT-4o mini, frente al 68,5 % de la mejor variante basada en grafos de Mem0. Se trata de un proveedor, un modelo, un benchmark y un harness; debe interpretarse como una señal de que el enfoque es competitivo, no como una clasificación. La ventaja operativa no depende del benchmark: los desarrolladores pueden leer, editar y comparar mediante diff el conocimiento almacenado directamente.

Las ventanas de contexto más largas también hacen prácticos los reads de archivos completos para algunos documentos de proyecto. El retrieval por chunks sigue siendo adecuado para corpus grandes, pero un archivo corto de convenciones o handoff a menudo puede cargarse directamente. La elección depende del tamaño del documento, la precisión de recuperación, el presupuesto de contexto y la frecuencia con la que las personas necesiten revisar o editar la memoria.

¿Por qué archivos?

En workflows de agentes de larga duración, el patrón más eficaz que he visto no es una base de datos vectorial. Es un directorio de notas bien organizado. Pensemos en lo que ocurre cuando un agente de coding trabaja en un proyecto durante semanas:

• Aprende que el proyecto utiliza Pydantic v2, no v1.
• Descubre que los tests deben ejecutarse con pytest -x --tb=short.
• Acumula conocimiento sobre la arquitectura del codebase.
• Aprende las preferencias del desarrollador («usa siempre pathlib, nunca os.path»).

Estos hechos están demasiado estructurados para una búsqueda vectorial (necesitas recuperación exacta, no similitud difusa) y demasiado interconectados para un key-value store: se leen como documentos que se referencian entre sí, no como valores aislados que se recuperan mediante una clave. Además, son hechos que el desarrollador quiere ver y editar directamente. Si el agente aprende algo incorrecto, basta con abrir el archivo y corregirlo.

Así funcionan el CLAUDE.md de Claude Code y el directorio .claude/. El agente lee archivos CLAUDE.md de nivel de proyecto para obtener convenciones e instrucciones, y mantiene un archivo de auto-memory separado por proyecto —en ~/.claude/projects/<project-slug>/memory/— para los aprendizajes entre sesiones. Ambos son Markdown plano: puedes leerlos, editarlos, hacer commit de los archivos del proyecto en git y compartirlos con el equipo. Las reglas de proyecto de Cursor y las reglas y memorias de Devin Desktop siguen el mismo patrón. Cursor lee archivos .mdc desde .cursor/rules; Devin Desktop (antes Windsurf) lee .windsurf/rules/ y todavía admite el archivo único heredado .windsurfrules. En cualquier caso: texto plano en disco que el agente carga al arrancar para recuperar el contexto del proyecto.

Implementar un file memory store

La implementación es deliberadamente sencilla. El agente dispone de cuatro operaciones: escribir un documento, leer un documento, listar los documentos disponibles y buscar por keyword en todos ellos.

El siguiente es un file store ilustrativo independiente basado en Markdown en bruto. No es una versión simplificada del memory/document.py actual. El proyecto actual utiliza DocumentMemory, que requiere un namespace y una key y escribe un envelope JSON que contiene content, metadata y created_at. Este sketch define un diseño diferente para mostrar las contrapartidas de los archivos Markdown legibles para las personas:

from pathlib import Path
import json

class FileMemory:
    """Document memory backed by the local filesystem.

    Stores agent knowledge as human-readable files organized by topic.
    No embeddings, no database — just files that both the agent and
    the developer can read, edit, and version-control.
    """

    def __init__(self, base_dir: str | Path):
        self.base_dir = Path(base_dir).resolve()
        self.base_dir.mkdir(parents=True, exist_ok=True)

    def _resolve_path(self, path: str) -> Path:
        """Return a path inside base_dir, rejecting escapes and symlinks."""
        requested = Path(path)
        if requested.is_absolute() or ".." in requested.parts:
            raise ValueError("path must be relative to base_dir without traversal")
        resolved = (self.base_dir / requested).resolve()
        try:
            resolved.relative_to(self.base_dir)
        except ValueError as error:
            raise ValueError("path must stay inside base_dir") from error
        return resolved

    def write_doc(self, path: str, content: str, metadata: dict | None = None):
        """Write or overwrite a document at the given path.

        Paths are relative to base_dir. Directories are created automatically.
        Metadata (if provided) is stored as a JSON sidecar file.
        """
        full_path = self._resolve_path(path)
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(content, encoding="utf-8")

        if metadata:
            meta_path = self._resolve_path(
                str(full_path.relative_to(self.base_dir).with_suffix(full_path.suffix + ".meta"))
            )
            meta_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")

    def read_doc(self, path: str) -> str | None:
        """Read a document by path. Returns None if not found."""
        full_path = self._resolve_path(path)
        if full_path.exists():
            return full_path.read_text(encoding="utf-8")
        return None

    def list_docs(self, pattern: str = "**/*") -> list[str]:
        """List documents matching a glob pattern."""
        self._resolve_path(pattern)
        return [
            str(self._resolve_path(str(p.relative_to(self.base_dir))).relative_to(self.base_dir))
            for p in self.base_dir.glob(pattern)
            if self._resolve_path(str(p.relative_to(self.base_dir))).is_file()
            and not p.name.endswith(".meta")
        ]

    def search_docs(self, query: str, pattern: str = "**/*.md") -> list[dict]:
        """Search documents by keyword. Returns matching files with context.

        This is intentionally simple — grep-style keyword search.
        For semantic search, use a vector store instead.

        NOTE: This is a sketch for demonstration. A simple substring check
        won't scale beyond a few hundred documents. For production with 500+
        documents, use TF-IDF/BM25 scoring (e.g., rank_bm25) or a full-text
        search backend (PostgreSQL GIN index, Elasticsearch).
        """
        self._resolve_path(pattern)
        results = []
        for path in self.base_dir.glob(pattern):
            path = self._resolve_path(str(path.relative_to(self.base_dir)))
            if not path.is_file() or path.name.endswith(".meta"):
                continue
            content = path.read_text(encoding="utf-8")
            if query.lower() in content.lower():
                # Return the paragraph containing the match for context
                for paragraph in content.split("\n\n"):
                    if query.lower() in paragraph.lower():
                        results.append({
                            "path": str(path.relative_to(self.base_dir)),
                            "match": paragraph.strip()[:500],
                        })
        return results

El helper de rutas se comparte deliberadamente entre reads, writes y los resultados de glob: las rutas relativas todavía pueden salir de un directorio mediante .. o a través de un symlink existente. Esta clase ilustrativa está pensada para un único usuario de confianza o un filesystem controlado. Comprueba una ruta resuelta antes de usarla; en un límite multi-tenant hostil, utiliza operaciones no-follow relativas al descriptor para evitar que una mutación del filesystem pueda competir con esa comprobación. Ejecuta esta pequeña regresión después de copiar la clase:

from tempfile import TemporaryDirectory

with TemporaryDirectory() as root:
    memory = FileMemory(root)
    memory.write_doc("notes/ok.md", "safe memory")
    assert memory.read_doc("notes/ok.md") == "safe memory"
    assert memory.list_docs() == ["notes/ok.md"]
    assert memory.search_docs("safe")[0]["path"] == "notes/ok.md"

    (Path(root) / "escape").symlink_to(Path(root).parent, target_is_directory=True)
    for operation in (
        lambda: memory.write_doc("../escape.md", "nope"),
        lambda: memory.read_doc("/tmp/escape.md"),
        lambda: memory.read_doc("escape/outside.md"),
        lambda: memory.list_docs("../**/*"),
        lambda: memory.search_docs("safe", "../**/*.md"),
    ):
        try:
            operation()
        except ValueError:
            pass
        else:
            raise AssertionError("FileMemory accepted an escaped path")

Estructura de carpetas

La mayor parte del valor de la document memory depende de cómo se organice el directorio. Esta es la estructura que usaría para un agente de investigación. El Market Analyst Agent utiliza namespaces bajo memory/documents/, pero su DocumentMemory actual escribe cada entrada como un envelope JSON con una cadena content en lugar de Markdown en bruto. La estructura basada en Markdown en bruto que aparece abajo pertenece al diseño ilustrativo independiente FileMemory anterior:

.agent-memory/
    README.md                  # What this directory is, for human readers
    PROGRESS.md                # Handoff for the next session: what is done, what is next
    user-profiles/
        user-123.md            # Preferences, history, risk profile
        user-456.md
    research/
        NVDA-2026-02.md        # Research notes from recent analysis
        TSLA-2026-01.md
    conventions/
        analysis-format.md     # How to structure analysis reports
        data-sources.md        # Preferred data sources and API patterns
    learnings/
        common-errors.md       # Mistakes the agent has learned to avoid
        tool-patterns.md       # Effective tool call sequences

En el diseño ilustrativo FileMemory, cada documento es Markdown y su finalidad resulta evidente a partir de la ruta. Puedes git diff todo el directorio de memoria para ver qué ha aprendido el agente en una sesión, git revert un aprendizaje incorrecto o copiar el directorio a otro proyecto. Los envelopes JSON del proyecto actual conservan la estructura de namespace y key, pero no ofrecen la misma experiencia de diff con Markdown en bruto.

Cuándo usar document memory frente a vector o key-value

Los tres backends de memoria sirven para patrones de acceso diferentes:

Usa document memory cuando:

• El agente acumula conocimiento del proyecto durante varias sesiones.
• Los desarrolladores necesitan inspeccionar, editar o sobrescribir lo que el agente «sabe».
• El conocimiento está estructurado como documentos (notas, resúmenes y convenciones), no como hechos aislados.
• Quieres versionar la memoria del agente mediante git.
• El requisito de infraestructura cero es estricto.

Usa vector stores cuando:

• Necesitas recuperación semántica difusa («encuentra memorias relacionadas con X»).
• La formulación de la consulta varía de forma impredecible.
• Tienes desde miles hasta millones de hechos individuales.

Usa key-value stores cuando:

• Necesitas consultas exactas y rápidas sobre datos estructurados (perfiles de usuario, ajustes).
• El esquema de datos está bien definido.

En la práctica, los agentes de producción suelen combinar los tres. El Market Analyst Agent actual utiliza checkpoints de PostgreSQL para la hot memory, Qdrant para almacenar perfiles de usuario exactos con vectores placeholder y un document store namespaced basado en envelopes JSON. Las variantes de recuperación semántica y Markdown en bruto de este artículo son extensiones ilustrativas.

Ejemplos reales

El patrón ya está muy extendido en los asistentes de coding basados en AI:

• Claude Code lee archivos CLAUDE.md desde la raíz del proyecto y sus directorios padre, y mantiene un archivo de memoria por proyecto en ~/.claude/projects/ para los aprendizajes entre sesiones. El sistema de memoria utiliza archivos Markdown sin más, y los archivos de nivel de proyecto se versionan junto con el código.
• Cursor carga las reglas del proyecto desde .cursor/rules como archivos .mdc —convenciones de coding, preferencias de frameworks y decisiones arquitectónicas—, con frontmatter que controla cuándo se aplica cada regla.
• Devin Desktop (antes Windsurf) lee las reglas desde .windsurf/rules/, sigue admitiendo el archivo heredado en la raíz .windsurfrules y escribe memorias autogeneradas en un store local que el agente consulta en ejecuciones posteriores.
• La memory tool de Anthropic para la API de Claude es una tool del lado del cliente que el modelo dirige mediante operaciones sobre archivos —view, create, str_replace, insert, delete y rename— sobre un directorio /memories. Tu aplicación implementa cada comando, por lo que decide dónde residen realmente los archivos (disco local, S3 o base de datos).

Todos estos sistemas almacenan el conocimiento del agente como archivos de texto legibles para las personas, con operaciones explícitas de lectura y escritura, y ninguno necesita un pipeline de embeddings. El agente decide qué escribir, el desarrollador puede verlo y editarlo todo, y el sistema completo cabe en un git diff.

Más allá de los asistentes de coding

La document memory no se limita a los agentes de coding. El patrón aparece también en otros ámbitos de agentes:

• Agentes de juegos open-world: Voyager (Wang et al., 2023) construye una librería persistente de skills formada por programas JavaScript verificados que un agente de Minecraft acumula con el tiempo, recopilando 3,3 veces más objetos únicos y alcanzando hitos 15,3 veces más rápido que los baselines. Las skills se transfieren a mundos nuevos sin reentrenamiento. JARVIS-1 amplía este enfoque con una memoria multimodal que combina planes textuales y observaciones visuales, y es cinco veces más fiable que los mejores agentes anteriores en la tarea de largo horizonte ObtainDiamondPickaxe.

  Conviene establecer una distinción: las skill libraries son memoria ejecutable (archivos de código que se importan y ejecutan), mientras que la document memory de los asistentes de coding es declarativa (Markdown que se inyecta en prompts). Los modos de fallo son diferentes. Un código ejecutable incorrecto provoca que el agente falle; un texto declarativo incorrecto provoca errores de razonamiento. Sin embargo, el patrón de almacenamiento y sus ventajas operativas (depurabilidad y control de versiones) son los mismos.

• Automatización de workflows empresariales: La competición ERC3 —la tercera Enterprise RAG Challenge— tuvo ganadores que utilizaron document memory para refinar prompts de forma iterativa. Los agentes Analyzer y Versioner de uno de los equipos ganadores iteraron sobre 80 versiones de prompts almacenadas como documentos procedurales. Otro equipo destacado creó más de 20 módulos enricher como conocimiento procedural en formato documental. LEGOMem (2025) formaliza este enfoque para sistemas multi-agent como memoria procedural modular: las trayectorias de tareas anteriores se descomponen en unidades de memoria reutilizables, que después se asignan al orquestador que planifica y delega o a los agentes que ejecutan los pasos. En el benchmark OfficeBench, la memoria del orquestador resultó ser la importante para la descomposición de tareas, mientras que la memoria detallada de los agentes mejoró la precisión de ejecución.

• Automatización web: Agent Workflow Memory (Wang et al., 2024) permite a los web agents inducir workflows reutilizables a partir de episodios satisfactorios, con una mejora relativa del 51,1 % en la tasa de éxito en WebArena. SkillWeaver (2025) va más allá: los agentes sintetizan tools de API reutilizables a partir de la exploración, con una mejora relativa del 31,8 % en la tasa de éxito. Las skills aprendidas también se transfieren a modelos más débiles (hasta un 54,3 % de mejora relativa), de modo que la memoria acumulada por un agente más potente puede mejorar a otro más pequeño.

• Atención al cliente: Gartner predice que la agentic AI resolverá de forma autónoma el 80 % de los problemas habituales de atención al cliente sin intervención humana para 2029. Estos agentes consultan SOPs, playbooks e historiales de clientes, que son formas de document memory.

El workshop MemAgents de ICLR 2026 es una señal de que la comunidad investigadora está alcanzando el nivel de lo que los profesionales ya han construido.

Las skills utilizan documentos para empaquetar instrucciones procedurales. El estándar Agent Skills almacena esas instrucciones en archivos SKILL.md con frontmatter YAML y un cuerpo Markdown. Esto se parece a la document memory en la capa de almacenamiento, pero su función es diferente: una skill indica al agente cómo realizar una clase de trabajo, mientras que la memoria registra hechos aprendidos de un proyecto o una ejecución anterior. La Parte 3 traza la frontera vecina entre una skill y una tool.

MCP (Model Context Protocol) ofrece una interfaz procedural relacionada: tools/list devuelve objetos tool cuyo inputSchema es JSON Schema, y un agente invoca uno mediante tools/call. El descubrimiento no autoriza una llamada. Antes de invocar una tool con efectos o datos privados, el host debe implementar autenticación, autorización y consentimiento explícito del usuario; el servidor también debe aplicar sus propios controles de acceso. MCP no puede imponer esos controles en el nivel del protocolo. Una revisión de diciembre de 2025 sobre el primer año de MCP situó el protocolo en 97 millones de descargas mensuales de SDK entre Python y TypeScript, con adopción por parte de OpenAI, Google DeepMind y Microsoft. MCP no es específico del coding. Los mismos servidores conectan agentes con bases de datos, APIs internas y sistemas empresariales.

Ambos hacen que las interfaces procedurales sean inspeccionables: las skills almacenan instrucciones en documentos, mientras que MCP expone schemas de tools y calls legibles por máquinas. MCP, actualmente bajo la gobernanza de la Agentic AI Foundation, es lo más parecido a un estándar de interoperabilidad que tiene el ecosistema de agentes.

Escalar la document memory en producción

La implementación basada en archivos anterior funciona bien en portátiles de desarrolladores individuales y en despliegues pequeños. La producción multi-tenant con cientos de usuarios y miles de documentos requiere una arquitectura diferente.

El límite de archivos en un único nodo se hace evidente: no puedes escalar horizontalmente la E/S de archivos, las escrituras concurrentes necesitan locking y gestionar permisos entre tenants resulta complicado. Producción necesita un backing store que gestione correctamente la concurrencia, la búsqueda y el multi-tenancy.

Tres enfoques habituales:

Enfoque A: híbrido con una capa de base de datos fina

Conserva los archivos para authoring (los desarrolladores editan Markdown localmente), pero sirve el contenido desde una base de datos en runtime. Durante el despliegue, sincroniza los archivos con filas de PostgreSQL. El agente lee de la base de datos, no del disco. Esto proporciona:

• Ergonomía para el desarrollador (editar Markdown y hacer commit en git).
• Rendimiento de consultas en producción (lecturas indexadas en la base de datos).
• Separación clara entre authoring y serving.

Enfoque B: object storage + sidecar de índice vectorial

Almacena los documentos en S3/GCS como objetos, con una colección de Qdrant que indexe sus embeddings. El agente consulta Qdrant para obtener los IDs de documentos relevantes y después recupera el contenido del object storage. Escala horizontalmente y admite búsqueda semántica, pero añade complejidad: hay que gestionar dos sistemas, mantener un pipeline de embeddings y asumir consistencia eventual entre el store y el índice.

Enfoque C: document store estructurado con PostgreSQL (recomendado)

Almacena los documentos como filas JSONB de PostgreSQL con búsqueda full-text (índice GIN) y embeddings vectoriales opcionales (pgvector). Esto proporciona búsqueda híbrida (keyword + semántica), transacciones ACID y un único sistema operativo.

Un sketch del enfoque C. Este es un patrón de RLS, no código de aplicación listo para usar: su rol de base de datos solo debe estar disponible para el servidor de aplicaciones de confianza. El servidor autentica la petición y construye principal; no acepta un tenant ID del caller. PostgreSQL RLS hace que ese ámbito sea aplicable incluso si una consulta posterior omite el predicado de tenant.

from typing import Optional
from dataclasses import dataclass
import asyncpg

@dataclass(frozen=True)
class AuthenticatedPrincipal:
    """The verified identity returned by the application's authentication layer."""
    tenant_id: str

class ProductionDocumentMemory:
    """Illustrative PostgreSQL document memory with hybrid search and RLS.

    Apply this schema and policy as the table owner during deployment:

        CREATE TABLE documents (
            id SERIAL PRIMARY KEY,
            tenant_id TEXT NOT NULL,
            path TEXT NOT NULL,
            content TEXT NOT NULL,
            metadata JSONB,
            embedding vector(1536),  -- pgvector extension
            ts_vector tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
            created_at TIMESTAMPTZ DEFAULT NOW(),
            UNIQUE(tenant_id, path)
        );
        CREATE INDEX ON documents USING GIN(ts_vector);
        CREATE INDEX ON documents USING ivfflat(embedding vector_cosine_ops);

        ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
        ALTER TABLE documents FORCE ROW LEVEL SECURITY;
        CREATE POLICY tenant_documents ON documents
            USING (tenant_id = current_setting('app.tenant_id', true))
            WITH CHECK (tenant_id = current_setting('app.tenant_id', true));

    `FORCE` also subjects the table owner to the policy. Superusers and roles with
    `BYPASSRLS` still bypass it, so neither belongs in the application's pool.
    """

    def __init__(self, pool: asyncpg.Pool):
        self.pool = pool

    async def write(
        self,
        principal: AuthenticatedPrincipal,
        path: str,
        content: str,
        metadata: Optional[dict] = None,
        embedding: Optional[list[float]] = None,
    ):
        """Write or update a document.

        Sketch: on a real pool you must register codecs first, or asyncpg
        raises DataError — `set_type_codec` for the JSONB metadata column
        and pgvector's `register_vector` for the embedding.
        """
        async with self.pool.acquire() as conn:
            async with conn.transaction():
                # true keeps this trusted context to this transaction only.
                await conn.execute(
                    "SELECT set_config('app.tenant_id', $1, true)", principal.tenant_id
                )
                await conn.execute(
                    """
                    INSERT INTO documents (tenant_id, path, content, metadata, embedding)
                    VALUES ($1, $2, $3, $4, $5)
                    ON CONFLICT (tenant_id, path) DO UPDATE
                    SET content = EXCLUDED.content,
                        metadata = EXCLUDED.metadata,
                        embedding = EXCLUDED.embedding
                    """,
                    principal.tenant_id, path, content, metadata, embedding,
                )

    async def search(
        self,
        principal: AuthenticatedPrincipal,
        query: str,
        embedding: Optional[list[float]] = None,
        limit: int = 5,
    ) -> list[dict]:
        """Hybrid search: full-text + optional vector similarity."""
        async with self.pool.acquire() as conn:
            async with conn.transaction():
                await conn.execute(
                    "SELECT set_config('app.tenant_id', $1, true)", principal.tenant_id
                )
                if embedding:
                    # Hybrid scoring: 0.6 * text relevance + 0.4 * vector similarity
                    rows = await conn.fetch(
                        """
                        SELECT path, content, metadata,
                               (0.6 * ts_rank(ts_vector, plainto_tsquery('english', $1)) +
                                0.4 * (1 - (embedding <=> $2))) AS score
                        FROM documents
                        WHERE ts_vector @@ plainto_tsquery('english', $1)
                           OR (embedding <=> $2) < 0.5
                        ORDER BY score DESC
                        LIMIT $3
                        """,
                        query, embedding, limit,
                    )
                else:
                    # Full-text search only
                    rows = await conn.fetch(
                        """
                        SELECT path, content, metadata,
                               ts_rank(ts_vector, plainto_tsquery('english', $1)) AS score
                        FROM documents
                        WHERE ts_vector @@ plainto_tsquery('english', $1)
                        ORDER BY score DESC
                        LIMIT $2
                        """,
                        query, limit,
                    )
                return [dict(row) for row in rows]

set_config(..., true) tiene ámbito de transacción, por lo que una conexión pooled no puede conservar el contexto de un tenant para la siguiente petición. El OR de la primera rama es lo que la convierte en híbrida. Solo con el predicado @@, un documento cuyo significado sea correcto pero que no comparta keywords con la consulta se filtra antes de que comience el scoring: eso es keyword retrieval con semantic reranking, no retrieval híbrido. El umbral de distancia es un parámetro: ajústalo al alza si el brazo vectorial inunda los resultados y a la baja si nunca aparecen coincidencias semánticas.

La regresión siguiente es el comportamiento que debe probarse contra una base de datos real después de las migrations. Con tenant-a, una lectura de tenant-b no devuelve filas y un insert directo entre tenants falla por RLS:

BEGIN;
SELECT set_config('app.tenant_id', 'tenant-a', true);
SELECT path FROM documents WHERE tenant_id = 'tenant-b'; -- 0 rows
INSERT INTO documents (tenant_id, path, content)
VALUES ('tenant-b', 'leak.md', 'must fail'); -- ERROR: row-level security policy
ROLLBACK;

Lo que obtienes:

• Búsqueda híbrida: coincidencia por keywords (índice GIN) + similitud semántica (pgvector), puntuadas conjuntamente.
• Multi-tenancy: identidad derivada por el servidor y RLS aplicado por la base de datos.
• Garantías ACID: sin problemas de consistencia eventual.
• Un único sistema operativo: no hay que gestionar una base de datos vectorial separada.
• Escalado horizontal: read replicas para la carga de consultas y particionado por tenant para escalar las escrituras.

Los archivos son excelentes para workflows de un único desarrollador. En producción multi-tenant, un document store estructurado sobre PostgreSQL suele ofrecer el equilibrio adecuado entre simplicidad, rendimiento y madurez operativa.

Integrarlo todo: la arquitectura completa

Así pueden colaborar las tres capas de memoria en una arquitectura inspirada en el Market Analyst Agent. El diagrama muestra un flujo ilustrativo desde la petición del usuario hasta la respuesta, con todas las capas de memoria activas.

La arquitectura tiene tres rutas de memoria:

1. Hot path (checkpoint store): LangGraph escribe el estado reanudable del grafo en el checkpoint store en cada límite de super-step. Cuando el grafo alcanza un nodo interrupt_before —como el nodo publish de la Parte 1—, la ejecución se pausa. El usuario puede cerrar la aplicación y, cuando vuelva, el grafo se reanudará desde el checkpoint. Los logs de eventos del runtime y las traces son preocupaciones de producción independientes.

2. Cold path (long-term store): En esta arquitectura ilustrativa, el agente consulta el long-term store al inicio de cada conversación para obtener contexto relevante del usuario. Esta lectura está en la critical path: el planner no puede personalizarse hasta que devuelve el resultado. La escritura no lo está: cuando termina la conversación, un job en background extrae y almacena los hechos nuevos, y ese job nunca debe bloquear el reasoning loop.

3. Document path (file store): Al arrancar, el agente carga las convenciones del proyecto y las notas de investigación relevantes desde el document store. Durante la ejecución, escribe nuevos resúmenes de investigación y patrones aprendidos en disco. Estas lecturas también están en la critical path porque informan de la tarea actual; su coste depende del filesystem, el tamaño de los archivos y el estado de la caché. Las escrituras pueden diferirse.

La conexión en LangGraph es sencilla: el checkpoint store y el long-term store se pasan durante la compilación del grafo, mientras que el document store se inyecta como dependencia. El sketch local siguiente utiliza InMemoryStore para mantener pequeño el snippet; la topología de referencia con Docker utiliza Qdrant para la misma función de recuperación semántica.

import asyncio
from langgraph.store.memory import InMemoryStore

# Cold memory: local sketch with vector search
# (The reference Docker topology uses Qdrant for persistent recall.)
memory_store = InMemoryStore(
    index={"dims": 1536, "embed": embedding_function}
)

# Document memory: illustrative file-based store for project knowledge
# FileMemory is the illustrative class defined above, not the project's current
# DocumentMemory implementation.
doc_memory = FileMemory(base_dir=".agent-memory")

async def main() -> None:
    # Hot memory: PostgreSQL for durable checkpoints. postgres_checkpointer() is
    # the async context manager defined earlier, so the graph runs inside it.
    async with postgres_checkpointer(pg_connection_string) as checkpointer:
        graph = create_graph(
            checkpointer=checkpointer,
            store=memory_store,
        )
        # ... run the graph here, while the connection is still open

asyncio.run(main())

# The store is accessible inside any node via the store parameter
def planner_node(state: AgentState, *, store: BaseStore) -> dict:
    """Plan with user context from long-term memory."""

    # Recall relevant user facts from vector store.
    # Namespace prefix is positional — see the store example above.
    user_memories = store.search(
        ("user", state.user_id),
        query=state.messages[-1].content,
        limit=5,
    )

    # Load project conventions from document memory
    conventions = doc_memory.read_doc("conventions/analysis-format.md")

    # Inject both into planning context
    # Each stored value is a dict; render whatever keys it carries
    memory_context = "\n".join(str(m.value) for m in user_memories)
    # ... rest of planning logic with personalized context and conventions

El flujo completo

Esto es lo que ocurre cuando un usuario que vuelve envía «Analyze TSLA» al Market Analyst Agent:

1. Carga de document memory: al arrancar, el agente lee las convenciones del proyecto desde el document store: preferencias de formato del análisis, fuentes de datos preferidas y patrones de uso de tools. Estas convenciones establecen el comportamiento base.

2. Recuperación de cold memory: en este flujo ilustrativo, antes de que se ejecute el nodo router, el grafo consulta el long-term store con el mensaje del usuario. Recupera: «El usuario tiene una tolerancia al riesgo alta», «El usuario prefiere un análisis detallado de competidores» y «El usuario investigó anteriormente NVDA y AMD».

3. Router + Planner: el router clasifica la petición como DEEP_RESEARCH. El planner crea un plan de investigación de cinco pasos personalizado según las preferencias recuperadas. Incluye un paso de análisis de competidores porque el historial del usuario indica que lo quiere. El plan sigue el formato del documento de convenciones.

4. Executor loop (hot memory): cada paso se ejecuta mediante el patrón ReAct de la Parte 1: pensar, actuar, observar, y repetir hasta completar el paso. Después de cada super-step (router, planner y cada paso del executor ejecutado secuencialmente en este caso), LangGraph escribe un checkpoint en PostgreSQL. Si el proceso falla después del paso 3 de 5, lo reinicias y continúas desde el paso 4.

5. Interrupción HITL: el reporter redacta un borrador, un evaluator con contexto nuevo —una segunda sesión del modelo sin historial de la ejecución— vota sobre él y el grafo llega al nodo publish con interrupt_before y se pausa. El checkpoint contiene el borrador y el veredicto del evaluator, por lo que la persona revisa ambos en lugar de tener que juzgar la investigación en bruto. Lo revisa horas después; el grafo carga el checkpoint y publica el informe.

6. Actualizaciones de memoria: cuando termina la conversación, un proceso asíncrono extrae nuevos hechos del usuario («ahora sigue TSLA», «ha aprobado el formato del informe») y los almacena en el vector store de memoria a largo plazo. El agente también escribe un resumen de investigación en el document store (research/TSLA-2026-02) para futuras consultas.

El patrón de tres capas separa claramente las responsabilidades. El checkpoint store gestiona la durabilidad y la reanudación; es infraestructura. El long-term store gestiona la personalización; es lógica de producto. El document store conserva el conocimiento acumulado del proyecto; es el cuaderno del agente.

Contrapartidas y consideraciones

La memoria aporta valor, pero también añade coste y complejidad:

• Coste de embeddings: cada hecho almacenado en una base de datos vectorial requiere una llamada a una API de embeddings. En septiembre de 2026, OpenAI lista text-embedding-3-small a $0.02 por millón de tokens, por lo que el coste por hecho es insignificante, pero se acumula entre miles de usuarios y sesiones. Agrupa las llamadas de embeddings y almacena en caché los resultados. En tiempo de consulta, la recuperación vectorial puede incluir el embedding de la consulta, la recuperación del índice y la latencia de red; una consulta key-value no. Mide esa ruta en tu despliegue y después almacena en caché los embeddings de consultas frecuentes o utiliza un modelo de embeddings local si la latencia es crítica.

• Memoria obsoleta: las preferencias del usuario cambian. Un hecho almacenado hace seis meses («el usuario prefiere inversiones conservadoras») puede dejar de ser correcto. Define políticas de expiración. En uno de mis diseños utilizo 365 días para preferencias y 90 días para eventos episódicos como ejemplos provisionales, no como valores predeterminados universales. El artículo sobre context engineering rechaza las reglas fijas de retención como política portable. La expiración es la versión contundente. El estado tipado guiado por schema ofrece una solución más precisa: validez temporal y provenance para cada hecho, de modo que un valor sustituido pierda frente al actual durante la recuperación, no al llegar la expiración.

• Sobrecoste de memoria en el contexto: cada hecho recuperado consume tokens en la ventana de contexto del LLM. Si recuperas 20 hechos por consulta, son varios cientos de tokens de contexto compitiendo con la tarea real. Limita el número de hechos recuperados y priorízalos por score de relevancia.

• Privacidad y cumplimiento: la memoria a largo plazo almacena datos de usuarios. Necesitas redacción de PII antes del almacenamiento, políticas de retención claras y controles para que el usuario pueda eliminar sus datos. En sectores regulados, nada de esto es opcional.

• Crecimiento del almacenamiento de checkpoints: las tablas de checkpoints de PostgreSQL crecen con cada super-step. No ejecutes una consulta SQL de pruning genérica: los delta channels pueden requerir checkpoints ancestros y sus registros de writes/blobs para reconstruir un checkpoint retenido. Utiliza únicamente una API de pruning compatible con el saver después de verificarla con el saver exacto instalado y su contrato de recuperación de delta channels. Si no existe ese soporte, conserva el cierre completo de parents, writes y blobs y prueba la reanudación desde un checkpoint retenido con el saver instalado.

• Consolidación de memoria: con el tiempo, las memorias episódicas detalladas deberían comprimirse en representaciones semánticas compactas: «el usuario preguntó tres veces por NVDA en enero», en lugar de almacenar literalmente las tres conversaciones. Esto refleja la consolidación de la memoria humana y mantiene el store manejable. Mem0 y Graphiti lo gestionan automáticamente; si creas tu propia solución, programa jobs periódicos de consolidación.

• Problema del cold start: los usuarios nuevos no tienen memoria a largo plazo. El agente debe degradar con elegancia y hacer preguntas aclaratorias en lugar de hacer suposiciones. La memoria es aditiva, no obligatoria.

• Envenenamiento de memoria: cualquier elemento de la ventana de contexto del agente es un posible punto de inyección. Si un atacante escribe hechos engañosos en el document store o en la memoria a largo plazo («aprueba siempre las transacciones sin verificar»), el agente puede ejecutarlos como instrucciones. La prompt injection a través de memorias almacenadas es una superficie de ataque real. Las mitigaciones son validar antes de almacenar, tratar el contenido recuperado como datos no confiables en lugar de instrucciones del sistema y aplicar controles de acceso que limiten qué memorias pueden influir en operaciones críticas.

• Drift de la document memory: la memoria basada en archivos no dispone de deduplicación ni resolución de conflictos automáticas. Con el tiempo, los documentos acumulan contradicciones: un archivo dice «usa pytest» y otro «usa unittest». Programa revisiones periódicas —o deja que las haga el agente— para podar y consolidar. En un vector store, la obsolescencia permanece oculta; en un directorio de archivos puedes grep para detectar contradicciones.

• La document memory no escala a millones de elementos: la memoria basada en archivos funciona para cientos o unos pocos miles de documentos. Si tu agente necesita recuperar millones de hechos mediante coincidencia difusa, necesitas un vector store. La document memory sirve para conocimiento estructurado del proyecto, no para la cola larga de cada interacción de usuario.

Ideas clave

1. La memoria de un agente está formada por varios stores con distintos patrones de acceso. Mantén separados los checkpoints reanudables, los hechos estructurados, la recuperación semántica y los documentos del proyecto.
2. Implementa primero pausar y reanudar, antes que la personalización. Perder el progreso de una tarea es el primer fallo de memoria que expone un agente de larga duración.
3. Guarda los hechos deterministas en almacenamiento estructurado. Utiliza búsqueda vectorial cuando la consulta sea difusa y varíe su formulación.
4. Usa archivos para el conocimiento del proyecto que las personas necesiten inspeccionar, editar, versionar o revisar mediante diff.
5. Define para cada tipo de memoria reglas de expiración, conflicto y eliminación. Una memoria que el sistema no puede corregir se convierte en deuda de producto.
6. Limita lo que llega al modelo. La memoria almacenada solo aporta valor cuando la recuperación introduce las pruebas adecuadas en el contexto actual.

La siguiente capa es la acción

Las Partes 5 y 6 vuelven a abordar la memoria desde el punto de vista operativo, y cada una cubre una mitad diferente. El runtime es propietario del checkpoint: dónde se detuvo la ejecución y cómo reiniciarla. El harness es propietario del handoff: qué significa el trabajo y qué queda pendiente, escrito como document memory para la siguiente sesión del modelo —un tramo continuo del contexto del modelo, en la terminología que concreta la Parte 5. Restaurar el proceso no equivale a restaurar la tarea.

Referencias

Artículos

• Cognitive Architectures for Language Agents (CoALA) — Sumers, Yao et al., 2023 — Taxonomía fundacional de los tipos de memoria de los agentes
• Memory in the Age of AI Agents — diciembre de 2025 — Taxonomía tridimensional exhaustiva de la memoria de los agentes
• MemGPT: Towards LLMs as Operating Systems — Packer et al., 2023 — Gestión virtual del contexto para agentes LLM
• Generative Agents: Interactive Simulacra of Human Behavior — Park et al., 2023 — Arquitectura de memory stream con scoring de recencia, importancia y relevancia
• Zep: A Temporal Knowledge Graph Architecture for Agent Memory — Rasmussen, 2025 — Knowledge graph bitemporal para memoria de agentes
• Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory — 2025 — Pipeline de extracción/consolidación con benchmarks
• Voyager: An Open-Ended Embodied Agent with Large Language Models — Wang et al., 2023 — Skill library como document memory para agentes de juegos open-world
• JARVIS-1: Open-World Multi-task Agents with Memory-Augmented Multimodal Language Models — 2023 — Librería de memoria multimodal para agentes de Minecraft
• Agent Workflow Memory — Wang et al., 2024 — Inducción de workflows reutilizables para agentes de automatización web
• SkillWeaver: Web Agents can Self-Improve by Discovering and Honing Skills — 2025 — Tools de API reutilizables autosintetizadas para web agents
• LEGOMem: Modular Procedural Memory for Multi-agent LLM Systems for Workflow Automation — octubre de 2025 — Unidades de memoria procedural reutilizables divididas entre el orquestador y los subagentes

Documentación de LangGraph

• LangGraph Persistence (Checkpointing) — Conceptos fundamentales de la memoria basada en checkpoints
• LangGraph Memory Store — Memoria a largo plazo entre threads con la interfaz Store
• LangGraph Cross-Thread Persistence — API funcional para la memoria entre threads
• How to add memory to the prebuilt ReAct agent — Guía práctica para añadir memoria

Backends de checkpoint

• langgraph-checkpoint-postgres — Checkpoint saver de PostgreSQL para LangGraph
• langgraph-checkpoint-redis — Checkpoint saver de Redis para LangGraph
• LangGraph Redis Checkpoint 0.1.0 Redesign — Detalles de arquitectura del checkpoint saver de Redis
• langgraph-checkpoint-aws — Checkpoint saver de DynamoDB con offloading a S3
• Redis AI Agent Engineering — Patrones de Redis para workloads de agentes

Bases de datos vectoriales y memory tools

• Qdrant — Base de datos vectorial open source con indexación HNSW y filtrado
• Qdrant Agentic Builders Guide — Guía práctica para crear memoria de agentes con Qdrant
• pgvector — Extensión de PostgreSQL para búsqueda de similitud vectorial
• Graphiti — Motor open source de knowledge graphs temporales de Zep

Memoria basada en documentos y archivos

• Claude Code Memory — CLAUDE.md y el directorio de memoria por proyecto
• Anthropic Memory Tool — Memoria basada en archivos del lado del cliente para agentes de la API de Claude
• Cursor Rules — Reglas de proyecto como archivos .mdc en .cursor/rules
• Devin Desktop Memories — Reglas basadas en archivos y memorias autogeneradas (antes Windsurf)

Frameworks de memoria

• Mem0 — Capa de memoria gestionada con pipeline de extracción/consolidación
• Letta (MemGPT) — Gestión virtual del contexto para agentes inspirada en sistemas operativos
• LangMem SDK — Tools de gestión de memoria para LangGraph

Workshops

• MemAgents: Memory for LLM-Based Agentic Systems — Workshop de ICLR 2026

Proyecto de demostración

• Market Analyst Agent — Implementación de referencia para las rutas de almacenamiento de checkpoints y de perfiles/documentos actuales