File stores

Agents don’t just think. They produce files. A generated report, a downloaded dataset, a configuration file an agent edited on your behalf. These artifacts need to survive beyond a single session, and they need to be reachable by other agents working on the same project. That’s what file stores are for.

What is a file store?

A file store is a managed, persistent filesystem attached to a project. It gives agents a real directory tree they read and write like a local disk, except the contents persist across sessions and can be shared across a team.

Each organization and user gets a default file store automatically; additional stores are opt-in. A store can back multiple projects, and a project can mount several, so you share artifacts without duplicating them.

How it works in the sandbox

Inside a pod, a file store is a real directory mounted into the sandbox. Agents use ordinary file operations (open, read, write, rename, delete) with no special “save” call and no adapter code. Any tool or library that expects a filesystem just works.

Changes are picked up on the next run, so the agent never sees stale data.

Persistence across sessions

The defining property of a file store is durability. Files an agent writes during one session are available the next time that agent, or any other agent with access to the same store, runs. This is what separates a file store from ephemeral sandbox storage, which vanishes when the pod shuts down.

Persistence makes it practical for agents to:

• Accumulate knowledge: an agent can write a findings file in one run and append to it in the next.
• Hand off work: one agent produces a data file; another agent in a different session picks it up and processes it further.
• Maintain state: configuration, caches, and working directories survive restarts.

For structured key-value memory rather than files, see memory stores.

Scopes: org vs. private

File stores come in two scopes:

• Org file stores are shared across everyone in the organization. They’re the default for collaborative work. Any agent running under the org can read and write the same files. The org’s default store is created automatically.
• Private file stores belong to a specific user or pod. They’re useful for personal scratch space, sensitive data that shouldn’t be shared, or isolated experiments that shouldn’t pollute the org’s shared filesystem.

The scope determines visibility, not capability. Both scopes offer the same read/write semantics inside the sandbox. The difference is who can see and mount the store.

Managing files outside the sandbox

Beyond what agents do inside the sandbox, you can manage a store directly:

• Upload: push a file from your local machine into the store.
• Remove: delete a specific file.
• Purge: clear the entire store at once.

This is for seeding a store with initial data, cleaning up after a project, or removing files an agent shouldn’t be able to delete itself.

Creating and listing file stores

You can manage file stores from the CLI:

ren file-stores create --name "project-data"
ren file-stores list

The CLI is the quickest way to create stores beyond the default and see which ones exist.

File stores and memory stores

File stores and memory stores solve different problems and complement each other:

• File stores hold arbitrary files such as documents, images, datasets, configs. They’re a filesystem: hierarchical, unstructured, and best for artifacts an agent produces or consumes.
• Memory stores hold structured key-value data such as facts, preferences, session summaries. They’re a database: queryable, typed, and best for information an agent needs to recall.

Most projects benefit from both. An agent might store its working files in a file store while keeping a running summary of what it’s learned in a memory store.