How do I install Stellavault?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Stellavault need an API key?

The publisher lists these environment variables: STELLAVAULT_DB_PATH.

What transport does Stellavault use?

Stellavault runs locally over stdio.

When was Stellavault last checked?

Last checked 2026-11-09. Local-first MCP server: Claude searches, asks & drafts from your Obsidian vault. 21 tools, no keys.

Stellavault MCP server

The local-first second brain that Claude remembers. Karpathy's self-compiling wiki × Zettelkasten — fully local, vault-safe, and MCP-native.

English · 한국어 · 日本語 · 简体中文

🤖 Add to Claude / Cursor · ⬇ Desktop App · ⚡ Quickstart · 🌐 Live Demo

One command to let Claude read your vault:
npx -y stellavault setup    # wires the MCP server into Claude Code / Desktop, Cursor, Windsurf, or VS Code
Claude Code user? Install the plugin instead — the MCP server plus /vault-ask, /vault-review, /vault-decision skills, in two commands:
/plugin marketplace add Evanciel/stellavault
/plugin install stellavault@stellavault

A second brain that compiles itself. Stellavault fuses two ideas about how knowledge should live and grow:

🧠 Karpathy's self-compiling wiki — drop in anything (a PDF, a YouTube link, a passing thought) and it's auto-extracted into raw/, then compiled into a clean _wiki/ of concepts and backlinks. Your knowledge re-compiles itself as it grows, instead of rotting in a folder.
🕸️ Zettelkasten — atomic notes, [[wikilinks]], and emergent connections, so a web of ideas (not a folder tree) becomes the real structure of how you think.

The result is one local-first knowledge tool — a full markdown editor, a 3D neural graph, hybrid AI search, and spaced-repetition memory decay — shipped as a desktop app, CLI, Obsidian plugin, and MCP server that lets Claude read your entire vault. No cloud, no API keys, and your original files are never modified.

Highlights · Why Stellavault? · Install · Editor · Pipeline · Intelligence · Search & Ranking · MCP Integration · 3D Visualization · Configuration · Performance · Tech Stack · Security · Troubleshooting

Highlights

🧠 It compiles itself. Drop in a PDF, a YouTube link, or a half-formed thought — Stellavault extracts it to raw/, then compiles a clean _wiki/ with concepts and backlinks. Knowledge that organizes itself as it grows.
🔍 Search that actually finds it. Hybrid retrieval fuses semantic meaning, exact keywords (BM25), and your own [[wikilinks]] / #tags with weighted RRF, then re-ranks by an FSRS memory model so what you're actually using resurfaces. 50+ languages, fully local, zero API keys.
🌌 Your mind, in 3D. A real-time neural graph (React Three Fiber) — cluster view with folder drilldown, per-note local graphs, tag overlays, and two-class edges that keep your wikilinks visually distinct from AI-inferred similarity. Scales to a full 17k-note vault. A way to see the shape of what you know.
🤖 Claude reads your entire vault. A first-class MCP server (21 tools): Claude can search, ask, draft, lint, and analyze your knowledge from Claude Code, Claude Desktop, Cursor, Windsurf, or VS Code.
⏳ It never silently forgets. FSRS memory decay surfaces the real notes you're about to lose — plus gap, contradiction, and duplicate detection across the whole vault.
🔒 Local-first. Vault-safe. Zero keys. Local embeddings, an on-device vector store, and your original files are never modified. Nothing leaves your machine unless you opt in.

Why Stellavault?

Most tools make you choose between writing, searching, and remembering. Stellavault does all three — locally, and in a way Claude can read.

	Stellavault	Obsidian	Notion	Plain RAG script
Local-first, works offline	✅	✅	☁️ cloud	⚠️ usually cloud
Semantic search, no API key	✅	⚠️ plugin + key	💰 paid AI	⚠️ needs key
Original files never modified	✅	✅	❌ proprietary	➖
Self-compiling (ingest → wiki)	✅	❌	❌	❌
3D knowledge graph	✅	2D / plugin	❌	❌
Spaced-repetition decay (FSRS)	✅	⚠️ plugin	❌	❌
Gap / contradiction / dup detection	✅	❌	❌	❌
MCP-native (Claude reads your vault)	✅	➖ community	☁️ cloud	➖

[!NOTE] Not either/or — Stellavault even runs inside Obsidian as a plugin. Keep your editor; add a brain.

Install

Desktop App (Recommended — one click)

[!TIP] Download → Unzip → Run stellavault.exe (Windows) or stellavault (Linux) → Pick your notes folder → Done.

CLI (for developers)

npm install -g stellavault    # or: npx stellavault
stellavault init              # Interactive setup (3 min): index vault + connect AI clients
stellavault setup             # Connect to Claude Code/Desktop, Cursor, Windsurf, VS Code (one command)
stellavault graph             # Launch 3D graph in browser

Requires Node.js 20+. Run stellavault doctor to diagnose issues.

Obsidian Plugin

Download main.js + manifest.json + styles.css from stellavault-obsidian releases
Place in .obsidian/plugins/stellavault/
Enable in Settings → Community plugins
Start API: npx stellavault graph in your vault folder

Editor

Full-featured markdown editor — on par with Obsidian.

Feature	Status
Bold, Italic, Underline, Strikethrough	✅
Headings 1–6	✅
Bullet, Numbered, Task lists (nested checkboxes)	✅
Tables (create, resize columns, add/remove rows & cols)	✅
Code blocks with syntax highlighting (40+ languages)	✅
Images (URL, clipboard paste, drag & drop)	✅
KaTeX math rendering ( $E=mc^2$ inline, `$$...$$` display)	✅
`/Slash commands` (12 block types, fuzzy search)	✅
`[[Wikilink]]` autocomplete	✅
Split view (vertical + horizontal, Ctrl+\)	✅
Text alignment (left / center / right)	✅
Highlight, Superscript, Subscript	✅
Smart typography (curly quotes, em/en dashes)	✅
Horizontal rules	✅

The Pipeline

Capture ──→ Organize ──→ Distill ──→ Express

Drop anything → auto-extract → raw/ → compile → _wiki/ → draft

Inspired by Karpathy's self-compiling knowledge architecture.

Ingest 14 Formats

Input	How
PDF, DOCX, PPTX, XLSX	`stellavault ingest report.pdf`
JSON, CSV, XML, YAML, HTML, RTF	`stellavault ingest data.json`
YouTube	`stellavault ingest https://youtu.be/...` — transcript + timestamps
URL	`stellavault ingest https://...` — HTML → markdown
Text	`stellavault ingest "quick thought"`
Folder	`stellavault ingest ./papers/` — batch all files
Desktop / Web UI	Drag & drop files directly

Express: Get Knowledge Out

stellavault draft "AI" --format blog      # Blog post from your vault
stellavault draft "AI" --format outline   # Structured outline
stellavault draft "AI" --ai              # Claude API enhanced ($0.03)

Or use the Express tab in the desktop app — enter a topic, pick a format, and generate a draft grounded in your vault. Save to _drafts/ and edit inline.

Intelligence (What Makes Stellavault Unique)

These features do not exist in Obsidian — even with plugins.

Feature	Command / Desktop	Description
Memory Decay	`stellavault decay` / Memory tab	FSRS-based — shows which real notes you are forgetting
Knowledge Gaps	`stellavault gaps`	Detects weak connections between topic clusters
Contradictions	`stellavault contradictions`	Finds conflicting statements across your vault
Duplicates	`stellavault duplicates`	Near-identical notes with similarity score
Health Check	`stellavault lint`	Aggregated vault health score (0–100)
Learning Path	`stellavault learn`	AI-personalized review recommendations
Daily Brief	Desktop app home screen	Push-type: top decaying notes + stats on app open
Auto-Tagging	Automatic on ingest	Content-based keyword extraction + category rules
Self-Compiling	`stellavault compile`	raw/ → _wiki/ with extracted concepts + backlinks

Search & Ranking

Hybrid retrieval that fuses multiple signals with weighted Reciprocal Rank Fusion (RRF) — tuned for a personal knowledge vault, fully local, zero API keys:

Signal	What it captures	Default weight
Semantic (dense)	meaning; multilingual (50+ languages)	`1.0`
BM25 (keyword)	exact terms, code, names	`1.0`
Entity-linking	your `[[wikilinks]]`, `#tags`, headings, titles — the curated graph	`1.5`
FSRS recency	gently surfaces notes you're actively using / forgetting	`±10%`

Entity matching resolves natural-language queries via fuzzy substring + punctuation-normalized matching (Korean / CJK friendly), with a per-document diversity cap so one large note can't flood the top results.
Recency reuses the same FSRS memory model as the decay engine (not raw file mtime) — a note you're forgetting resurfaces; a mastered evergreen note isn't buried just for being old.
Adaptive rerank (long-running MCP server) further boosts results by your current session context (recent tags / paths).
Every weight is tunable per vault or via env vars — see Configuration.

MCP Integration (21 Tools)

stellavault setup            # one command → Claude Code, Claude Desktop, Cursor, Windsurf, VS Code
# or, for Claude Code only:
claude mcp add stellavault -- stellavault serve

{
  "mcpServers": {
    "stellavault": {
      "command": "npx",
      "args": ["-y", "stellavault", "serve"]
    }
  }
}

Listed on the MCP registry as io.github.Evanciel/stellavault (also discoverable via Glama, Smithery, and mcp.so).

Claude can search, ask, draft, lint, and analyze your vault directly. Search runs the full hybrid pipeline — weighted RRF over semantic + BM25 + entity-linking, plus FSRS recency and session-adaptive reranking (see Search & Ranking).

Tool	What it does
`search`	Weighted RRF (semantic + BM25 + entity) + FSRS recency + adaptive rerank
`ask`	Vault-grounded Q&A
`generate-draft`	AI drafts from your knowledge
`get-decay-status`	Memory decay report (FSRS)
`detect-gaps`	Knowledge gap analysis
`create-knowledge-node`	AI creates wiki-quality notes
`federated-search`	P2P search across vaults
+ 14 more	Documents, topics, decisions, snapshots, export

3D Visualization

Neural graph with cluster coloring (React Three Fiber)
Cluster view (default) — a large vault folds into a small galaxy of labeled cluster super-nodes; an in-viewer [Cluster | All nodes] toggle switches to the dense raw view without reload, and clicking a super-node drills into that cluster's members
Constellation view (MST star patterns)
Heatmap overlay + Timeline slider + Decay overlay
Multiverse view — your vault as a universe in a P2P network
Dark/Light theme

Graph viewer scaling

The 3D graph renderer is bounded by two environment knobs (set them in the environment before launching stellavault graph):

Env var	Default	Applies to	What it caps
`GRAPH_NODE_CAP`	`1500`	raw / "All nodes" view	# of (most-recent) notes rendered as individual nodes.
`GRAPH_CLUSTER_CAP`	`3000`	cluster view (default)	# of notes folded into the galaxy before clustering.

Why the caps matter. Edge construction is an inline O(n²) all-pairs cosine loop — n·(n-1)/2 pairs, each over 384 dims (see packages/core/src/api/graph-data.ts, the neighbors loop). At cap=3000 that is ~4.5M pairs (the multi-second build the 5-minute server cache absorbs); raising toward 13000 is ~84M pairs = minutes of build plus a multi-GB intermediate array that freezes the single-threaded Express handler (there is no worker). The raw "All nodes" path is the expensive direction (it runs the full cap), so the server clamps the requested ?cap per view (raw ≤ 4000, cluster ≤ 6000, rounded) to bound both build cost and cache cardinality.

Even the default cluster view is cheap to RENDER, not to BUILD. The first uncached fetch of either view runs the scoped-embedding load + the O(n²) cosine pass + k-means + a force settle on a single thread, stalling the handler for seconds. The viewer shows a loading state on the toggle so the tap isn't silently swallowed during that cold build.

Try It Now (Demo Vault)

npx stellavault index --vault ./examples/demo-vault   # Index 10 sample notes
npx stellavault search "vector database"               # Semantic search
npx stellavault graph                                  # 3D graph visualization

The demo vault includes interconnected notes about Vector Databases, Knowledge Graphs, Spaced Repetition, RAG, MCP, and more — perfect for exploring all features instantly.

Getting Started Guide

Desktop App

Download → Unzip → Run
First launch asks you to pick your notes folder
Your notes appear in the sidebar — click to open
Press Ctrl+P for quick file switching
Click ✦ in the title bar for AI panel (semantic search, stats, draft)
Click ◉ for 3D graph

CLI

npm install -g stellavault
stellavault init                          # Setup wizard
stellavault search "machine learning"     # Semantic search
stellavault ingest paper.pdf              # Add knowledge
stellavault graph                         # 3D graph in browser
stellavault brief                         # Morning briefing
stellavault decay                         # What are you forgetting?

Keyboard Shortcuts (Desktop)

Shortcut	Action
`Ctrl+P`	Quick Switcher (fuzzy file search)
`Ctrl+Shift+P`	Command Palette (all actions)
`Ctrl+S`	Save current note
`Ctrl+\`	Toggle split view
`Ctrl+B`	Bold
`Ctrl+I`	Italic
`Ctrl+U`	Underline
`Ctrl+E`	Inline code
`/`	Slash commands (at start of line)
`[[`	Wikilink autocomplete

Quick Reference

Action	Desktop	CLI
Search notes	Ctrl+P or AI panel	`stellavault search "query"`
Add a note	+ Note button or drag & drop	`stellavault ingest "text"`
See 3D graph	◉ button	`stellavault graph`
Memory decay	AI panel → Memory	`stellavault decay`
Generate draft	AI panel → Draft	`stellavault draft "topic"`
Health check	AI panel → Stats	`stellavault lint`

Configuration

Stellavault reads ./.stellavault.json (or ~/.stellavault.json). Search ranking is fully tunable — sensible defaults work out of the box:

{
  "search": {
    "rrfK": 60,
    "weights": { "semantic": 1.0, "bm25": 1.0, "entity": 1.5 },
    "recencyWeight": 0.2,                          // FSRS recency strength; 0 = off
    "entityAliases": { "k8s": ["kubernetes"] }     // synonym / cross-lingual groups (exact-only)
  }
}

Environment variables override config (parsed with guards):

Env var	Effect
`STELLAVAULT_W_SEMANTIC` / `_BM25` / `_ENTITY`	per-signal RRF weight (e.g. `STELLAVAULT_W_ENTITY=2.0` for aggressive entity surfacing)
`STELLAVAULT_RECENCY_WEIGHT`	recency strength `0`–`1` (`0` disables)
`STELLAVAULT_DB_PATH`	override the index DB location
`STELLAVAULT_WATCH`	`0` to disable the auto-reindex file watcher while `serve` runs

Note: cross-lingual recall (e.g. a Korean query finding English notes) is handled automatically by the multilingual embedding model — entityAliases is an optional precision boost for the curated entity graph (tags / wikilinks) and abbreviations.

Performance

Tested on synthetic vaults — all operations under 1 second for typical use cases:

Operation	100 docs	500 docs	1000 docs
Store init	15ms	15ms	16ms
Bulk upsert	12ms	102ms	~200ms
Search (BM25)	<1ms	<1ms	<1ms
Get all docs	<1ms	2ms	~4ms
124K dot products	—	36ms	—

Run your own benchmarks:

node tests/stress.mjs 500     # Test with 500 synthetic documents

Key optimizations:

HNSW graph building — sqlite-vec KNN for 200+ docs (O(n·K·log n) vs O(n²))
Pre-normalized vectors: cosine similarity → single dot product
Batched embedding loading (500/batch, prevents RAM overflow)
Upper-triangle brute-force for small vaults (< 200 docs)
O(n) K-Means centroid updates with typed arrays

Tech Stack

Layer	Tech
Desktop	Electron + React + TipTap (15 extensions) + Zustand
Runtime	Node.js 20+ (ESM, TypeScript)
Vector Store	SQLite-vec (local, zero config)
Embedding	MiniLM-L12-v2 (local, 50+ languages, batch processing)
Search	Weighted RRF (semantic + BM25 + entity) + FSRS recency
Math	KaTeX (inline + display)
Code	lowlight / highlight.js (40+ languages)
3D	React Three Fiber + Three.js
AI	MCP (21 tools) + Anthropic SDK
P2P	Hyperswarm (optional, differential privacy)
CI	GitHub Actions (Node 20 + 22)

Security

Local-first — no data leaves your machine unless you use --ai
Vault files never modified — indexes into SQLite, originals untouched
Electron sandbox enabled — renderer runs with reduced OS privileges
IPC path validation — all file operations stay inside vault root
API auth token — per-session, header-only (X-Stellavault-Token). Token endpoint is same-origin-only
CORS allow-list — localhost / 127.0.0.1 only by default; MCP HTTP transport opt-in
SSRF protection — private IPs blocked on URL ingest
E2E encryption — AES-256-GCM for cloud sync

Federation (experimental, off by default)

Peer-to-peer semantic search is shipped as an opt-in experimental feature. The default install does not join any swarm and never shares data.

Enable explicitly:

# PowerShell
$env:STELLAVAULT_FEDERATION_EXPERIMENTAL = "1"

# bash / zsh
export STELLAVAULT_FEDERATION_EXPERIMENTAL=1

stellavault federate join

When enabled, federation uses Ed25519 identities with signed envelopes, mutual challenge-response handshake, per-envelope replay nonces, handshake timeout, per-peer rate limiting, and a receive-only sharing default (myNodeLevel=0). Run set-level 1+ in the federation prompt to actually share titles/snippets with peers.

[!WARNING] Upgrade note (v0.7.4) — federation wire format bumped from v2.0 to v2.1 (envelope-level nonce). v0.7.3 federation nodes are not compatible. Existing ~/.stellavault/federation/sharing.json files are not auto-downgraded to the safer defaults; review your myNodeLevel if you previously opted in.

See SECURITY.md for full details.

Troubleshooting

stellavault doctor    # Check config, vault, DB, model, Node version

Common issues:

"Command not found" → npm i -g stellavault@latest
"API server not found" → npx stellavault graph
Empty graph → stellavault index
Slow first run → AI model downloads ~30MB once

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md to get started, and SECURITY.md to report a vulnerability responsibly.

License

MIT — full source code available for audit.

Links

Found this useful? ⭐ Star Stellavault — it genuinely helps the project reach more people who think in connected notes.

Built with ✦ for second-brain builders. · Download · Connect Claude · Report an issue