Skip to content

Vault and files

A vault is an ordinary folder of .md files on your disk. There is no database, no import, and no proprietary container. Point mdai at a folder you already have and it reads what is there.

Action macOS Windows / Linux
Open File… ⌘O Ctrl+O
Open Vault… ⇧⌘O Ctrl+Shift+O

Open File opens a single document. Open Vault opens a folder, which is what fills the Files panel, the task index, the tag index and backlinks — the features that need to know about more than one note.

You don’t need a vault to work. Open any Markdown file and mdai saves it back in the same place — nothing is copied into a vault.

One exception: publishing uploads images only from the vault you have open. Without a vault the text of the post is sent, but images that are files on your computer are not — mdai asks about each one whether to skip it or cancel the publishing.

File → Close Vault puts mdai back to single-document mode. Pending edits are saved first; no file is moved or deleted.

⌃⌘1 / Ctrl+Shift+1 shows the file tree: your folders and your Markdown files, folders first, then alphabetical. Empty folders show too. It is a view of the folder, not a copy of it. Names are shown without .md, and the note you have open is highlighted. A note’s image folder (note-name.assets) is not shown in the tree.

At the top of the panel are the vault’s name, + for a new tab, Collapse all folders, an Open File… button, and Filter files…, which narrows the tree and the Open section to names that contain what you type. Click the vault’s name to show its folder in Finder, File Explorer or Files; to open another vault, use More → Open Vault in the left rail.

Under them, four rows stay in place while the rest of the panel scrolls: Today opens today’s note, Todo shows how many open tasks are overdue or due today, Calendar opens the calendar, and then Tags. Click Todo and those tasks open in a short list right under the row; click Tags for every tag with its count — click a tag to see where it is used. Click the row again to fold the list. Below the rows come Pinned, Recent, Open and the vault’s tree; click a section’s title to fold it, and mdai remembers what you folded.

Below them, the Open section lists the files in your open tabs — with or without a vault — so a file from outside the vault is one click away. Click one and mdai switches to its tab. With split view on, it lists the tabs of both panes. A file that is no longer on disk is marked, and you can close its tab from there. The vault’s files follow under In vault. Click In vault to fold the vault’s files.

If the vault mdai remembers can’t be read when it starts — a disk that isn’t connected, or a folder the system no longer lets mdai open — the message stays on screen until you close it, and the Files panel says why it is empty.

Right-click a folder, or the empty space below the tree, and choose New Note or New Folder, then type the name. The name must not already be taken in that folder; if it is, nothing is changed.

Right-click it and choose Move to…, then pick the folder. Open tabs follow the file to its new place. A note with unsaved changes asks first: Save and move, Discard changes or Cancel. For a folder, mdai tells you how many notes and files move with it, and how many of them are open or unsaved.

A note’s images move with it: its note-name.assets folder goes along, and links to images elsewhere in the vault are rewritten so they keep working, including image paths with spaces in them. To leave the images where they are, turn off Settings → General → When moving a note: move its images; the image links in the note are then updated to point at the old place.

Right-click a note or a folder and choose Move to Trash… (Move to Recycle Bin… on Windows). mdai first asks, and says what is affected: the note’s note-name.assets folder, which goes with it, or for a folder how many notes and files it holds and how many of them are open or unsaved. Open tabs from it are closed. Nothing is ever deleted for good — you can restore it from the Trash or Recycle Bin.

On Linux, where a Flatpak can’t reach the system Trash for some folders, mdai moves the item into a hidden .trash folder inside your vault instead and tells you so.

A folder note is a note with the folder’s own name, inside that folder — Projects/Projects.md. Right-click a folder and choose Create Folder Note; if the folder already has one, the menu says Open Folder Note and opens it instead. It is an ordinary Markdown file: rename it, link to it, move it like any other note. A [[Projects]] link from a note inside that folder opens it.

Turn on Settings → General → Clicking a folder opens its folder note and a click on the folder takes you straight to its note. The arrow still folds and unfolds the folder. It is off unless you turn it on.

Find Unused Images… in the command palette (⇧⌘P / Ctrl+Shift+P) lists every image in the vault that no note uses. Nothing is ticked at first: tick the ones you want to remove and confirm, and they go to the Trash (Recycle Bin on Windows), so you can still get them back. Images that a note uses are never on the list. Where the system Trash can’t be reached, they go into a folder inside your vault instead, and mdai tells you so.

Rename a note from the Files panel, from its tab, with File → Rename… or from the command palette. mdai offers to update the [[links]] in other notes and changes them only after you confirm. The note’s version history moves with it.

Notes you open all the time can sit at the top of the Files panel, in a Pinned section above the tree. Right-click a note and choose Pin, or open the note and run Pin note from the command palette (⇧⌘P / Ctrl+Shift+P). Unpin works the same way.

Pins belong to the vault — each vault has its own — and they are still there after you restart mdai. Pinning only changes what the panel shows; the file stays where it is on disk.

mdai follows the folder while you work. A file changed by another program — a sync client, a script, another editor — is picked up on its own, and the panels refresh with it. You do not have to tell mdai that something happened outside its window.

If a file was changed both on disk and in your open tab, mdai asks before overwriting anything.

View → Rescan Vault rebuilds the index from scratch. You should not need it in normal use; it is there for the cases where the folder changed in a way the operating system does not report — a whole directory restored from a backup, a network share that reconnected, a sync client that wrote a thousand files at once.

It has no shortcut on purpose: it is a repair, not a daily action.

Nothing here locks you in. Every note is a text file, every folder is a folder, and any other editor opens them unchanged. If you delete mdai tomorrow, your vault is exactly what it was — a folder you can read.