# Where your files live

A vault is a folder. Your originals are files. What you decided about them is text. The database is a cache. Here is what that looks like on disk.

*Written from Teserra 1.3.16.*

**In short**

1. Your library is a folder: your originals, and a small text file next to each one.
2. The database is a cache: **Settings → General**, **Rebuild from files**.
3. Back it up like any folder. Delete Teserra and lose nothing.

## The folder

```
~/Pictures/Studio/
  vault.json                          the library's id, name, description, format version
  originals/
    3f/3f9c2a7d41b0e8c5.webp          an original, named by its content hash
    3f/3f9c2a7d41b0e8c5.webp.teserra  its sidecar: what you decided about it
  meta/
    a7/a71c….teserra                  the sidecar of an item with no file, a link for instance
  collections/
    c-41e37e7ed0608fda.toml           a collection: name, parent, icon, colour
    c-41e37e7ed0608fda.taste.md       its written taste, when an agent saved one
  thumbs/                             regenerable
  favicons/                           site icons of your links
  (cache, elsewhere)                  the SQLite database, per machine
```

Originals are named by a hash of their content, so the same image never enters twice and a file can be found again even if renamed elsewhere. The sidecar keeps the original filename. A written taste is plain Markdown that any agent, or you, can read. [Agent access](https://teserra.app/docs/agents)

## A sidecar

One TOML file per item, written atomically each time you change something. It holds the decisions: name, title, description, tags, rating, collections (by stable id), pins, source URL, the visible text the Curator or your agent read, an article's body, and a tombstone if the item is in the trash. Plus the file's identity: dimensions, format, dates. Anything a newer version writes that an older one does not know is preserved untouched.

```
spec = 1
name = "hand-sphere.webp"
kind = "image"
added = "2026-08-27T09:12:44Z"
file_created = "2026-08-26T18:03:10Z"
updated = "2026-09-16T15:41:02Z"
title = "The sphere"
description = "A sculpted hand rises from a flat surface…"
rating = 4
tags = ["hand", "minimal", "sculpture"]
collections = ["c-41e37e7ed0608fda"]
source_url = "https://teserra.app"

[file]
width = 1600
height = 2000
size = 412806
format = "webp"
```

## The database is a cache

Teserra keeps a SQLite file per machine to make the grid fast. It is rebuilt from the folder: **Settings → General → Rebuild from files** reconstructs every item, collection and tag. Tested on a real vault: 826 items, 40 collections, 6,716 tag links back in under a second.

## Sync and several Macs

Teserra watches the folder. Edit a sidecar by hand, drop files from another Mac, let iCloud Drive or [Teserra's own sync](https://teserra.app/docs/sync) bring changes: the grid follows within seconds. When iCloud Drive leaves two copies of the same sidecar, tags and collections are merged and the latest copy gives the rest. Teserra's own sync goes further: each field keeps the side that changed it, and a tag removed on one Mac stays removed; only when both Macs changed the same field does the latest edit win. Files iCloud has offloaded show a cloud badge and download when opened.

> **What this means.** Back the folder up like any folder. Put it in git if you like. Open it in ten years with a text editor. Delete Teserra and lose nothing.