Vault Kosmos

A local-first 3D space for flying through Obsidian-compatible Markdown vaults.

Vault Kosmos turns a folder of Markdown notes into a calm spatial constellation. It reads your vault locally, maps folders and links in 3D, and lets you fly through the structure of your own notes.

Open the static demo · Use local connector mode · Read the media kit

Distant approach	Link structure	Cluster flight

Download the 38-second MP4 teaser

Public alpha: polished enough to explore, intentionally still experimental.

Why It Exists

Because it is beautiful to move through your own vault.

Vault Kosmos is not trying to prove that every thought must become a dashboard, metric, or productivity system. The point is simpler: a Markdown vault can feel like a place. Folders become regions, notes become landmarks, links become paths, and the familiar structure of your own writing suddenly has depth.

It is built for people who use Obsidian or plain Markdown and want the quiet pleasure of experiencing their notes as a three-dimensional landscape without sending them to a cloud service.

Cinematic Flight

The GIFs above are short excerpts from a frame-by-frame cinematic export from the real Vault Kosmos renderer: distant approach, orbit, readable link structure, cluster flight, and exit into the title card.

It is meant as a quick visual proof of the core idea: your Markdown vault is not only searchable. It can become a navigable knowledge space.

What You Can Do

• Fly through files, folders, Wikilinks, Markdown links, unresolved links, tags, status, type, and selected frontmatter relations.
• Watch local file changes appear as pulses in the graph and timeline.
• Move between overview, focus, depth, and free-flight modes.
• Use a static public demo without installing anything.
• Connect a private local vault through the Node connector when running on your own machine.
• Keep vault content local: no telemetry, no cloud indexing, no automatic writes to your notes.

Quick Start

Requirements:

• Node.js 24 or newer
• npm

git clone https://github.com/H4R7W16/vault-kosmos.git
cd vault-kosmos
npm install
cp vault-kosmos.config.example.json vault-kosmos.config.json
npm run dev

Open:

• App: http://127.0.0.1:5173
• API: http://127.0.0.1:8787

The example config points to ./example-vault. On startup, choose a local vault folder with the vault picker or continue with the configured demo vault.

Use Your Own Vault

Either edit vault-kosmos.config.json:

{
  "vaultPath": "D:/Obsidian/MyVault"
}

or start the app and use Choose Vault... in the startup dialog or Vault panel.

Relative paths are resolved from the app folder. Absolute paths work too.

Privacy Model

Vault Kosmos is local-first by design.

• Vault content is read on your machine.
• Runtime history is written to .runtime/events.ndjson inside the app folder.
• The app does not write notes into the vault.
• The app does not send vault content to an external service.
• The app does not request camera access.

The hosted GitHub Pages version uses a curated static demo vault. It cannot read a private local folder unless you explicitly run the local connector and open ?local=1.

Capture And Media Mode

The public demo has deterministic capture presets for screenshots and videos:

• ?demo=1&capture=hero
• ?demo=1&capture=focus
• ?demo=1&capture=timeline
• ?demo=1&capture=privacy
• ?demo=1&capture=trailer

These modes use only public demo graphs and fixed timestamps. The trailer preset runs a scripted app flight through a dedicated showcase vault, opening the relevant windows as the route moves from note to note.

Scripts

npm run dev       # backend + frontend
npm test          # parser, indexer and watcher tests
npm run build     # type-check and production build

Media production lives in media/ and is intentionally isolated from the app dependencies.

API

• GET /api/config
• PUT /api/config
• POST /api/reload
• GET /api/graph
• GET /api/events?limit=200
• WS /ws

What Gets Indexed

• Markdown files and folders
• Obsidian Wikilinks: [[Note]], [[Folder/Note|Alias]], [[Note#Heading]]
• Local Markdown links
• YAML frontmatter
• Tags and aliases
• Relation-like properties: related, depends_on, blocks, initiative, project, repo, source

Malformed frontmatter is tolerated: the file still appears in the graph while invalid properties are skipped.

Current Alpha / Next

Current alpha:

• Local web app, not an Obsidian plugin.
• Static public demo and local connector mode.
• Stable depth cues, focus flights, timeline, filters, and mini-map.

Next:

• Link level-of-detail for very large vaults.
• Better route-based presentation mode.
• More deliberate clustering and graph performance work.
• Exportable media presets for documentation and publishing.

Contributing

Issues and focused pull requests are welcome. Start with CONTRIBUTING.md, keep the local-first privacy model intact, and avoid adding services that would move vault content out of the user's machine.

License

MIT