Skip to main content

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.

Files is persistent storage that follows your Experts across Sessions. Anything an Expert writes there survives the VM, reappears in the next Session, and can be shared with the rest of your organization.

​
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