Session memory

What is `ctx.memory`?

ctx.memory is an HTTP client to Jelou’s Memory API. It talks to the same key-value store as the user’s memory ($memory in the builder). Anything you write from a Function is visible in {{$memory.key}} placeholders in the workflow and vice versa — it is a single memory per user, not a parallel copy. Automatically available when the request comes from an active conversation and the company has a workflow API key configured. Typical use cases:

Multi-step flows — remember which step the user is on
Shopping carts — accumulate products during the conversation
Counters — limit login attempts, retry tracking
User preferences — language, format, filters that persist across conversations

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: "What is your name?" };
    }

    if (step === "name") {
      await ctx.memory.set("name", input.answer || "", 3600);
      await ctx.memory.set("step", "email", 3600);
      return { question: "What is your email?" };
    }

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

Check availability

if (!ctx.memory.available) {
  ctx.log("Memory not available — outside a conversation or no workflow API key");
  return { error: "memory_unavailable" };
}

ctx.memory.available is false when the request does not come from an active conversation or the workflow API key is not configured. Calling methods on an unavailable client throws an Error.

Primitives vs JSON

Use set()/get() for simple values and setJson()/getJson() for objects:

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 });

The return type of get() matches the type of the default value:

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)

There are two expiration layers in Memory:

Per-variable TTL (the one you pass to set) — controls when that individual variable expires.
30-day hashTTL (managed by the platform) — controls when the user’s entire memory expires. When it elapses, all of their Memory is wiped.

hashTTL renewal from ctx.memory: writes through ctx.memory only initialize the hashTTL when the user’s memory is empty; subsequent writes do not extend it. Writes through $memory in the builder do extend the hashTTL on every write. If your flow persists exclusively through Functions and needs continuous activity, combine with at least one write from the builder.

The per-variable TTL is specified in seconds:

Method	Per-variable TTL	Max per variable
`set()`	Optional	86,400 (24h)
`setJson()`	Required	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)

Limits

Restriction	Value
Max length of `set()`	255 characters
Max per-variable TTL	86,400 seconds (24h)
Total user memory duration	30 days from the first write; only writes through `$memory` in the builder renew the window (see Warning above)
Scope	Per user — same memory the builder’s `$memory` sees

Values from set() that exceed 255 characters throw an Error. For larger data, use setJson().

Common patterns

Multi-step flow
Shopping cart
Attempt limit

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 };
}

Error handling

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;
}

When to use `ctx.memory` vs a database?

	`ctx.memory`	External database
Scope	Per user	Global
Persistence	Up to 30 days of inactivity · TTL optional for `set()`, required for `setJson()` (max 24h)	Permanent
Setup	Zero — included	Requires connection string in secrets
Ideal for	Conversation state, user preferences	Historical data, catalogs, shared config

Accessing another user’s memory

From cron or event triggers, you can access a specific user’s memory with ctx.memory.for(userId):

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

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

    // Access user 12345's memory
    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() only works from cron or event triggers. In regular HTTP requests, ctx.memory is already bound to the current user’s session — calling .for() throws an error.

Getting Started

Developer

Jelou CLI

Outbound Messaging

Management

Marketplace

Channels

Configuration

Billing

What is `ctx.memory`?

Quick start

Check availability

Primitives vs JSON

TTL (time to live)

Limits

Common patterns

Error handling

When to use `ctx.memory` vs a database?

Accessing another user’s memory

​What is ctx.memory?

​Quick start

​Check availability

​Primitives vs JSON

​TTL (time to live)

​Limits

​Common patterns

​Error handling

​When to use ctx.memory vs a database?

​Accessing another user’s memory

What is `ctx.memory`?

Quick start

Check availability

Primitives vs JSON

TTL (time to live)

Limits

Common patterns

Error handling

When to use `ctx.memory` vs a database?

Accessing another user’s memory