# Golem Custom Snapshot Moonbit

> Enabling snapshot-based recovery and implementing custom snapshot save/load functions for MoonBit agents. Use when adding manual update support, custom state serialization, or — equally importantly — when a long-running agent's oplog is growing large and recovery/replay is becoming slow (heartbeats, polling loops, recurring tasks, frequent state changes). Snapshotting compacts the oplog and lets recovery start from the latest snapshot instead of replaying full history.

- Skill: `golemcloud/golem-custom-snapshot-moonbit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add golemcloud/golem-custom-snapshot-moonbit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/golemcloud/golem-custom-snapshot-moonbit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: golemcloud (https://skillmd.com/u/golemcloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/golemcloud/golem-custom-snapshot-moonbit

---


# Custom Snapshots in MoonBit

Golem agents can implement the `Snapshottable` trait to support manual (snapshot-based) updates and snapshot-based recovery.

## 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 (`every_n(N)`), 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.

## Automatic JSON Snapshotting (Default)

When the agent struct derives `ToJson` and `@json.FromJson`, the SDK's code generation automatically provides JSON-based snapshotting. Enable it via the `snapshotting` attribute on `#derive.agent`:

```moonbit
#derive.agent(snapshotting="every_n(1)")
struct Counter {
  name : String
  mut value : UInt64
} derive(ToJson, @json.FromJson)

fn Counter::new(name : String) -> Counter {
  { name, value: 0 }
}

pub fn Counter::increment(self : Self) -> Unit {
  self.value += 1
}

pub fn Counter::get_value(self : Self) -> UInt64 {
  self.value
}
```

The code generation tool detects both `ToJson` and `@json.FromJson` derives and generates JSON saving plus a restoration factory. Automatic loading is generated only when the complete agent type is JSON-deserializable.

### Snapshotting Modes

The `snapshotting` attribute accepts these values:

| Mode | Example | Description |
|------|---------|-------------|
| (omitted) | `#derive.agent` | Snapshotting disabled |
| Every N | `#derive.agent(snapshotting="every_n(1)")` | Snapshot every N successful invocations |

## Custom Snapshotting

For custom binary serialization or cross-version migration, implement the saving-only `Snapshottable` trait and define a separate static restoration factory:

```moonbit
pub(open) trait Snapshottable {
  save_snapshot(Self) -> Bytes
}

pub fn Agent::load_snapshot(
  bytes : Bytes,
  context : @agents.SnapshotRestoreContext,
) -> Result[Agent, String]
```

### Example

```moonbit
#derive.agent(snapshotting="every_n(1)")
struct Counter {
  name : String
  mut value : UInt64
}

fn Counter::new(name : String) -> Counter {
  { name, value: 0 }
}

pub fn Counter::increment(self : Self) -> Unit {
  self.value += 1
}

pub fn Counter::get_value(self : Self) -> UInt64 {
  self.value
}

///|
pub impl @agents.Snapshottable for Counter with save_snapshot(self) {
  // Serialize value as 8 big-endian bytes
  let arr : Array[Byte] = []
  for i = 7; i >= 0; i = i - 1 {
    arr.push(((self.value >> (i * 8)).to_int() & 0xff).to_byte())
  }
  Bytes::from_array(arr)
}

///|
pub fn Counter::load_snapshot(
  bytes : Bytes,
  context : @agents.SnapshotRestoreContext,
) -> Result[Counter, String] {
  if bytes.length() != 8 {
    return Err("Expected an 8-byte long snapshot")
  }
  let mut v : UInt64 = 0
  for i = 0; i < 8; i = i + 1 {
    v = v | (bytes[i].to_uint64() << ((7 - i) * 8))
  }
  let name : String = context.identity(0) catch {
    error => return Err(error.to_string())
  }
  Ok({ name, value: v })
}
```

### Method Signatures

```moonbit
// Save: serialize the agent's current state to bytes
save_snapshot(Self) -> Bytes

// Load: static factory returning a complete agent from bytes and restore context
// Return Err to reject the snapshot
Agent::load_snapshot(Bytes, SnapshotRestoreContext) -> Result[Agent, String]
```

The restoration factory does not receive `self` and does not call `Agent::new`. Its context provides identity fields, the full agent ID, restored principal, and phantom ID. Fresh agent configuration remains available through the SDK's config API.

## Restoration Is Read-Only

`load_snapshot` is a specially supported SDK lifecycle operation, not an agent method. It must return the complete fresh agent value; the SDK installs that value only after the factory succeeds.

Snapshot loading runs in read-only mode and writes nothing to the oplog. Decoding, local computation, config reads, and other permitted reads can be used to construct the value. Mutating host operations and outgoing HTTP or agent RPC calls are rejected before they take effect.

If the factory returns `Err`, partial state is discarded. A manual update remains on the previous component version. During automatic recovery, Golem recreates the component and replays without the failed automatic snapshot; it does not try an older automatic snapshot.

## How the SDK Wires Snapshots

The code generation tool (`golem_sdk_tools agents`) produces a `ConstructedAgent` struct for each agent. When snapshotting is enabled:

1. If the agent has `ToJson` + `@json.FromJson` derives, generated code provides JSON saving and a restoration factory.
2. If the agent has a manual `impl Snapshottable`, the static `Agent::load_snapshot` factory is required and the custom binary implementation is used instead.
3. The `ConstructedAgent` records the `snapshottable` interface reference and `snapshot_format` (`Json` or `Binary`).
4. Registration keeps normal construction and snapshot restoration as distinct factories.
5. The SDK's `save-snapshot` and `load-snapshot` WIT exports delegate to these operations.

## Best Practices

1. **Prefer automatic (JSON) snapshotting** — derive `ToJson` and `@json.FromJson` on the agent struct for zero-effort persistence.
2. **Keep snapshots small** — large snapshots impact recovery and update time.
3. **Version your snapshot format** — include a version byte so `load_snapshot` can handle snapshots from older versions.
4. **Test round-trips** — verify that `save_snapshot` → `load_snapshot` produces equivalent state without calling `new`.
5. **Handle migration** — when the state schema changes between versions, `load_snapshot` in the new version should be able to parse snapshots from the old version.
6. **Return `Err` to reject incompatible snapshots** — `load_snapshot` returning `Err` causes the update to fail gracefully, reverting the agent to the old version.