Memória de sessão - Jelou AI Docs

O que é `ctx.memory`?

ctx.memory é um cliente HTTP para a Memory API da Jelou. Ele fala com o mesmo armazenamento chave-valor do usuário ($memory no builder). Tudo que você escrever a partir de uma Function é visível em placeholders {{$memory.key}} do workflow e vice-versa — é uma única memória por usuário, não uma cópia paralela. Disponível automaticamente quando a requisição vem de uma conversa ativa e a empresa tem uma chave de API de workflow configurada. Casos de uso típicos:

Fluxos multi-etapa — lembrar em qual etapa o usuário está
Carrinhos de compra — acumular produtos durante a conversa
Contadores — limitar tentativas de login, rastreamento de retentativas
Preferências do usuário — idioma, formato, filtros que persistem entre conversas

Quick start

index.ts

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

export default define({
  name: "registration-flow",
  description: "Multi-step registration with session memory",
  input: z.object({
    answer: z.string().optional(),
  }),
  handler: async (input, ctx) => {
    if (!ctx.memory.available) {
      return { error: "memory_unavailable" };
    }

    const step = await ctx.memory.get("step", "start");

    if (step === "start") {
      await ctx.memory.set("step", "name", 3600);
      return { question: "Qual é o seu nome?" };
    }

    if (step === "name") {
      await ctx.memory.set("name", input.answer || "", 3600);
      await ctx.memory.set("step", "email", 3600);
      return { question: "Qual é o seu e-mail?" };
    }

    const name = await ctx.memory.get("name", "");
    await ctx.memory.delete("step");
    await ctx.memory.delete("name");
    return { completed: true, name, email: input.answer };
  },
});

Verificar disponibilidade

if (!ctx.memory.available) {
  ctx.log("Memória não disponível — fora de uma conversa ou sem chave de API de workflow");
  return { error: "memory_unavailable" };
}

ctx.memory.available é false quando a requisição não vem de uma conversa ativa ou a chave de API de workflow não está configurada. Chamar métodos em um cliente indisponível lança um Error.

Primitivos vs JSON

Use set()/get() para valores simples e setJson()/getJson() para objetos:

await ctx.memory.set("step", "confirmation", 3600);
const step = await ctx.memory.get("step", "start");

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

O tipo de retorno de get() corresponde ao tipo do valor padrão:

const name = await ctx.memory.get("name", "anonymous");   // string
const attempts = await ctx.memory.get("attempts", 0);     // number
const verified = await ctx.memory.get("verified", false); // boolean

TTL (time to live)

Existem duas camadas de expiração na Memory:

TTL por variável (o que você passa ao set) — controla quando essa variável individual expira.
hashTTL de 30 dias (gerenciado pela plataforma) — controla quando a memória completa do usuário expira. Quando expira, toda a sua Memory é apagada.

Renovação do hashTTL a partir de ctx.memory: escritas via ctx.memory apenas inicializam o hashTTL quando a memória do usuário está vazia; escritas posteriores não o estendem. Já escritas via $memory no builder estendem o hashTTL a cada write. Se seu fluxo persistir apenas via Functions e precisar de atividade contínua, combine com ao menos uma escrita a partir do builder.

O TTL por variável é especificado em segundos:

Método	TTL por variável	Máximo por variável
`set()`	Opcional	86.400 (24h)
`setJson()`	Obrigatório	86.400 (24h)

await ctx.memory.set("step", "payment");                  // no explicit TTL
await ctx.memory.set("step", "payment", 1800);            // expires in 30 min
await ctx.memory.setJson("cart", cart, 86400);            // expires in 24h (maximum)

Limites

Restrição	Valor
Comprimento máximo de `set()`	255 caracteres
TTL máximo por variável	86.400 segundos (24h)
Duração total da memória do usuário	30 dias desde a primeira escrita; apenas escritas via `$memory` no builder renovam a janela (ver Warning acima)
Escopo	Por usuário — mesma memória que o `$memory` do builder vê

Valores de set() que excedem 255 caracteres lançam um Error. Para dados maiores, use setJson().

Padrões comuns

Fluxo multi-etapa
Carrinho de compras
Limite de tentativas

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

  if (step === "start") {
    await ctx.memory.set("step", "data", 3600);
    return { next: "data" };
  }

  if (step === "data") {
    await ctx.memory.set("name", input.name, 3600);
    await ctx.memory.set("step", "confirm", 3600);
    return { next: "confirm", name: input.name };
  }

  const name = await ctx.memory.get("name", "");
  await ctx.memory.delete("step");
  await ctx.memory.delete("name");
  return { completed: true, name };
}

interface Cart {
  items: Array<{ id: string; name: string; price: number; quantity: number }>;
  total: number;
}

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

  cart.items.push({
    id: input.productId,
    name: input.name,
    price: input.price,
    quantity: input.quantity,
  });
  cart.total = cart.items.reduce(
    (sum, i) => sum + i.price * i.quantity, 0
  );

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

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

  if (attempts >= 3) {
    return { blocked: true, message: "Too many attempts" };
  }

  const valid = input.pin === "1234";
  if (!valid) {
    await ctx.memory.set("pin_attempts", attempts + 1, 1800);
    return { blocked: false, error: "Incorrect PIN" };
  }

  await ctx.memory.delete("pin_attempts");
  return { blocked: false, verified: true };
}

Tratamento de erros

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

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

Quando usar `ctx.memory` vs um banco de dados?

	`ctx.memory`	Banco de dados externo
Escopo	Por usuário	Global
Persistência	Até 30 dias de inatividade · TTL opcional em `set()`, obrigatório em `setJson()` (máx 24h)	Permanente
Configuração	Zero — incluído	Requer connection string nos secrets
Ideal para	Estado da conversa, preferências do usuário	Dados históricos, catálogos, config compartilhada

Acessar memória de outro usuário

A partir de triggers cron ou event, você pode acessar a memória de um usuário específico com ctx.memory.for(userId):

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

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

    // Acessar a memória do usuário 12345
    const userMemory = ctx.memory.for("12345");
    const step = await userMemory.get("step", "unknown");

    if (step === "pending") {
      await userMemory.set("step", "reminded", 3600);
    }

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

ctx.memory.for() só funciona a partir de triggers cron ou event. Em requisições HTTP normais, ctx.memory já está vinculado à sessão do usuário atual — chamar .for() lança um erro.

​O que é ctx.memory?

​Quick start

​Verificar disponibilidade

​Primitivos vs JSON

​TTL (time to live)

​Limites

​Padrões comuns

​Tratamento de erros

​Quando usar ctx.memory vs um banco de dados?

​Acessar memória de outro usuário

O que é `ctx.memory`?

Quick start

Verificar disponibilidade

Primitivos vs JSON

TTL (time to live)

Limites

Padrões comuns

Tratamento de erros

Quando usar `ctx.memory` vs um banco de dados?

Acessar memória de outro usuário