Last updated

Core ideas: how Undra actually works

By the end of this page you will have one mental model of Undra, the one the reference pages quietly assume. Not how to click anything: why the pieces fit together the way they do. Get these six ideas and the rest of the docs stop feeling like a list of features and start feeling like one coherent thing. Each idea is a couple of sentences and a link to where it actually shows up.

1. Items are files you own

An Undra workspace is an ordinary folder on your disk, and the things inside it are real files, not rows hidden in some database. A note is a Markdown .md file you could open in any other editor; plans, canvases, and the rest are Undra’s own file formats, but they are still just files sitting in that folder. The payoff is plain: you can back it up, sync it, move it to a new machine, or open it in another tool, because nothing is trapped.

See Local-first trust for why this is the foundation, and Notes for what one of those files actually looks like on disk.

2. Identity lives in the id, not the filename

Every item carries a small stable id in its frontmatter, and that id, not the filename, is who the item is. So you can rename a note or move it to another folder and nothing breaks: the links pointing at it still resolve, its place in any ordering holds, its backlinks stay attached. Filenames stay human and readable precisely because they are not load-bearing; the id does the quiet work underneath.

The frontmatter id is shown in Notes (the real example near the end), and rename-safe linking is the whole point of Wikilinks & backlinks.

3. The indexes are caches, not your data

Search, the graph, and the semantic index are all derived from your files. They are caches the app builds for speed and for finding things; if one were ever lost, Undra just rebuilds it from the files, and none of your actual work is at stake. One exception to know about: the semantic index (search by meaning rather than exact words) is not automatic. It is an explicit, one-time Build index step you turn on when you want it.

Why indexes are safe to lose is covered in Local-first trust; the build-it-once semantic index lives in Setting up AI, and everyday search is in Search.

4. AI writes, you can see it and undo it

Trust is undo-first, not approve-every-keystroke. Mira can create and edit workspace items while working; you see what changed in chat, and one Undo can roll the whole run back. In folder portals, the same rule covers real files on disk: edits and deletions both apply as the AI works, anything overwritten or deleted is backed up first, and one Undo reverses the whole run.

How Mira runs that model is in Mira; the portal gates and undo path are in Folder Portals.

You stay in control

The rule under all of this: if something changes your workspace, you should be able to see what it changed and why, and take it back. Control here means every change is visible and reversible, not that you have to approve each one before it happens.

5. Views are lenses, not copies

A plan’s calendar view and the graph do not hold their own data. They are live lenses pointing at the same items. A calendar view is your plan tasks that have dates, laid on a grid; drag one and the underlying plan changes, because there is only one copy. This is why edits show up everywhere at once: there is nothing to keep in sync.

See Plans (whose calendar view lays dated tasks on a grid) for the clearest everyday example; the graph view is in Undraverse.

6. Capture first, structure later

You do not design a taxonomy before you start. You write things down, and the structure assembles itself out of what you wrote. The mechanism that makes this work is the wikilink: type [[Some item]] mid-thought and you get a backlink on the other item and an edge in the graph for free, with no filing. Link as you go, and the map of your work emerges instead of being planned.

This is the heart of Wikilinks & backlinks; the low-friction surface you usually capture into is Notes, and the map those links draw is Undraverse.

Where to go next