stellavault 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.4.2] - 2026-04-07
+
+### Features — Karpathy Architecture Complete
+- **Session Hooks** — `stellavault session-save`: auto-capture session summaries to daily logs
+  - Pipe via stdin or --summary flag
+  - Creates `raw/_daily-logs/daily-log-YYYY-MM-DD.md`
+  - Auto-compiles wiki after save
+  - Works with Claude Code hooks (PreCompact, Stop)
+- **Flush Process** — `stellavault flush`: daily logs → wiki compilation
+  - Extracts concepts and connections from all daily logs
+  - Rebuilds wiki index with backlinks
+  - Karpathy's "source code → executable" compilation
+- **Wikilink Auto-Connect** — Auto-insert [[wikilinks]] matching existing note titles on ingest
+- **Hooks Setup Guide** — `docs/hooks-setup.md` with Claude Code settings.json config
+
+### The Compounding Loop
+```
+Session → session-save → daily-log → flush → wiki
+  ↑                                            ↓
+  └── Claude reads wiki via MCP for better answers ←┘
+```
+
+## [0.4.1] - 2026-04-07
+
+### Features
+- **Binary File Ingest** — PDF (unpdf), DOCX (mammoth), PPTX (officeparser), XLSX (SheetJS) text extraction
+- **Auto Pipeline** — `ingest` now auto-runs `compile` → wiki generated automatically
+- **Web File Upload** — Drag & drop files in browser (POST /api/ingest/file, 50MB limit)
+- **Mobile/PWA** — Responsive IngestPanel, service worker registration, installable as app
+- **Express: stellavault draft** — Generate blog/report/outline from vault knowledge
+- **MCP generate-draft** — 20th MCP tool: Claude writes drafts using vault context (free in Claude Code)
+- **CLI --ai flag** — `stellavault draft --ai` uses Claude API for full AI-generated drafts
+- **Configurable folders** — Override raw/_wiki/_literature/ in .stellavault.json
+- **Multilingual embeddings** — paraphrase-multilingual-MiniLM-L12-v2 (50+ languages)
+
+### Changes
+- Binary files default to fleeting stage (Zettelkasten principle: all inputs start as fleeting)
+- Repositioned as "Self-compiling knowledge MCP server"
+- .npmignore excludes PDF (was 16MB in npm package)
+- MCP tools: 19 → 20
+
+### Fixes
+- CLI YouTube ingest now properly calls extractYouTubeContent
+- officeparser type cast fix (OfficeParserAST → string)
+- unpdf text array handling (pages returned as array, not string)
+
 ## [0.4.0] - 2026-04-06
 
 ### Features

package/README.md

@@ -1,124 +1,89 @@
 # Stellavault
 
-> **Notes die in folders. Stellavault keeps your knowledge alive.**
+> **Self-compiling knowledge MCP server** — ingest anything, auto-organize into Zettelkasten wiki, and let Claude access your entire knowledge base.
 
-Your Obsidian vault is more than files — it's a living network. Stellavault turns it into a self-compiling knowledge system that **discovers hidden connections**, **tracks fading memories**, **finds blind spots**, and **gives AI agents direct access to everything you know**.
+Drop a PDF, paste a YouTube link, type a thought — Stellavault compiles it into structured knowledge, connects the dots, and gives your AI agent full access through 20 MCP tools.
 
 <p align="center">
   <img src="images/screenshots/graph-dark-full.png" alt="3D Knowledge Graph" width="800" />
   <br><em>Your vault as a neural network. Clusters form constellations.</em>
 </p>
 
-## Why Stellavault?
+## Two Core Ideas
 
-| Problem | Stellavault Solution |
-|---------|---------------------|
-| Notes pile up but never become knowledge | **Self-compiling wiki** — raw notes auto-organized into linked concepts |
-| You forget what you wrote | **FSRS decay tracking** — see what's fading, get review suggestions |
-| Search finds words, not meaning | **Hybrid AI search** — BM25 + vector + RRF fusion, locally |
-| AI agents can't access your knowledge | **17 MCP tools** — Claude remembers everything you know |
-| No way to see the big picture | **3D neural graph** — constellations, heatmaps, timeline |
-
-## 5-Minute Setup
-
-```bash
-# Install
-npm install -g stellavault
-
-# Interactive setup (indexes your vault + verifies search)
-stellavault init
-
-# Launch 3D graph + API server
-stellavault graph
+**1. "Drop it and forget it"** (Karpathy's Self-Compiling Knowledge)
 ```
+Any input → auto-classify → raw/ → compile → wiki → connected knowledge
+```
+PDF, DOCX, YouTube, URL, text — everything goes through the same pipeline. You never manually organize.
 
-> **Prerequisites**: Node.js 20+ (`node --version`)
-
-## Give Your AI Agent Memory
-
+**2. "Claude knows what you know"** (MCP Integration)
 ```bash
 claude mcp add stellavault -- stellavault serve
 ```
+20 MCP tools give Claude direct access to search, ask, draft, and navigate your entire knowledge base.
 
-Now Claude Code can search your notes, track decisions, detect knowledge gaps, and generate daily briefings — using 17 MCP tools.
+## 5-Minute Setup
 
-## Screenshots
+```bash
+npm install -g stellavault
+stellavault init          # Interactive setup + vault indexing
+stellavault graph         # Launch 3D graph + API server
+```
 
-<p align="center">
-  <img src="images/screenshots/graph-search-highlight.png" alt="Semantic Search" width="800" />
-  <br><em>Search by meaning. Matching nodes pulse and glow.</em>
-</p>
+> **Prerequisites**: Node.js 20+
 
-<details>
-<summary>More screenshots</summary>
+## The Pipeline
 
-| Light Mode | Timeline Slider | Heatmap |
-|:---:|:---:|:---:|
-| <img src="images/screenshots/graph-light-mode.png" width="260" /> | <img src="images/screenshots/graph-timeline.png" width="260" /> | <img src="images/screenshots/graph-heatmap.png" width="260" /> |
+```
+Capture ──→ Organize ──→ Distill ──→ Express
 
-</details>
+stellavault ingest <anything>     # PDF, DOCX, URL, YouTube, text
+  → auto-extract text             # unpdf, mammoth, yt-dlp
+  → raw/ (fleeting)               # Zettelkasten inbox
+  → compile → _wiki/              # Auto: concepts + backlinks
+  → stellavault draft "topic"     # Blog, report, or outline
+```
 
-## Core Workflow
+### Ingest Anything
 
-```
-Capture → Compile → Connect → Review
-
-stellavault fleeting "idea"     # Instant capture
-stellavault ingest <url>        # Clip any URL/file
-stellavault compile             # Raw → structured wiki
-stellavault autopilot           # Full flywheel: inbox → compile → lint
-stellavault ask "question"      # Q&A with auto-filing (--save)
-stellavault lint                # Knowledge health check (score 0-100)
-```
+| Input | How |
+|-------|-----|
+| PDF, DOCX, PPTX, XLSX | `stellavault ingest report.pdf` — auto text extraction |
+| YouTube | `stellavault ingest https://youtu.be/...` — transcript + timestamps |
+| URL | `stellavault ingest https://...` — HTML → clean text |
+| Text | `stellavault ingest "quick thought"` |
+| Web UI | Drag & drop files in browser (mobile too) |
 
-## Daily Commands
+### Express: Get Knowledge Out
 
 ```bash
-stellavault brief               # Morning knowledge briefing
-stellavault decay               # What's fading from memory?
-stellavault learn               # AI-generated learning path
-stellavault digest --visual     # Weekly report with Mermaid charts
-stellavault review              # FSRS spaced repetition session
-stellavault gaps                # Knowledge gap detection
+stellavault draft "AI"                    # Rule-based scaffold (free)
+stellavault draft "AI" --ai               # Claude API writes full draft ($0.03)
+stellavault draft "AI" --format report    # Formal report format
+stellavault draft --format outline        # All-knowledge outline
 ```
 
-## Intelligence Features
-
-| Feature | Command | What it does |
-|---------|---------|-------------|
-| **FSRS Decay** | `sv decay` | Track memory strength with spaced repetition |
-| **Gap Detection** | `sv gaps` | Find missing connections between topics |
-| **Contradiction Detection** | `sv contradictions` | Spot conflicting statements |
-| **Duplicate Detection** | `sv duplicates` | Find redundant notes |
-| **Knowledge Lint** | `sv lint` | Health score + issues + suggestions |
-| **Learning Path** | `sv learn` | AI-recommended review order |
-| **Semantic Evolution** | MCP `get-evolution` | Track how ideas change over time |
-| **Code Linker** | MCP `link-code` | Connect code files to knowledge notes |
-| **Adaptive Search** | MCP `search` | Context-aware result reranking |
-
-## Zettelkasten Automation
+Or in Claude Code: *"Write a blog post about machine learning from my notes"* — Claude uses MCP `generate-draft` tool (free, no API key).
 
-Inspired by Luhmann + Karpathy's "Self-Compiling Zettelkasten":
+## Daily Commands
 
 ```bash
-stellavault fleeting "raw idea"          # Capture → raw/
-stellavault ingest https://article.com   # Any URL → auto-classified
-stellavault compile                      # Raw → wiki with concepts + backlinks
-stellavault promote file.md --to permanent  # Upgrade note stage
-stellavault autopilot                    # Full cycle: inbox → compile → lint → archive
+stellavault ask "What did I learn about X?"   # Q&A from vault
+stellavault brief                              # Morning knowledge briefing
+stellavault decay                              # What's fading from memory?
+stellavault lint                               # Health score (0-100)
+stellavault learn                              # AI learning path
+stellavault digest --visual                    # Weekly Mermaid chart report
 ```
 
-- **Frontmatter-first scanning** — 10x token reduction
-- **Luhmann index codes** — auto-assigned hierarchical numbering (1A → 1A1)
-- **Inbox Zero** — processed notes auto-archived
-- **Atomicity check** — detects notes with too many topics
-- **3-stage classification** — fleeting → literature → permanent
-
-## MCP Tools (17)
+## MCP Tools (20)
 
 | Tool | What it does |
 |------|-------------|
 | `search` | Hybrid search (BM25 + vector + RRF) |
+| `ask` | Q&A with optional vault filing |
+| `generate-draft` | Gather vault context for AI draft writing |
 | `get-document` | Full document with metadata |
 | `get-related` | Semantically similar documents |
 | `list-topics` | Topic cloud |
@@ -128,7 +93,6 @@ stellavault autopilot                    # Full cycle: inbox → compile → lin
 | `detect-gaps` | Knowledge gap analysis |
 | `get-evolution` | Semantic drift tracking |
 | `link-code` | Code-knowledge connections |
-| `ask` | Q&A with optional vault filing |
 | `create-knowledge-node` | AI creates wiki-quality notes |
 | `create-knowledge-link` | AI connects existing notes |
 | `log-decision` / `find-decisions` | Decision journal |
@@ -136,38 +100,53 @@ stellavault autopilot                    # Full cycle: inbox → compile → lin
 | `generate-claude-md` | Auto-generate CLAUDE.md |
 | `export` | JSON/CSV export |
 
-## 3D Visualization
+## Zettelkasten (Luhmann + Karpathy)
 
-- **Neural graph** — force-directed layout with cluster coloring
-- **Constellation view** — MST-based star patterns with LOD zoom
-- **Heatmap overlay** — activity score (cold → fire gradient)
-- **Timeline slider** — filter by creation/modification date
-- **Multiverse view** — see connected Federation peers
-- **Decay overlay** — visualize fading knowledge
-- **Dark/Light theme** — monochrome light mode with color-on-interaction
-- **Export** — PNG screenshots + WebM recording
+```bash
+stellavault fleeting "raw idea"                # → raw/
+stellavault ingest report.pdf                  # → auto text extract → raw/
+stellavault compile                            # → raw/ → _wiki/ (concepts + backlinks)
+stellavault promote note.md --to permanent     # Upgrade stage
+stellavault autopilot                          # Full cycle: inbox → compile → lint → archive
+```
 
-## Obsidian Plugin
+- **3-stage flow**: fleeting → literature → permanent
+- **Luhmann index codes**: auto-assigned (1A → 1A1)
+- **Frontmatter-first scanning**: 10x token reduction
+- **Configurable folders**: override raw/_wiki/_literature/ in `.stellavault.json`
+
+```json
+{
+  "vaultPath": "/path/to/vault",
+  "folders": {
+    "fleeting": "01-Inbox",
+    "literature": "02-Reading",
+    "permanent": "03-Notes",
+    "wiki": "04-Wiki"
+  }
+}
+```
 
-Manual install (community plugin review pending):
+## Intelligence
 
-1. Download `main.js`, `manifest.json`, `styles.css` from [GitHub Releases](https://github.com/Evanciel/stellavault-obsidian/releases/tag/0.1.0)
-2. Copy to `.obsidian/plugins/stellavault/`
-3. Enable in Settings > Community plugins
-4. **Run `stellavault graph` first** — the plugin connects to the API server
+| Feature | Command |
+|---------|---------|
+| FSRS Decay | `sv decay` — spaced repetition memory tracking |
+| Gap Detection | `sv gaps` — missing connections between topics |
+| Contradictions | `sv contradictions` — conflicting statements |
+| Duplicates | `sv duplicates` — redundant notes |
+| Learning Path | `sv learn` — AI review recommendations |
+| Code Linker | MCP `link-code` — connect code to knowledge |
 
-Features: semantic search modal, memory decay sidebar, learning path suggestions.
+## 3D Visualization
 
-## Architecture
-
-```
-stellavault/
-├── packages/
-│   ├── core/       Search, MCP, API, Intelligence, Federation, Cloud, Team, i18n
-│   ├── cli/        36+ commands
-│   ├── graph/      3D visualization (React Three Fiber)
-│   └── sync/       Notion ↔ Obsidian sync
-```
+- Neural graph with cluster coloring
+- Constellation view (MST star patterns)
+- Heatmap overlay (activity score)
+- Timeline slider (creation/modification filter)
+- Decay overlay (fading knowledge)
+- Dark/Light theme
+- Mobile responsive + PWA installable
 
 ## Tech Stack
 
@@ -175,46 +154,12 @@ stellavault/
 |-------|------|
 | Runtime | Node.js 20+ (ESM, TypeScript) |
 | Vector Store | SQLite-vec (local, no server) |
-| Embedding | all-MiniLM-L6-v2 (local, no API key) |
+| Embedding | paraphrase-multilingual-MiniLM-L12-v2 (local, 50+ languages) |
 | Search | BM25 + Cosine + RRF Fusion |
+| File Parsing | unpdf, mammoth, officeparser, SheetJS |
 | Memory | FSRS (Free Spaced Repetition Scheduler) |
-| 3D | React Three Fiber + Three.js + Zustand |
-| P2P | Hyperswarm (NAT traversal + DHT) |
-| AI | MCP (Model Context Protocol) |
-| Security | AES-256-GCM, HMAC-SHA256, Differential Privacy |
-
-## Troubleshooting
-
-<details>
-<summary>"Stellavault API server not found"</summary>
-
-The Obsidian plugin and 3D graph require the API server. Open a terminal in your vault:
-
-```bash
-stellavault graph
-```
-
-Default port: 3333. Change in `.stellavault.json`: `{ "mcp": { "port": 3334 } }`
-</details>
-
-<details>
-<summary>"No documents indexed"</summary>
-
-```bash
-stellavault index /path/to/your/vault
-```
-
-First indexing takes 2-5 minutes for large vaults (1000+ notes).
-</details>
-
-<details>
-<summary>Port conflict</summary>
-
-```bash
-# Use a different port
-stellavault graph --port 3334
-```
-</details>
+| 3D | React Three Fiber + Three.js |
+| AI | MCP (Model Context Protocol) + Anthropic SDK |
 
 ## License
 
@@ -223,5 +168,5 @@ MIT
 ## Links
 
 - [Obsidian Plugin](https://github.com/Evanciel/stellavault-obsidian)
-- [Wiki: Vault Structure Guide](docs/wiki/vault-structure.md)
-- [Wiki: Federation Guide](docs/wiki/federation-guide.md)
+- [npm](https://www.npmjs.com/package/stellavault)
+- [GitHub Releases](https://github.com/Evanciel/stellavault/releases)