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 proposes, you review, then it applies

AI does not quietly rewrite your files. It proposes a change, you see exactly what it wants to do, and only then does it land, and everything it does is reversible. The autonomy is risk-scaled: safe, recoverable edits can apply on their own, while deletions always stop and ask you first. That mix is what makes it comfortable to hand work to AI without watching every keystroke.

The full propose, review, apply flow (including the auto-apply setting and the undo behavior) is documented in Folder Portals, and the helpers that run it are in Agents.

You stay the one deciding

The rule under all of this: if something changes your workspace, you should be able to see what it changed and why, before it sticks. Risk-scaled autonomy just decides how much it asks first, never whether you can undo.

5. Views are lenses, not copies

The Calendar, dashboards, the graph, and query widgets do not hold their own data. They are live lenses pointing at the same items. The Calendar is your plan tasks that have dates, laid on a grid; drag one and the underlying plan changes, because there is only one copy. A dashboard that says “due this week” is reading the same tasks, not a separate list you have to keep in sync. This is why edits show up everywhere at once: there is nothing to keep in sync.

See the Calendar (a view of dated plan tasks) and Dashboards (assembled live from your items) for the two clearest examples; 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