Files and task state

Each project has a disk with three parts: key-value entries, files, and task state. All of them outlive the session and are shared by every key of the project with the disk scope.

Key-value

Small values, optionally with an expiry:

kv_set({key: "last-invoice-checked", value: "in_…", ttl_seconds: 86400})
kv_get({key: "last-invoice-checked"})

Values up to 256 KB, keys up to 512 bytes, expiry up to 365 days.

Task state

The state of a piece of work, saved by one session and loaded by another:

state_save({task_id: "refund-1042", state: {order: 1042, step: "waiting"}, note: "Waiting for approval"})
state_load({task_id: "refund-1042"})

Up to 256 KB per task. Use the task_id as state_ref when you ask a person, so the answer leads back to the work: see Your agent asks permission on Telegram.

Files

Small files go inline, up to 1 MB:

file_put({path: "reports/2026-10.csv", content_base64: "…", content_type: "text/csv"})

Larger files, up to 100 MB, go through an upload URL: file_put({path, upload: {size, content_type}}) returns the URL to PUT the bytes to, then file_put({path, complete: "<upload id>"}) finishes the upload.

Every file has a disk://… reference that other tools accept, for example email_send attachments.

Share a file

file_url({path: "reports/2026-10.csv", expires_in: 3600})

returns a download link valid for one hour by default, up to 7 days. file_url goes through your policy like email_send: a rule on tool file_url can require a person's approval before a link leaves the project.

Limits

1 GB per project across key-value, task state, files and inbound email payloads, and up to 10,000 key-value entries, task state included. Files and key-value entries never expire unless you set a ttl_seconds on a key; inbound event payloads are deleted after 30 days.