Skip to main content
Traces don’t carry media bytes. They carry names for them: an R2 key such as users/<id>/photos/<uuid>.jpg, a link, or a [Media: image/png <url>] marker in a tool result. With media capture, your Worker hands each file to Moda once, under its name. Moda then links every name it finds in your traces to the file, including files that arrive after the trace. Replays use the real bytes:
  • a replayed read of env.R2_BUCKET.get(key) returns the original object;
  • a replayed fetch of a captured URL returns the original response body;
  • any other name behaves as it did before.
There is no separate Worker and no hook on each put. R2 event notifications feed a queue, and one branch in the queue() handler you already have consumes it.
These files are your users’ photos, voice notes and videos. Turn capture on only for prefixes your terms and user consent cover. Use prefixes and parseKey to leave out anything they don’t cover.
Ask Moda to enable media linking for your workspace before you start. Until it’s enabled, files still upload, but traces and replays don’t link to them.

1. Create the queue and the notification rules

Create one rule for each prefix that holds media your agent reads or writes:

2. Consume the queue in your Worker

Add the consumer to your Wrangler config:
Then add one branch to your existing queue() handler:
The handler acknowledges each message when it’s done. It asks for redelivery only when Moda or R2 is briefly unavailable (HTTP 408, 429, 5xx, or a network error). Under at-least-once delivery, a file is stored once:
  • uploads are keyed by the file’s SHA-256;
  • redelivered notifications are skipped;
  • copies of one notification in the same batch share one upload.
Deletes are ignored, and so is a notification for an object that was overwritten since. Objects over 8 MB are hashed while they stream (crypto.DigestStream), so memory stays flat.

3. Capture media fetched from outside URLs

Media that never lands in R2, such as a CDN image your image tool fetches, goes through captureFetchedMedia right after the fetch:
Moda files the bytes under a hash of the URL’s origin and path. The upload sends only that hash and the host, never the URL or its query string, because a signed link is a bearer token. A re-signed link to the same path still matches.
This covers the upload only. If a signed URL also appears in a message or tool result, your trace sends it to Moda like any other text, and Moda stores it with the trace. Redact signed URLs from traces separately.

What Moda stores