State & artifacts
Introspection separates task inputs, durable outputs, and personal memory. That makes it clear what the agent may change, what survives sandbox replacement, and what can return in a later task.
The task workspace
Most of the sandbox filesystem is ephemeral. The agent should do routine work there and use the three managed workspace directories only for resources that need their specific persistence behavior:
| Directory | Purpose | Lifetime |
|---|---|---|
/workspace/files | User-uploaded resources and files supplied by the recipe | Read-only inputs for the current task |
/workspace/outputs | Intentional artifacts the agent wants to return from the task | Task-scoped; restored if the sandbox is replaced and surfaced as task outputs |
/workspace/memories | Durable context the agent learns about the current owner | Owner-scoped; available to later tasks for the same owner in the same project and environment |
Introspection mounts these directories, but with one exception it does not
automatically inject workspace usage instructions into the agent’s prompt. A
recipe that expects its agent to use them must add that guidance to
SYSTEM.md or the agent’s
system_instructions, including the relevant paths,
access rules, and persistence behavior.
The exception is uploads attached to a task: their paths are announced to the agent on the turn they arrive, so it knows a file was handed to it. See Input files.
Input files
/workspace/files contains resources supplied to the task, including user
uploads and files packaged by the recipe. The agent can read them but should
not modify them. Local changes to this directory are not persisted.
Uploads are attached by id through the files field on task and run creation —
see the CLI, JavaScript,
or Python docs. A file attached
partway through a conversation lands before that turn runs, without restarting
the sandbox.
Their paths, and only their paths, are announced to the agent on the turn the file arrives:
<uploaded_files>
<file path="/workspace/files/spec.md" />
</uploaded_files>Contents are never injected — the agent reads the file itself, so a large
attachment costs nothing until it does. A file the platform cannot serve is
reported as status="unavailable" with a reason rather than failing the task,
so the agent can say the attachment did not arrive instead of inventing its
contents. Because rehydration re-fetches the original bytes, an agent’s local
edits under this directory do not survive a sandbox replacement.
Outputs
/workspace/outputs is for deliberate, lightweight deliverables such as a
report, research notes, or structured results. Files written there survive a
sandbox replacement during the task and appear as the task’s output files.
Each output file may be at most 25 MB. There is no aggregate size limit,
but dependencies, caches, build products, logs, and routine intermediate work
belong in the ephemeral workspace rather than in outputs. Files created
directly through the Files API may be up to 50 MB per file; managed
workspace files retain the stricter 25 MB runtime limit.
Memories
/workspace/memories holds durable, reusable context for the current owner.
Unlike outputs, memories can return in later tasks for that owner. They should
contain stable preferences, decisions, and useful facts—not task artifacts,
transient notes, credentials, or instructions that override the current task.
MEMORY.md is the concise index, with detailed topics kept in focused files.
Every file managed at run time through these workspace directories is limited to 25 MB per file, applied per file rather than as a cumulative total across the task.
That bound governs what a task reads and writes. Files a recipe ships in its own
files/ directory are bounded separately, at package time, by the limits in
Packaging a recipe.
What belongs where
| Need | Use |
|---|---|
| Give the agent an uploaded or recipe-provided input | /workspace/files |
| Keep a generated report, dataset, or other output | /workspace/outputs |
| Let someone read a file or conversation | A read-only share |
| Let a group read and write a growing set of files and tasks | A tag carried by both the rows and the group’s members |
| Reproduce work from someone else’s conversation | A fork created from a shared conversation |
| Carry an owner’s stable preferences into later tasks | /workspace/memories |
A concrete example
A research agent may save its final report as a file, share the source conversation with a reviewer, and let that reviewer fork a new task to challenge one conclusion. The agent can remember the original user’s preferred output format for next time, while that personal memory remains unavailable to the reviewer.
Files, shares, and forks
A file is a durable, versioned project artifact. When a task writes new
content to a file, it creates a new version rather than overwriting history.
Use files for generated reports, uploaded inputs, datasets, and other durable
artifacts. Inside a task, uploaded inputs appear in /workspace/files, while
artifacts written to /workspace/outputs are saved as output files. The rest
of the sandbox filesystem is temporary.
A share is a read-only grant for one file or conversation. It can be shared with a project, one member, or one end-user identity. It never grants write access or changes ownership. Tasks themselves are not shareable. Share a conversation when someone else needs to reproduce or investigate work; they can then fork a new, independent task from that immutable record.
A fork tries to seed the new task with the shared conversation. If that source can no longer be loaded, the new task can still be created without the copied history. Keep the share available until the forked task has started if the earlier context is required.
Use runner.files for files and versions, and runner.shares for read-only
grants. Both are Data Plane namespaces, so in the Node and Python SDKs they hang
off the runner rather than the top-level client. The browser client talks only
to the Data Plane, so it carries files and shares directly. The
JavaScript SDK shows the runner API, and
Browser applications covers the browser
client’s equivalent namespaces.
There is no restore verb: recovering an earlier version means reading it and writing it back, which lands as a new version rather than rewinding the history.
A share reaches one member and grants read only. To give a group read and write over a growing set of files — a team’s working documents, a shared memory file — put a tag on the rows and the same tag on each member who should reach them. Tags follow a file across versions, so a new version does not silently drop the group. A collaborator admitted by a tag can update the file but cannot change its tags, so they cannot re-share it.
Memory
Memory is durable file-backed context for one authenticated owner. It is
mounted at /workspace/memories. The agent reads and writes ordinary files
with its normal file tools; MEMORY.md is the short index loaded at the start
of each task, with linked files holding the detail.
Memory is scoped to a project, environment lane, and owner identity—not a runtime—so the same owner can retain context across runtime versions in the same lane.
| Task caller | Memory owner | Eligible? |
|---|---|---|
| Federated end user authenticated as a customer member | That authenticated member | Yes |
| API key or service-account application with runner identity | First available of user_id, anonymous_id, then conversation_id | Yes |
| Application traffic without runner identity | None | No |
| Dashboard or CLI business member | None | No |
Only one owner is selected for a task. Identity kinds are namespaced, so the same text used as a user ID and an anonymous ID does not join their memory. A task without an eligible owner has no persistent memory, and one owner’s memory never appears in another owner’s task. See Authentication & identity for how callers establish those identities.
Keep preferences, decisions, notes, and small facts in memory. Large artifacts belong in files, and credentials belong in bindings, never memory.
Related
- Tasks & conversations: execution sessions, replayable records, and conversation forks.
- Tags: grouping files and tasks, and sharing them with a cohort of members.
- Authentication & identity: how identity scopes memory.