golem-custom-snapshot-ts

Custom Snapshots in TypeScript

Golem agents can opt into snapshotting to support manual (snapshot-based) updates and snapshot-based recovery. In the fluent SDK this is configured declaratively with the snapshotting option on defineAgent(...), and — when you need full control over the bytes — with a snapshot: { save, load } block on .implement(...).

When to Use Snapshotting

Snapshotting solves two distinct problems:

1. Manual / snapshot-based component updates — required when updating agents between incompatible component versions.
2. Fast recovery and oplog compaction — for long-running agents whose oplog grows over time (heartbeats, polling loops, recurring tasks, agents with frequent state changes). Without snapshotting, every recovery replays the full oplog from the beginning, which becomes increasingly expensive. With periodic snapshotting, recovery starts from the latest snapshot and replays only the entries after it.

You cannot opt out of oplog writes for a durable agent. If you are worried about oplog volume or replay cost, do not try to skip persistence — enable snapshot-based recovery here instead.

Enabling Snapshotting

Set the snapshotting option on defineAgent(...). Without it, snapshotting is disabled:

import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';

export const CounterAgent = defineAgent({
    name: 'CounterAgent',
    id: { name: z.string() },
    http: http.mount('/counters/{name}'),
    // Typed state schema + a policy for WHEN to snapshot.
    snapshotting: { state: z.object({ count: z.number() }), policy: { everyNInvocations: 1 } },
    methods: {
        increment: method({ input: {}, returns: z.number(), http: http.post('/increment') }),
    },
});

Snapshotting Policies

The policy controls when a snapshot is taken. It can be given directly (snapshotting: 'default') or inside { policy, state }:

Typed State Snapshotting (recommended)

Give snapshotting a state schema to snapshot only the schema-declared fields of your state — typed and scoped, so scratch/ephemeral fields are not persisted. On recovery the executor restores those fields from the last snapshot and replays the oplog tail. This is the declarative fluent replacement for overriding save/loadSnapshot.

export const CounterAgentImpl = CounterAgent.implement({
    // `count` is persisted; any other field returned here is not.
    init: () => ({ count: 0 }),
    methods: {
        increment() {
            this.count += 1;
            return this.count;
        },
    },
});

A bare policy without a state schema (e.g. snapshotting: 'default' or snapshotting: { everyNInvocations: 5 }) falls back to reflective JSON serialization of the whole state (config fields are excluded). Prefer the typed state form.

Custom Snapshotting

For state the default JSON path can't represent (a compact binary format, cross-version migration logic), supply a snapshot: { save, load } block on .implement(...). this is the agent state; save() returns the raw snapshot bytes and load(bytes) restores from them:

import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';

export const CounterWithSnapshot = defineAgent({
    name: 'CounterWithSnapshot',
    id: { name: z.string() },
    http: http.mount('/snapshot-counters/{name}'),
    snapshotting: { everyNInvocations: 1 },
    methods: {
        increment: method({
            input: {},
            returns: z.number(),
            promptHint: 'Increase the count by one',
            description: 'Increases the count by one and returns the new value',
            http: http.post('/increment'),
        }),
    },
});

export const CounterWithSnapshotImpl = CounterWithSnapshot.implement({
    init: () => ({ value: 0 }),
    methods: {
        increment() {
            this.value += 1;
            return this.value;
        },
    },
    snapshot: {
        save() {
            const snapshot = new Uint8Array(4);
            new DataView(snapshot.buffer).setUint32(0, this.value);
            console.info(`Saved snapshot: ${this.value}`);
            return snapshot;
        },
        load(bytes) {
            this.value = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0);
            console.info(`Loaded snapshot: ${this.value}`);
        },
    },
});

Signatures

// save: serialize the agent's state into raw snapshot bytes.
save(): Uint8Array | Promise<Uint8Array>

// load: restore the agent's state from previously saved snapshot bytes.
load(bytes: Uint8Array): void | Promise<void>

A custom snapshot block overrides the default serialization entirely. load may throw to signal that an update should fail and the agent should revert to the old version.

Best Practices

1. Prefer the typed state schema unless you need a compact binary format or cross-version migration logic.
2. Keep snapshots small — large snapshots impact recovery and update time.
3. Version your snapshot format — include a version byte or marker so load can handle snapshots from older versions.
4. Test round-trips — verify that save → load produces equivalent state.
5. Handle migration — when the state schema changes between versions, load in the new version should be able to parse snapshots from the old version.
6. Define both or neither — always provide save and load together to keep serialization consistent.

Project Template

A ready-made project with snapshotting can be created using:

golem new --yes --language ts --template snapshotting my-project