Sempere
Guide contents

How it works

Inside a vault

The folder tree, the append-only revision files, and why sync tools never see a conflict.

A vault is a plain folder, not a package or a database. You can copy it, sync it, back it up and inspect it with ordinary tools.

What is inside a vault folder A vault named My Notes.sempere is a plain folder. My Notes.sempere/: a plain folder: sync it, copy it, back it up. vault.json: devices, wraps of the vault key; not encrypted. epochs/: a record at creation, then per device change (encrypted). joins/: requests of devices asking to join. keys/: optional: the recovery key under a passphrase (encrypted). notes/: your notes. 3f2c…/: one note: a folder named by a random id. …-a1b2c3d4-1.delta.age: one save from the iPad: what changed (encrypted). …-9e07c1d5-1.delta.age: a save from the Mac, its own name (encrypted). …-a1b2c3d4-9.snapshot.age: the whole note at one moment (encrypted). att/2b9d….image.age: an attachment, padded (encrypted). notebooks/: records that keep empty notebooks (encrypted). inbox/: quick voice notes not yet filed (encrypted). settings.age: shared settings, if you sync them (encrypted). summaries/: sealed note lists for a fast start (encrypted). = encrypted My Notes.sempere/ a plain folder: sync it, copy it, back it up vault.json devices, wraps of the vault key; not encrypted epochs/ a record at creation, then per device change joins/ requests of devices asking to join keys/ optional: the recovery key under a passphrase notes/ your notes 3f2c…/ one note: a folder named by a random id …-a1b2c3d4-1.delta.age one save from the iPad: what changed …-9e07c1d5-1.delta.age a save from the Mac, its own name …-a1b2c3d4-9.snapshot.age the whole note at one moment att/2b9d….image.age an attachment, padded notebooks/ records that keep empty notebooks inbox/ quick voice notes not yet filed settings.age shared settings, if you sync them summaries/ sealed note lists for a fast start
The vault is a folder of files. Names are random ids, device ids and counters, never your titles.

Files that are written once

Everything under notes/, notebooks/ and epochs/ is write-once: a file is created, and then never changed. When you edit a note, Sempere does not rewrite it. It adds a new file, a delta, with just what changed. Now and then it adds a snapshot with the whole note, so a note opens quickly without replaying every delta.

A revision’s name looks like 0001760985600000-a1b2c3d4-7.delta.age:

  • a timestamp from a clock that every device keeps in step (a hybrid logical clock), so the order is clear even if a device’s clock is off;
  • the writing device id, eight random characters, made when the app is installed (never a hardware id);
  • that device’s own counter for this note: 1, 2, 3, with no gaps.

A note is rebuilt from all of its files. Order does not matter: any set of the same files gives the same note.

Only a handful of files are ever replaced: vault.json (by the home device), settings.age, and the published summaries. Sempere replaces each one whole, through a temporary file and a rename, so a crash never leaves half a file. One more exception: a device that missed a device change re-encrypts files it wrote itself under the old key (Devices and keys).

Why sync tools never conflict

Sync tools (iCloud Drive, Dropbox, Syncthing, a NAS client) get into trouble when two devices change the same file: one version wins, or you get a “conflicted copy”. In a Sempere vault that cannot happen to your notes. Two devices never write the same file name, because each name holds the writer’s device id and counter, and existing files are never changed. A sync tool only ever sees new files to copy.

How two devices' edits to one note merge The iPad, device a1b2c3d4, adds strokes and saves two files ending a1b2c3d4-7 and a1b2c3d4-8. At the same time the Mac, device 9e07c1d5, renames the note and saves a file ending 9e07c1d5-3. All three files land in the note's folder; their names never collide. The note you see is rebuilt from all of them: strokes and pages from both devices are kept and a removal wins; the title, notebook and paper take the latest edit; a tag added on one device survives a removal made at the same time on another. iPad adds strokes Mac renames the note …-a1b2c3d4-7.delta …-a1b2c3d4-8.delta …-9e07c1d5-3.delta same moment notes/3f2c…/ All three files arrive. Each name holds a deviceid and that device's own counter, so no twodevices ever write the same file. The note you see Strokes, pages, items: everything from both.A removal wins. Title, notebook, paper: the latest edit wins. Tags: an add beats a removal made atthe same time.
Saves are new files with unique names, so a sync tool only ever adds files, and the app merges them.

How edits merge:

  • Strokes, pages, items, recordings: everything from every device is kept. A removal wins over the same item’s addition, and a removed thing stays removed.
  • Title, notebook, paper, page order, favorite, deleted: the latest change wins, field by field. Renaming a note on the Mac and moving it to a notebook on the iPad keeps both.
  • Tags: an added tag wins over a removal made at the same time.
  • If two devices cut or move the same stroke at the same moment, the later edit wins.

For the few replaceable files, Sempere resolves conflicts itself, so you are never asked to pick a version: settings merge key by key, and of two versions of vault.json it takes the later one by the home device, or keeps its own and reports the other.

Attachments

Images, PDFs, recordings, transcripts and clips live in the note’s att/ folder. Each is encrypted, padded to a size class, and named with a keyed hash of its content, so the same picture added twice to a note is stored once, and the name reveals nothing. Attachments are never deleted when a note changes; Settings ▸ Backups & History ▸ Storage ▸ Unused Attachments removes ones no note uses any more, 30 days after they were found unused.

Keeping it tidy

Deltas pile up over time. Thinning (in Version History) removes old autosaves that a snapshot already covers; saved versions are never removed. The format specification is docs/format.md.