Where your files live

Two places, and only one of them holds anything you'd miss.

Your vault

The folder you chose. It holds your .md files, in whatever folders you put them in, and nothing Halcyon added.

These files are the originals. Everything else Halcyon keeps is built from them and can be thrown away.

The app's storage

~/Library/Application Support/co.themillers.halcyon/
  indexes/Notes-6c5ac4e81c72fb72.sqlite     the search index, disposable
  session.json                              which windows were open, and where
  recents.json                              the Open Recent menu
  remote/Notes-6c5ac4e81c72fb72.bind.json   a synced vault: which remote copy it is
  remote/Notes-6c5ac4e81c72fb72.state.json  how far sync has got, and what it last saw
  remote/Notes-6c5ac4e81c72fb72.lock        keeps one copy of Halcyon syncing a vault
  journal/Notes-6c5ac4e81c72fb72/           copies of notes Halcyon replaced or removed

The three remote/ files appear only once you've turned on Sync.

Each vault gets its own database, named for the folder plus a hash of its full path, so two vaults both called notes can't collide. The sync state files are named the same way for the same reason.

Only journal/ holds note content, and none of them holds a secret.

The journal is the exception, and on purpose: it's the copy Halcyon keeps of anything it replaced or removed on its own, for 30 days. Deleting it throws those copies away and nothing else. See Getting a note back.

Deleting the index

Safe. Delete indexes/*.sqlite and Halcyon rescans that vault on the next launch and rebuilds it from the files on disk.

You lose one thing: pins, which are the single piece of state stored only here. Everything else is derived.

This is the fix for a note list that disagrees with the folder, and it costs nothing but the rescan.

Deleting the sync state

The two remote/ JSON files are not equally disposable.

File	Losing it costs
*.state.json	A slow first sync. Halcyon asks the server what it holds and compares. Nothing else
*.bind.json	The link itself. Nothing can work out again which account and which remote vault this folder was

If you delete the binding, the folder becomes an ordinary local vault and you'd attach it again through Open remote vault. Nothing is lost from either copy, but it's more work than it sounds.

The Keychain

Your refresh token and every encryption key live in the macOS Keychain, never in a file. Keychain items get OS-level access control; a file in Application Support is readable by anything running as you, and travels into every backup you make.

Signing out deletes them.

What syncs, and what doesn't

	Travels between Macs
.md files in the vault	Yes, with Sync on
Images, PDFs, anything not .md	No
Pins	No. Device-local, in the index
Settings and keybindings	No
Window layout and Open Recent	No

Backing up

Back up your vault folder. That's everything.

Time Machine covers it, and so does git, Dropbox, or anything else that copies files. Because notes are plain markdown, git init in a vault gives you a complete version history that Halcyon knows nothing about and can't interfere with.

Tip

A vault in git and a vault in Sync work together fine. They're solving different problems: git is history you control, Sync is the same notes on your other Mac.

Backing up Application Support is optional. Everything there rebuilds, except pins, window layout, and the recovery copies in journal/.

Clearing Halcyon's own state

Your notes are never involved. They're plain files in a folder you picked, and nothing about them belongs to the app.

rm -rf ~/Library/Application\ Support/co.themillers.halcyon
rm -f ~/.local/bin/halcyon

The first clears search indexes, window state, the Open Recent list, pins, any sync bindings, and every recovery copy Halcyon was holding. The second removes the halcyon command.

Keys and tokens aren't in either place: they're in the Keychain, and signing out is what removes those.

Deleted notes

Deleting a note removes it from disk. It does not go to the macOS Trash, and there's no Put Back.

There's no staging step and no hidden folder: Halcyon deletes the file the same way it writes and renames one, through the vault's own directory rather than a path that names it, and the file is gone once that call returns.

If the vault syncs, the note isn't gone for good. Older versions live in the server's history, so you can recover one from there even though the local Trash never had it. See What Halcyon Sync is.

A note deleted on another Mac is a different case, because nobody here agreed to it. Halcyon keeps a copy before applying that delete, and Getting a note back is how you reach it, with or without Sync.

Symbolic links in a vault

Halcyon won't read or write through one. A symlinked note, or any note inside a symlinked folder, doesn't appear in the note list and can't be opened or saved.

Links end up in vaults by accident more often than on purpose: a Time Machine restore, an rsync, a git checkout, or another app's sync client. Following one would mean a file outside your vault could be read, and overwritten, as though it were a note inside it.

Nothing is lost when this happens. The file the link points at is untouched, and replacing the link with a real file, or deleting it, is enough to bring the note back.

Vaults on other kinds of disk

A vault works on any volume macOS can write to. One difference is worth knowing on ExFAT, which is how most USB sticks and SD cards arrive formatted.

APFS and HFS+ can rename a file only if the destination name is free, as one indivisible step. ExFAT can't do that, so Halcyon checks the name and then renames. Two notes created at the same instant can therefore land on the same name. You'd need two creations inside the same millisecond to see it, so it's a risk for something creating notes in bulk rather than for you typing ⌘N.

Everything else behaves the same, deletes included.