Stellavault

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

[](#mcp-integration-21-tools) [](https://www.npmjs.com/package/stellavault) [](https://github.com/Evanciel/stellavault/actions/workflows/ci.yml) []() []() [](LICENSE)

English · [한국어](README.ko.md) · [日本語](README.ja.md) · [简体中文](README.zh.md)

[🤖 Add to Claude / Cursor](#mcp-integration-21-tools) · ⬇ Desktop App · [⚡ Quickstart](#install) · 🌐 Live Demo

> One command to let Claude read your vault: > > ``bash > npx -y stellavault setup # wires the MCP server into Claude Code / Desktop, Cursor, Windsurf, or VS Code > ``

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](#highlights) · [Why Stellavault?](#why-stellavault) · [Install](#install) · [Editor](#editor) · [Pipeline](#the-pipeline) · [Intelligence](#intelligence-what-makes-stellavault-unique) · [Search & Ranking](#search--ranking) · [MCP Integration](#mcp-integration-21-tools) · [3D Visualization](#3d-visualization) · [Configuration](#configuration) · [Performance](#performance) · [Tech Stack](#tech-stack) · [Security](#security) · [Troubleshooting](#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 coloring, constellations, heatmaps, a timeline, and a multiverse P2P view. 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)

⬇ Download for Windowsx64 · 273 MB · ZIP ⬇ Download for Linuxx64 · 243 MB · ZIP macOSComing soon

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

Full formatting & block support — tables, code, KaTeX, slash commands, wikilinks, split view… (click to expand)

| 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](#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

Manual config (any MCP client) — copy-paste JSON

{
  "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](#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.

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)

| 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 va

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Evanciel
• Source: Evanciel/stellavault
• License: MIT
• Homepage: https://www.npmjs.com/package/stellavault

Install and usage instructions live in the source repository linked above.