Arquitectura de memoria para agentes que recuerdan

Pídele a tres ingenieros que le "agreguen memoria" a un agente y vas a terminar con tres sistemas distintos, porque "memoria" esconde tres problemas separados: mantener coherente la conversación actual, recordar qué pasó en sesiones anteriores y conocer datos duraderos sobre el usuario y el dominio. Si los juntas, construyes el anti-patrón clásico, todo metido en un solo vector store, que sale lento, caro y, sin que te des cuenta, equivocado justo en los datos que más importan. Esta guía separa las tres capas, guarda cada una en el store más barato que le sirva, y te da un schema concreto en Supabase más la política de lectura y escritura que de verdad decide si tu agente se siente como que recuerda o como que está adivinando.

El encuadre que vuelve obvio todo lo demás: la memoria no es una base de datos que le atornillas al agente. Es un presupuesto que gastas. Cada token de contexto recuperado le quita espacio al modelo para razonar, así que la ingeniería de verdad está en decidir qué vale la pena llevar al siguiente turno y qué soltar.

01 · Requisitos y el modelo de tres capas

Antes de tocar SQL, deja claro el modelo, porque condiciona cada decisión de almacenamiento y retrieval que viene después. Hay tres tipos de memoria, y son problemas genuinamente distintos:

• Memoria de trabajo: la conversación actual. Vive en la ventana de contexto y desaparece cuando termina la sesión. Su única forma de fallar es desbordarse.
• Memoria episódica: qué pasó en sesiones anteriores. "El martes pasado el usuario preguntó por reembolsos y lo resolvimos." Con marca de tiempo, narrativa, recuperada por recencia y relevancia.
• Memoria semántica: datos duraderos sobre el usuario o el dominio. "Esta cuenta está en el plan Pro." "El usuario prefiere unidades métricas." Atemporales hasta que cambian, y tienen que estar exactos.

Necesitas tener un par de cosas listas antes de escribir código:

1. Un proyecto de Supabase (o cualquier Postgres 14+ con la extensión vector). El tier gratis sobra para armar esto.
2. Un modelo de embeddings y su dimensión de salida exacta, por ejemplo 1536. Ese número queda fijo en el tipo de una columna y no lo puedes cambiar después sin volver a generar todos los embeddings.
3. Las API keys del modelo de embeddings y de Claude, en variables de entorno, jamás en la base de datos ni en el bundle del cliente.
4. Una respuesta clara a una pregunta por cada dato que vayas a guardar: ¿esto tiene que estar exacto, o solo ser relevante? Esa sola pregunta decide a dónde va cada escritura.

02 · Memoria de trabajo: resume, no recortes

La memoria de trabajo es la conversación que el modelo tiene enfrente. El arreglo ingenuo cuando se desborda es descartar los turnos más viejos, y así es justo como un agente se olvida del límite que le diste hace cinco mensajes. El arreglo más barato y mejor es resumir los turnos viejos en un brief continuo y mantener ese brief en contexto en vez del transcript crudo.

El patrón es una compactación progresiva: deja los últimos turnos tal cual, y una vez que el transcript pasa cierto umbral de tokens, le pides al modelo que pliegue todo lo más viejo en un brief compacto que conserve decisiones, límites y preguntas abiertas, y luego descartas los turnos crudos que ese brief reemplazó.

Lo que el brief tiene que conservar, en orden de prioridad:

1. Decisiones y compromisos, como "acordamos usar Postgres", "la fecha límite es el viernes".
2. Límites duros, como "tiene que quedar por debajo de 200ms", "nunca le escribas un correo al cliente".
3. Hilos abiertos: qué sigue sin resolverse y esperando.

Todo lo demás (cortesías, contexto repetido, callejones sin salida) se puede perder sin problema. El arte está en el prompt que escribe el brief, no en el almacenamiento; aquí no hay nada que persistir más allá de la sesión.

03 · Memoria episódica: filas con tiempo y un resumen

La memoria episódica es el registro de sesiones pasadas: qué se habló, qué se decidió, cómo terminó. Guárdala como filas de Postgres a secas, una fila por sesión o por evento que valga la pena, con una marca de tiempo y un resumen corto. Aquí no entran los vectores primero; este es un lugar para recencia y filtrado estructurado, con recall semántico montado encima solo cuando la recencia por sí sola no alcanza.

Una fila por episodio, escrita al cerrar la sesión por el mismo resumidor que corrió la compactación de tu memoria de trabajo:

create table episodic_memory (
  id         bigint generated always as identity primary key,
  user_id    uuid not null,
  summary    text not null,            -- "Resolvió duda de reembolso; prometió seguimiento el viernes"
  outcome    text,                     -- "resolved" | "escalated" | "open"
  embedding  vector(1536),             -- opcional, para recall semántico
  created_at timestamptz not null default now()
);

create index on episodic_memory (user_id, created_at desc);

El retrieval va por recencia primero: "las últimas cinco sesiones con este usuario" es un solo query indexado y resuelve la mayoría de los casos. Agrega la columna de embedding para también poder pedir "sesiones pasadas parecidas en sentido a lo que está preguntando ahora" cuando la conversación hace referencia a algo viejo. El índice sobre (user_id, created_at desc) es lo que mantiene rápido el caso común; el vector es el camino de excepción, no el default.

La disciplina que vuelve útil la memoria episódica es escribir buenos resúmenes. Una fila que dice "el usuario hizo unas preguntas" es ruido. Una fila que dice "usuario en plan Pro pidió bajar de plan; le expliqué el prorrateo; decidió quedarse" es un recuerdo que de verdad vale la pena tener.

04 · Memoria semántica: vectores para recall, almacenamiento exacto para la verdad

Esta es la capa que todos agarran de primero y en la que más se equivocan. La memoria semántica guarda datos duraderos, y se parte limpiamente en dos stores según la pregunta de la sección 01: ¿exacto, o nada más relevante?

Datos que tienen que estar exactos, usa clave-valor exacto

La dirección actual de un usuario, su plan, su preferencia de idioma, si se dio de baja del correo: esos nunca se deben aproximar. Guárdalos en una tabla sencilla con clave por usuario y nombre del dato, y léelos con un lookup exacto:

create table user_facts (
  user_id    uuid not null,
  key        text not null,           -- "shipping_address" | "plan" | "email_optout"
  value      text not null,
  updated_at timestamptz not null default now(),
  primary key (user_id, key)
);

Leer un dato es un lookup por primary key que devuelve el único valor verdadero. Actualizarlo sobrescribe la fila en su lugar, así que el agente siempre ve el estado actual, no la conjetura histórica más cercana.

Conocimiento que solo necesita ser relevante, usa vectores

Preferencias dichas al pasar, notas del dominio, "cosas que al usuario le suelen importar", conocimiento difuso que se va acumulando, es donde pgvector se gana el sueldo. Genera el embedding de cada nota y recupéralas por similitud con el turno actual. Es la misma maquinaria de vecino más cercano que usa RAG, pero apuntada a datos sobre el usuario en vez de a un corpus de documentos.

La división es justo el punto: el almacenamiento exacto responde "qué es verdad" y los vectores responden "qué podría ser relevante". Si los mezclas, te queda un agente que afirma con toda seguridad cosas equivocadas que tranquilamente debería haber consultado.

05 · Ejemplo práctico: armar el contexto dentro de un presupuesto

Ahora conecta las capas en un solo paso de retrieval. El error aquí es volcar al prompt todo lo que encuentres. El retrieval es un presupuesto: fija un techo de tokens para la memoria, llénalo por prioridad y para. Los datos exactos son baratos y sostienen todo lo demás, así que van primero; los episodios relevantes y las notas semánticas llenan lo que quede.

async function buildContext(userId: string, userTurn: string, tokenBudget = 1500) {
  // 1. Primero los hechos exactos — pequeños, obligatorios, tienen que estar correctos.
  const facts = await getUserFacts(userId)        // reads por primary key

  // 2. Episodios recientes — recencia primero, baratos y casi siempre suficientes.
  const recent = await getRecentEpisodes(userId, 5)

  // 3. Recall semántico — solo episodios/notas relevantes para este turno.
  const related = await searchSemantic(userId, userTurn, 4)

  // Llena el presupuesto por prioridad; nunca lo excedas.
  return packByPriority(
    [factsBlock(facts), episodesBlock(recent), notesBlock(related)],
    tokenBudget,
  )
}

El orden es la política. Los datos entran enteros porque son pequeños y la corrección depende de ellos. Los episodios vienen después porque la recencia resuelve la mayoría de las preguntas. Las notas semánticas llenan el presupuesto que sobre. Cuando el presupuesto está apretado, el primer bloque que se recorta es el de menor prioridad, y el modelo igual se queda con sus datos y su historial reciente.

Errores comunes

• Todo en un solo vector store. El anti-patrón estrella. Los datos que tienen que estar exactos terminan emparejados de forma difusa, y el agente manda el paquete a la dirección equivocada. Mejor enruta por exacto vs. relevante.
• Recortar la memoria de trabajo. Descartar los turnos viejos elimina sin avisar los límites que diste. Resume en un brief continuo; deja los últimos turnos en crudo.
• Resúmenes episódicos vagos. "El usuario hizo preguntas" es ruido que ensucia el recall. Escribe resúmenes que una sesión futura de verdad querría tener.
• Retrieval sin tope. Echarle veinte matches al prompt le quita espacio al razonamiento e infla el costo. Fija un presupuesto y llénalo por prioridad.
• Nunca dejar que la memoria decaiga. Los episodios viejos se acumulan y diluyen la relevancia. Vence o bájale el peso a las filas viejas que nunca se recuperan.

06 · Decaimiento, corrección y saber cuándo esto ya alcanza

La memoria que solo crece a la larga te juega en contra: mientras más filas viejas cargues, más ruidoso se vuelve cada retrieval. Mete el decaimiento desde el arranque. Bájale el peso a los episodios que nunca se recuperan, vence las filas de poco valor después de cierta ventana y, esto es clave, haz que corregir salga barato. Cuando un dato cambia, sobrescribe la fila exacta; cuando un episodio queda superado, márcalo en vez de dejar que afloren las dos versiones.

Sé honesto también sobre el techo. Este diseño de tres stores en un solo proyecto de Supabase le sirve de sobra a productos reales: Postgres para lo episódico y los datos exactos, pgvector para el recall semántico. Solo le ves los límites cuando el índice semántico ya no cabe en memoria, o cuando necesitas búsqueda híbrida pesada con reranking sobre millones de notas, y aun así la migración es mecánica, porque cada capa ya está separada y cada fila ya carga sus claves. Arranca aquí; la mayoría de los agentes nunca lo superan.

La memoria no es una función que instalas; es un conjunto de decisiones sobre qué guardar, qué consultar y qué olvidar. Separa las tres capas, enruta cada dato según si tiene que estar exacto o nada más ser relevante, gasta el retrieval como un presupuesto, y tu agente deja de adivinar y empieza a recordar de verdad, sobre infraestructura que ya tienes corriendo.