Stellavault README

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:

Terminal

Copy

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:

Code

Copy

/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.

Your vault as a neural network. Local-first, no cloud required.

Contents

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.

[!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

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

Editor

Full-featured markdown editor — on par with Obsidian.

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

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.

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:

• 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"]
    }
  }
}

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).

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):

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.

Heatmap — connection density across clusters	Timeline — watch your vault grow over time
Search — semantic matches highlighted in-graph	Multiverse — federated vaults as orbiting universes

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

1. Download → Unzip → Run
2. First launch asks you to pick your notes folder
3. Your notes appear in the sidebar — click to open
4. Press Ctrl+P for quick file switching
5. Click ✦ in the title bar for AI panel (semantic search, stats, draft)
6. 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)

Quick Reference

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):

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:

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

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

• ⬇ Download Desktop App
• Landing Page
• Obsidian Plugin
• npm
• GitHub Releases
• Security Policy