# stellavault [Health: Active]
**Category:** ๐ง Knowledge & Memory
**Repository:** https://github.com/Evanciel/stellavault
**GitHub Stars:** 3
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/stellavault
## Description
Local-first MCP server: Claude searches, asks & drafts from your Obsidian vault. 21 tools, no keys.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"stellavault": {
"command": "npx",
"args": ["-y","stellavault"]
}
}
```
## Documentation & README
**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)
> [!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 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:
```bash
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:
```bash
# 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](SECURITY.md) for full details.
## Troubleshooting
```bash
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](CONTRIBUTING.md) to get started, and [SECURITY.md](SECURITY.md) to report a vulnerability responsibly.
## License
MIT โ full source code available for audit.
## Links
- **[โฌ Download Desktop App](https://github.com/Evanciel/stellavault/releases/tag/desktop-v0.3.0)**
- [Landing Page](https://evanciel.github.io/stellavault/)
- [Obsidian Plugin](https://github.com/Evanciel/stellavault-obsidian)
- [npm](https://www.npmjs.com/package/stellavault)
- [GitHub Releases](https://github.com/Evanciel/stellavault/releases)
- [Security Policy](SECURITY.md)
---
**Found this useful?** โญ [**Star Stellavault**](https://github.com/Evanciel/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