> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Files

> Files persist across Expert Sessions — how Experts produce them, how they sync, and how you browse files and folders in Cosmos.

**Files** is the storage layer Experts use between Sessions. Anything written there outlives the VM, shows up again in the next Session, and — if you scope it that way — is readable by your whole org.

## Scopes

Files are scoped two ways:

* **User** — private to you. Only your Sessions can read or write them.
* **Organization** — shared with everyone in your organization. The right place for team knowledge and outputs an Expert wants to hand off to another Expert.

## How Experts Create Files

You don't upload files yourself. Experts produce files as a side effect of doing their work, using the same file tools they use everywhere else. There is no special API or tool — an Expert writes to a path under the **User** or **Organization** scope and the sync layer takes care of the rest.

Typical patterns:

* A **research Expert** writes notes to `user/notes/<topic>.md` so the next Session can read them.
* A **code-review Expert** writes a per-PR summary to `organization/pr-reviews/<repo>/<pr>.md`. The next reviewer (human or agent) starts with that context already in front of them.
* A **triage Expert** appends one JSON record per incident to `organization/incidents/log.jsonl`, building up a queryable history over time.

Sync happens automatically at turn boundaries — once an Expert finishes a turn, every file change it made is uploaded and visible to the next Session.

To add, edit, or remove a file, ask an Expert to do it from a Session:

* *"Save the contents of this message as `user/notes/sync-strategy.md`."*
* *"Read `organization/pr-reviews/repo-x/142.md` and update the conclusion section."*
* *"Delete every file under `user/scratch/` older than 30 days."*

The Expert performs the change, the sync layer persists it at the end of the turn, and the new state shows up next time you refresh the matching Files page.

## Browsing Files

You can inspect Files from inside Cosmos.

### The Files pages

**Files** is a sidebar group with two entries — **Organization** and **User** — each opening its own tree at `/app/vfs/org` or `/app/vfs/user`.

1. Pick a scope from the sidebar to open its tree.
2. Expand folders to drill down. Each row shows the path, size, last-modified time, and the agent that last wrote the file.
3. Select a file to preview it inline (text files up to 1 MB).
4. Use the per-row **⋯** menu (or the inline icons in the file viewer) to **Copy path**, **Copy content**, or **Download**.

### The Files tab inside a Session

Open any cloud Session and switch to the **Files** tab in the right sidebar. Same tree and preview, plus a third scope option: **Workspace** — the running VM's live workspace at `/workspace` for that Session.

## Versioning and Recovery

Every write to a file creates an immutable version snapshot. A buggy Expert cannot silently overwrite shared state without leaving a trail — every version is attributed to the agent that wrote it, and deletions are recorded as tombstones rather than erasures.

Older versions are pruned on a time-decayed schedule: every version is kept for the first 15 minutes, then progressively thinned out as the file ages, with at least one version per week retained beyond 30 days. To restore an older version, ask an Expert in a Session to read the version you need and write it back as the current file.

## Limits

* **1 MB** per file
* **10,000** files per filesystem
* **100 MB** total per filesystem
* Writes that would exceed these limits are rejected at sync time

## Common Questions

**My Expert wrote a file but I don't see it in the matching Files page.**
File sync runs at turn boundaries. Wait for the Expert's current turn to finish, then refresh.

**A teammate's Session wrote a file I need.**
Open the **Organization** Files page. Files written there by any teammate's Expert are visible to everyone in the organization.

## See Also

* [Configuring Cosmos](/cosmos/configuring-cosmos) — set up your Environment, Experts, and integrations