File-first: files are the source of truth
The unit of data in Notarium is a plain Markdown file on your disk. Not a row in someone else's database, not a block in a proprietary store, but a file you can open in any editor — one that stays complete without Notarium. This is the file-first principle, and everything else follows from it.
What is "truth" and what is derived
The source of truth is the .md files themselves. Anything that can be computed from their contents is derived and recoverable:
- derived (rebuilt from scratch by a rescan): the search index, the
[[wikilinks]]graph, the tree, snippets. Deleting the index is no cause for concern — the engine reindexes the files on the next start; - non-derivable (lives in a separate metadata database): version history, users, membership, and access. This is what can't be recovered from the text of the files, so it's moved into a single, clearly separated home.
Identity, by contrast, is anchored in the files themselves: a note's notarium-id lives in its frontmatter, and space and project identifiers live in marker files (.notariummeta). That's why the space and project tables in the metadata database are a scan-recoverable cache, not the sole home of identity: identity survives even when the folder is moved outside Notarium.
Losing the index is harmless: it simply gets rebuilt. The files are never touched in the process — writes are atomic (write to a temporary file, then rename), and external edits (git, another editor) are treated as a normal mode of operation, not an error.
An external edit is picked up even when the file keeps its previous size and modification time — which is exactly what happens after a git checkout, a sync, or a restore from an archive. Notarium doesn't take file metadata at its word: the content has the final say, so the derived surfaces (the list, search, the graph) converge on what's actually on disk instead of getting stuck on a stale version.
A file-note, not a block
The boundary here is drawn deliberately: the unit of data is a whole file-note, not a paragraph or a block inside it. Notarium introduces no separate entities smaller than a file — the note as a whole stays the minimal unit; this is exactly the point where file-based note-taking apps usually switch to a database as their source of truth and lose portability. A note stays a file, and the structure inside it is just Markdown.
Notes are rendered as GitHub Flavored Markdown; metadata fields are stored in the frontmatter at the top of the file.
Identity survives the move
Every note has a stable internal identifier, notarium-id — a 12-character URL-safe key in the file's frontmatter:
---
notarium-id: aB3kR7xQ_2mv
title: My note
---
The note's text in plain Markdown.
Identity lives in the file itself, not only in a database. That's why renaming, moving between folders, and even moving it outside Notarium won't orphan the version history and connections: the log and the links are bound to notarium-id, not to the path. The file name is derived (kebab-case via transliteration, slug(title).md) and is not identity.
No lock-in
You can grab the folder of files and leave at any moment — without Notarium the notes stay readable and complete. You don't need a separate export operation: you're never "inside" in the first place — your data always sits as plain files on your disk. git can be the source of truth: version the folder, sync it, read the history with the tools you already use.
This is also the foundation of Notarium's privacy: it rests not on end-to-end encryption (the smart server deliberately sees the contents — otherwise there'd be no search, semantics, or agents), but on the fact that you keep the server and the files yourself. More in Spaces and projects and Access model.