User-Defined Snapshotting

Golem recovers agent state by replaying the oplog — the log of all operations performed by the agent. For long-running or CPU-heavy agents, this replay can become slow. Golem 1.5 introduces user-defined snapshotting, allowing agents to opt in to periodic snapshots so that recovery only needs to replay entries recorded after the last snapshot.

Snapshotting also enables manual agent updates between incompatible versions — see Updating Agents for details.

Go snapshotting is not supported in this release. Leave snapshotting disabled for Go agents and use oplog replay for recovery. There is no go/snapshotting template. The Go API examples below are reference material, not a supported recovery or update workflow.

Automatic snapshotting is optional. Without it, recovery starts from the authoritative recovery baseline, if one exists: the snapshot of the last successful manual update or snapshot-assisted automatic update. Otherwise it replays the full oplog.

Snapshotting is for durable agents only. An ephemeral agent takes no snapshots: a restart of an ephemeral agent replays only its initialization and never loads a snapshot. Each SDK refuses an ephemeral agent definition that enables snapshotting, and golem build refuses a component with such an agent type. The error names the agent. Remove the snapshotting option or make the agent durable.

Default snapshotting implementation

Each language SDK can generate JSON saving and loading when the complete agent state has an explicit JSON-deserialization contract. Automatic loading is not generated for arbitrary state: use custom snapshotting when your SDK cannot deserialize the complete state.

These counters use the default JSON implementation, without custom byte encoding. Each example requests a snapshot after every successful invocation to make the behavior easy to try. This is an example schedule, not the server’s default snapshotting policy; see Configuring snapshot-based recovery for other schedules.

TypeScript

Provide a state schema in the snapshotting configuration and do not provide a custom snapshot: { save, load } block. The SDK serializes and restores the schema-defined state as JSON:


import { defineAgent, method } from '@golemcloud/golem-ts-sdk';
import { z } from 'zod';
 
const Counter = defineAgent({
  name: 'Counter',
  id: { name: z.string() },
  snapshotting: {
    state: z.object({ value: z.number() }),
    policy: { everyNInvocations: 1 },
  },
  methods: {
    increment: method({ input: {}, returns: z.number() }),
  },
});
 
Counter.implement({
  init: () => ({ value: 0 }),
  methods: {
    increment() {
      this.value += 1;
      return this.value;
    },
  },
});

Only the schema-defined value is saved. On restoration, the SDK decodes it into fresh state without calling init. A bare enabled policy without state requires a custom save/load pair.

Effect TypeScript

Declare the saved value with Snapshot.define(...) and use a matching implementation strategy such as Snapshot.ref():


import { Effect, Ref, Schema } from "effect";
import { defineAgent, method, Snapshot } from "@golemcloud/effect-golem";
 
const Counter = defineAgent({
  name: "Counter",
  id: { name: Schema.String },
  snapshotting: Snapshot.define({
    schema: Schema.Struct({ value: Schema.Number }),
    policy: Snapshot.policy.everyN(1),
  }),
  methods: {
    increment: method({ input: {}, success: Schema.Number }),
  },
});
 
Counter.implement<Ref.Ref<{ value: number }>>({
  init: () => Ref.make({ value: 0 }),
  methods: (state) => ({
    increment: () => Ref.updateAndGet(state, ({ value }) => ({
      value: value + 1,
    })).pipe(Effect.map(({ value }) => value)),
  }),
  snapshot: Snapshot.ref<{ value: number }>(),
});

Snapshot.ref() reads the value from the Ref when saving and creates a new Ref from the decoded state when restoring. Restoration does not call init.

Rust

If your agent struct implements Serialize and DeserializeOwned (from serde ), do not override the save_snapshot and load_snapshot methods. The SDK will use a default JSON-based implementation. Ordinary owned structs commonly satisfy these bounds by deriving Serialize and Deserialize.


use golem_rust::{agent_definition, agent_implementation};
use golem_rust::serde::{Deserialize, Serialize};
 
#[agent_definition(snapshotting = "every(1)")]
trait Counter {
    fn new(name: String) -> Self;
    fn increment(&mut self) -> u32;
}
 
#[derive(Serialize, Deserialize)]
struct CounterImpl {
    name: String,
    value: u32,
}
 
#[agent_implementation]
impl Counter for CounterImpl {
    fn new(name: String) -> Self {
        Self { name, value: 0 }
    }
 
    fn increment(&mut self) -> u32 {
        self.value += 1;
        self.value
    }
}

Serde saves and restores both fields. Restoration deserializes CounterImpl directly; it does not call new.

Scala

Mix Snapshotted[S] into the implementation and provide a Schema[S] (from zio-blocks-schema ). The SDK handles JSON, while a companion loadSnapshot(state, context) factory constructs the complete implementation instance.


import golem.{BaseAgent, Snapshotted}
import golem.runtime.SnapshotRestoreContext
import golem.runtime.annotations.{agentDefinition, agentImplementation}
import zio.blocks.schema.Schema
import scala.concurrent.Future
 
@agentDefinition(snapshotting = "every(1)")
trait Counter extends BaseAgent {
  class Id(val value: String)
  def increment(): Future[Int]
}
 
final case class CounterState(value: Int) derives Schema
 
@agentImplementation()
final class CounterImpl(private val name: String)
    extends Counter with Snapshotted[CounterState] {
  var state: CounterState = CounterState(0)
 
  override def increment(): Future[Int] = Future.successful {
    state = state.copy(value = state.value + 1)
    state.value
  }
}
 
object CounterImpl {
  def loadSnapshot(
    state: CounterState,
    context: SnapshotRestoreContext
  ): Future[CounterImpl] = Future.successful {
    val instance = new CounterImpl(context.identity[String](0))
    instance.state = state
    instance
  }
}

The snapshot contains CounterState. The factory restores that state and gets the constructor identity from the restore context instead of saving it twice.

MoonBit

If your agent struct derives ToJson and @json.FromJson, the SDK auto-generates JSON saving and a restoration factory.


#derive.agent(snapshotting="every_n(1)")
pub(all) struct Counter {
  name : String
  mut value : Int
} derive(ToJson, FromJson)
 
pub fn Counter::new(name : String) -> Counter {
  { name, value: 0 }
}
 
pub fn Counter::increment(self : Self) -> Int {
  self.value += 1
  self.value
}

The generated loader decodes both fields from JSON without calling new. No custom snapshot trait or loader is needed.

Go

If the state type does not implement golem.Snapshotter, the SDK saves the state’s exported fields as JSON and restores them with encoding/json. Unexported fields are not visible to it, so keep the state you need in exported fields or use custom snapshotting:


package counter
 
import "github.com/golemcloud/golem/sdks/go/golem"
 
type ID struct{ Name string }
 
type state struct {
    Value int64 `json:"value"`
}
 
var Agent = golem.DefineAgent[ID](golem.Spec{
    Name: "Counter",
    Snapshot: golem.SnapshotEveryN(1),
})
var Increment = Agent.Method[golem.Unit, int64]("increment")
 
func init() {
    counter := Agent.Implement(func(ID) *state { return &state{} })
    counter.Handle(Increment, func(
        ctx *golem.Context[state],
        _ golem.Unit,
    ) int64 {
        ctx.State.Value++
        return ctx.State.Value
    })
}

The SDK restores Value into a fresh state without running the constructor passed to Implement. No custom Save or Load methods are needed.

Evolving the state schema

During a manual update, the source revision saves a snapshot, and the target revision loads it. With the default implementation, the target revision decodes the saved JSON using its own state schema or deserializer. It does not run normal initialization first, so values supplied only by init or a constructor do not fill missing snapshot fields.

The target revision must be able to decode the snapshots of the agents you update:

TypeScript

With Zod, give a new field a .default(...) value or make it .optional(). A new required field without a decoding default makes loading fail when the saved JSON does not contain it:


snapshotting: {
    state: z.object({
        value: z.number(),
        label: z.string().default(''),
        lastUpdated: z.number().optional(),
    }),
    policy: { everyNInvocations: 1 },
}

This schema can load an earlier snapshot containing only value. The restored label is ''; lastUpdated may be absent, so agent methods must handle that case.

Effect TypeScript

The schema passed to Snapshot.define(...) decodes the saved state before the restoration strategy runs. Make new fields optional in that schema, or give them a decoding default. A default supplied only by init does not apply.

To convert an existing JSON snapshot, keep Snapshot.define(...) and use a schema that accepts the earlier representation. The restoration strategy can then construct the target state from the decoded value. Switching to Snapshot.custom(...) does not bypass JSON decoding: that mode accepts only binary snapshot envelopes.

Rust

The default loader uses serde_json::from_slice::<Self>. Give a new field #[serde(default)], use an Option<T> field, or provide a custom deserializer that accepts the earlier JSON. A constructor default alone does not affect Serde decoding.

Scala

The JSON codec derived from the target revision’s Schema[S] decodes the saved state before calling loadSnapshot(state, context). The codec must accept missing new fields or supply decoding defaults. A default in the implementation constructor does not repair a codec error; use custom byte-based snapshot loading when you need to convert an earlier state format.

MoonBit

The generated loader uses @json.from_json to decode the saved JSON into the target revision’s agent type. Its FromJson implementation must accept missing new fields. When the derived implementation cannot decode the earlier JSON, use a custom load_snapshot factory to convert it.

Go

The default loader decodes the saved JSON with encoding/json into the zero value of the target revision’s state struct. A new field that the saved JSON does not contain keeps its zero value, and a field that the target revision removed is ignored. The constructor does not run, so set a default for a new field in the OnRestore hook:


agent.OnRestore(func(_ *golem.InitContext[ID, state, golem.NoConfig], s *state) error {
    if s.Label == "" {
        s.Label = "unnamed"
    }
    return nil
})

A changed field type makes decoding fail. Implement golem.Snapshotter to convert an earlier state format.

A Go agent cannot take a manual (snapshot-based) update yet, so a target revision does not load a Go snapshot during an update. Snapshot-based recovery and automatic updates work. See Updating agents.

For a rename or type change, the loader must accept the earlier representation and convert it to the complete target state. Use custom snapshotting when the default decoder cannot do this, subject to the SDK’s format restrictions described above. A version marker can help a custom loader select the conversion, but the marker alone does not make an earlier snapshot loadable. Test loading a snapshot saved by the source revision, not just a save/load round-trip in the target revision.

If decoding fails during a manual update, the update fails and the agent stays on its source revision. Inspect the update history:


golem agent get <AGENT_ID>

The history shows Failed update to ... with details such as Manual update failed to load snapshot: ... followed by the loader error. A typed TypeScript schema mismatch includes snapshot state does not match its declared schema. Fix the loader or schema in a new revision, deploy it, and request the update again. See Updating agents.

The same decoding rule applies when an automatic update uses a snapshot from the source revision. A decoding failure during a snapshot-assisted automatic update has UPDATE_SNAPSHOT_INCOMPATIBLE; see Failure codes.

Custom snapshotting

You can implement custom saving and restoration to control exactly how agent state is serialized. Saving runs on the live instance. Loading is a separate factory that returns the complete state or instance; the SDK never runs the normal agent initialization path first and then hands that instance to the loader. The following example shows a counter agent that saves its count as raw bytes:

TypeScript

Provide a snapshot: { save, load } block on .implement(...). save() has the agent state as this. load(bytes, context) has no this and returns a complete fresh state object:


import { z } from 'zod';
import { defineAgent, method } from '@golemcloud/golem-ts-sdk';
 
export const Counter = defineAgent({
    name: 'Counter',
    id: { name: z.string() },
    snapshotting: { everyNInvocations: 1 },
    methods: {
        increment: method({ input: {}, returns: z.number() }),
    },
});
 
export const CounterImpl = Counter.implement({
    init: () => ({ value: 0 }),
    methods: {
        increment() {
            this.value += 1;
            return this.value;
        },
    },
    snapshot: {
        save() {
            const snapshot = new Uint8Array(8);
            new DataView(snapshot.buffer).setFloat64(0, this.value);
            return snapshot;
        },
        load(bytes, _context) {
            const value = new DataView(
                bytes.buffer,
                bytes.byteOffset,
                bytes.byteLength,
            ).getFloat64(0);
            return { value };
        },
    },
});

Effect TypeScript

Select binary snapshots on the definition and provide save and restore effects on the implementation. Restoration constructs fresh state and does not run init first:


import { Effect, Ref } from "effect"
import { Snapshot } from "@golemcloud/effect-golem"
 
// In defineAgent({ ... }):
snapshotting: Snapshot.custom({
  policy: Snapshot.policy.everyN(1),
})
 
// In .implement({ ... }):
snapshot: {
  save: (state) =>
    Ref.get(state).pipe(
      Effect.map((value) => {
        const bytes = new Uint8Array(8)
        new DataView(bytes.buffer).setFloat64(0, value)
        return bytes
      }),
    ),
  restore: (bytes, _context) =>
    Ref.make(
      new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
        .getFloat64(0),
    ),
}

Rust

Define instance save_snapshot and an associated load_snapshot factory. The factory returns Self; it does not receive &mut self:


use golem_rust::{agent_definition, agent_implementation};
use golem_rust::agentic::SnapshotRestoreContext;
 
#[agent_definition(snapshotting = "every(1)")]
trait Counter {
    fn new(name: String) -> Self;
    fn increment(&mut self) -> u32;
}
 
struct CounterImpl { value: u32 }
 
#[agent_implementation]
impl Counter for CounterImpl {
    fn new(_name: String) -> Self {
        Self { value: 0 }
    }
 
    fn increment(&mut self) -> u32 {
        self.value += 1;
        self.value
    }
 
    async fn save_snapshot(&self) -> Result<Vec<u8>, String> {
        Ok(self.value.to_le_bytes().to_vec())
    }
 
    async fn load_snapshot(
        bytes: Vec<u8>,
        _context: SnapshotRestoreContext,
    ) -> Result<Self, String> {
        let arr: [u8; 4] = bytes
            .try_into()
            .map_err(|_| "Invalid snapshot".to_string())?;
        Ok(Self { value: u32::from_le_bytes(arr) })
    }
}

Scala

Define saveSnapshot() on the implementation and loadSnapshot(...) on its companion object:


import golem.BaseAgent
import golem.runtime.SnapshotRestoreContext
import golem.runtime.annotations.{agentDefinition, agentImplementation}
import scala.concurrent.Future
 
@agentDefinition(snapshotting = "every(1)")
trait Counter extends BaseAgent {
  class Id(val value: String)
  def increment(): Future[Int]
}
 
@agentImplementation()
final class CounterImpl(name: String) extends Counter {
  private var value: Int = 0
 
  override def increment(): Future[Int] = Future.successful {
    value += 1
    value
  }
 
  def saveSnapshot(): Future[Array[Byte]] =
    Future.successful {
      val buffer = java.nio.ByteBuffer.allocate(4)
      buffer.putInt(value)
      buffer.array()
    }
}
 
object CounterImpl {
  def loadSnapshot(
    bytes: Array[Byte],
    context: SnapshotRestoreContext
  ): Future[CounterImpl] = Future.successful {
    val instance = new CounterImpl(context.identity[String](0))
    instance.value = java.nio.ByteBuffer.wrap(bytes).getInt()
    instance
  }
}

MoonBit

Implement the saving-only @agents.Snapshottable trait and define a separate static load_snapshot factory:


pub impl @agents.Snapshottable for Counter with save_snapshot(self) {
  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 snapshot")
  }
  let mut value: UInt64 = 0
  for i = 0; i < 8; i = i + 1 {
    value = value | (bytes[i].to_uint64() << ((7 - i) * 8))
  }
  let name: String = context.identity(0) catch {
    error => return Err(error.to_string())
  }
  Ok({ name, value })
}

Go

Implement golem.Snapshotter (Save() ([]byte, error) and Load([]byte) error) on the state type. A restore does not run the constructor passed to Implement: the SDK calls Load on a zero state, then runs the optional OnRestore hook, which receives the same *golem.InitContext as a configured constructor (ID, agent ID, principal, config) and rebuilds what the snapshot does not carry:


type state struct{ value int64 }
 
func (s *state) Save() ([]byte, error) {
    return binary.BigEndian.AppendUint64(nil, uint64(s.value)), nil
}
 
func (s *state) Load(data []byte) error {
    if len(data) != 8 {
        return errors.New("expected an 8-byte snapshot")
    }
    s.value = int64(binary.BigEndian.Uint64(data))
    return nil
}
 
func init() {
    agent.OnRestore(func(ic *golem.InitContext[ID, state, golem.NoConfig], s *state) error {
        // rebuild runtime-only fields here, e.g. from ic.ID()
        return nil
    })
}

Multipart snapshots: JSON state and named bytes

Use explicit multipart snapshots when the live instance contains binary resources that should not be serialized into JSON. Save a small schema-backed state projection separately from a dynamic map of named {bytes, contentType} parts. This is an additional mode: the simpler JSON, byte-only, and existing SQLite snapshot modes remain available.

These examples save a revision counter and an in-memory binary index. The loaders construct fresh live state; ordinary initialization is skipped.

TypeScript

Select multipart.state in the definition. Both save and load are required, and may be async. The live state returned by init is independent of the saved schema.


import { Snapshot } from '@golemcloud/golem-ts-sdk';
 
// In defineAgent({ ... }):
snapshotting: {
  multipart: { state: z.object({ revision: z.number() }) },
  policy: { everyNInvocations: 10 },
}
 
// In .implement({ ... }), with live { revision, index }:
snapshot: {
  async save() {
    return {
      state: { revision: this.revision },
      parts: new Map([
        ['index', { bytes: this.index, contentType: 'application/octet-stream' }],
      ]),
    };
  },
  async load(saved, _context) {
    return {
      revision: saved.state.revision,
      index: Snapshot.requirePart(saved.parts, 'index', 'application/octet-stream'),
    };
  },
}

Standard Schema validates the input on save, but the SDK persists that input JSON, not a transformed validation result. On load, the schema validates stored JSON and the loader receives its output type. There is no reverse encoding. Do not combine state and multipart configuration. Explicit multipart does not automatically discover SQLite databases and rejects managed db: parts.

Effect TypeScript

Snapshot.multipart requires an explicit strategy. Effect Schema encodes the saved state and decodes it before restoration.


// In defineAgent({ ... }):
snapshotting: Snapshot.multipart({
  schema: Schema.Struct({ revision: Schema.Number }),
  policy: Snapshot.policy.everyN(10),
})
 
// In .implement({ ... }), with a Ref of { revision, index }:
snapshot: {
  save: (ref) => Ref.get(ref).pipe(Effect.map((live) => ({
    state: { revision: live.revision },
    parts: new Map([
      ['index', { bytes: live.index, contentType: 'application/octet-stream' }],
    ]),
  }))),
  restore: (saved, _context) => Effect.gen(function* () {
    const index = yield* Snapshot.requirePart(saved.parts, 'index', 'application/octet-stream')
    return yield* Ref.make({ revision: saved.state.revision, index })
  }),
}

To compose managed SQLite databases, add databases: ["main"] as const to Snapshot.multipart or Snapshot.define and expose databases: live => ({ main: live.database }) on the strategy. The SDK checks DatabaseSync.location(): memory/temp databases carry db: images, while file-backed databases carry only logical-name-to-location fileDatabases metadata. Host filesystem snapshots exclusively own file-backed contents. Arbitrary user part: bytes remain application-owned.

Before user restoration, the SDK validates the complete, disjoint image/location inventory and checks that recorded database files exist. Your restore strategy must reopen those locations. The SDK validates all returned handles, hydrates only memory/temp images, and warms connection caches before constructing method handlers. Defer database-dependent reconstruction until the methods factory. Small nonempty file-backed databases may be read in full for cache warming; those bytes are discarded, not stored in the application snapshot. Autocommit and attached-schema restrictions apply during save and restoration.

Use scoped acquisitions for cleanup if restoration fails. Raw handles and SqliteClient.fromDatabase wrappers are externally owned unless you register a finalizer or set closeOnScopeClose: true. Filesystem snapshot availability is host-controlled: there is no fallback application capture of file contents when it is disabled. Without filesystem snapshots, changed files prevent periodic snapshots and snapshot-based manual updates.

Rust

Define both async hooks inside the #[agent_implementation] block. The live implementation does not need Serde; only the saved projection does.


use golem_rust::{agent_definition, agent_implementation};
use golem_rust::agentic::{
    MultipartSnapshot, SnapshotPart, SnapshotRestoreContext,
};
 
#[agent_definition(snapshotting = "every(10)")]
trait Index {
    fn new(name: String) -> Self;
    fn advance(&mut self) -> u32;
}
 
#[derive(golem_rust::serde::Serialize, golem_rust::serde::Deserialize)]
struct SavedState { revision: u32 }
 
struct IndexImpl {
    revision: u32,
    index: Vec<u8>,
}
 
#[agent_implementation]
impl Index for IndexImpl {
    fn new(_name: String) -> Self {
        Self { revision: 0, index: Vec::new() }
    }
 
    fn advance(&mut self) -> u32 {
        self.revision += 1;
        self.revision
    }
 
    async fn save_snapshot_parts(
        &self,
    ) -> Result<MultipartSnapshot, String> {
        MultipartSnapshot::from_state(
            &SavedState { revision: self.revision },
            std::collections::BTreeMap::from([(
                "index".into(),
                SnapshotPart {
                    bytes: self.index.clone(),
                    content_type: "application/octet-stream".into(),
                },
            )]),
        )
    }
 
    async fn load_snapshot_parts(
        snapshot: MultipartSnapshot,
        _context: SnapshotRestoreContext,
    ) -> Result<Self, String> {
        let saved: SavedState = snapshot.decode_state()?;
        let index = snapshot
            .require_part("index", "application/octet-stream")?
            .to_vec();
        Ok(Self { revision: saved.revision, index })
    }
}

Keep the normal snapshot policy annotation. An incomplete hook pair, or combining explicit byte-only and multipart hooks, is a compile error.

Scala

Add the instance saver and companion loader without a new mixin. Schema is needed for the saved projection, not the live instance.


import golem.BaseAgent
import golem.runtime.{
  MultipartSnapshot, SnapshotPart, SnapshotRestoreContext
}
import golem.runtime.annotations.{agentDefinition, agentImplementation}
import zio.blocks.schema.Schema
import scala.concurrent.Future
 
@agentDefinition(snapshotting = "every(10)")
trait Index extends BaseAgent {
  class Id(val name: String)
  def advance(): Future[Int]
}
 
final case class SavedState(revision: Int) derives Schema
 
@agentImplementation()
final class IndexImpl(name: String) extends Index {
  private var revision: Int = 0
  private var index: Array[Byte] = Array.emptyByteArray
 
  override def advance(): Future[Int] = Future.successful {
    revision += 1
    revision
  }
 
  def saveSnapshotParts(): Future[MultipartSnapshot] = Future.fromTry(
    MultipartSnapshot.fromState(SavedState(revision), Map(
      "index" -> SnapshotPart(index.clone(), "application/octet-stream")
    )).toTry
  )
}
 
object IndexImpl {
  def loadSnapshotParts(
    snapshot: MultipartSnapshot,
    context: SnapshotRestoreContext
  ): Future[IndexImpl] = Future.fromTry((for {
    saved <- snapshot.decodeState[SavedState]
    bytes <- snapshot.requirePart("index", "application/octet-stream")
  } yield {
    val instance = new IndexImpl(context.identity[String](0))
    instance.revision = saved.revision
    instance.index = bytes
    instance
  }).toTry)
}

Keep the normal policy annotation and registration. Incomplete or conflicting explicit hooks, including multipart combined with Snapshotted[S], are compile errors.

MoonBit

Implement the async saving trait and a separate static async loader. The generator suppresses automatic JSON hooks for this explicit pair; the existing synchronous Snapshottable trait is unchanged.


priv struct SavedState { revision : Int } derive(ToJson, FromJson)
 
impl @agents.MultipartSnapshottable for Index with fn save_snapshot_parts(self) {
  Ok(@agents.MultipartSnapshot::from_state(SavedState::{revision: self.revision}, {
    "index": { bytes: self.index, content_type: "application/octet-stream" },
  }))
}
 
pub async fn Index::load_snapshot_parts(
  snapshot : @agents.MultipartSnapshot,
  context : @agents.SnapshotRestoreContext,
) -> Result[Index, String] {
  let saved : SavedState = match snapshot.decode_state() {
    Ok(saved) => saved
    Err(error) => return Err(error)
  }
  let index = match snapshot.require_part("index", "application/octet-stream") {
    Ok(index) => index
    Err(error) => return Err(error)
  }
  let name : String = context.identity(0)
  Ok({ name, revision: saved.revision, index })
}

Keep #derive.agent and the normal snapshot policy. Merely deriving JSON traits on the live instance does not conflict with the explicit multipart pair.

Go

Implement golem.MultipartSnapshotter on the state type. LoadParts runs on the zero state, as Load does, and the OnRestore hook runs after it. Only the saved projection goes through JSON.


type savedState struct {
	Revision uint32 `json:"revision"`
}
 
func (s *state) SaveParts() (golem.MultipartSnapshot, error) {
	return golem.NewMultipartSnapshot(savedState{Revision: s.revision}, map[string]golem.SnapshotPart{
		"index": {Bytes: s.index, ContentType: "application/octet-stream"},
	})
}
 
func (s *state) LoadParts(snapshot golem.MultipartSnapshot) error {
	var saved savedState
	if err := snapshot.DecodeState(&saved); err != nil {
		return err
	}
	index, err := snapshot.RequirePart("index", "application/octet-stream")
	if err != nil {
		return err
	}
	*s = state{revision: saved.Revision, index: index}
	return nil
}

Keep the snapshot policy in golem.Spec. A state that implements both golem.Snapshotter and golem.MultipartSnapshotter is a definition error, and a multipart snapshot does not load into a state that does not implement MultipartSnapshotter.

Part and envelope rules

Names are case-sensitive and match [A-Za-z0-9_][A-Za-z0-9_.-]*. Logical names state and __proto__ are valid. Parts have no automatic resource semantics; applications decide what they mean and whether to accept extra parts.
Content types must be bare ASCII MIME type/subtype strings, such as application/octet-stream. They are normalized to lowercase; parameters such as ; charset=utf-8 are rejected. requirePart checks both presence and content type, returning the SDK’s normal snapshot error on failure.
Multipart is emitted even when there are no binary parts. Binary-only applications use JSON null state. Empty bytes and trailing CR, LF, or CRLF are preserved exactly.
The SDK owns the principal envelope. On the wire, one state part contains UTF-8 JSON {version:1, principal, state}, user names become part:<name>, and managed SQLite images use db:<name>. Do not construct these prefixes or envelope metadata yourself.
The SDK validates framing, metadata, names, duplicate structural fields, and supported namespaces before invoking user restoration. Changing snapshot modes does not enable fallback parsing or historical-format migration.

Snapshots are whole-buffer operations. Copies of state, part bytes, encoded payloads, and restored resources can amplify peak memory usage. The host’s 64 KiB inline/blob-spill setting is a storage threshold, not a maximum snapshot size. Save and load hooks are unpersisted lifecycle operations and may be retried; async hooks do not make external effects exactly-once.

How snapshot restoration runs

Snapshot loading is a specially supported SDK lifecycle operation, not an agent method. The SDKs keep it separate from normal initialization and install the returned state or instance only after restoration succeeds. Restore context exposes the agent identity and restored principal, plus the phantom ID and fresh configuration where applicable.

Golem runs snapshot loading in read-only mode and writes nothing from it to the oplog. Decoding, local computation, fresh randomness, configuration access, and other permitted reads can be used to construct the restored value. Durable host calls classified as writes, and outgoing HTTP or agent RPC calls, are rejected before they take effect. This restriction is not a general filesystem write sandbox: local filesystem writes are not blocked by it.

If loading fails, partial state is discarded:

A manual update fails and the agent remains on its previous component version. This is also true when the agent exits during the load. When an interrupt stops the load, the update stays pending, and the next start loads the snapshot again. See Updating agents.
A snapshot-assisted automatic update fails with UPDATE_SNAPSHOT_INCOMPATIBLE, and the agent remains on its previous component version. Golem does not reject the snapshot record. See Updating agents.
If an automatic snapshot is rejected by its loader, or loading or subsequent replay fails deterministically, Golem rejects only that snapshot record and recreates the component. The next start uses the previous usable automatic snapshot, if Golem keeps one and it is not the rejected record. When no usable automatic snapshot is left, Golem starts from the authoritative recovery baseline, or from the beginning if none exists. Transient failures and resource-limit failures can instead propagate or cause recovery to retry.
Failure to load the authoritative recovery baseline of an already completed manual update or snapshot-assisted update cannot fall back to pre-update history.

Configuring snapshot-based recovery

Choose when Golem takes automatic snapshots in the agent definition. Disabling automatic snapshot creation does not discard the authoritative recovery baseline of the last successful update, if one exists.

TypeScript

Pass the snapshotting option to defineAgent(...):


export const Counter = defineAgent({
    name: 'Counter',
    id: { name: z.string() },
    snapshotting: {
        state: z.object({ value: z.number() }),
        policy: { periodicSeconds: 5 },
    },
    methods: {
        increment: method({ input: {}, returns: z.number() }),
    },
});

Set snapshotting.policy to one of these values when using a state schema:

Policy	Behavior
`'disabled'`	Disables automatic snapshot creation. Omitting `snapshotting` also disables it.
`'default'`	Uses the server’s default schedule, which may be disabled.
`{ everyNInvocations: 10 }`	Takes a snapshot every 10 successful invocations.
`{ periodicSeconds: 5 }`	Schedules snapshots at safe invocation boundaries after each 5-second interval.

For custom byte snapshots, pass the policy directly as snapshotting instead of wrapping it in { state, policy }.

Effect TypeScript

Pass a Snapshot definition to snapshotting:


snapshotting: Snapshot.define({
  schema: Schema.Struct({ value: Schema.Number }),
  policy: Snapshot.policy.periodic("5 seconds"),
})

Select the policy inside Snapshot.define(...), Snapshot.custom(...), or Snapshot.multipart(...):

Configuration	Behavior
Omit `snapshotting`	Disables automatic snapshot creation. There is no `Snapshot.policy.disabled`.
`Snapshot.policy.default`	Uses the server’s default schedule, which may be disabled.
`Snapshot.policy.everyN(10)`	Takes a snapshot every 10 successful invocations.
`Snapshot.policy.periodic("5 seconds")`	Schedules snapshots at safe invocation boundaries after each 5-second interval.

Rust

Set snapshotting on #[agent_definition]:


#[agent_definition(snapshotting = "periodic(5s)")]

Attribute value	Behavior
`"disabled"`	Disables automatic snapshot creation. This is also the default when the attribute argument is omitted.
`"enabled"`	Uses the server’s default schedule, which may be disabled.
`"every(10)"`	Takes a snapshot every 10 successful invocations.
`"periodic(5s)"`	Schedules snapshots at safe invocation boundaries after each 5-second interval. Durations also accept units such as `1m`.

Scala

Set snapshotting on @agentDefinition:


@agentDefinition(snapshotting = "periodic(5 seconds)")

Annotation value	Behavior
`"disabled"`	Disables automatic snapshot creation. This is also the default when the annotation argument is omitted.
`"enabled"`	Uses the server’s default schedule, which may be disabled.
`"every(10)"`	Takes a snapshot every 10 successful invocations.
`"periodic(5 seconds)"`	Schedules snapshots at safe invocation boundaries after each 5-second interval. Use a finite Scala duration, such as `500 millis` or `1 minute`.

MoonBit

Set snapshotting on #derive.agent:


#derive.agent(snapshotting="every_n(5)")

Attribute value	Behavior
`"disabled"`	Disables automatic snapshot creation. This is also the default when the attribute argument is omitted.
`"default"`	Uses the server’s default schedule, which may be disabled.
`"every_n(10)"`	Takes a snapshot every 10 successful invocations.
`"periodic(5 seconds)"`	Schedules snapshots at safe invocation boundaries after each 5-second interval. A bare number, such as `periodic(5)`, is also measured in seconds.

Go

Set Snapshot on the agent’s Spec to one of golem.SnapshotDisabled, golem.SnapshotDefault, golem.SnapshotEveryN(n) or golem.SnapshotPeriodic(d):


var Agent = golem.DefineAgent[ID](golem.Spec{
    Name:     "Counter",
    Snapshot: golem.SnapshotPeriodic(5 * time.Second),
})

Policy	Behavior
`golem.SnapshotDisabled`	Disables automatic snapshot creation. This is also the zero value when `Spec.Snapshot` is omitted.
`golem.SnapshotDefault`	Uses the server’s default schedule, which may be disabled.
`golem.SnapshotEveryN(10)`	Takes a snapshot every 10 successful invocations.
`golem.SnapshotPeriodic(5 * time.Second)`	Schedules snapshots at safe invocation boundaries after each 5-second interval. The argument is a positive `time.Duration`.

Agent files and snapshots

To include the agent’s files in snapshot-based recovery:

Run the agent on executors with filesystem snapshots enabled. The local golem server run command enables them by default on macOS. Standalone executors and local servers on other platforms disable them by default.
Configure the agent’s snapshotting policy and application state saving and loading as described above. Enabling executor snapshots alone does not schedule snapshots for an agent.
Flush file output streams before each invocation returns. Your snapshot saver must not modify files: Golem does not run it again during replay.

Golem captures and restores the files together with the application snapshot. You do not need to include file contents in the application snapshot or write extra snapshot code for files. See Recovery and storage for capture, confirmation, restoration, failures, retention, and cold-start costs. For update-specific file conflicts, see Updating agents.

Without filesystem snapshots, automatic snapshots work only while the files are reconstructible from untouched read-only initial files. Otherwise Golem skips the snapshot and recovers from an older usable restore point or by replay, which rebuilds the files without data loss but can take longer. A snapshot-based manual update then fails with UPDATE_NEEDS_FILESYSTEM_SNAPSHOTS. A successful update’s authoritative recovery baseline is not optional: if it requires a filesystem snapshot, the agent cannot start without it. See Recovery without filesystem snapshots.

TypeScript

Typed state snapshotting saves the contents of top-level in-memory and temporary DatabaseSync fields. For a file-backed database it saves only the path; filesystem snapshots restore the file. Commit or roll back transactions before returning. Closed databases and fields holding StatementSync, Session, or SQLTagStore cannot be saved. SQLite replay also has page-cache limits. See the custom snapshot guide for the full rules.

Observability

When using the default (JSON-based) snapshotting implementation, snapshot entries recorded in the oplog contain the serialized JSON state of the agent. This makes it easy to inspect agent state at any snapshot point for debugging purposes.

Snapshotting is also used when updating agents across incompatible versions, allowing Golem to capture the agent’s state before applying the update.