The Vault — notes, editor, search and sharing
Omniscio's built-in Markdown vault: point it at a folder of notes and edit them in place, with a file tree, search, wiki-links, images and sharing. (Formerly called KMS.) This page covers getting around the vault and the editor; the long tail — the editor's details, media, the AI tools and the internals — continues on the parts below.
On this page
What it is
Status: Phases 1-3, 5, 6 shipped — full Markdown vault editor with images, AI summaries, and agent access over the CLI routes. Omniscio hosts a TipTap-based Markdown editor inside the Vault panel, with autosave, persisted open tabs, note CRUD (create / rename / move / soft-delete / hide), wiki-link back-reference rewriting on rename, wiki-link autocomplete, find/replace, source view toggle, a unified search modal across note titles + content + images + mind maps, full image support (paste / drop / picker import, content-addressed asset dedup, gallery panel, full-screen lightbox, AI-derived per-image title / description / OCR / tags / category, image FTS5 search), per-note AI summaries with drift detection + opt-in auto-regen worker + in-editor status chip, and hybrid semantic search. Agents reach the vault over Omniscio's own
/kms/*routes — the read-onlykms_*MCP tools were retired on 2026-09-19 (Vault agent tools). Writes land on disk under the configured vault root only; soft-delete moves notes into<vaultRoot>/.trash/<timestamp>__<basename>instead of unlinking. Image assets live in<vaultRoot>/assets/<sha256>.<ext>(content-addressed → automatic dedup across the vault). Phase 4 (Tasks UI) and the Quick Compose capture window are not built, and vault export and the remaining Phase 8 polish items are deferred — though the KMS appearance / custom theme options from Phase 8 DID ship (see Custom theme options), and so did crash recovery (see kms-part-6.md) — see What the Vault does not include. For a verified feature-by-feature parity map against the standalone "Knowledge Management Tool" (Nothari) app — what's present / partial / missing and a proposed build-wave roadmap to reach full parity — see kms-parity-audit.md.
The Vault is an integration that exposes a folder of Markdown notes (a "vault") to Omniscio as a knowledge surface you can both read and edit in place. You point Omniscio at a vault root on disk, and Omniscio parses every .md file under it once, then watches the folder for changes. The notes show up as The Vault, a virtual project under the Productivity group in the sidebar. From there you can browse the vault list, open a note in the editor, edit it (with autosave to disk), search across every note's body with FTS5, rename / move / soft-delete notes, and see external filesystem changes land in real time when something else on disk updates a file.
The vault format is plain Markdown — one note per .md file, YAML frontmatter optional, #hashtag and [[wiki-link]] syntax recognized but not required. The integration deliberately does not own the file format — it reads and writes whatever round-trips through the editor's serializer, and stays out of the way otherwise. You can continue using the KMS desktop app (or any Markdown editor — VS Code, Obsidian, plain Notepad) alongside Omniscio; the watcher picks external edits up and refreshes the sidebar.
How tags are read. A tag is # followed by a letter and then letters, digits, _, - or /, up to 64 characters — so #project/alpha is one tag. Only the English letters A–Z count as letters: #café is read as #caf, and #日本 or #2024 is not a tag at all. Tags are case-sensitive (#Work and #work are two different tags), a tag inside a code block or inline code is ignored, and an over-long tag is dropped. Front-matter tags may be a list, or one space- or comma-separated string: each entry is trimmed and a leading # dropped, then it must be at most 64 characters of letters, digits, _, - or / — but unlike a #hashtag it does not have to begin with a letter, so 2024-review in front matter is a tag even though #2024-review in the body is not. A front-matter café is dropped outright rather than truncated. Renaming a tag must produce a name the body can express, so a rename target must start with a letter: renaming goals to 2024-goals is refused rather than rewriting every #goals in your notes into a #2024-goals token the indexer can never read back.
Off by default. The integration is gated by the nothariEnabled setting (default false). With it off, no parser runs, no watcher runs, no DB tables are touched, the editor chunk never loads (TipTap is React.lazy-imported behind the panel), and the sidebar entry is hidden. One background job is the exception and has a switch of its own: if you turned on Auto-regenerate stale summaries, its timer keeps running — and keeps paying for AI summaries and rewriting note files — until you switch that toggle off too, even with the Vault off. See kms-summaries.md. The intended onboarding is one step: Settings → Features → flip Enable Vault. With no folder saved it creates and uses Documents/Omniscio Notes, saves that as the vault root, and runs a full index pass, so the sidebar entry appears straight away. The folder itself is set in ONE place — Settings → Plugins → Vault — where the optional Vault folder card points the Vault at a folder you already have (e.g. C:/My Knowledge Vault/); that is not a required second step, and the Features screen only says where the folder lives and hands you there. That default folder is where your notes are then written: nothing else on this computer uses it, but deleting or moving it takes any notes inside it with it, so move them somewhere else first if you want to keep them.
On more than one computer. Omniscio does not copy your Vault between computers, and Cross-Device Sync does not include it. To use the same notes on two computers, keep the vault folder in a folder-sync service (OneDrive, Dropbox, iCloud Drive, or similar) and choose that folder on each computer. Version history, bookmarks, hidden notes and picture descriptions stay on the computer where you made them.
Pictures in a folder you already have. The Vault shows only pictures it stored itself, in the vault's assets folder. If you point it at an existing Obsidian or Markdown folder, Obsidian picture embeds (![[picture.png]]), pictures linked by any other path, and web pictures all show as a broken image link. The note text is untouched, and the pictures still work in your other editor. To bring a folder over with its pictures working, use Import from Obsidian (KMS Obsidian Import Wizard), which copies them into the Vault.
Off by default. The integration is gated by the nothariEnabled setting (default false). With it off, no parser runs, no watcher runs, no DB tables are touched, the editor chunk never loads (TipTap is React.lazy-imported behind the panel), and the sidebar entry is hidden. One background job is the exception and has a switch of its own: if you turned on Auto-regenerate stale summaries, its timer keeps running — and keeps paying for AI summaries and rewriting note files — until you switch that toggle off too, even with the Vault off. See kms-summaries.md. The intended onboarding is one step: Settings → Features → flip Enable Vault. With no folder saved it creates and uses Documents/Omniscio Notes, saves that as the vault root, and runs a full index pass, so the sidebar entry appears straight away. The Vault folder card on the same Features screen is the optional override for pointing the Vault at a folder you already have (e.g. C:/My Knowledge Vault/), not a required second step. That default folder is where your notes are then written: nothing else on this computer uses it, but deleting or moving it takes any notes inside it with it, so move them somewhere else first if you want to keep them.
A one-time reset on 2026-05-26 (src/main/services/force-off-features-migration.ts) flipped nothariEnabled — along with Marketplace, Marketplace Review, and Tasks Outliner — OFF for every install, overriding any deliberate enable, so even users who had the Vault running before now start with it off. After that one-time reset your toggle choice is authoritative: enable it once and it stays on across launches. The flag is read with settings.nothariEnabled ?? false, so an install that never persisted the field simply reads as off.
Where to find it
The Vault panel in Omniscio's sidebar — that is the vault, and the editor inside it is where you write. The switches that control it live in Settings, where the Vault itself has to be enabled before anything else here appears.
How it behaves
How to use it (Phase 2)
Turn it on. Settings → Features → flip Enable Vault. That is enough: with no folder saved, turning the Vault on creates Documents/Omniscio Notes and saves it as the vault root, so the Vault is usable immediately instead of waiting for a folder choice. The same holds if you press New note before any folder is set up: the Vault makes that folder first and then writes the note, rather than doing nothing; if it genuinely cannot make one, it says so with a button that opens the Vault settings page. Your notes are written into that folder — nothing else on this computer uses it, but deleting or moving it deletes or moves the notes in it. A second, isolated copy of the app (a test or sandbox instance) never shares it: that instance makes its own default folder inside its own data folder instead.
Optionally, point Omniscio at a folder you already have. Settings → Plugins → Vault → Vault root folder → Choose folder… (desktop only) picks the vault root. That Vault page is the one place the folder is set; the Enable Vault row on Settings → Features names the current folder and links straight there. The folder is validated first — it must be a real directory, not a system folder, a shortcut/symlink, or missing — and is saved ONLY if it passes, so a bad pick shows a plain-English reason inline instead of silently failing to index. A good pick applies immediately (no restart): the indexer kicks off a full scan and reports progress in the sidebar. Picking a different folder switches the open vault to it — the Vault panel follows the folder you've configured, not whichever vault you set first. (Changing the folder registers a NEW
nothari_vaultsrow; the registry is orderedcreated_at ASC, so the active vault is resolved by matching the configured root in the main process —getConfiguredVaultId()→KMS_VAULT_LIST.activeVaultId, plus aKMS_ACTIVE_VAULT_CHANGEDpush for the live switch — never blindlyvaults[0]. Pinned by I7 of the contract below.) The currently-set folder is re-checked whenever Settings opens, so a moved/deleted vault surfaces a ⚠ warning. The validate-before-persist seam reuses the same hardenedvalidateVaultRootthe indexer uses, via the read-onlyKMS_VALIDATE_VAULT_ROOTIPC; pinned by the KMS vault-root picker contract. Forgetting an old folder. After a switch the app still keeps the old folder's index, saved versions, summaries and drafts. The Vault folder card on Settings → Plugins → Vault lists every such stored folder with a Forget button: after a confirm it removes everything the app kept about that folder and takes down pages published from it (kms:vault-forget; agents usePOST /kms/vault/forget, which waits for your approval). The Markdown files in that folder are never touched, and the active folder cannot be forgotten. Quick notes and web clips refuse with one shared sentence and one code. With no notes folder chosen they say, word for word: "No Vault folder has been chosen yet - open The Vault and pick your notes folder first." and carry the machine reasonvault-not-set-up. With a folder chosen that the Vault has no record of yet they say "The Vault is still setting up that folder - give it a moment, then try again." and carryvault-not-ready. Either way a capture is never filed into the previous folder, so a quick note or clip can't land somewhere you can no longer see. The Obsidian import, the agent routes and the vault-folder picker show the same two conditions in their own words and do not yet carry the machine reason — search the sentence, not the code, on those three.Switching folders keeps the old folder's notes. Picking a different folder registers a new vault and indexes it; nothing deletes the previous folder's notes from Omniscio. Their text, tags, links, embeddings, saved versions and image analysis stay in Omniscio's local database — they are simply no longer watched or re-indexed, so they go stale, and they survive even if you delete that folder from disk. They also stay reachable:
GET /kms/searchandGET /kms/semantic-searchsearch every registered vault whenvaultIdis omitted, so an agent's search still finds the old folder's notes. Every other route acts on one vault — the inventory and image routes resolve the configured vault, or answer409once more than one vault is registered — so pass the old folder'svaultId(fromGET /kms/vaults) to read its notes directly. If you want them gone from what agents can find at all, remove the old folder's notes before you switch.Wait for the first index. The first scan walks every
.mdfile under the vault root, parses frontmatter / hashtags / wiki-links, and writes a row per note into Omniscio's SQLite DB. Subsequent launches are incremental — only changed files reparse.The first successful start also writes starter notes into that folder, without asking. It creates a
Playbooks/folder with five notes — Getting Started with AI Agents, Daily Operations Checklist, Writing Effective Prompts, Managing Agent Costs and Troubleshooting Common Issues — and, if the setup interview recorded your AI comfort as low or medium, one more note at the root: My AI Journey. Starter notes go ONLY into the folder the app made for you (Documents/Omniscio Notes) and only while it is still empty: pointing the Vault at a folder you already use — an Obsidian vault synced to other devices, say — never writes anything into it. They are made once per install, not once per folder. They are ordinary notes: read, edit or delete them like any other, and a deleted one does not come back.Open the Vault. It is listed on the Installed Plugins page; its In side nav switch adds a row to the side nav. Clicking it mounts the Vault editor shell. The file tree lives in Omniscio's native Pane 2 sub-sidebar — the same slot Tools, Skills, Alarms, AI Coaching use — so you get the standard Omniscio sidebar affordances (resize handle, mobile drill-down). The center pane holds the open-tabs strip on top, the formatting toolbar in its own rounded card, the TipTap editor in the middle, and a thin status bar at the bottom. The open note's tab is a folder tab joined to the page below it, on a tab band one shade deeper, with thin dividers between the other tabs; every color follows the current theme, light or dark. A side-panel drawer (Outline / Backlinks / Smart Connections / Tags / Bookmarks / Hidden / History / Trash) is available behind the toolbar's Toggle side panel button — closed by default after the 2026-05-21 layout rework. It opens as a solid floating card at the right edge, and while it is open the note slides left to make room instead of being covered (since 2026-11-16). Click the X in its header to dismiss without leaving the editor.
Open a note. Single-click any row in the file tree. Each file row is labelled by the note's name with the
.mdextension hidden, whatever its case — a note saved asNote.MDreadsNote, notNote.MD(the tree reuses the tabs'deriveTitlehelper, so a note reads identically in the tree and its tab; folders show verbatim — this is the FILE-name label, which can differ from the note's title, see below). This is display-only — the inline rename input still seeds with the full.mdfilename, so renames preserve the extension on disk. The note loads into the editor and a tab appears in the tabs strip. Open multiple notes — each gets its own tab, and the strip is preserved across relaunches via thenothari_tabstable. Switching between open notes is instant: the TipTap editor instance is reused across note switches rather than torn down and rebuilt (KMS nav speed Fix 4 dropped the per-tabkeyremount), so there's no rebuild flash. A cross-note switch still resets per-note state — empty undo history (Ctrl+Z can't bleed into the previous note) and scroll-to-top — exactly as the old remount did; a same-note external refresh preserves scroll + cursor. (Behavior pinned in the KMS editor scroll-stability contract.) A note's title and its file name can differ. The file list and the tab strip label a note by its file name; search results, Backlinks, Smart Connections and the[[link picker use the note's title, which is its front-mattertitleif it has one, otherwise its first heading, otherwise its file name. So a note saved as2026-01-05.mdwhose first line is# Daily noteshows as2026-01-05in the tree and asDaily noteeverywhere a link is built. Two notes that share a first heading therefore share a title, and a link built from the picker resolves to the lowest note id among them (The Vault — appearance and search has the resolution rule). Give notes distinct first headings, or atitle:in front matter, when you want links to land on the one you mean.Edit. Type into the editor. Five hundred milliseconds after you stop typing, the autosave debounce flushes — the body round-trips through the editor's markdown serializer, the frontmatter is re-attached byte-for-byte, and the file is written to disk. The write is atomic (temp file + rename); the rename is retried through a transient Windows file lock — a real-time AV scan, a file-sync client (OneDrive/Dropbox), or the Search indexer briefly holding the just-written temp file makes a bare
renamethrowEPERM, which used to lose the whole autosave — via the sharedrenameWithRetry(EPERM/EBUSY/EACCES, bounded), so a momentary lock no longer fails a save. Autosave runs silently: there is no per-keystroke dirty indicator (the status bar's amber Unsaved chip and the tab's dirty dot were removed 2026-06-09 — the sub-second type→save→clear cycle made them flicker on every keystroke). What the status bar does show is a brief Saving… while a write is in flight and Saved for about 1.5 seconds after it lands, both driven off the save itself rather than the dirty bit, so they never flicker as you type. Only a persistently failed write (the retry exhausted, or a non-transient error) surfaces, as a toast. A failed save, and an edit the editor holds back rather than risk writing a damaged file, also leaves a lasting Not saved mark — an error triangle on the tab, whose accessible label reads "…, not saved", and a Not saved mark in the status bar that says which of the two it is and offers the way out of it: Retry beside the mark when the write itself failed, Open source view beside it when the edit was held back — and it clears only once the editor matches disk again — the next save that succeeds, or the unsaved edit being discarded (you load the outside version, or the note's vault is switched away, and the reload actually lands). The internal dirty bit still exists and remains load-bearing (flush-on-close, flush-on-tab-switch, the privacy dirty-gate) — only its visual presentation was dropped.Find / replace (3-scope bar).
Ctrl+Fopens the find bar;Ctrl+Hopens it with the replace input visible — on a Mac those areCmd+FandCmd+Option+F, becauseCmd+His the system Hide command there. The bar carries three scope tabs — This Note · All Documents · Images — over one shared query box;Tab/Shift+Tabcycle them (or click a tab), and each tab shows a live result count. This Note searches the active note in both the rich editor and source view (source view uses textarea selection on the active match), with a<current> / <total>counter,Enter/Shift+Enterto step forward / back, case / whole-word / regex toggles, and replace / replace-all. All Documents + Images run the SAME vault-wide FTS asCtrl+P(theuseUnifiedSearchengine is shared, never duplicated) — arrow keys move the highlight,Enteropens: a document result switches back to the This-Note tab and opens that note with the query still highlighted, an image result opens the lightbox.Esccloses. This brings the Ctrl+F bar to parity with the standalone Nothari app's find bar; behavior pinned in the KMS find/replace contract.Source view.
Shift+Ctrl+Mtoggles the editor between the rich-text TipTap surface and a raw markdown textarea — useful for hand-editing tricky YAML frontmatter or pasting in pre-formatted content. Source-view typing saves exactly like typing in the rich editor: the tab goes dirty, the same 500 ms autosave debounce writes the body (the note's frontmatter is re-attached on the way out), and every flush point — switching tabs, closing the tab, unmounting, quitting — carries the text with it. Switching tabs never discards an unsaved source-view edit.Rename, move and delete. The file tree's context menu (right-click a row) exposes Rename on notes and folders alike, then Move to… and Delete on file rows, and Delete folder on a folder row — which moves every note inside to the same Trash, with the same one-Undo, because a folder here is only the notes that live under its path. Rename updates every
[[wiki-link]]that points at the note, one linking note at a time. If a linking note cannot be saved, the rename still happens and a warning names the notes that still use the old name, so you can fix them by hand. Delete pops a danger confirmation ("moved to the vault trash … recover from the vault's.trashfolder"), then soft-deletes byrelativePath: the file moves into<vaultRoot>/.trash/<timestamp>__<basename>and the row is removed fromnothari_notes(restorable until the retention sweep reaps it: press Undo on the toast that appears right after the delete, or open the side panel's Trash section and press Restore. See part 3 → Trash panel and Undo. After the sweep the note is gone for good). Deleting an open note closes its tab and discards any in-flight autosave so no doomed write fires against the gone file. Select several rows (Ctrl/Shift-click) and the menu collapses to Delete N items — one confirmation, deleted deepest-first, partial failures tolerated. The Command-Palette "Delete note" does the same to the active note. Behavior pinned in the KMS delete contract. See Moving a note below for Move to… and the file-list keys. The same menu's Copy link action (file rows only, right under Open) copies a deep link to the page — see Deep linking to a note. Renaming or moving a note that is open in a tab takes the tab with it — in the app, from the tree's drag-and-drop move, or from an agent over the CLI. The tab, its cached body and any waiting autosave all follow to the new path, so what you type next still saves into the note; a note you renamed is never left behind as a tab that silently refuses every save. Behavior pinned in the KMS open-tab-follows-move contract.Hide a note (Phase 3 Sub-PR 3f-2). The file tree's context menu also exposes Hide between Rename and Delete — file rows only, never folders. Hiding a note stamps a
hidden_attimestamp on the row but leaves the file on disk untouched. Hidden notes are filtered out of the file tree, the search index, and link suggestions. They remain reachable through the right-pane Hidden panel (see below).Watch for external changes. The file watcher debounces filesystem events and re-parses changed notes on the fly. The renderer receives a
kms:note-changedpush event with{ vaultId, noteId, relativePath, op: 'added' | 'updated' | 'removed' }(plusrenamedTo/renamedToUpdatedAton a rename'sremovedpush, so an open tab can follow the note) and refreshes the tree + the editor if the changed file is the active tab. Every open surface takes this refresh, including the phone's Files list with no editor on screen, and a phone that lost its connection re-checks its open notes the moment it reconnects (the kms store's own listener callsreconcileExternalNoteChangein external-change-slice.ts, and the web reconnect hook callsrevalidateOpenNotes; no editor component listens, so nothing depends on the editor being mounted — see the self-write echo contract). If the note you have open also has unsaved edits, nothing is overwritten — that note's autosave freezes (your text stays in the editor, and on screen it is still your version) and a toast offers Keep my version (writes your text over the outside one) or Load the outside version (drops your edits and reloads theirs). Nothing reaches disk until you pick, so a keystroke can no longer lose either copy; dismissing the toast writes nothing and leaves the note flagged unsaved. Closing, evicting or quitting with that choice still open does not pick for you — the outside version stays on disk and your text is handed to the crash-recovery draft, so the next launch offers it back. A note with no unsaved edits simply takes the outside version. The watcher is always on — its old Watch vault for changes row is gone from Settings, so there is nothing to switch off. (For agents: a storednothariFileWatcherEnabled: falseis still honored — the backend reads it as?? true— andPATCH /settingscan still set it; there is just no Settings row any more.) The watcher's ignore list is hard-coded and MUST mirror the indexer'sIGNORED_DIRSso the live watcher and the full re-scan agree on what is not a note:.git/,.kms/,assets/,node_modules/, and.trash/(so a soft-deleted note — which the CRUD service moves into.trash/— is not re-indexed and resurrected in search), plus any non-.mdfile. Internally the watcher does NOT use chokidar (which opens one OS file-watch handle per file — ~256 for a 243-note vault, tripping the resource-pressure alert): it puts a non-recursivefs.watchon each folder as a change signal, thenreaddir-diffs the folder to derive the real add/change/remove — so handle count scales with folder count, and it never trusts libuv's Windows directory-watch filename (which is corrupted). The vault root MUST be a real directory (no symlinks, no system paths, no traversal); every write-side handler funnels its user-supplied path throughresolveInsideVault()which rejects anything outside the configured root.
A write that loses the SQLite write lock is retried, and the retry waits off the UI thread. Both index write paths — the full re-scan's per-note upsert and the watcher's single-note index (indexSingleNote, which is also what a save's outside-edit refusal calls) — go through ONE helper in indexer.ts: up to three attempts, each allowed to sit on the SQLite write lock for at most MAIN_UI_LOCK_WAIT_MS (250 ms, via withBoundedLockWait), spaced by a 1.75 s then 3.5 s async backoff that yields the event loop. The upsert is a single transaction that rolls back on SQLITE_BUSY, so a retry can never double-write. The bound is the point: the main connection's busy_timeout is 2,000 ms, so each unbounded attempt blocks the thread that draws the screen for the whole wait before it throws — that is the shape behind the measured 13 s whole-app freeze, and one contended pass over 6–9 notes used to cost 36–54 s of it in six-second steps, typically at startup. Bounding each attempt to 250 ms and widening the async backoff keeps the same overall rescue window of roughly 6 s per note while cutting blocked UI time to at most 750 ms, and the watcher path — which had no retry at all, so a lost race was logged as a failed note and the edit was dropped — now gets the same rescue.
An external edit whose index FAILED is retried, not lost until restart. The watcher's per-folder snapshot records a file only once its add/change/remove callback reports that the index actually applied it; a callback that answers false (or throws) leaves that entry on its previous fingerprint — or out of the snapshot entirely, for a file it has never recorded — so the next filesystem signal or the 10-minute rescan re-emits it, while an entry the index did apply is recorded and never re-emitted. A file briefly held by a sync client, or a database is locked on the row write, therefore costs one delayed refresh instead of leaving an outside edit missing from search, the note list and the note's row (or a deleted file's row behind as a ghost) until the file changes again or the app restarts. A folder torn down because the whole folder was deleted keeps any removal the index refused, and the 10-minute rescan re-attempts it from the folder's surviving snapshot, so a delete that loses the SQLite lock cannot leave a ghost row until the next restart. A file the index will never accept — over the size limit, or a path it refuses — is recorded as handled rather than retried and re-logged on every rescan.
A folder that cannot be READ is not a folder whose notes were DELETED. A failed readdir is a transient condition (a locked or permission-denied folder, an I/O error, a cloud-sync folder briefly offline, a sleeping external disk), so it never counts as evidence that anything inside the folder is gone. In the watcher, any readdir error other than ENOENT keeps that folder's existing snapshot and skips the diff, so the next filesystem signal or the 10-minute rescan simply retries; an ENOENT counts as genuinely gone only when the folder's parent is still present AND sits on the vault's own volume (the watcher records the vault root's device when it starts and demands a match), and a read that succeeds on a different device is treated as unreadable too, which is what stops an unmounted drive, an offline share, or a mount point that outlives its volume from reporting every note under it as removed. The full re-scan applies the same rule on the index side: the walk records each directory it could not read, and the prune spares every note whose path lies under one of them (an unreadable vault root spares all of them, since nothing in the vault was reached). Rows, tags, links and note version history therefore survive an unreadable folder, while the folders that DID read are pruned exactly as before.
When the notes folder is missing, or the Vault isn't yours
A missing notes folder is said on the Vault screen, not only in Settings. If the saved folder is gone from this computer — a restore onto a new machine, an unplugged drive, a renamed directory — the file tree is replaced by a plain line naming the folder ("Your notes folder name isn't on this computer"), a note that nothing can be opened or saved until it is back, and a Find or change the notes folder button that opens the folder card. The old notes are not listed as though everything were fine: the index still holds them, so without this the Vault looked restored and then refused every save.
Which Vault is opened. The app opens the vault the notes-folder setting points at. When no folder is configured yet — a first run, or an install upgraded from before that setting existed — it opens the most recently added vault rather than the oldest one, so a machine carrying several old rows does not land on a folder the person stopped using. When a folder IS configured but is not on this computer, nothing is loaded and the message above is shown: another vault's notes are never substituted for the configured one.
One Vault per computer, not per account. The Vault folder and its index belong to the installation, so on a machine where more than one Omniscio account signs in, the second account meets the first account's notes. The Vault says so in a line above the file tree ("This Vault belongs to this computer, not to your account. Everyone who signs in on this machine can read and edit these notes.") rather than presenting them as its own. The account that sets the Vault up is recorded in nothariVaultOwnerAccountId; the notice appears only for a different account, and an install that never recorded one is claimed by whoever opens the Vault next.
When no note is open
With nothing open, the editor area is a starting screen rather than a blank pane. It offers:
- New note — creates an empty note in the open folder and opens it.
- Start from a template — two ready-made notes you can fill in. Agent Playbook is a step-by-step guide for a repeatable process; AI Learning Journal is for tracking your AI experiments, what worked and what you learned. Picking one creates the note with its headings and tags already set.
- Recent notes — your five most recently changed notes. Hover one to warm it up, click to open it.
- Retake the Quick Reference — replays the Vault walkthrough. The same walkthrough can be reopened later from Settings.
If an Obsidian vault is found on this computer, an offer to import it appears here too (see the Obsidian import page).
Moving a note, and the file-list keys
Move to… is the menu way to move a note. It sits right after Rename in the right-click menu of a note row (the picker moves that one note — a FOLDER moves by dragging), in the row's actions sheet on a touch screen, and in the command palette (Move to… moves the open note). All three open the same folder picker: the vault's top level first, then every folder, a search box that filters by folder path, Up / Down to move the highlight, and Enter or the Move button to go. The note's own folder is listed with a Current badge and cannot be chosen. Moving is the same as dragging: the note jumps to its new folder at once, a refused move puts it back and shows one plain error message, an open tab follows the note, and the destination folder opens so you can see where it landed. The picker moves the one note it was opened for; drag-and-drop still moves a multi-selection.
Folders. New folder is in the Files header (the folder-with-a-plus button), in the right-click menu, and in the command palette. A folder is not a separate thing on disk — it exists because notes live at a path — so creating one writes its first blank note, and the folder disappears on its own when its last note leaves. Drag a folder onto another folder and every note under it moves, keeping its own subfolders; drag it onto the empty area below the list and it goes back to the top level. Rename on a folder row renames the folder and every note inside it in place, and Delete folder moves everything inside to the Trash with one Undo that brings it all back. Every one of those actions runs through the same per-note move and rename the rest of the list uses, so [[wiki links]] to the notes keep working throughout. A move or rename that would put two notes of the same name in one folder is refused before anything moves, with one plain sentence.
Keys in the file list. With the file list focused: F2 renames the focused row (a folder too), Delete deletes it (the usual confirmation; with two or more rows selected and the focused row among them it deletes the whole selection; a folder row deletes the folder and everything in it), Shift+F10 opens the row's menu, and the Menu key on a keyboard always opens it. The right-click menu shows the bound key beside Rename and Delete. The three are rebindable at Settings → Keyboard Shortcuts → Vault Shortcuts (rows named "Rename file-list item", "Delete file-list item" and "Open file-list menu"). They act only inside the file list, so Delete in the editor still deletes text.
The star follows the note, not its path. The bookmark star in the toolbar is lit when the open note is bookmarked, and it decides that from the note's identity, so renaming or moving a bookmarked note leaves the star lit. A rename or move also tells the Bookmarks panel to reload, so its rows show the note's new path and title instead of the old ones. Clicking the star on a bookmarked note removes the bookmark rather than trying to add it again.
A shared chord is reported once, for the place that would really lose it. When the same key is bound to a panel command and to a file-list command, the file-list row says the panel command wins, because panel shortcuts are claimed before the file list ever sees the key. A key shared between an editor action and a file-list command is NOT reported as a loss: editor actions only fire while the editor has focus, so the two never compete for the same keystroke. Adding a key a command already holds is a no-op rather than a second chip, and removing one spelling of a chord removes the chord.
On a touch screen every row ends in a ⋯ button that opens that row's actions as a bottom sheet: Rename, Move to…, Copy link, Publish page…, Hide and Delete — only the ones that row offers. Rows get the 44px touch target size there and nothing changes on a mouse screen.
How it's wired (repo detail). The picker is MoveToFolderDialog.tsx, mounted by KmsView and by MobileKmsPanel (the phone's Files screen has no KmsView); the note it was opened for lives in the kms store as moveDialogPath (openMoveDialog / closeMoveDialog), and its folder list is collectFolderPrefixes over the loaded notes. The move itself is moveNotesToFolder in move-notes.ts, the same function drag-and-drop calls — see the tree-move contract (every-move-route-shares-one-move-function). The three key rows are KMS_SHORTCUT_DEFINITIONS entries with scope: 'tree': useTreeKeyboardNav matches them in the tree's own keydown, and buildKmsPanelBindingLookup leaves them out of the panel-wide dispatcher. The touch sheet is FileTreeActionSheet.tsx over the same action list the context menu builds.
Making a folder. The New folder here menu item is there but greyed out, marked coming soon. A folder appears in the list only once a note is inside it, so an empty folder you make in File Explorer stays hidden until a note lands in it.
To start one from inside the Vault, rename a note to include the folder name — for example rename Idea.md to Projects/Idea.md. The folder is created and the note moves into it. The name you type is relative to the folder the note is in now, so doing this on a note already inside Notes/ gives you Notes/Projects/Idea.md.
Ask the AI about a selection, or have it keep writing
Select a passage in a note, open the command palette (Ctrl+Shift+P) and pick Ask AI about the selection. A small card appears over the text with four buttons — Rewrite, Shorten, Explain, Fix grammar — and a box for your own question about the passage. Pick one, and the answer appears in the card while your note stays exactly as it was.
Then you choose what happens: Replace puts the answer in place of the selection, Insert leaves every word you wrote and adds the answer as its own paragraph after it, Discard (or Esc) changes nothing. A Replace or Insert is one undo step — Ctrl+Z brings your original text straight back, including when you had been typing just before.
Continue writing works the same way from the cursor: the palette row reads the text before your caret, writes one to three sentences in the note's own voice, and shows them for you to accept or discard. It never inserts on its own.
The answer is refused rather than applied if the note or the selected text changed while the AI was thinking, and nothing can be written into a read-only note — so a preview can never land on another note or on text you did not select. Every call is paid the same way as note summaries: your own AI keys first, then your Omniscio credits, with no Anthropic key of your own needed. It draws on the same daily Vault AI budget (raise or lower it at Settings → Optional Features → Vault → Vault summary options → Daily cost cap) — shared when you have an Anthropic API-key account; without one, editor AI and summaries each count against their own copy of the daily cap. When nothing can pay for the call, the AI card says so instead of failing silently. Because the two draw on the same budget where it is shared, heavy editor use can use up the day's budget that summaries also draw on, and once it is spent the AI rows say so and send nothing. The commands work on the desktop only: a paired phone or the web bridge cannot call them, because they spend your AI budget. Whatever the AI writes is kept as plain writing: HTML tags it includes show up as text, remote images are dropped, and links that are not web, email, in-page or relative addresses are dropped.
Only keep pinned notes as tabs (preview-tab mode)
By default every note you open adds a tab, and the strip caps at 10 unpinned tabs — open an 11th and the least-recently-active unpinned one drops off (pinned tabs never count against the cap). Turning on Settings → Features → Vault → "Only keep pinned notes as tabs" (nothariTabsPreviewMode, default off) switches to a single-preview model: opening a note reuses one ephemeral slot instead of appending, so the strip only ever holds your pinned tabs + the note you're reading. Open another note and it takes over that same slot. Pin a note to keep it. On desktop (with a mouse or trackpad) an unpinned tab shows no pin button — right-click the tab → Pin; a pinned tab then shows a small pin glyph you can click to unpin, so you can still see which tabs are pinned at a glance. On touch (a phone or tablet) the inline pin glyph is always shown on every tab — it is the only pin affordance there, since touch has no right-click. Either way, a pinned note becomes a permanent tab. Reloading the vault (or relaunching) collapses a strip that had accumulated unpinned tabs down to pinned + one preview, so the bar starts clean; the surviving preview is the one you were most recently on. Replacing the current preview flushes its autosave first, so an in-progress edit is never dropped. Off is byte-identical to today's append-and-cap behavior — nothing changes until you opt in. Pinned by the KMS tab preview-mode contract.
Collapsing the file-tree sidebar
The Vault file-tree sub-sidebar (Omniscio's native Pane 2 — the notes/folder list) can be collapsed the same way the regular Sessions and Projects sidebars hide. A collapse button (a chevron with the accessible name "Collapse Vault sidebar") sits at the top of the sub-sidebar; clicking it tucks the file tree away and replaces it with a thin clickable reopen edge-strip (hover reveals a chevron; click brings the tree back). The collapsed/expanded state persists across launches via the integrationSidebarHidden setting (default false — expanded). A rebindable shortcut Ctrl+Alt+\ ("Toggle Vault sidebar", editable at Settings → Keyboard Shortcuts) toggles it too, and is inert anywhere except the Vault screen. (This is separate from the right-pane drawer's Toggle side panel button in step 4 — that hides Outline/Backlinks/Tags/Bookmarks; this hides the whole file-tree column.)
It is desktop-only: on a phone the Vault panel uses its own Files/Sessions drill-down (MobileKmsPanel), so the collapse control never renders there. It is also Vault-specific by opt-in: the collapse is driven by a sidebarCollapsible flag on the Vault integration's UI manifest, so the other routed sub-sidebars (Tools, Skills, Alarms, AI Coaching) are unaffected — setting that flag on another integration is the only change needed to make its sub-sidebar collapsible too.
How it's wired (repo detail). The collapse button lives in KmsSubSidebar.tsx (desktop render path only, after the mobile early-return) and sets integrationSidebarHidden. DashboardDesktopLayout.tsx swaps the routed sub-sidebar for the shared SidebarEdgeGutter reopen strip when shouldShowIntegrationReopenGutter(activeIntegration, integrationSidebarHidden) is true (integration-sidebar-collapse.ts; the gutter side follows the sidebarsRight layout). The setting is a flat appearance setting (appearance-settings.ts); the toggleKmsSidebar shortcut (core.keybindings.ts) resolves the active integration via resolveActiveIntegration and no-ops unless it is collapsible. Invariants are locked by integration-sidebar-collapse.test.ts (scope guard — a non-collapsible integration never collapses), KmsSubSidebar-collapse.test.tsx (desktop-only button + toggle), and kms-ui-registry.test.ts (the sidebarCollapsible flag on KMS).
Sorting the file tree
The sort order is chosen from a sort dropdown in the file-tree header (FileTreeSortMenu.tsx); the ordering itself is a pure comparator in tree-builder.ts (compareNodes). Folders always sort above files at the same level regardless of mode; within each group the chosen comparator applies, with the note name as the final stable tiebreak. A folder is synthetic (the Vault has no folder entity — folders are derived from note paths), so it carries no date of its own: for the three time-based sorts each folder takes an aggregate time = the most-recent among the notes it contains (recursively), so the folder group orders by freshest content — the folder you touched most recently rises to the top — instead of collapsing to a name tiebreak. Five modes:
- Name (A→Z) / Name (Z→A) — locale-compared, case-insensitive, numeric-aware.
- Modified — most-recently-edited on top (
updated_at, which mirrors the note file's real on-disk modification time, so the order matches what you'd see in Explorer / the KMS desktop app / Obsidian). Opening a note to read it (no edit) does not move it. - Created — most-recently-created on top (
created_at, the note file's real on-disk creation time). - Recently opened — most-recently-opened on top (
last_opened_atdesc). A note's "opened" time is stamped every time you open it in the editor — including clicking back to an already-open tab — so this answers "what was I just looking at." Notes you've never opened sink to the bottom (alphabetical among themselves), and before you've opened anything in a vault the tree is simply alphabetical (everylast_opened_atis null, so the comparator falls through to name). Restoring your open tabs on app launch does not count as opening — otherwise a relaunch would scramble the order.
There is no manual order and no way to drag a note to a position: a drag changes which folder a note lives in, never its place inside one (see the tree-move contract).
How "Recently opened" is wired (repo detail). The open-note action in kms-store.ts optimistically bumps the in-memory note's lastOpenedAt (so the tree reorders instantly) and fires a fire-and-forget KMS_NOTE_TOUCH_OPENED (kms:note-touch-opened) IPC; its handler (kms-handlers.ts) stamps last_opened_at = <now ISO> on the row via touchNoteOpened (queries-kms/notes.ts). The column lives on nothari_notes (migration 20260620230000-kms-notes-last-opened-at-column), so the opened-time persists across restarts and is shared to the mobile/web client exactly like Modified/Created. The indexer's note-upsert never writes the column, so an external edit or a file-watcher reindex can't wipe an opened-time — regression-locked in queries-kms.test.ts. The sort selection is per-device (localStorage), like every other mode; the opened-times are shared via the DB so the ordering is consistent everywhere.
How "Modified" / "Created" get their dates (repo detail). The indexer derives both timestamps from the file itself, not from the moment Omniscio scanned it: noteTimestampsFromStat(stat, now) in indexer.ts maps the file's mtime → updated_at and birthtime → created_at (read off the same fs.stat the indexer already does for the size check), and upsertNote (queries-kms/notes.ts) writes those through — created_at is write-once unless the indexer supplies the file's birthtime to heal a row. So the two date sorts mirror the real files and survive a reindex (cold start / vault re-open re-derives the same dates). Before this fix the reindex stamped updated_at/created_at with now, so a full rescan collapsed every note to within milliseconds of the scan and the Modified/Created sorts degenerated to directory-walk-then-alphabetical order — most visible on an imported vault, where every note claimed the same "modified" minute. Self-write echoes are unaffected: a recognized autosave echo still re-indexes metadata only and preserves updated_at (it never reaches the time-writing path), so typing doesn't churn the sort — see the KMS self-write echo contract.
How folders get a sort time (repo detail). Folder nodes are built on the fly from note paths in buildTree (tree-builder.ts) with no timestamps of their own. A post-order pass computeFolderTimestamps then rolls each folder's updatedAt / createdAt / lastOpenedAt up to the most-recent value among its descendants (a folder holding only never-opened notes keeps a null opened-time, so it sorts last, just like a never-opened file). Before this, folder nodes carried null timestamps and the three time-based sorts silently fell back to alphabetical for folders while the files beside them reordered by date — now locked by tree-tree.test.ts "folders sort by their freshest contained note".
Adding a note — the tree scrolls to it
Adding a blank page — the + button in the file-tree header, or right-click a row / blank area → New note here — creates an Untitled note, opens it in the editor, and scrolls the file tree to it so you always see where it landed. This matters because the sort (above) decides where a fresh Untitled sorts: under Modified / Created it lands at the top and is already in view, but under Name (A→Z) it sorts down near the bottom, which in a large vault is off-screen — so the tree scrolls it into view. The new page is also highlighted as the open note. If you create the note inside a collapsed folder (right-click that folder → New note here), the folder expands first so the new page is visible. The scroll only happens when the row isn't already visible (no jump when it already is), and it works the same in the mobile notes drawer (which reuses the same file tree). The new note is named as it is created: the new row opens with its name field focused and the name (without .md) selected, so you type the name straight away instead of collecting Untitled notes and renaming each one later — press Enter to keep the name, Escape to keep Untitled. The same naming opens on every route that creates a note (the tree, the tab strip's +, the empty-state New note and the Command Palette). You can also start a new page from the + at the end of the open-tabs strip (on both the desktop and mobile tab strips): it creates the same Untitled note (auto-numbered on repeat) and opens it as a new tab — the tab-bar + does create-and-open only, so the new note is still highlighted in the tree once it appears, but it doesn't force the tree to scroll the way the header + does.
Making a folder. Right-click a folder, a note or the blank area of the file tree → New folder here (the same row is in the touch actions sheet). Type a name and press Create: the folder appears where you right-clicked (inside the folder, beside the note, or at the top level) holding one blank Untitled note, which opens so you can start writing. The folder needs that note because the Vault has no separate folder record — a folder exists while a note lives in it. The dialog refuses a name it cannot use before anything is written: an empty name, a / or \, . or .., a character Windows does not allow (< > : " | ? *), a name ending in a dot, a Windows reserved name such as CON, or a folder that already exists there (ignoring capital letters). Agents can make a folder the same way, by creating a note inside it with POST /kms/notes. The dialog is NewFolderDialog.tsx; the name rules are new-folder-name.ts; pinned by N9 of the KMS new-note contract.
How it's wired (repo detail). On a successful kms:note-create, FileTreePanel.tsx handleNewNote records the handler's resolved path (so an auto-numbered Untitled 2.md is the one revealed), calls expandFolders(ancestorFolders(path)) to open any collapsed ancestors, and sets a revealPath state. Because the new row only enters the tree after the async KMS_NOTE_CHANGED → debounced loadTree reload, a reveal effect watches the flat rows and, once the row appears, calls virtualizer.scrollToIndex(findRowIndex(flat, path), { align: 'auto' }) (align:'auto' = scroll only when off-screen; instant, so no reduced-motion concern). The open-note highlight (KMS_TREE_ROW_ACTIVE) keys on the active tab's notePath (not the tab id), so the just-added page stands out. Pinned by N5/N6 of the KMS new-note contract (FileTreePanel.reveal.test.tsx).
Opening a very large note
A note of several megabytes and tens of thousands of lines opens without freezing the window, however many times the Vault has been opened since Omniscio started. Each editor in the app (the Vault, Writer Studio, meeting notes, the message composer) reads markdown with its own private parser, so one editor never slows another, and the Vault's readers for numbered lists, callouts and task lists read only the lines of the block in front of them. Before this, a 2 MB log note took about 13 seconds per copy of the readers that had piled up on one shared parser, which reached minutes after a day of use. The rules are one-markdown-parser-per-editor and a-block-reader-reads-only-its-block in the markdown serialization contract.
There is a size limit, and it applies to editing, not just opening. The Vault keeps at most the first 5 MB of a note's body. A note between 5 MB and 25 MB still appears in the file list and opens — as the first 5 MB followed by a line reading […note truncated by KMS — exceeds 5 MB body cap. Open the file directly to see the rest.…]. A file larger than 25 MB is skipped by the indexer and never enters the vault at all, so it shows up in neither the file list nor search. Do not edit a truncated note in the Vault: a save from the editor carries only that truncated text, so it either fails outright or writes back the first 5 MB and loses everything after it. Open the file in another editor (Obsidian, VS Code, Notepad) to work on a note that size, then come back — the Vault picks the change up from disk.
When another program changes a note
If another program (a sync tool, Obsidian, an editor) changed the note and the Vault had not noticed yet, saving now stops and asks which version to keep, instead of overwriting. Both versions stay in the note's history — Keep my version writes yours over theirs and keeps the outside text one click away in the note's History panel (where it is), and Load the outside version takes theirs and leaves your unsaved text in the editor. A save that carries no such choice (an AI summary writeback, a rename's link rewrite) still writes, but it copies the text it is about to replace into the note's history first, so nothing another program wrote disappears without a copy. A note the Vault has not fingerprinted yet, and a note whose file was deleted on disk, save exactly as they always did. The check can be switched off in Settings.
Version history keeps the 50 most recent saves of each note and drops the rest. The Vault saves each time there is a pause while typing, so a long editing session can push older versions off within minutes; copy anything you need to keep somewhere other than the history.
Troubleshooting: a note is missing, or an outside edit never appears
The Vault indexes every .md file it can reach, and the watcher reports outside edits as they happen — but four things make it skip quietly, and none of them shows anything on screen:
- Symlinked files and folders inside the vault are not followed. Only the vault ROOT must be a real folder, but a shortcut/symlink inside it is skipped. Move the real folder into the vault instead.
- A folder the app cannot open is skipped. Antivirus locks, permissions and cloud-sync placeholders all do this. The notes in it keep their place in the tree, and the Vault reports itself as unhealthy instead of silently dropping them — the folder is named by a short reference in the log, never by its real name.
- A note over 25 MB is skipped. That is far beyond any real note; split the file if you need it indexed.
- On a network share or a cloud-sync folder the per-folder watch can fail. Edits then appear at the next rescan (every 10 minutes) or the next app start rather than instantly.
To check what the Vault thinks: open Settings → Features → Show advanced → The Vault and read the folder's health. An agent can read the same thing with GET /kms/vault/health (IPC kms:health) and should relay its health and lastError to you. To force a full rescan, pick the vault folder again in that same card.
Troubleshooting: Not saved will not clear
A Not saved mark — an error triangle on the tab and a chip in the status bar — clears by itself the next time the editor matches disk. It is not a warning about your text: the changes are kept on this computer and survive a close or crash (the draft heartbeat is described under crash recovery in KMS — mobile, sync and internals). The usual reasons it keeps coming back are a full disk, antivirus or a sync client holding the file past the retry, folder permissions that stop the write, and a vault folder on a drive that is disconnected or asleep.
To clear it: copy the text somewhere safe, check the vault folder really is reachable and writable in Explorer, free some space or pause the sync client, then type one character and let autosave run again. If the folder is gone, point the Vault at its new location in Settings → Features → Show advanced → The Vault.
Related
The editor's own details — its toolbar, slash commands, tables, footnotes, syntax highlighting and the rest — are on The Vault — the editor. Appearance and finding things are on The Vault — appearance and search; images and links on The Vault — images, media and links; the AI features, extra windows and publishing on The Vault — AI, windows and sharing; and mobile, crash recovery and the internals on The Vault — mobile, sync and internals.
- The Vault Overview — a searchable/sortable inventory table of every note, with
GET /kms/inventoryserving the same rows to agents — is documented at kms-vault-overview.md.
Last verified 2026-11-14