Memoization

Mark a Step memoizable: true to cache successful results and skip re-execution on identical inputs. Covers the cache key (step definition plus inputs), in-memory LRU semantics, and when memoization is and isn't safe.

What It Is

Memoization caches Step results so that identical inputs return immediately without calling the Step again. It’s opt-in per Step via memoizable: true.

{
  "id": "lookup-exchange-rate",
  "name": "Lookup Exchange Rate",
  "memoizable": true,
  "type": "sync",
  "http": { "endpoint": "https://api.example.com/rates", "timeout": 5000 },
  "attributes": {
    "from_currency": { "role": "required", "type": "string" },
    "to_currency": { "role": "required", "type": "string" },
    "rate": { "role": "output", "type": "number" }
  }
}

How It Works

The cache key is derived from the Step’s definition (type, config, attributes) and the input values. If the same Step runs with the same inputs, the cached result is returned and the Step handler is never called.

graph TD Execute["Step scheduled to execute"] Check{"Cache hit?"} Call["Call step handler"] Cache["Store result in cache"] Return["Return cached result"] Done["Output available to Flow"] Execute --> Check Check -->|"yes"| Return --> Done Check -->|"no"| Call --> Cache --> Done

Updating a Step definition automatically invalidates the cache, since the definition is part of the key.

Cache Properties

In-memory per engine instance, not shared across instances, not persisted on restart
LRU eviction, configurable size (default 65536 entries) via MEMO_CACHE_SIZE
No TTL, entries live until evicted
Failure not cached, only successful executions are cached, so failures always retry

When to Use It

Use memoization for steps that are:

Deterministic: same inputs always produce the same output
Read-only: no side effects, no state changes
Expensive: slow API calls, heavy computation, repeated patterns

Do not use it for payments, writes, timestamps, random values, or anything where calling the Step twice with the same inputs would produce different or dangerous results.