Stellavault
Evanciel/stellavault
Segundo cérebro local que Claude entende — grafo neural 3D + busca híbrida
Ver no GitHubServidor MCP que transforma seu acervo de notas em um segundo cérebro inteligente e compilável. Combina grafo de conhecimento 3D, busca semântica híbrida, rastreamento de decaimento de memória e federação P2P — tudo local, sem APIs externas. Integra-se nativamente com Claude através de 21+ ferramentas MCP.
Instalação
npx convez-ai Evanciel/stellavault1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir e navegar grafos de conhecimento pessoal com IA
- Busca semântica inteligente em arquivos Markdown e PDFs
- Integrar Claude como agente leitor de vault com memória contextual
- Zettelkasten moderno com compilação automática de conceitos
Veredito

Stellavault é uma ferramenta ambiciosa que resolve um problema real: notas espalhadas perdem valor. A compilação automática, grafo 3D e integração MCP são inovações legítimas, embora a curva de aprendizado seja íngreme. Recomendado para quem já usa Zettelkasten ou buscas semânticas e quer ecossistema local robusto com Claude.
README
A tradução para o português deste README ainda está na fila.
The local-first second brain that Claude remembers. Karpathy's self-compiling wiki × Zettelkasten — fully local, vault-safe, and MCP-native.
⬇ Download Desktop App · ⚡ Quickstart · 🤖 MCP Setup · 🌐 Live Demo
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.
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]]/#tagswith 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)
[!TIP] Download → Unzip → Run
stellavault.exe(Windows) orstellavault(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 doctorto diagnose issues.
Obsidian Plugin
- Download
main.js+manifest.json+styles.cssfrom stellavault-obsidian releases - Place in
.obsidian/plugins/stellavault/ - Enable in Settings → Community plugins
- Start API:
npx stellavault graphin 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
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)
- 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
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+Pfor 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 —
entityAliasesis 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.1only 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.jsonfiles are not auto-downgraded to the safer defaults; review yourmyNodeLevelif 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