Skip to main content
A replay runs one past turn of your agent again. To do that faithfully it needs the state your agent read at the start of that turn: its memories, calendar, rules, prompt-visible files and configuration. Moda can infer that state from your traces (what the prompt rendered, what tool calls changed), but inference misses writes no prompt ever shows. When your agent reports its writes directly, the replay uses exactly what you reported. Reported writes take precedence over inferred state for the same row from the first report on. Rows you never report, and the time before you started reporting, still come from inference.
State writes are enabled per workspace. Ask Moda to turn them on; until then POST /v1/state-writes answers 404 and span events are ignored.

Node and Workers SDK

moda-ai/state (moda-ai 1.19.0 or later) works on Node and Cloudflare Workers. Report each write at the storage helper every writer goes through, after the write has landed:
recordStateWrite returns immediately and never throws. Outside a traced turn, writes are batched and sent to POST /v1/state-writes. Inside one (an active, recording OpenTelemetry span), the write becomes a moda.state_write event on that span and is exported with the trace, which links it to the turn. Fields named like credentials (token, secret, password, api_key, cookie, authorization, credential, and similar) are removed at any depth before anything is sent. Narrow further with stores (an allowlist) and redact (a hook that may change a write or drop it by returning null).

Write fields

value, fields and before together may be at most 64 KiB of JSON per write.

POST /v1/state-writes

Up to 500 writes and 512 KiB per request. Each write is validated on its own:

Span event

Inside a traced turn, attach the same write object (one per event) to the turn’s span:
  • event name moda.state_write
  • string attribute moda.state_write.json holding the write as JSON
The trace id comes from the span. When the write has no conversationId or userId, the span’s moda.conversation_id and moda.user_id attributes are used. Invalid events are dropped without affecting the trace.

How replays use reported writes

For a replay of a turn, Moda builds the state from every reported write up to the turn’s start, in time order: create and upsert replace the row, update patches it, delete removes it. Writes made during the turn itself or after it are never included. From a row’s first reported write on, what Moda inferred about that row is ignored.