File Storage

Persistent file storage with categories, tags, and sandbox integration.

Overview

Edward can store files permanently — generated images, code artifacts, uploaded documents, processed outputs. Files are organized with categories and tags, stored on disk with hex-prefix sharding, and tracked in PostgreSQL.

Storage Architecture

Files are stored on disk using hex-prefix sharding to avoid overloading any single directory:

FILE_STORAGE_ROOT/
├── a3/
│   ├── a3f7c2..._report.pdf
│   └── a3e1b0..._chart.png
├── f1/
│   └── f1d4a9..._notes.txt
└── ...

The path format is {id[0:2]}/{id}_{filename}. The storage root defaults to ./storage and can be configured via the FILE_STORAGE_ROOT environment variable.

File Categories

Category	Description
`upload`	Files uploaded directly by the user
`generated`	Files created by Edward (code output, images, etc.)
`artifact`	Build artifacts or intermediate outputs
`processed`	Files that have been transformed or analyzed
`general`	Default category for uncategorized files

Sandbox-to-Storage Flow

When Edward executes code (Python, JavaScript, shell), output files land in a per-conversation sandbox directory. These are temporary — cleaned up after 24 hours. To keep a file permanently, Edward uses the save_to_storage tool to move it from the sandbox to persistent storage.

Code execution sandbox (temporary, 24h TTL)
           ↓
  save_to_storage tool
           ↓
  Persistent file storage (permanent)

Limits

Maximum file size: 50 MB
Allowed types: MIME type allowlist (common document, image, audio, video, and code formats)
Metadata: Each file tracks filename, MIME type, size, category, tags, source, and timestamps

LLM Tools

File storage tools are always available (not skill-gated):

Tool	Description
`save_to_storage`	Move a sandbox file to persistent storage
`list_storage_files`	List stored files with optional category/tag filters
`get_storage_file_url`	Get a download URL for a stored file
`read_storage_file`	Read the contents of a stored text file
`tag_storage_file`	Update a file's description, tags, or category
`delete_storage_file`	Delete a file from storage