# 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-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add golemcloud/golem-custom-snapshot-moonbit-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/golemcloud/golem-custom-snapshot-moonbit-2/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-2

---


# 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 `ToJson` and `@json.FromJson` derives and generates a `Snapshottable` implementation that serializes the agent as JSON.

### 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 `Snapshottable` trait manually:

```moonbit
pub(open) trait Snapshottable {
  save_snapshot(Self) -> Bytes
  load_snapshot(Self, Bytes) -> Result[Unit, 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 bytes = Bytes::new(8)
  let v = self.value
  for i in 0..<8 {
    bytes[i] = ((v >> ((7 - i).to_uint64() * 8)).to_int() & 0xff).to_byte()
  }
  bytes
}

///|
pub impl @agents.Snapshottable for Counter with load_snapshot(self, bytes) {
  if bytes.length() != 8 {
    return Err("Expected an 8-byte long snapshot")
  }
  let mut v : UInt64 = 0
  for i in 0..<8 {
    v = v | (bytes[i].to_uint64() << ((7 - i).to_uint64() * 8))
  }
  self.value = v
  Ok(())
}
```

### Method Signatures

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

// Load: restore the agent's state from previously saved bytes
// Return Err to signal the update should fail and the agent should revert
load_snapshot(Self, Bytes) -> Result[Unit, String]
```

## 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, the generated code automatically provides a `Snapshottable` implementation using JSON serialization.
2. If the agent has a manual `impl Snapshottable`, the custom implementation is used instead.
3. The `ConstructedAgent` records the `snapshottable` interface reference and `snapshot_format` (Json or Binary).
4. The SDK's `save-snapshot` and `load-snapshot` WIT exports delegate to these implementations.

## 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.
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.