Arquitectura de memoria para AI Agent: checkpoints y almacenes vectoriales

Viacheslav Dubrov

2026-02-14 · Actualizado 2026-09-06 · 41 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.

Actualización del artículo

Publicado originalmente el 14 de febrero de 2026. Revisado y actualizado el 6 de septiembre de 2026. La actualización cubre la compactación del contexto, los benchmarks de memoria y las APIs de almacenamiento, y aclara las diferencias entre el estado de trabajo, los checkpoints y la memoria a largo plazo.

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. Este artículo 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 análisis— como referencia para explicar los hot checkpoints. Las secciones independientes sobre vectores en frío y Markdown en bruto son diseños ilustrativos que muestran extensiones aún no implementadas en el proyecto actual. Después explicaré cuándo tiene sentido utilizar PostgreSQL, Redis, Qdrant, almacenes clave-valor y archivos Markdown normales.

En resumen: para pausar y reanudar, utiliza un checkpoint store. Para datos exactos del usuario, usa almacenamiento estructurado; añade recuperación vectorial solo cuando la pregunta varíe en su formulación. Usa archivos cuando las personas necesiten inspeccionar y editar el conocimiento acumulado del proyecto. Un checkpoint conserva el estado; el grafo y el harness siguen decidiendo qué hacer con él.

El harness lee todos los almacenes siguientes: es el código que dirige el loop alrededor del modelo. El harness decide qué parte de su contenido llega a la ventana de contexto; los almacenes 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. Un diseño puede utilizar checkpoints, almacenes semánticos o estructurados y documentos legibles por personas. Elige únicamente los almacenes que necesiten los requisitos de recuperación y recuperación tras fallos del producto.

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 sin estado 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 estos comportamientos:

• Pausar y reanudar: un usuario inicia una tarea de investigación, cierra el portátil y vuelve al día siguiente. Sin estado guardado en un checkpoint, el agente empieza desde cero.
• Coherencia entre turnos: durante una conversación larga, el agente debe recordar qué herramientas ha llamado, qué datos ha recopilado y qué pasos del plan ha completado.
• 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 las 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 «está bien, pero añade un análisis de la competencia», un checkpoint restaura el plan y la investigación desde el último paso completado. Añadir el paso de competencia requeriría interpretar la petición y volver a planificar; el companion no implementa ese comportamiento. El checkpoint proporciona el estado anterior, mientras que la aplicación debe decidir cómo modifica la nueva petición el plan.

La memoria a largo plazo aborda un caso distinto. Si el usuario vuelve una semana después y pregunta «Actualiza mi análisis de NVDA», el agente quizá necesite recordar una preferencia por evaluaciones de riesgo conservadoras y el interés por las acciones de empresas de semiconductores. Un almacén de memoria respaldado por vectores puede recuperar esos datos entre sesiones sin volver a pedírselos al usuario.

Los ejemplos de implementación siguientes utilizan LangGraph, la biblioteca open source de LangChain para construir agentes como grafos de estado explícitos; los límites de almacenamiento que establece se generalizan a cualquier framework. Piensa en la conversación continua de un usuario «Analyze NVDA» como un thread. Cada vez que el grafo se ejecuta para responder o continuar, se trata de un run dentro de ese thread. Mientras un run está activo, el contexto del modelo y las variables locales del programa constituyen su memoria de trabajo; desaparecen cuando se detiene ese trabajo. LangGraph denomina short-term memory al estado guardado para ese thread y long-term memory a los datos disponibles para otros threads. En adelante, «thread» y «conversación» significan lo mismo. La Parte 5 utiliza «sesión» para el registro persistente de un run, por lo que este artículo evita ese término para referirse a la conversación.

Taxonomía de la memoria de un AI agent

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

La memoria de trabajo contiene las observaciones actuales, los datos recuperados y los resultados intermedios utilizados por el run activo. Algunos elementos viven en variables de la aplicación; los mensajes seleccionados y los tool results forman la entrada del modelo. Esa entrada debe caber en la ventana de contexto del modelo, mientras que el estado de la aplicación puede ser mayor y persistir durante varios pasos. La memoria del proceso se pierde tras un fallo salvo que se guarde explícitamente. Las demás capas proporcionan información a este estado de trabajo.

La short-term memory es el checkpoint que LangGraph escribe después de 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 memoria documental almacena notas del proyecto, resúmenes de investigación y convenciones aprendidas en archivos que pueden inspeccionar tanto las personas como los agentes. La memoria procedimental incluye instrucciones del sistema, definiciones de herramientas y procedimientos reutilizables que pueden recuperarse para una tarea. Las duraciones de la tabla son ilustrativas; la retención sigue la política de la aplicación, y el estado de trabajo puede durar todo un run activo.

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. Las memorias episódica y semántica se convierten en cold memory, para recuperar información entre threads. La memoria documental mantiene legible y editable directamente el conocimiento acumulado del proyecto. La memoria de trabajo se agrupa con la capa hot porque los checkpoints pueden conservar el estado necesario para reconstruir un run activo. Un checkpoint no es el cálculo interno completo del modelo. Los procedimientos pueden distribuirse con el agente o almacenarse y recuperarse desde archivos u otro almacén. Estas capas describen las decisiones de implementación de este artículo, no tipos de memoria mutuamente excluyentes.

CoALA clasifica las memorias de trabajo, episódica, semántica y procedimental. El estudio Memory in the Age of AI Agents organiza la memoria por forma, función y dinámica, e incluye documentos, codebases y workflows reutilizables. Los archivos pueden implementar varias de esas categorías. Este artículo denomina por separado a la memoria documental para hacer visibles sus responsabilidades de almacenamiento y mantenimiento.

El mismo patrón de almacenamiento aparece en otros ámbitos. Un agente de Minecraft (Voyager) guarda habilidades de juego reutilizables como bibliotecas de código, y los agentes web inducen workflows de navegación reutilizables a partir de ejecuciones satisfactorias. Volveré a ambos ejemplos más adelante. Los archivos inspeccionables y la recuperación indexada pueden coexistir: Voyager recupera programas mediante embeddings de sus descripciones.

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 después decide cuándo recuperarlo.

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

La compaction mantiene utilizable una conversación

Una ventana de contexto más grande no elimina la necesidad de decidir qué sobrevive. Las APIs actuales pueden resumir una conversación antigua antes de que llene la ventana. La compaction del lado del servidor de Claude, todavía en beta a 06-09-2026, devuelve un bloque compaction que las peticiones posteriores utilizan en lugar del contenido anterior. Puede reducir el trabajo de resumido en el cliente, pero el resumen puede omitir un dato que se necesite más adelante.

Mantén fuera de ese resumen el estado autoritativo de la tarea: efectos completados, aprobaciones, referencias a fuentes y restricciones exactas del usuario. Un checkpoint restaura la ejecución; la compaction acorta el contexto del modelo; la memoria a largo plazo selecciona conocimiento para otra conversación. Prueba estos tres comportamientos por separado. Fuerza una compaction a mitad de una prueba y comprueba que la acción siguiente siga respetando una restricción anterior. No utilices un transcript compactado como único registro de lo que se aprobó.

Memoria short-term del agente: el checkpoint store

LangGraph guarda checkpoints del estado del grafo en los límites de los super-steps: un nodo o un conjunto de nodos ejecutados en paralelo. Con el valor predeterminado durability="async", el paso siguiente puede ejecutarse mientras termina esa escritura; durability="sync" espera a que finalice la persistencia antes de continuar, lo que añade latencia de escritura. La recuperación tras un fallo utiliza el último checkpoint persistido, que no tiene por qué ser el paso completado más recientemente. Esta es la base de los workflows de pausar/reanudar, depuración time-travel y HITL.

Un checkpoint contiene el estado del grafo necesario para reanudar: el AgentState de la Parte 1: mensajes, identidad, perfil del usuario, pasos del plan, datos de investigación y modo de ejecución. Después de una interrupción HITL o del reinicio de un proceso, LangGraph restaura el último estado guardado y utiliza sus metadatos de scheduling para elegir el siguiente nodo. Reanuda en el límite de un nodo completado, no en una línea de Python arbitraria. Los detalles almacenados incluyen un ID de checkpoint y una marca temporal, una versión para cada canal —la denominación de LangGraph para una clave de estado— y las versiones de canal que cada nodo ya ha visto. El número de paso es metadato de ese checkpoint. Un checkpoint también se diferencia de un event log append-only o de un 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 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 del checkpointing. 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 duradero

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

Una versión simplificada de la configuración de checkpoints en memory/hot.py. Si un atacante pudiera escribir checkpoints, establece LANGGRAPH_STRICT_MSGPACK=true o configura allowed_msgpack_modules. Esto limita la deserialización a tipos seguros o declarados; el valor predeterminado permisivo avisa sobre tipos no registrados, pero sigue permitiéndolos.

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(authenticated_user_id: str) -> 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(
            {"user_id": authenticated_user_id,
             "messages": [HumanMessage(content="Analyze NVDA")]}, config
        )

        # After the server authenticates the approver and validates approval
        # of this exact draft, update the companion's approval field.
        await graph.aupdate_state(config, {"report_approved": True})
        # Continue the static interrupt_before pause; new input starts a new run.
        result = await graph.ainvoke(None, config)

# Local fixture identity. A server supplies this only after authentication.
asyncio.run(main(authenticated_user_id="user-123"))

El user_id de la entrada del grafo procede del contexto autenticado del servidor; thread_id solo localiza checkpoints y no establece la identidad ni autoriza el acceso a un thread. 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 locks: dos workers en el mismo thread no se corromperán mutuamente, pero tampoco coordinarán sus acciones.

Redis: cuando la latencia es el cuello de botella

Cuando la latencia del checkpoint 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 de checkpoints 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.
    Durability depends on RDB snapshots, AOF fsync policy, and replication.
    AOF with appendfsync everysec can still lose about one second of writes
    after a crash; enabling AOF alone is not a no-loss guarantee.
    """
    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 integró los valores de checkpoint y sustituyó la recuperación por canal por una ruta JSON.GET. Ese cambio afecta a la recuperación de valores, no a todas las operaciones de persistencia; las mediciones de latencia del proveedor dependen de su carga de trabajo. Redis 8.0+ incluye RedisJSON y RediSearch de forma predeterminada, sin necesidad de instalar módulos adicionales.

Elige la política de persistencia y fsync de Redis en función de la ventana de pérdida tolerada. RDB puede perder las escrituras posteriores al último snapshot; la política AOF habitual appendfsync everysec puede perder aproximadamente un segundo. always intercambia latencia de escritura por una persistencia más sólida, mientras que no deja el flushing en manos del sistema operativo. Prueba la recuperación con la configuración real de disco y replicación.

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

Cuándo utilizar cada uno

Utiliza PostgreSQL cuando:

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

Utiliza Redis cuando:

• La latencia del checkpoint sea tu cuello de botella (chat en tiempo real, UX en streaming)
• Estés construyendo bots de voz o experiencias en streaming en las que el acceso al checkpoint esté en una ruta crítica de latencia medida
• Necesites escalar horizontalmente entre muchos threads independientes. Si varios agentes modifican estado compartido, asigna un propietario a ese estado y coordínalo fuera del saver de checkpoints.
• Tengas 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 solo proceso. Para stacks nativos de AWS, langgraph-checkpoint-aws proporciona un DynamoDBSaver con offloading automático del payload; el saver documentado descarga los payloads por encima de su umbral de 350 KB cuando se configura un bucket S3. Ese umbral es una política de implementación, no el límite de 400 KB por elemento de DynamoDB. 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 datos, 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 recuperar datos 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 filtrada. Expliqué HNSW y sus compromisos en detalle en mi artículo sobre ranking de búsqueda. 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 el futuro. 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 alcance de la recuperación, no la autorización.

from qdrant_client import QdrantClient
from qdrant_client.models import (
    PointStruct, Distance, VectorParams, Filter, FieldCondition, MatchValue,
)
import hashlib
import json
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."""
        identity = json.dumps([principal.user_id, fact], ensure_ascii=False).encode()
        point_id = hashlib.sha256(identity).hexdigest()[:32]
        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 ID del punto aplica un hash a un array JSON formado por el ID del usuario y el dato, de modo que los delimitadores incluidos en cualquiera de los valores no puedan fusionar dos identidades. Por ejemplo, el usuario a:b con el dato c debe ser distinto del usuario a con el dato b:c. Los 32 caracteres hexadecimales encajan en la representación de point-ID UUID de Qdrant.

El flujo tiene tres pasos. En este diseño ilustrativo, un LLM extrae datos clave de la interacción («el usuario tiene una tolerancia alta al riesgo», «al usuario le interesan las acciones de empresas de semiconductores»). Esos datos 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 el 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 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 dato de ayer supere a otro equivalente de hace seis meses.
• Importancia: relevancia evaluada por un LLM en una escala de 1 a 10. «La cartera del usuario ha bajado un 40 %» obtiene una puntuación mayor que «el usuario ha dicho hola».
• Relevancia: similitud coseno de embeddings entre la consulta y el dato almacenado.

El artículo normaliza las tres señales a escalas comparables antes de combinarlas. Haz lo mismo antes de ajustar los pesos; de lo contrario, una puntuación de importancia bruta de 1 a 10 dominaría una señal de 0 a 1. La puntuación final de recuperación es una suma ponderada: score = alpha * recency + beta * importance + gamma * relevance. Esto evita que los datos recientes e importantes queden ocultos bajo otros obsoletos pero semánticamente similares. Para un prototipo de análisis financiero, empezaría con alpha = 0.3 para recencia, beta = 0.2 para importancia y gamma = 0.5 para relevancia, porque la consulta actual suele determinar qué dato válido debe entrar en el contexto. El artículo Generative Agents utilizó pesos iguales; estos valores son un punto de partida propuesto, no una mejora medida. Ajústalos con pruebas de recall retenidas y comprobaciones de calidad de las tareas antes de basarte en ellos.

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 utilizar alternativas:

Los almacenes clave-valor funcionan bien con datos estructurados. Si tu memoria a largo plazo es un perfil de usuario —tolerancia al riesgo, horizonte de inversión, sectores preferidos—, un hash de Redis o una columna JSONB de PostgreSQL es más sencillo y rápido que generar embeddings y consultar vectores. Utiliza 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 clave-valor basada en namespaces con búsqueda vectorial opcional. La API BaseStore es sencilla: put(), get(), search() y delete(), con alcance jerárquico mediante namespaces. Hay tres implementaciones disponibles:

• InMemoryStore: para desarrollo y pruebas (los datos se pierden al salir el proceso)
• PostgresStore: almacén persistente de producción con consultas SQL completas
• AsyncRedisStore: memoria entre threads con búsqueda vectorial, soporte de TTL y filtrado de 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 clave-valor si tu memoria está estructurada y bien definida (perfiles de usuario, ajustes, entidades con nombre). Añade búsqueda vectorial cuando necesites recuperación semántica sobre datos no estructurados o cuando la formulación de la consulta sea impredecible.

Los grafos de conocimiento resultan rentables cuando importan las relaciones entre entidades, por ejemplo: «¿Sobre qué empresas ha preguntado el usuario que sean competidoras de NVDA?». El proyecto reciente más interesante en este ámbito es Graphiti (de Zep), que construye un grafo de conocimiento con conciencia temporal y registra cuándo eran ciertos los datos, no solo qué era cierto. Sus relaciones temporales pueden conservar intervalos de validez y valores sustituidos; la lógica de extracción y actualización sigue determinando si un dato es actual. El artículo de Zep informa de una precisión DMR del 94,8 % para el sistema Zep evaluado, basado en Graphiti y GPT-4 Turbo, frente al 94,4 % del contexto completo. DMR utiliza conversaciones de 60 mensajes y una tarea limitada de recuperación de datos. Esa pequeña diferencia no demuestra una ventaja general de los grafos temporales.

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

Los frameworks de memoria gestionada, como Mem0 y Letta (antes MemGPT), se encargan 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 dato nuevo con las entradas existentes en el vector store y un resolver decide si añadir, actualizar, eliminar o no hacer nada. Esto mantiene el almacén 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, moviendo datos de forma autónoma entre la «core memory» (en contexto) y la «archival memory» (fuera de contexto). Ambos merecen evaluación si quieres reducir el tiempo hasta producción y no necesitas controlar por completo el pipeline de memoria.

Memoria documental: el archivador del agente

Los vector stores y los backends clave-valor gestionan bien la recuperación semántica y las búsquedas estructuradas. El contexto acumulado del proyecto —convenciones, notas de investigación y decisiones que se mantienen entre sesiones— suele pertenecer a archivos que las personas puedan leer, revisar y versionar.

Esto es la memoria documental: 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.

En una evaluación realizada por un proveedor, Letta informó de una precisión del 74,0 % en LoCoMo, un benchmark de pregunta-respuesta sobre conversaciones largas, para un agente basado en GPT-4o mini que utilizaba archivos adjuntos, embeddings automáticos, search_files semántico y reglas obligatorias para las herramientas de búsqueda. La mejor variante de grafo de Mem0 obtuvo un 68,5 %. Esto corresponde a un proveedor, modelo, benchmark y harness concretos. Demuestra que una interfaz orientada a archivos puede funcionar bien en esa configuración; no demuestra que el Markdown en bruto o la búsqueda por palabras clave sean suficientes. La ventaja operativa es independiente: los desarrolladores pueden leer, editar y comparar mediante diff directamente el conocimiento almacenado.

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

¿Por qué archivos?

Para un proyecto de agente de larga duración, utiliza un directorio de notas bien organizado cuando las personas necesiten un registro revisable. Piensa en un agente de coding que trabaja en un proyecto durante semanas:

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

Estos datos podrían vivir en un sistema vectorial o clave-valor. Aquí, los archivos son la mejor opción predeterminada porque el desarrollador necesita leer, editar, revisar y versionar notas relacionadas. Añade búsqueda por palabras clave o semántica solo cuando el corpus documental y el patrón de consulta lo requieran. Si el agente aprende algo incorrecto, abre el archivo y corrígelo.

Claude Code, Cursor y Devin Desktop utilizan variantes de este patrón. Los ejemplos siguientes muestran cómo almacena y carga sus archivos cada uno.

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 palabras clave en todos los documentos.

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

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.

        # ponytail: linear scan of file bytes; add an index when measured
        # latency, concurrency, or retrieval quality requires it.
        """
        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 las lecturas, las escrituras y los resultados de glob: las rutas relativas aún pueden salir de un directorio mediante .. o un symlink existente. Esta clase ilustrativa está pensada para un sistema de archivos de confianza, de un solo usuario o controlado. Comprueba una ruta resuelta antes de utilizarla; en un límite multi-tenant hostil, utiliza operaciones relativas al descriptor y sin seguimiento de symlinks para impedir que una mutación del sistema de archivos compita con esa comprobación. Ejecuta esta pequeña prueba de 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 memoria documental procede de cómo se organiza el directorio. Esta es la estructura que utilizarí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 de Markdown en bruto siguiente pertenece al diseño FileMemory independiente e ilustrativo 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, todos los documentos son Markdown y el propósito de cada uno resulta evidente por su 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 clave, pero no ofrecen la misma experiencia de diff con Markdown en bruto.

Cuándo utilizar memoria documental, vectorial o clave-valor

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

Utiliza memoria documental cuando:

• El agente acumule conocimiento del proyecto durante varias sesiones
• Los desarrolladores necesiten inspeccionar, editar o sobrescribir lo que el agente «sabe»
• El conocimiento esté estructurado como documentos (notas, resúmenes, convenciones), no como datos aislados
• Quieras versionar la memoria del agente mediante git
• El requisito de infraestructura cero sea estricto

Utiliza vector stores cuando:

• Necesites recuperación semántica difusa («encuentra memorias relacionadas con X»)
• La formulación de la consulta varíe de forma impredecible
• Tengas entre miles y millones de datos individuales

Utiliza almacenes clave-valor cuando:

• Necesites búsquedas exactas y rápidas de datos estructurados (perfiles de usuario, ajustes)
• El esquema de datos esté bien definido

Los tres almacenes pueden coexistir, pero no es obligatorio. El Market Analyst Agent actual utiliza checkpoints de PostgreSQL para la hot memory, Qdrant para el almacenamiento exacto del perfil de usuario con vectores placeholder y un document store namespaced de 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 los 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 normales, 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.
• El agente Cascade heredado de Devin Desktop lee reglas de .devin/rules/, manteniendo .windsurf/rules/ y el .windsurfrules de nivel raíz como fallbacks heredados. Cascade almacena memorias autogeneradas localmente por workspace y las recupera después; el agente Devin Local predeterminado para pestañas nuevas no persiste memorias.
• La memory tool de Anthropic para la API de Claude es una herramienta del lado del cliente que el modelo dirige mediante operaciones de 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 viven realmente los archivos (disco local, S3 o base de datos).

Las variantes respaldadas por archivos almacenan el conocimiento del agente como texto legible, con operaciones explícitas de lectura y escritura, y ninguna necesita un pipeline de embeddings. El agente decide qué escribir; cuando ese texto vive en un directorio local gestionado por Git, el desarrollador puede verlo y editarlo en un git diff. Cuando un handler de la memory tool de Anthropic asigna /memories a S3 o a una base de datos, la inspección y el versionado dependen de esa implementación.

Notas declarativas y skills ejecutables

El conocimiento respaldado por archivos también aparece fuera de los asistentes de coding, pero el formato de almacenamiento no indica cómo se utiliza. Voyager almacena programas JavaScript reutilizables que el agente puede ejecutar. El método Agent Workflow Memory, en cambio, añade workflows web inducidos al contexto del prompt como guía para acciones posteriores. Su experimento AWM_AS independiente expone los workflows como acciones invocables. Un procedimiento descrito en el contexto y un procedimiento ejecutable requieren comprobaciones distintas.

Prueba las skills invocables ejecutándolas en un entorno controlado y comprobando sus efectos. Revisa las notas del proyecto y los workflows contextuales para conocer los datos, restricciones y guías de acción que proporcionan; después comprueba si esas instrucciones mejoran el comportamiento posterior. Cualquiera de las dos formas puede conducir a una acción dañina; ninguna concede permisos adicionales.

Este mismo límite mantiene separadas la memoria, las skills y las herramientas. El estándar Agent Skills utiliza archivos SKILL.md para indicar al agente cómo realizar una clase de trabajo; la memoria registra datos aprendidos de un proyecto o de una ejecución anterior. La Parte 3 establece el límite vecino entre una skill y una herramienta. Elige un file store para el contexto aprendido e inspeccionable; elige una skill o una herramienta solo cuando el requisito sea un procedimiento o una capacidad reutilizable.

Escalar la memoria documental en producción

La implementación basada en archivos anterior encaja en un sistema de archivos controlado y de un solo usuario. Varios tenants y escritores concurrentes requieren coordinación explícita de acceso y escritura, independientemente del número de documentos.

El almacén en bruto anterior no tiene coordinación de escrituras concurrentes, modelo de tenants ni índice de búsqueda. Mide esos requisitos antes de sustituirlo. Una base de datos o un object store puede proporcionar contratos distintos de concurrencia y acceso; los archivos también pueden indexarse.

Tres enfoques habituales:

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

Mantén los archivos para la autoría (los desarrolladores editan Markdown localmente), pero sirve 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 desarrolladores (editar Markdown y hacer commit en git)
• Rendimiento de consulta en producción (lecturas desde una base de datos indexada)
• Separación clara entre autoría y serving

Enfoque B: object storage + sidecar de índice vectorial

Almacena los documentos en S3/GCS como objetos y utiliza una colección de Qdrant que indexe sus embeddings. El agente consulta Qdrant para obtener los IDs de documento relevantes y después recupera el contenido del object storage. Esto escala horizontalmente y admite búsqueda semántica, pero añade complejidad: dos sistemas que gestionar, un pipeline de embeddings que mantener y consistencia eventual entre el almacén 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 ofrece búsqueda híbrida (keyword + semántica), transacciones ACID y un único sistema operativo.

Este es un esquema del enfoque C. La puntuación combinada realiza scoring exacto sobre un corpus de tenants acotado; no utiliza un índice approximate nearest-neighbor (ANN). pgvector requiere ordenar directamente por distancia ascendente con LIMIT para esa ruta de índice. Para un corpus mayor, recupera por separado candidatos acotados por keyword y por vector y después fusiona sus rankings. Este es un patrón de RLS, no código de aplicación listo para usar: su rol de base de datos debe estar disponible únicamente para el servidor de aplicación de confianza. El servidor autentica la petición y construye principal; no acepta un ID de tenant del caller. PostgreSQL RLS hace que ese alcance 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);

        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 * COALESCE(1 - (embedding <=> $2), 0)) 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 alcance transaccional, por lo que una conexión de un pool no puede conservar el contexto de un tenant para la petición siguiente. El OR de la primera rama es lo que la convierte en híbrida. COALESCE mantiene en el conjunto de resultados, con su puntuación de texto, un documento que coincide por palabras clave pero no tiene embedding; no aporta similitud vectorial. Con solo el predicado @@, un documento que expresa el significado correcto pero no comparte palabras clave con la consulta se filtra antes de que se ejecute el scoring: eso es recuperación por keywords con reranking semántico, no recuperación híbrida. Los pesos 0,6/0,4 son ilustrativos: el ranking textual y la similitud coseno tienen escalas distintas. Normalízalos con tu evaluación de recuperación o utiliza rank fusion antes de interpretar esos pesos como importancia relativa. El umbral de distancia es un parámetro: ajústalo al alza si la rama vectorial inunda los resultados, o a la baja si nunca aparecen coincidencias semánticas.

La regresión siguiente representa el comportamiento que se debe probar contra una base de datos real después de las migraciones. 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 palabras clave (índice GIN) + similitud semántica (pgvector), puntuadas conjuntamente
• Multi-tenancy: identidad derivada por el servidor y RLS aplicada por la base de datos
• Garantías ACID: las transacciones en el primary hacen commit atómicamente; las lecturas de réplicas pueden tener lag
• Un único sistema operativo: no hay una base de datos vectorial separada que gestionar
• Escalado: las réplicas de lectura pueden servir consultas tolerantes a datos obsoletos. El particionado nativo puede ayudar con el pruning y el mantenimiento, pero no distribuye escrituras entre servidores; para eso se necesita un diseño explícito de sharding. Dirige las rutas read-after-write al primary o mide una política síncrona adecuada

Los archivos son excelentes para workflows de un solo 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 trabajar juntas 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 del grafo que puede reanudarse 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 event logs y traces del runtime son preocupaciones de producción independientes.

2. Cold path (long-term store): Después de que el router elija una ruta, el planner consulta el long-term store en busca de contexto relevante del usuario. El planner no puede personalizarse hasta que esa lectura devuelva resultados. Una búsqueda respaldada por vectores puede incluir la generación del embedding de la consulta y la recuperación desde el índice; una búsqueda clave-valor no. Los datos nuevos pueden extraerse y almacenarse después de terminar la conversación, de modo que esa escritura no retrase el reasoning loop.

3. Ruta documental (file store): Durante la planificación, el agente lee las convenciones del proyecto y las notas de investigación necesarias para la petición. Durante la ejecución, escribe en disco resúmenes de investigación y patrones aprendidos. Esas lecturas informan la tarea actual, por lo que el tamaño de los archivos, la velocidad del sistema de archivos y el estado de la caché afectan al tiempo de respuesta. Usa caché solo si tiene reglas claras de invalidación y aislamiento de tenants. Las escrituras pueden hacerse más tarde.

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 esquema local siguiente compila un builder StateGraph ya configurado, incluidos los nodos que aceptan el store. Esto amplía la conexión del grafo; los helpers create_graph de la Parte 1 y del companion no aceptan un argumento store. Utiliza InMemoryStore para mantener pequeño el snippet; la topología Docker de referencia usa Qdrant para el mismo papel 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:
        # builder is the configured StateGraph for this extended design.
        # The Part 1/companion create_graph helper does not accept store.
        graph = builder.compile(
            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

En el diseño ampliado anterior, la petición «Analyze TSLA» de un usuario que vuelve podría seguir este flujo. La recuperación semántica y la extracción asíncrona de datos son extensiones propuestas, no comportamientos actuales del companion:

1. Carga de la memoria documental: cuando se ejecuta el planner, lee del document store las convenciones del proyecto: preferencias de formato del análisis, fuentes de datos preferidas y patrones de uso de herramientas. Estas convenciones establecen el comportamiento base de ese plan.

2. Router: el router clasifica la petición como DEEP_RESEARCH. En este ejemplo, el routing utiliza la propia petición, no las preferencias a largo plazo.

3. Recuperación de cold memory + planner: el planner consulta el long-term store con el mensaje del usuario. Recupera: «El usuario tiene una tolerancia alta al riesgo», «El usuario prefiere un análisis detallado de la competencia» y «El usuario investigó anteriormente NVDA y AMD». Después crea un plan de investigación de cinco pasos personalizado según esas preferencias. Incluye un paso de análisis de la competencia 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 y observar, repetido hasta completar el paso. LangGraph crea un checkpoint en cada super-step (router, planner y cada paso secuencial del executor en este caso). La recuperación comienza en el último checkpoint persistido. Si la escritura del paso 3 se completó, el grafo puede continuar desde el paso 4; con persistencia asíncrona, un fallo puede obligar a repetir un paso ya completado.

5. Interrupción HITL: el reporter redacta un borrador. Otra sesión de modelo, sin historial de ese run, lee el borrador y registra una evaluación. El grafo llega entonces a publish, donde interrupt_before lo pausa independientemente de esa evaluación. El checkpoint contiene tanto el borrador como la evaluación, de modo que la persona puede revisarlos antes de decidir si publica. Horas después, el grafo recarga el checkpoint y sigue esa decisión.

6. Actualizaciones de memoria: después de terminar la conversación, un proceso asíncrono extrae nuevos datos del usuario («el usuario ahora sigue TSLA», «el usuario aprobó el formato del informe») y los almacena en el vector store 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 contiene el conocimiento acumulado del proyecto; es el cuaderno del agente.

Compromisos y consideraciones

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

• Coste de embeddings: cada dato almacenado en una base de datos vectorial requiere generar un embedding. Un proveedor de embeddings hosted añade una llamada a la API, un coste específico del proveedor y latencia de red; en septiembre de 2026, OpenAI lista text-embedding-3-small a $0,02 por millón de tokens. El coste por dato de un modelo hosted es insignificante, pero se acumula con miles de usuarios y sesiones. Agrupa las llamadas hosted y almacena los resultados en caché. En tiempo de consulta, la recuperación vectorial puede incluir el embedding de la consulta, el índice y la latencia de red; una búsqueda clave-valor no. Mide esa ruta en tu despliegue y después almacena en caché los embeddings de consultas frecuentes o utiliza un modelo local si la latencia es crítica.

• Memoria obsoleta: las preferencias del usuario cambian. Un dato almacenado hace seis meses («el usuario prefiere inversiones conservadoras») puede dejar de ser correcto. Define políticas de expiración. Por ejemplo, un equipo podría hacer expirar las preferencias a los 365 días y los eventos episódicos a los 90 días si sus reglas de privacidad, ritmo de actualización y evaluación de recuperación justifican esas ventanas; esos valores son una política propuesta, no valores predeterminados portables. El artículo sobre context engineering rechaza las reglas fijas de retención como política portable. La expiración es la versión más rudimentaria. El estado tipado guiado por esquema ofrece una solución más precisa: validez temporal y procedencia en cada dato, de modo que un valor sustituido pierda frente al actual durante la recuperación, no al expirar.

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

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

• Crecimiento del almacenamiento de checkpoints: las tablas de checkpoints de PostgreSQL crecen con cada super-step. No ejecutes una consulta SQL general de pruning: los canales delta pueden requerir checkpoints antecesores y sus registros de writes/blobs para reconstruir un checkpoint conservado. Utiliza una API de pruning proporcionada por el saver solo después de verificarla con el saver exacto instalado y su contrato de recuperación de canales delta. Si no existe ese soporte, conserva el cierre completo de parent, write y blob, y prueba la reanudación desde un checkpoint conservado 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ó por NVDA tres veces en enero», en lugar de almacenar literalmente las tres conversaciones. Esto imita la consolidación de la memoria humana y mantiene el almacén manejable. Mem0 y Graphiti lo gestionan automáticamente; si construyes 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 degradarse con elegancia y formular preguntas aclaratorias en lugar de hacer suposiciones. La memoria es aditiva, no obligatoria.

• Memory poisoning: cualquier elemento de la ventana de contexto del agente puede ser un punto de inyección. Si un atacante escribe datos 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 mediante memorias almacenadas es una superficie de ataque real. Las mitigaciones son validar antes de almacenar, tratar el contenido recuperado como datos no fiables y no como instrucciones del sistema, y aplicar controles de acceso que limiten qué memorias pueden influir en operaciones críticas.

• Drift de la memoria documental: la memoria basada en archivos no tiene 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 depurar y consolidar. Los archivos admiten grep; los payloads de los vector stores también pueden inspeccionarse o exportarse. Ningún formato de almacenamiento detecta contradicciones por sí solo.

• Escala de búsqueda: el escaneo de archivos en bruto anterior lee el corpus en cada consulta. Elige un índice según los bytes escaneados, el ritmo de actualización, la concurrencia, la latencia y la calidad de recuperación. El contenido respaldado por archivos puede utilizar un índice full-text o vectorial; el número de documentos por sí solo no determina el backend.

Probar la recuperación y el ciclo de vida de la memoria

Compara los baselines sin memoria y con contexto completo utilizando preguntas retenidas. Incluye paráfrasis, contradicciones, cambios de preferencias, datos obsoletos, preguntas sin respuesta, eliminaciones y peticiones entre tenants. LongMemEval proporciona 500 preguntas sobre extracción, razonamiento multi-sesión y temporal, actualizaciones y abstención. Mide la precisión/recall de la recuperación por separado de la corrección de la respuesta, además del uso de datos obsoletos, las revelaciones no autorizadas, la corrección de las operaciones de escritura/actualización/eliminación, la latencia y el coste.

Las preguntas de recuperación son solo una parte de la evaluación. MemoryArena añade tareas interdependientes entre sesiones, en las que una acción anterior y su feedback deben cambiar el comportamiento posterior. Sus tareas abarcan compras, planificación de viajes, búsqueda progresiva y razonamiento formal. Utiliza ese diseño cuando el producto prometa aprender del trabajo, no solo responder preguntas sobre conversaciones almacenadas. Son tareas de investigación, no mediciones de un servicio de memoria desplegado.

EvoMemBench también separa el conocimiento de la experiencia de ejecución, así como la memoria intra-episodio de la memoria entre episodios. Su comparación de 15 métodos no encuentra una forma de memoria uniformemente superior; los baselines de contexto largo siguen siendo competitivos con su protocolo. Esto respalda mantener los baselines sencillos en la evaluación, en lugar de sustituir cada almacén por el framework más reciente.

Conserva la procedencia y la validez junto a los datos recuperados. Las puntuaciones de importancia no pueden establecer la confianza ni cambiar permisos. La política de eliminación debe cubrir los índices, los resúmenes almacenados en caché y los artefactos conservados, además del registro original.

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 distinta. 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 memoria documental para la siguiente sesión del modelo —un tramo continuo de 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 fundamental 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 — Grafo de conocimiento bitemporal para la 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 — Biblioteca de skills como memoria documental para agentes de juegos de mundo abierto
• JARVIS-1: Open-World Multi-task Agents with Memory-Augmented Multimodal Language Models — 2023 — Biblioteca de memoria multimodal para agentes de Minecraft
• Agent Workflow Memory — Wang et al., 2024 — Inducción de workflows reutilizables para agentes web
• SkillWeaver: Web Agents can Self-Improve by Discovering and Honing Skills — 2025 — Herramientas API reutilizables autosintetizadas para agentes web
• LEGOMem: Modular Procedural Memory for Multi-agent LLM Systems for Workflow Automation — octubre de 2025 — Unidades de memoria procedimental reutilizables separadas entre el orquestador y los subagentes

Documentación de LangGraph

• LangGraph Persistence (Checkpointing) — Conceptos básicos de 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 checkpoints

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

Bases de datos vectoriales y herramientas de memoria

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

Memoria documental y basada en 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 del proyecto como archivos .mdc bajo .cursor/rules
• Devin Desktop Memories — Reglas de Cascade y memorias autogeneradas locales del workspace; Devin Local predeterminado no las persiste

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 — Herramientas 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 checkpoints y de almacenamiento actual de perfiles/documentos