​

Redis session cache

​

Write-through pattern

1. Cursor write — SET ctx:<sessionId>:cursor <cursor JSON> EX <ttl> records the new storage cursor (seq, entry id, rawSha256).
2. Tail invalidation — DEL ctx:<sessionId>:tail drops the cached transcript tail, so the next read repopulates it from Postgres.

append → Postgres commit → SET cursor (EX ttl) → DEL tail
read   → GET tail → cursor match? serve : SELECT from Postgres → SET tail (EX ttl)

​

What is cached

​

Degradation semantics

• Operation timeout: 250 ms. Any Redis op slower than that is abandoned and the Postgres path serves the read.
• Connect timeout: 1 s; close timeout: 250 ms. A cache that cannot come up at gateway start is skipped (redis ctx cache unavailable; continuing without cache).
• Failures log at most once per 60 s (Redis ctx cache operation failed; continuing from Postgres) instead of per operation.
• Missing redisUrl logs redis ctx cache requires session.storage.redisUrl; continuing without cache and starts cacheless.

​

Configuration surface

​

For administrators

// ~/.openclaw/openclaw.json
{
  session: {
    storage: {
      backend: "postgres",
      databaseUrl: "postgres://user:pass@host:5432/wednesdayai",  // or OPENCLAW_DATABASE_URL
      cache: "redis",
      redisUrl: "redis://cache-host:6379",
      redis: {
        keyPrefix: "ctx",     // default
        ttlSeconds: 300,      // default: 5 minutes
      },
    },
  },
}

• The cache takes effect at gateway startup — restart after changing these keys (Linux: systemctl --user restart openclaw-gateway; macOS: wednesdayai gateway restart --deep).
• cache: "redis" without backend: "postgres" is ignored (SQLite and JSONL backends have no Redis cache path).
• Redis going down or being flushed is safe: reads fall back to Postgres automatically and logged warnings are rate-limited to once a minute. Expect elevated Postgres load and slower tail reads during an outage — nothing else changes.
• The cache stores derived/correlated data only; Postgres remains the sole durable store. Do not point ttlSeconds at retention expectations — TTL only bounds staleness of cached copies.
• redis (the node-redis client) is loaded lazily; only Postgres+cache installs need it available.

​

Extending from a plugin

import type { StorageCursor } from "openclaw/plugin-sdk";

type CachedProjection = { cursor: StorageCursor; payload: Record<string, unknown> };

function isFresh(cached: CachedProjection, current: StorageCursor | undefined): boolean {
  if (!current) return false;
  return (
    cached.cursor.backend === current.backend &&
    cached.cursor.sessionId === current.sessionId &&
    cached.cursor.seq === current.seq &&
    cached.cursor.rawSha256 === current.rawSha256
  );
}

​

Related

• Context engine — the read paths this cache accelerates
• Sessions — storage backends, maintenance, and privacy
• Plugin hooks reference — storage.afterAppend and context hooks