Memoria de sesión - Jelou AI Docs

¿Qué es `ctx.memory`?

ctx.memory es un cliente HTTP al Memory API de Jelou. Habla con el mismo almacenamiento key-value del usuario ($memory en el builder). Lo que escribas desde una Function es visible en placeholders {{$memory.key}} del workflow y viceversa — es una sola memoria por usuario, no una copia paralela. Disponible automáticamente cuando la petición viene de una conversación activa y la empresa tiene una API key de workflow configurada. Casos de uso típicos:

Flujos multi-paso — recordar en qué paso está el usuario
Carritos de compras — acumular productos durante la conversación
Contadores — limitar intentos de login, tracking de reintentos
Preferencias del usuario — idioma, formato, filtros que persisten entre conversaciones

Inicio rápido

index.ts

import { define, z } from "@jelou/functions";

export default define({
  name: "flujo-registro",
  description: "Registro multi-paso con memoria de sesión",
  input: z.object({
    respuesta: z.string().optional(),
  }),
  handler: async (input, ctx) => {
    if (!ctx.memory.available) {
      return { error: "memory_unavailable" };
    }

    const paso = await ctx.memory.get("paso", "inicio");

    if (paso === "inicio") {
      await ctx.memory.set("paso", "nombre", 3600);
      return { pregunta: "¿Cuál es tu nombre?" };
    }

    if (paso === "nombre") {
      await ctx.memory.set("nombre", input.respuesta || "", 3600);
      await ctx.memory.set("paso", "email", 3600);
      return { pregunta: "¿Cuál es tu email?" };
    }

    const nombre = await ctx.memory.get("nombre", "");
    await ctx.memory.delete("paso");
    await ctx.memory.delete("nombre");
    return { completado: true, nombre, email: input.respuesta };
  },
});

Verificar disponibilidad

if (!ctx.memory.available) {
  ctx.log("Memory no disponible — fuera de una conversación o sin API key de workflow");
  return { error: "memory_unavailable" };
}

ctx.memory.available es false cuando la petición no viene de una conversación activa o la API key del workflow no está configurada. Llamar a métodos en un cliente no disponible lanza un Error.

Primitivos vs JSON

Usa set()/get() para valores simples y setJson()/getJson() para objetos:

await ctx.memory.set("paso", "confirmacion", 3600);
const paso = await ctx.memory.get("paso", "inicio");

await ctx.memory.setJson("carrito", { items: [], total: 0 }, 86400);
const carrito = await ctx.memory.getJson("carrito", { items: [], total: 0 });

El tipo de retorno de get() coincide con el tipo del valor por defecto:

const nombre = await ctx.memory.get("nombre", "anónimo");     // string
const intentos = await ctx.memory.get("intentos", 0);           // number
const verificado = await ctx.memory.get("verificado", false);   // boolean

TTL (tiempo de vida)

Hay dos capas de expiración en Memory:

TTL por variable (el que pasas al set) — controla cuándo caduca esa variable individual.
hashTTL de 30 días (gestionado por la plataforma) — controla cuándo caduca la memoria completa del usuario. Cuando expira, se borra todo su Memory.

Renovación del hashTTL desde ctx.memory: las escrituras vía ctx.memory solo inicializan el hashTTL cuando la memoria del usuario está vacía; escrituras posteriores no lo extienden. En cambio, las escrituras vía $memory en el builder sí extienden el hashTTL en cada write. Si tu flujo persiste solo desde Functions y necesitas actividad continua, combina con al menos una escritura desde el builder.

El TTL por variable se especifica en segundos:

Método	TTL por variable	Máximo por variable
`set()`	Opcional	86,400 (24h)
`setJson()`	Requerido	86,400 (24h)

await ctx.memory.set("paso", "pago");                 // sin TTL explícito
await ctx.memory.set("paso", "pago", 1800);           // expira en 30 min
await ctx.memory.setJson("carrito", carrito, 86400);   // expira en 24h (máximo)

Límites

Restricción	Valor
Longitud máxima de `set()`	255 caracteres
TTL máximo por variable	86,400 segundos (24h)
Duración total de la memoria del usuario	30 días desde la primera escritura; solo las escrituras vía `$memory` del builder renuevan la ventana (ver Warning arriba)
Alcance	Por usuario — misma memoria que ve `$memory` del builder

Valores de set() que excedan 255 caracteres lanzan un Error. Para datos más grandes, usa setJson().

Patrones comunes

Flujo multi-paso
Carrito de compras
Límite de intentos

handler: async (input, ctx) => {
  const paso = await ctx.memory.get("paso", "inicio");

  if (paso === "inicio") {
    await ctx.memory.set("paso", "datos", 3600);
    return { siguiente: "datos" };
  }

  if (paso === "datos") {
    await ctx.memory.set("nombre", input.nombre, 3600);
    await ctx.memory.set("paso", "confirmar", 3600);
    return { siguiente: "confirmar", nombre: input.nombre };
  }

  const nombre = await ctx.memory.get("nombre", "");
  await ctx.memory.delete("paso");
  await ctx.memory.delete("nombre");
  return { completado: true, nombre };
}

interface Carrito {
  items: Array<{ id: string; nombre: string; precio: number; cantidad: number }>;
  total: number;
}

handler: async (input, ctx) => {
  const vacio: Carrito = { items: [], total: 0 };
  const carrito = await ctx.memory.getJson<Carrito>("carrito", vacio);

  carrito.items.push({
    id: input.productoId,
    nombre: input.nombre,
    precio: input.precio,
    cantidad: input.cantidad,
  });
  carrito.total = carrito.items.reduce(
    (sum, i) => sum + i.precio * i.cantidad, 0
  );

  await ctx.memory.setJson("carrito", carrito, 86400);
  return { carrito };
}

handler: async (input, ctx) => {
  const intentos = await ctx.memory.get("intentos_pin", 0);

  if (intentos >= 3) {
    return { bloqueado: true, mensaje: "Demasiados intentos" };
  }

  const valido = input.pin === "1234";
  if (!valido) {
    await ctx.memory.set("intentos_pin", intentos + 1, 1800);
    return { bloqueado: false, error: "PIN incorrecto" };
  }

  await ctx.memory.delete("intentos_pin");
  return { bloqueado: false, verificado: true };
}

Manejo de errores

import { MemoryApiError } from "@jelou/functions";

try {
  await ctx.memory.set("paso", "pago", 3600);
} catch (err) {
  if (err instanceof MemoryApiError) {
    ctx.log("Memory API falló", { status: err.status, code: err.code });
    if (err.isRateLimit()) {
      return { error: "rate_limit", retryAfter: 2 };
    }
  }
  throw err;
}

¿Cuándo usar `ctx.memory` vs una base de datos?

	`ctx.memory`	Base de datos externa
Alcance	Por usuario	Global
Persistencia	Hasta 30 días de inactividad · TTL opcional en `set()`, requerido en `setJson()` (máx 24h)	Permanente
Configuración	Cero — viene incluido	Requiere connection string en secrets
Ideal para	Estado de conversación, preferencias del usuario	Datos históricos, catálogos, config compartida

Acceder a memoria de otro usuario

Desde triggers cron o event, puedes acceder a la memoria de un usuario específico con ctx.memory.for(userId):

import { define } from "@jelou/functions";

export default define({
  name: "recordatorio-usuario",
  handler: async (_input, ctx) => {
    if (!ctx.isCron && !ctx.isEvent) return { skipped: true };

    // Acceder a la memoria del usuario 12345
    const userMemory = ctx.memory.for("12345");
    const paso = await userMemory.get("paso", "desconocido");

    if (paso === "pendiente") {
      await userMemory.set("paso", "recordado", 3600);
    }

    return { checked: true, paso };
  },
});

ctx.memory.for() solo funciona desde triggers cron o event. En requests HTTP normales, ctx.memory ya está vinculado a la sesión del usuario actual — llamar .for() lanza un error.

​¿Qué es ctx.memory?

​Inicio rápido

​Verificar disponibilidad

​Primitivos vs JSON

​TTL (tiempo de vida)

​Límites

​Patrones comunes

​Manejo de errores

​¿Cuándo usar ctx.memory vs una base de datos?

​Acceder a memoria de otro usuario

¿Qué es `ctx.memory`?

Inicio rápido

Verificar disponibilidad

Primitivos vs JSON

TTL (tiempo de vida)

Límites

Patrones comunes

Manejo de errores

¿Cuándo usar `ctx.memory` vs una base de datos?

Acceder a memoria de otro usuario