All chapters
Getting started
Daily work
Find and understand
Research and publish
Protect your notes
Reference
Trust, safety & privacy
Your Markdown files are the record. Header keeps its own working data beside them, shows you a diff before it changes several notes at once, and lets you lock the app or a single note. This chapter explains what Header writes, how it handles crashes and edit clashes, the checks it can run on your vault, and how to see which AI requests and lookups have left your Mac.
Your files are the source of truth Local
Your notes stay as Markdown files in the vault folder you chose, and those files are what counts. Everything else Header stores falls into two groups:
- The search index lives outside your vault, at
~/Library/Application Support/, one SQLite file per vault. It is derived data. If it is lost or deleted, Header rebuilds it from your notes.Header/ VaultIndex/ - The
.headerfolder sits inside your vault and holds Header's own metadata: note history (.header/history/), receipts (.header/receipts/), small JSON files such as your starred notes, and a cache of thumbnails and previews (.header/cache/). Finder hides it because its name starts with a dot.
The cache can be rebuilt. History and the other JSON files can't, so leave the .header folder in place when you move or copy a vault.
Reviewable edit plans Safety
When Header proposes a change to the text of your notes, it opens a review sheet first. Each changed region is listed as its own diff with a checkbox, and a counter shows how many you have selected. Only the regions you leave ticked are written when you click Apply (the button reads, for example, Apply 3 changes). Cancel writes nothing.
You'll see this sheet for:
- Update links to “…” after you rename a note or a file, so
[[Trip plan]]becomes[[Lisbon trip, May]]in every note that links to it. - Fix links… in Vault Integrity, which creates the notes your broken links point to, and repointing a broken link to a note with a close name.
- Markdown Refactor, Writing Tools edits, and a change proposed by Ask Header.
Before writing, Header saves each edited note to its history. It also re-reads every file first and skips any note that changed on disk after the plan was built, so a review can't overwrite newer work.
Crash recovery & edit conflicts Safety
After a crash
If Header didn't shut down cleanly, the next launch shows Recover unsaved work with the notes that had unsaved changes and a preview of each. Restore as Drafts opens them as new drafts. It never overwrites the files on disk, so you can compare a draft with the saved note and keep what you want. Discard drops them.
When another app changes an open note
Say you have Client meeting.md open with unsaved edits and your sync service, or another editor, changes the same file. Header doesn't overwrite either version. A bar appears above the note, Changed outside Header, with four choices:
| Button | What happens |
|---|---|
| Review Changes | Opens your edits and the current disk version side by side. |
| Keep Mine | Keeps the text in the editor. |
| Use Disk | Takes the version on disk. |
| Save Both | Keeps each version as a separate note. |
In the review window the same choices read Keep My Version, Use Disk Version and Save Both, and Header checks the disk version again before it writes. For a locked note the two versions can't be shown side by side, because the disk copy is encrypted, but the buttons work the same way.
Recovery data is kept until Header has confirmed the matching version on disk. Text from locked notes is left out of recovery data and history.
Time Travel
Each note keeps a private timeline of versions. Header adds one when you save, run an AI edit, add an image or rename the note, and before the reviewed changes described above. You can preview any version, compare it with the one before, and restore it. The full walkthrough is in The Note Inspector & history.
Vault Integrity
Vault Integrity scans the whole vault and groups what it finds:
- Broken links: a
[[link]]that points to no note. - Possibly out of date: a note with dates or decisions in it that hasn't been touched in months.
- Possible duplicates: two notes that share much of their content. Header names both notes and their folders, so you can tell Reading list in Inbox from Reading list in Projects.
- Cold open loops: a note that still has an unfinished item and hasn't been touched in a while.
Each row has Open and a close button that dismisses it until that note changes. A duplicate pair gets a button for each note. Rescan runs the check again, and when there are broken links, Fix links… opens a review sheet that creates the missing notes.
Contradiction check (Labs)
An optional AI check looks for related notes that disagree, such as two different dates for the same deadline. Turn on Contradiction check (AI) in Settings → Labs. It needs Apple Intelligence on this Mac or a cloud AI provider, and it runs only when you ask. A Contradictions menu then appears in Vault Integrity with two commands:
- Check for contradictions (AI) scans related notes across the vault.
- Compare notes… lets you pick the notes you suspect disagree and compares them in full.
Results appear as Possible contradictions (AI), with a button to open each side. Treat them as leads to check, not facts: results can be wrong, and on-device checks catch fewer subtle conflicts than a strong cloud model. A cloud check sends note text to your provider and is billed by them.
App lock Safety
On a shared or travel Mac, turn on Require Touch ID or password to open Header. Header uses Touch ID or your Mac password and stores no passphrase of its own. Then choose when it locks:
- Immediately when it loses focus
- After 1 minute, After 5 minutes or After 15 minutes
The first time you turn the lock on, Header sets it to five minutes. To lock straight away, choose File → Lock Now (⌃⌘L). While Header is locked, the contents of its windows and the menu-bar capture panel stay hidden until you unlock. header:// links and Shortcuts actions are refused, so run them again after you unlock.
Locked notes Safety
To encrypt a single note, such as Passport and visas, Control-click it in the note list and choose Lock Note. The first time, Header explains the limits and asks you to confirm:
- Locking encrypts the note's text only. Images embedded in it stay readable on disk.
- If this Mac's Keychain key is lost, the note can't be recovered. There is no recovery passphrase yet.
A locked note drops out of search and AI features, and Spotlight shows its title only. Locking also removes the note's earlier plain-text versions from Time Travel and from crash-recovery data, so history doesn't keep a readable copy.
Opening the first locked note asks for Touch ID or your login password. After that, locked notes open without asking again until you choose Lock Locked Notes from the command palette (⌘K), the app lock engages, or you quit Header. To turn a note back into plain Markdown, Control-click it and choose Unlock Note.
Privacy Receipts Privacy
With the send preview on (it starts on), Header opens a sheet before content goes to a cloud AI provider. It names the provider and the feature, and says what the request includes. Review exact content shows the text itself, and nothing is sent until you click Send to …. The checkbox Don't ask again for … skips the sheet for that one feature. The send preview covers the setting in full.
Each time you approve a cloud AI request or a public research lookup, Header writes a receipt on this Mac. Privacy Receipts lists them by day, with the time, the provider and model, the feature that sent it, its size in characters, and why it was allowed (for example You approved or Always allowed).
On-device AI never appears, because nothing leaves. That includes pictures from Apple's Image Playground (Insert Generated Image…): they are made on this Mac, so there is nothing to record. Requests that carry none of your content, such as the update check, aren't listed either. If you have never sent anything, the page says None of your notes have left this Mac.
Settings shows the same boundary as a short table under What may leave this Mac?:
| Action | Leaves your Mac? |
|---|---|
| Save note | No |
| Search, Lenses, Graph | No |
| HTML/PDF export | No by default; only if you let an export load remote images |
| Save a Link | Yes, to the website you clip |
| Review with Header, Ask Header | Only if a cloud AI provider is selected |
| Feedback bundle | Never sent automatically |
How Header Protects Your Files
This window gathers Header's file-safety promises in one place. It has sections for your files and the index, the metadata Header writes into the vault, saving and conflicts, the network requests Header can make and when each one happens, Ollama, and diagnostics. It's a good page to show a colleague who asks where their notes go.
Siri, Shortcuts and locked notes Privacy
Shortcuts actions and Siri requests go through the same checks as the app. While Header is locked, they stop and ask you to unlock Header first. A locked note can't be read or changed by them, and in lists it appears by file name only. Every change they make to a note is saved to Time Travel first.
Ask Header a Question answers on this Mac only, with Apple Intelligence when it's available and otherwise with the exact matching passages. Header's Spotlight entries, which Siri also uses, hold each note's title, a short preview and up to about 24,000 characters of its text for searching. Locked notes are listed by title only.
Header's cloud send preview and Privacy Receipts cover the AI requests and research lookups Header sends. Git backups and Save a Link aren't listed there. Once Siri has a result, what happens to it is up to Siri and Apple. AI-app access to a vault (MCP), which isn't in the beta, will also leave locked notes out.