Your notes are plain markdown files — and the file wins

When most apps say they “support markdown,” they mean export. You press a button, get a zip of files, and the moment you edit one of them it stops meaning anything to the app it came from. The real copy lives in a database you never see.

Clusker works the other way around. Every page is a plain markdown file, in a folder that mirrors your projects and folders. The blocks you see in the editor are a cache of that file. When the two disagree, we believe the file.

The file is the original. The database is a cache.

When you type in Clusker, the change is written to the file first, and the blocks in the database are rebuilt from it. If the file was written, the edit happened. If the database falls behind for any reason, it gets rebuilt from the file — never the other way around.

It works in the other direction, too. Change the file outside Clusker — in another editor, with a script, with a git pull — and a watcher on the folder notices and rebuilds the page. There’s no import step and no “sync now” button.

The file makes sense on its own. A page’s fields live in its front matter. A checklist item that became a task is still just a checklist line:

- [x] Send the lease draft to the landlord +anna {task=0f3a2c}

The plus sign says who it’s assigned to; the braces point to the task. Tick the box in the file and the task closes in Clusker, as if you’d clicked it there.

Conflicts are shown, not merged

Two copies of the same text will disagree sooner or later. Clusker fingerprints each file, so it can tell who moved: only the file, only Clusker, or both.

When both did, Clusker doesn’t try to be clever. Your file stays untouched. Clusker’s version is saved next to it as a separate file marked conflict, and the page shows a bar: this file was changed outside, here are both sides, choose one.

Quietly merging two versions of a note is how text goes missing — and you notice a week later, when nobody remembers what was there.

That’s a little friction on a rare day, in exchange for never losing a paragraph without being told.

Update: when people write together

Added in September 2026, when shared editing shipped.

Pages and canvases can now be edited by several people at once. That forced an honest answer to a hard question: while three people are typing into the same page, what exactly is “the file”?

The answer is a boundary in time.

• When a page is closed, the file is the original, exactly as described above.
• While a page is open for shared editing, the original is the live session everyone is typing into. The file gets a snapshot every few seconds, and again when the last person leaves.
• If someone edits the file while the session is open, the page turns read-only and everyone on it sees the same choice. We don’t merge live edits with text from another editor; that would mean guessing on your behalf.
• If the file changed while nobody was around, the file wins over any older saved state. A stale session will never overwrite what you wrote somewhere else.

Why this is worth the trouble

A note you can’t open in any editor or put in git isn’t really your file. It’s a row in someone else’s database.

• Leaving isn’t a conversion. Your pages are already markdown — headings, lists, links and images written the way any editor expects. Taking them with you means copying files, not translating out of a proprietary format and hoping nothing gets lost.
• Your other tools keep working. A folder of .md files opens in Obsidian, versions with git, backs up with rsync and searches with grep.
• Plain text outlasts apps. It has outlived every program that ever wrapped it, and it will outlive ours.
• Passwords never go there. Entries from the vault are never written to the folder — not to files, not to git.

Where the folder lives today

We want to be precise about this. The folder lives on the server that runs Clusker. If you run Clusker on your own server, it’s an ordinary directory: open it in Obsidian, commit it to git, back it up however you like. That’s how we work with it ourselves.

On app.clusker.io the same files exist for your team, but there isn’t yet a way to take the whole folder home in one click — we’d rather say that than imply otherwise. In the meantime, any page can be selected with ⌘ A and copied, and it lands on your clipboard as markdown.