# Stellavault

> Notes die in folders. Stellavault keeps your knowledge alive — 3D knowledge graph, AI semantic search, memory decay tracking, P2P federation, 17+ MCP tools. npm i -g stellavault

- **Type:** MCP server
- **Install:** `agentstack add mcp-evanciel-stellavault`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Evanciel](https://agentstack.voostack.com/s/evanciel)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.8.5
- **License:** MIT
- **Upstream author:** [Evanciel](https://github.com/Evanciel)
- **Source:** https://github.com/Evanciel/stellavault
- **Website:** https://www.npmjs.com/package/stellavault

## Install

```sh
agentstack add mcp-evanciel-stellavault
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

**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**](https://github.com/Evanciel/stellavault/releases/tag/desktop-v0.3.0) · [**⚡ Quickstart**](#install) · [**🌐 Live Demo**](https://evanciel.github.io/stellavault/)

> **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](https://github.com/Evanciel/stellavault-obsidian). 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)

```bash
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](https://github.com/Evanciel/stellavault-obsidian/releases/latest)
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

```bash
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)

```bash
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

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

Listed on the [MCP registry](https://registry.modelcontextprotocol.io) 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)

```bash
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

```bash
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:

```jsonc
{
  "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](https://github.com/Evanciel)
- **Source:** [Evanciel/stellavault](https://github.com/Evanciel/stellavault)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/stellavault

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.8.5 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.8.5** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-evanciel-stellavault
- Seller: https://agentstack.voostack.com/s/evanciel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.