File Format

Inside .mage. SQLite, content-addressed assets, forward-compatible.

A .mage file is one SQLite database. Every asset (image, brush, grain, timelapse snapshot) lives inside, deduplicated by SHA-256. Portable documents. Forward-compatible schema.

Why SQLite#

  • Single file: copy, sync, version-control as one unit
  • Atomic writes: no half-saved corruption on crash
  • Random access: open a 2 GB document, read just one layer
  • Tooled: inspect with sqlite3 if you want
  • Durable: format isn't going anywhere

Schema#

Three tables:

Table Columns
manifest id (always 1), json. One document containing schemaVersion, meta, graph, workspace.
blobs hash, byte_size, mime, data, refcount. Bytes keyed by SHA-256.
assets id, type, hash, original_path. Logical records pointing at blobs.

The split lets us deduplicate. Two Image nodes pointing at the same imported PNG share one blob row.

Content-Addressed Assets#

Assets referenced as assets/<id> (embedded) or mal:<id> (Magerie Asset Library). Two consequences:

  1. Automatic dedup: same image into ten Image nodes stores bytes once
  2. Refcount GC: before save, Magerie walks the graph and frees orphans

Embedded by Default#

The .mage is the only container. Drag an image onto canvas, bytes go into the blob store, Image node holds an assets/<id> reference. Save, reopen on another machine, nothing extra needed. Bytes are inside.

Exception: parameters explicitly pointed at an external path are respected. Most users never need this.

Draft Documents#

Untitled documents run on a tempDir-backed draft .mage. Painting and embedding work immediately. No "save first" friction. Draft upgrades to your chosen path on first save.

Forward Compatibility#

Schema versioned with migration path for old documents. Brush engine versioned too. Old timelapse recordings keep replaying against their original engine version.

Backups#

Auto-backup every 30 seconds (interval configurable in Settings). On crash, next launch detects the lock file and offers recovery. Last 5 backups per document are kept; older ones auto-prune.

Next#