---
title: "File-first: files are the source of truth"
description: "Notes are plain Markdown files on your disk: they are the source of truth, while the index, graph, and search are recoverable derived artifacts."
---

# 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.

> [!note] Why this matters
> 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:

```md
---
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](/docs/concepts/spaces-and-projects/) and [Access model](/docs/concepts/access-model/).