apunkt/vestige
1
0
Fork 0
mirror of https://github.com/samvallad33/vestige.git synced 2026-04-25 00:36:22 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
vestige/docs/VESTIGE_STATE_AND_PLAN.md

1274 lines
87 KiB
Markdown
Raw Normal View History

v2.0.8 Pulse — Reasoning Theater + Pulse Toast + Terrarium + Intel Mac (#44) * docs: anti-hedging banner + master state-and-plan + UI roadmap Project-level CLAUDE.md line 1 is now the anti-hedging banner referencing the global rule at /Users/entity002/CLAUDE.md. When Sam commits to an execution path (content cadence, shipping velocity, outreach, launch), forecasts compute as if the commitment is already met — no discounting by execution probability. VESTIGE_STATE_AND_PLAN.md (1135 lines, 14 parts): single-page reference any AI agent can read to plan the next phase without re-reading the repo. Covers current state of every crate, the 24 MCP tools, the 19 WebSocket event types, the 8 IDE integrations, and v2.1 through v3.0 roadmap. UI_ROADMAP_v2.1_v2.2.md: compiled UI-gap analysis from 4 parallel research agents (April 19). 10 critical UI gaps + 2026 bleeding-edge patterns + unclaimed territory (menu bar widget, voice-first, AR/VR, time-scrubber). * feat(v2.2-pulse): InsightToast + multi-process STORAGE docs Two independent ship items landing together on the v2.2 branch ahead of the Tuesday launch — a new UI surface that makes Vestige's cognitive events visible in real time, and honest documentation of the multi-process safety story that underpins the Stigmergic Swarm narrative. **InsightToast** (apps/dashboard/src/lib/components/InsightToast.svelte, apps/dashboard/src/lib/stores/toast.ts): The dashboard already had a working WebSocket event stream on ws://localhost:3927/ws that broadcast every cognitive event (dream completions, consolidation sweeps, memory promotions/demotions, active- forgetting suppression and Rac1 cascades, bridge discoveries). None of that was surfaced to a user looking at anything other than the raw feed view. InsightToast subscribes to the existing eventFeed derived store, filters the spammy lifecycle events (Heartbeat, SearchPerformed, RetentionDecayed, ActivationSpread, ImportanceScored, MemoryCreated), and translates the narrative events into ephemeral toasts with a bioluminescent colored accent matching EVENT_TYPE_COLORS. Design notes: - Rate-limited ConnectionDiscovered at 1.5s intervals (dreams emit many). - Max 4 visible toasts, auto-dismiss at 4.5-7s depending on event weight. - Click or Enter/Space to dismiss early. - Bottom-right on desktop, top-banner on mobile. - Reduced-motion honored via prefers-reduced-motion. - Zero new websocket subscriptions — everything piggybacks on the existing derived store. Also added a "Preview Pulse" button to Settings -> Cognitive Operations that fires a synthetic sequence of four toasts (DreamCompleted, ConnectionDiscovered, MemorySuppressed, ConsolidationCompleted) so the animation is demoable without waiting for real cognitive activity. **Multi-Process Safety section in docs/STORAGE.md**: Grounds the Stigmergic Swarm story with concrete tables of what the current WAL + 5s busy_timeout configuration actually supports vs what remains experimental. Key honest points: - Shared --data-dir + ONE vestige-mcp + N clients is the shipping pattern for multi-agent coordination. - Two vestige-mcp processes writing the same file is experimental — documented with the lsof + pkill recovery path. - Roadmap lists the three items that would promote it to "supported": advisory file lock, retry-with-jitter on SQLITE_BUSY, and a concurrent-writer load test. Build + typecheck: - npm run check: 0 errors, 0 warnings across 583 files - npm run build: clean static build, adapter-static succeeds * feat(v2.3-terrarium): Memory Birth Ritual + event pipeline fix v2.3 "Terrarium" headline feature. When a MemoryCreated event arrives, a glowing orb materialises in the cosmic center (camera-relative z=-40), gestates for ~800ms growing from a tiny spark into a full orb, then arcs along a dynamic quadratic Bezier curve to the live position of the real node, and on arrival hands off to the existing RainbowBurst + Shockwave + RippleWave cascade. The target position is re-resolved every frame so the force simulation can move the destination during flight without the orb losing its mark. **New primitive — EffectManager.createBirthOrb()** (effects.ts): Accepts a camera, a color, a live target-position getter, and an arrival callback. Owns a sprite pair (outer halo + inner bright core), both depthTest:false with renderOrder 999/1000 so the orb is always visible through the starfield and the graph. - Gestation phase: easeOutCubic growth + sinusoidal pulse, halo tints from neutral to event color as the ritual charges. - Flight phase: QuadraticBezierCurve3 with control point at midpoint raised on Y by 30 + 15% of orb-to-target distance (shooting-star arc). Sampled with easeInOutQuad. Orb shrinks ~35% approaching target. - Arrival: fires onArrive callback once, then fades out over 8 frames while expanding slightly (energy dispersal). - Caller's onArrive triggers the burst cascade at arrivePos (NOT the original spawnPos — the force sim may have moved the target during the ritual, so we re-read nodeManager.positions on arrival). - Dispose path integrated with existing EffectManager.dispose(). **Event pipeline fix — Graph3D.processEvents()**: Previously tracked `processedEventCount` assuming APPEND order, but websocket.ts PREPENDS new events (index 0) and caps the array at MAX_EVENTS. Result: only the first MemoryCreated event after page load fired correctly; subsequent ones reprocessed the oldest entry. Fixed to walk from index 0 until hitting the last-processed event by reference identity — correct regardless of array direction or eviction pressure. Events are then processed oldest-first so causes precede effects. Found while wiring the v2.3 demo button; would have manifested as "first orb only" in production. **Demo trigger** (Settings -> Birth Ritual Preview): Button that calls websocket.injectEvent() with a synthetic MemoryCreated event, cycling through node types (fact / concept / pattern / decision / person / place) to showcase the type-color mapping. Downstream consumers can't distinguish synthetic from real, so this drives the full ritual end-to-end. Intended for demo clip recording for the Wednesday launch. **Test coverage:** - events.test.ts now tests the v2.3 birth ritual path: spawns 2+ sprites in the scene immediately, and fires the full arrival cascade after driving the effects.update() loop past the ritual duration. - three-mock.ts extended with Vector3.addVectors, Vector3.applyQuaternion, Color.multiplyScalar, Quaternion, QuadraticBezierCurve3, Texture, and Object3D.quaternion/renderOrder so production code runs unaltered in tests. Build + typecheck: - npm run check: 0 errors, 0 warnings across 583 files - npm test: 251/251 pass (net +0 from v2.2) - npm run build: clean adapter-static output The Sanhedrin Shatter (anti-birth ritual for hallucination veto) needs server-side event plumbing and is deferred. Ship this as the Wednesday visual mic-drop. * fix(v2.3): 5 FATAL bugs + 4 god-tier upgrades from post-ship audit Post-ship audit surfaced 6 FATALs and 4 upgrades. Shipping 5 of the 6 + all 4 upgrades. FATAL 4 (VRAM hemorrhage from un-pooled label canvases in createTextSprite) is pre-existing, not from this session, and scoped separately for a proper texture-pool refactor. **FATAL 1 — Toast Silent Lobotomy** (stores/toast.ts) Subscriber tracked events[0] only. When Svelte batched multiple events in one update tick (swarm firing DreamCompleted + ConnectionDiscovered within the same millisecond), every event but the newest got silently dropped. Fixed to walk from index 0 until hitting lastSeen — same pattern as Graph3D.processEvents. Processes oldest-first to preserve narrative order. **FATAL 2 — Premature Birth** (graph/nodes.ts + graph/events.ts) Orb flight is 138 frames; materialization was 30 frames. Node popped fully grown ~100 frames before orb arrived — cheap UI glitch instead of a biological birth. Added `addNode(..., { isBirthRitual: true })` option that reserves the physics slot but hides mesh/glow/label and skips the materializing queue. New `igniteNode(id)` flips visibility and enqueues materialization. events.ts onArrive now calls igniteNode at the exact docking moment, so the elastic spring-up peaks on impact. **FATAL 3 — 120Hz ProMotion Time-Bomb** (components/Graph3D.svelte) All physics + effect counters are frame-based. On a 120Hz display every ritual ran at 2x speed. Added a `lastTime`-based governor in animate() that early-returns if dt < 16ms, clamping effective rate to ~60fps. `- (dt % 16)` carry avoids long-term drift. Zero API changes; tonight's fast fix until physics is rewritten to use dt. **FATAL 5 — Bezier GC Panic** (graph/effects.ts birth-orb update) Flight phase allocated a new Vector3 (control point) and a new QuadraticBezierCurve3 every frame per orb. With 3 orbs in flight that's 360 objects/sec for the GC to collect. Rewrote as inline algebraic evaluation — zero allocations per frame, identical curve. **FATAL 6 — Phantom Shockwave** (graph/events.ts) A 166ms setTimeout fired the 2nd shockwave. If the user navigated away during that window the scene was disposed, the timer still fired, and .add() on a dead scene threw unhandled rejection. Dropped the setTimeout entirely; both shockwaves fire immediately in onArrive with different scales/colors for the same layered-crash feel. **UPGRADE 1 — Sanhedrin Shatter** (graph/effects.ts birth-orb update) If getTargetPos() returns undefined AFTER gestation (target node was deleted mid-ritual — Stop hook sniping a hallucination), the orb turns blood-red, triggers a violent implosion in place, and skips the arrival cascade. Cognitive immune system made visible. **UPGRADE 2 — Newton's Cradle** (graph/events.ts onArrive) On docking the target mesh's scale gets bumped 1.8×, so the elastic materialization + force-sim springs physically recoil instead of the orb landing silently. The graph flinches when an idea is born into it. **UPGRADE 3 — Hover Panic** (stores/toast.ts + InsightToast.svelte) Paused dwell timer on mouseenter/focus, resume on mouseleave/blur. Stored remaining ms at pause so resume schedules a correctly-sized timer. CSS pairs via `animation-play-state: paused` on the progress bar. A toast the user is reading no longer dismisses mid-sentence. **UPGRADE 4 — Event Horizon Guard** (components/Graph3D.svelte) If >MAX_EVENTS (200) events arrive in one tick, lastProcessedEvent falls off the end of the array and the walk consumes ALL 200 entries as "fresh" — GPU meltdown from 200 simultaneous births. Detect the overflow and drop the batch with a console.warn, advancing the high-water mark so next frame is normal. Build + test: - npm run check: 0 errors, 0 warnings - npm test: 251/251 pass - npm run build: clean static build * test(v2.3): full e2e + integration coverage for Pulse + Birth Ritual Post-ship verification pass — five parallel write-agents produced 229 new tests across vitest units, vitest integration, and Playwright browser e2e. Net suite: 361 vitest pass (up from 251, +110) and 9/9 Playwright pass on back-to-back runs. **toast.test.ts (NEW, 661 lines, 42 tests)** Silent-lobotomy batch walk proven (multi-event tick processes ALL, not just newest, oldest-first ordering preserved). Hover-panic pause/resume with remaining-ms math. All 9 event type translations asserted, all 11 noise types asserted silent. ConnectionDiscovered 1500ms throttle. MAX_VISIBLE=4 eviction. clear() tears down all timers. fireDemoSequence staggers 4 toasts at 800ms intervals. vi.useFakeTimers + vi.mock of eventFeed; vi.resetModules in beforeEach for module-singleton isolation. **websocket.test.ts (NEW, 247 lines, 30 tests)** injectEvent adds to front, respects MAX_EVENTS=200 with FIFO eviction, triggers eventFeed emissions. All 6 derived stores (isConnected, heartbeat, memoryCount, avgRetention, suppressedCount, uptimeSeconds) verified — defaults, post-heartbeat values, clearEvents preserves lastHeartbeat. 13 formatUptime boundary cases (0/59/60/3599/3600/ 86399/86400 seconds + negative / NaN / ±Infinity). **effects.test.ts (EXTENDED, +501 lines, +21 tests, 51 total)** createBirthOrb full lifecycle — sprite count (halo + core), cosmic center via camera.quaternion, gestation phase (position lock, opacity rise, scale easing, color tint), flight Bezier arc above linear midpoint at t=0.5, dynamic mid-flight target redirect. onArrive fires exactly once at frame 139. Post-arrival fade + disposal cleans scene children. Sanhedrin Shatter: target goes undefined mid-flight → onArrive NEVER called, implosion spawned, halo blood-red, eventual cleanup. dispose() cleans active orbs. Multiple simultaneous orbs. Custom gestation/flight frame opts honored. Zero-alloc invariant smoke test (6 orbs × 150 frames, no leaks). **nodes.test.ts (EXTENDED, +197 lines, +10 tests, 42 total)** addNode({isBirthRitual:true}) hides mesh/glow/label immediately, stamps birthRitualPending sentinel with correct totalFrames + targetScale, does NOT enqueue materialization. igniteNode flips visibility + enqueues materialization. Idempotent — second call no-op. Non-ritual nodes unaffected. Unknown id is safe no-op. Position stored in positions map while invisible (force sim still sees it). removeNode + late igniteNode is safe. **events.test.ts (EXTENDED, +268 lines, +7 tests, 55 total)** MemoryCreated → mesh hidden immediately, 2 birth-orb sprites added, ZERO RingGeometry meshes and ZERO Points particles at spawn. Full ritual drive → onArrive fires, node visible + materializing, sentinel cleared. Newton's Cradle: target mesh scale exactly 0.001 * 1.8 right after arrival. Dual shockwave: exactly 2 Ring meshes added. Re-read live position on arrival — force-sim motion during ritual → burst lands at the NEW position. Sanhedrin abort path → rainbow burst, shockwave, ripple wave are NEVER called (vi.spyOn). **three-mock.ts (EXTENDED)** Added Color.setRGB — production Three.js has it, the Sanhedrin- Shatter path in effects.ts uses it. Two write-agents independently monkey-patched the mock inline; consolidated as a 5-line mock addition so tests stay clean. **e2e/pulse-toast.spec.ts (NEW, 235 lines, 6 Playwright tests)** Navigate /dashboard/settings → click Preview Pulse → assert first toast appears within 500ms → assert >= 2 toasts visible at peak. Click-to-dismiss removes clicked toast (matched by aria-label). Hover survives >8s past the 5.5s dwell. Keyboard Enter dismisses focused toast. CSS animation-play-state:paused on .toast-progress- fill while hovered, running on mouseleave. Screenshots attached to HTML report. Zero backend dependency (fireDemoSequence is purely client-side). **e2e/birth-ritual.spec.ts (NEW, 199 lines, 3 Playwright tests)** Canvas mounts on /dashboard/graph (gracefully test.fixme if MCP backend absent). Settings button injection + SPA route to /graph → screenshot timeline at t=0/500/1200/2000/2400/3000ms attached to HTML report. pageerror + console-error listeners catch any crash (would re-surface FATAL 6 if reintroduced). Three back-to- back births — no errors, canvas still dispatches clicks. Run commands: cd apps/dashboard && npm test # 361/361 pass, ~600ms cd apps/dashboard && npx playwright test # 9/9 pass, ~25s Typecheck: 0 errors, 0 warnings. Build: clean adapter-static. * fix(graph): default /api/graph to newest-memory center, add sort param memory_timeline PR #37 exposed the same class of bug in the graph endpoint: the dashboard Graph page (and the /api/graph endpoint it hits) defaulted to centering on the most-connected memory, ran BFS at depth 3, and capped the subgraph at 150 nodes. On a mature corpus this clustered the visualization around a historical hotspot and hid freshly ingested memories that hadn't accumulated edges yet. User-visible symptom: TimeSlider on /graph showing "Feb 21 → Mar 1 2026" when the database actually contains memories through today (Apr 20). **Backend (`crates/vestige-mcp/src/dashboard/handlers.rs`):** - `GraphParams` gains `sort: Option<String>` (accepted: "recent" | "connected", unknown falls back to "recent"). - New internal `GraphSort` enum + case-insensitive `parse()`. - Extracted `default_center_id(storage, sort)` so handler logic and tests share the same branching. Recent path picks `get_all_nodes(1, 0)` (ORDER BY created_at DESC). Connected path picks `get_most_connected_memory`, degrading gracefully to recent if the DB has no edges yet. - Default behaviour flipped from "connected" to "recent" — matches user expectation of "show me my recent stuff". **Dashboard (`apps/dashboard`):** - `api.graph()` accepts `sort?: 'recent' | 'connected'` with JSDoc explaining the rationale. - `/graph/+page.svelte` passes `sort: 'recent'` when no query or center_id is active. Query / center_id paths unchanged — they already carry their own centering intent. **Tests:** 6 new unit tests in `handlers::tests`: - `graph_sort_parse_defaults_to_recent` (None, empty, garbage, "recent", "Recent", "RECENT") - `graph_sort_parse_accepts_connected_case_insensitive` - `default_center_id_recent_returns_newest_node` — ingest 3 nodes, assert newest is picked - `default_center_id_connected_prefers_hub_over_newest` — wire a hub node with 3 spokes, then ingest a newer "lonely" node; assert the hub wins in Connected mode even though it's older - `default_center_id_connected_falls_back_to_recent_when_no_edges` — fresh DB with no connections still returns newest, not 404 - `default_center_id_returns_not_found_on_empty_db` — both modes return 404 cleanly on empty storage Build + test: - cargo test -p vestige-mcp --lib handlers:: → 6/6 pass - cargo test --workspace --lib → 830/830 pass, 0 failed - cargo clippy -p vestige-core -p vestige-mcp --lib -- -D warnings → clean - npm run check → 0 errors, 0 warnings - npm test → 361/361 pass Binary already installed at ~/.local/bin/vestige-mcp (copied from cargo build --release -p vestige-mcp). New Claude Desktop / Code sessions will pick it up automatically when they respawn their MCP subprocess. The dashboard HTTP server on port 3927 needs a manual relaunch from a terminal with the usual pattern: nohup bash -c 'tail -f /dev/null | \ VESTIGE_DASHBOARD_ENABLED=true ~/.local/bin/vestige-mcp' \ > /tmp/vestige-mcp.log 2>&1 & disown * feat(v2.4): UI expansion — 8 new surfaces exposing the cognitive engine Sam asked: "Build EVERY SINGLE MISSING UI PIECE." 10 parallel agents shipped 10 new viewports over the existing Rust backend, then 11 audit agents line-by-line reviewed each one, extracted pure-logic helpers, fixed ~30 bugs, and shipped 549 new unit tests. Everything wired through the layout with single-key shortcuts and a live theme toggle. **Eight new routes** - `/reasoning` — Reasoning Theater: Cmd+K ask palette → animated 8-stage deep_reference pipeline + FSRS-trust-scored evidence cards + contradiction arcs rendered as live SVG between evidence nodes - `/duplicates` — threshold-driven cluster detector with winner selection, Merge/Review/Dismiss actions, debounced slider - `/dreams` — Dream Cinema: trigger dream + scrubbable 5-stage replay (Replay → Cross-reference → Strengthen → Prune → Transfer) + insight cards with novelty glow - `/schedule` — FSRS Review Calendar: 6×7 grid with urgency color bands (overdue/today/week/future), retention sparkline, expand-day list - `/importance` — 4-channel radar (Novelty/Arousal/Reward/Attention) with composite score + top-important list - `/activation` — live spreading-activation view: search → SVG concentric rings with decay animation + live-mode event feed - `/contradictions` — 2D cosmic constellation of conflicting memories, arcs colored by severity, tooltips with previews - `/patterns` — cross-project pattern transfer heatmap with category filters, top-transferred sidebar **Three layout additions** - `AmbientAwarenessStrip` — slim top band with retention vitals, at-risk count, active intentions, recent dream, activity sparkline, dreaming indicator, Sanhedrin-watch flash. Pure `$derived` over existing stores. - `ThemeToggle` — dark/light/auto cycle with matchMedia listener, localStorage persistence, SSR-safe, reduced-motion-aware. Rendered in sidebar footer next to the connection dot. - `MemoryAuditTrail` — per-memory Sources panel integrated as a Content/Audit tab into the existing /memories expansion. **Pure-logic helper modules extracted (for testability + reuse)** reasoning-helpers, duplicates-helpers, dream-helpers, schedule-helpers, audit-trail-helpers, awareness-helpers, contradiction-helpers, activation-helpers, patterns-helpers, importance-helpers. **Bugs fixed during audit (not exhaustive)** - Trust-color inconsistency between EvidenceCard and the page confidence ring (0.75 boundary split emerald vs amber) - `new Date('garbage').toLocaleDateString()` returned literal "Invalid Date" in 3 components — all now return em-dash or raw string - NaN propagation in `Math.max(0, Math.min(1, NaN))` across clamps - Off-by-one PRNG in audit-trail seeded mock (seed === UINT32_MAX yielded rand() === 1.0 → index out of bounds) - Duplicates dismissals keyed by array index broke on re-fetch; now keyed by sorted cluster member IDs with stale-dismissal pruning - Empty-cluster crash in DuplicateCluster.pickWinner - Undefined tags crash in DuplicateCluster.safeTags - Debounce timer leak in threshold slider (missing onDestroy cleanup) - Schedule day-vs-hour granularity mismatch between calendar cell and sidebar list ("today" in one, "in 1d" in the other) - Schedule 500-memory hard cap silently truncated; bumped to 2000 + banner - Schedule DST boundary bug in daysBetween (wall-clock math vs startOfDay-normalized) - Dream stage clamp now handles NaN/Infinity/floats - Dream double-click debounce via `if (dreaming) return` - Theme setTheme runtime validation; initTheme idempotence (listener + style-element dedup on repeat calls) - ContradictionArcs node radius unclamped (trust < 0 or > 1 rendered invalid sizes); tooltip position clamp (could push off-canvas) - ContradictionArcs $state closure capture (width/height weren't reactive in the derived layout block) - Activation route was MISSING from the repo — audit agent created it with identity-based event filtering and proper RAF cleanup - Layout: ThemeToggle was imported but never rendered — now in sidebar footer; sidebar overflow-y-auto added for the 16-entry nav **Tests — 549 new, 910 total passing (0 failures)** ReasoningChain 42 | EvidenceCard 50 DuplicateCluster 64 | DreamStageReplay 19 DreamInsightCard 43 | FSRSCalendar 32 MemoryAuditTrail 45 | AmbientAwareness 60 theme (store) 31 | ContradictionArcs 43 ActivationNetwork 54 | PatternTransfer 31 ImportanceRadar 35 | + existing 361 tests still green **Gates passed** - `npm run check`: 0 errors, 0 warnings across 623 files - `npm test`: 910/910 passing, 22 test files - `npm run build`: clean adapter-static output **Layout wiring** - Nav array expanded 8 → 16 entries (existing 8 + 8 new routes) - Single-key shortcuts added: R/A/D/C/P/U/X/N (no conflicts with existing G/M/T/F/E/I/S/,) - Cmd+K palette search works across all 16 - Mobile nav = top 5 (Graph, Reasoning, Memories, Timeline, Feed) - AmbientAwarenessStrip mounted as first child of <main> - ThemeToggle rendered in sidebar footer (was imported-but-unmounted) - Theme initTheme() + teardown wired into onMount cleanup chain Net branch delta: 47 files changed, +13,756 insertions, -6 deletions * chore(release): v2.0.8 "Pulse" Bundled release: Reasoning Theater wired to the 8-stage deep_reference cognitive pipeline, Pulse InsightToast, Memory Birth Ritual (v2.3 Terrarium), 7 new dashboard surfaces (/duplicates, /dreams, /schedule, /importance, /activation, /contradictions, /patterns), 3D graph brightness system with auto distance-compensation + user slider, and contradiction-detection + primary-selection hardening in the cross_reference tool. Intel Mac (x86_64-apple-darwin) also flows through to the release matrix from PR #43. Added: - POST /api/deep_reference — HTTP surface for the 8-stage pipeline - DeepReferenceCompleted WebSocket event (primary + supporting + contradicting memory IDs for downstream graph animation) - /reasoning route, full UI + Cmd+K Ask palette - 7 new dashboard surfaces exposing the cognitive engine - Graph brightness slider + localStorage persistence + distance-based emissive compensation so nodes don't disappear into fog at zoom-out Fixed: - Contradiction-detection false positives: adjacent-domain memories no longer flagged as conflicts (NEGATION_PAIRS wildcards removed, shared-words floor 2 → 4, topic-sim floor 0.15 → 0.55, STAGE 5 overlap floor 0.15 → 0.4) - Primary-memory selection: unified composite 0.5 × relevance + 0.2 × trust + 0.3 × term_presence with hard topic-term filter, closing the class of bug where off-topic high-trust memories won queries about specific subjects - Graph default-load fallback from sort=recent to sort=connected when the newest memory is isolated, both backend and client Changed: - Reasoning page information hierarchy: chain renders first as hero, confidence meter + Primary Source citation footer below - Cargo feature split: embeddings code-only + ort-download | ort-dynamic backends; defaults preserve identical behavior for existing consumers - CI release-build now gates PRs too so multi-platform regressions surface pre-merge
2026-04-23 02:21:11 -05:00
# Vestige: State of the Engine & Next-Phase Plan
> **For:** AI agents planning the next phase of Vestige alongside Sam.
> **From:** Sam Valladares (compiled via multi-agent inventory of the live codebase).
> **As of:** 2026-04-19 ~22:10 CT, post-merge of v2.0.8 into `main` (CI green on all four jobs).
> **Repo:** https://github.com/samvallad33/vestige
> **Related repo (private):** `~/Developer/vestige-cloud` (Feb 12, 2026 skeleton; Part 7).
>
> This document is the single authoritative briefing of what Vestige *is today* and what *ships next*. Everything in Part 1 is verifiable against the source tree; everything in Part 3 is the committed roadmap agreed 2026-04-19.
---
## Table of Contents
0. [Executive Summary (60-second read)](#0-executive-summary-60-second-read)
1. [What Vestige Is](#1-what-vestige-is)
2. [Workspace Architecture](#2-workspace-architecture)
3. [`vestige-core` — Cognitive Engine](#3-vestige-core--cognitive-engine)
4. [`vestige-mcp` — MCP Server + Dashboard Backend](#4-vestige-mcp--mcp-server--dashboard-backend)
5. [`apps/dashboard` — SvelteKit + Three.js Frontend](#5-appsdashboard--sveltekit--threejs-frontend)
6. [Integrations & Packaging](#6-integrations--packaging)
7. [`vestige-cloud` — Current Skeleton](#7-vestige-cloud--current-skeleton)
8. [Version History (v1.0 → v2.0.8)](#8-version-history-v10--v208)
9. [The Next-Phase Plan](#9-the-next-phase-plan)
10. [Composition Map](#10-composition-map)
11. [Risks & Known Gaps](#11-risks--known-gaps)
12. [Viral / Launch / Content Plan](#12-viral--launch--content-plan)
13. [How AI Agents Should Consume This Doc](#13-how-ai-agents-should-consume-this-doc)
14. [Glossary & Citations](#14-glossary--citations)
---
## 0. Executive Summary (60-second read)
Vestige is a Rust-based MCP (Model Context Protocol) cognitive memory server that gives any AI agent persistent, structured, scientifically-grounded memory. It ships three binaries (`vestige-mcp`, `vestige`, `vestige-restore`), a 3D SvelteKit dashboard embedded into the binary, and is distributed via GitHub releases + npm. As of v2.0.7 "Visible" (tagged 2026-04-19), it has **24 MCP tools**, **29 cognitive modules** implementing real neuroscience (FSRS-6 spaced repetition, synaptic tagging, hippocampal indexing, spreading activation, reconsolidation, Anderson 2025 suppression-induced forgetting, Rac1 cascade decay), **1,292 Rust tests**, **251 dashboard tests** (80 just added for v2.0.8 colour-mode), and **402 GitHub stars**. AGPL-3.0.
**The branch `feat/v2.0.8-memory-state-colors` was fast-forwarded into `main` tonight** adding the FSRS memory-state colour mode, a floating legend, ruthless unit coverage, the Rust 1.95 clippy-compat fix (12 sites), and the dark-glass-pill label redesign. CI on main: all 4 jobs ✅.
**The next six releases are scoped:** v2.1 "Decide" (Qwen3 embeddings, in-flight on `feat/v2.1.0-qwen3-embed`), v2.2 "Pulse" (subconscious cross-pollination — **the viral moment**), v2.3 "Rewind" (temporal slider + pin), v2.4 "Empathy" (emotional/frustration tagging, **first Pro-tier gate candidate**), v2.5 "Grip" (neuro-feedback cluster gestures), v2.6 "Remote" (`vestige-cloud` upgrade from 5→24 MCP tools + Streamable HTTP). v3.0 "Branch" reserves CoW memory branching and multi-tenant SaaS.
**Sam's context** (load-bearing for any strategic advice): no steady income since March 2026, Mays Business School deadline May 1 ($400K+ prizes), Orbit Wars Kaggle deadline June 23 ($5K × top 10), graduation June 13. Viral OSS growth comes first; paid tier gates second.
---
## 1. What Vestige Is
### 1.1 Mission
Give any AI agent that speaks MCP a long-term memory and a reasoning co-processor that survives session boundaries, with retrieval ranked by scientifically-validated decay and strengthening rules — not a vector database with a nice coat of paint.
### 1.2 Positioning vs. the competitive landscape
| System | Vestige's angle |
|---|---|
| Zep, Cognee, Letta, claude-mem, MemPalace, HippoRAG | Vestige is **local-first + MCP-native + neuroscience-grounded**. The others are cloud-first (Zep/Cognee), RAG-wrappers (HippoRAG), or toy (claude-mem). Vestige is the only one that implements 29 stateful cognitive modules. |
| ChatGPT memory, Cursor memory | Both are opaque key-value caches owned by their vendor. Vestige is open source and the memory is yours. |
| Plain vector DBs (Chroma, Qdrant) | They retrieve by similarity. Vestige *rewires* the graph on access (testing effect), decays with FSRS-6, competes retrievals, and dreams between sessions. |
### 1.3 The "Oh My God" surface
1. The 3D graph that **animates in real-time** when memories are created, promoted, suppressed, or cascade-decayed.
2. The `dream()` tool that runs a 5-stage consolidation cycle and generates insights from cross-cluster replay.
3. `deep_reference` — an 8-stage cognitive reasoning pipeline with FSRS trust scoring, intent classification, contradiction analysis, and a pre-built reasoning chain. Not just retrieval — actual reasoning.
4. Active forgetting (v2.0.5 "Intentional Amnesia") — top-down inhibitory control with Rac1 cascade that spreads over 72h, reversible within a 24h labile window.
5. Cross-IDE persistence. Fix a bug in VS Code, open the project in Xcode, the agent remembers.
### 1.4 Stats (as of 2026-04-19 post-merge)
| Metric | Value |
|---|---|
| GitHub stars | 402 |
| Total commits (main) | 139 |
| Rust source LOC | ~42,000 (vestige-core) + ~vestige-mcp |
| Rust tests passing | 1,292 (workspace, release profile) |
| Dashboard tests passing | 251 (Vitest, 7 files, 3,291 lines) |
| MCP tools | 24 |
| Cognitive modules | 29 (16 neuroscience + 11 advanced + 2 search) |
| FSRS-6 trained parameters | 21 |
| Embedding dim (default) | 768 (nomic-embed-text-v1.5), truncatable to 256 (Matryoshka) |
| Binary targets shipped | 3 (aarch64-darwin, x86_64-linux, x86_64-windows) |
| IDE integrations documented | 8 (Claude Code, Claude Desktop, Cursor, VS Code Copilot, Codex, Xcode, JetBrains/Junie, Windsurf) |
| Latest GitHub release | v2.0.7 "Visible" (binaries up, npm pending Sam's Touch ID) |
| `main` HEAD | `30d92b5` (2026-04-19 21:52 CT) |
| CI on HEAD | All 4 jobs ✅ (Test macos, Test ubuntu, Release aarch64-darwin, Release x86_64-linux) |
### 1.5 License
**AGPL-3.0-only** (copyleft). If you run a modified Vestige as a network service, you must open-source your modifications. This is intentional — it protects against extract-and-host competitors while allowing a future commercial-license path for SaaS (Part 9.7).
---
## 2. Workspace Architecture
### 2.1 Repo layout
```
vestige/
├── Cargo.toml # Workspace root
├── Cargo.lock
├── pnpm-workspace.yaml # pnpm monorepo marker
├── package.json # Root (v2.0.1, private)
├── .mcp.json # Self-registering MCP config
├── README.md # 22.5 KB marketing + quick-start
├── CHANGELOG.md # 31 KB, v1.0 → v2.0.7 Keep-a-Changelog format
├── CLAUDE.md # Project-level Claude instructions
├── CONTRIBUTING.md # Dev setup + test commands
├── SECURITY.md # Vuln reporting
├── LICENSE # AGPL-3.0 full text
├── crates/
│ ├── vestige-core/ # Library crate (cognitive engine)
│ └── vestige-mcp/ # Binary crate (MCP server + dashboard backend)
├── apps/
│ └── dashboard/ # SvelteKit 2 + Svelte 5 + Three.js frontend
├── packages/
│ ├── vestige-mcp-npm/ # npm: vestige-mcp-server (binary wrapper)
│ ├── vestige-init/ # npm: @vestige/init (zero-config installer)
│ └── vestige-mcpb/ # legacy, appears abandoned
├── tests/
│ └── vestige-e2e-tests/ # Integration tests over MCP protocol
├── docs/
│ ├── CLAUDE-SETUP.md
│ ├── CONFIGURATION.md
│ ├── FAQ.md
│ ├── SCIENCE.md
│ ├── STORAGE.md
│ ├── integrations/
│ │ ├── codex.md
│ │ ├── cursor.md
│ │ ├── jetbrains.md
│ │ ├── vscode.md
│ │ ├── windsurf.md
│ │ └── xcode.md
│ ├── launch/
│ │ ├── UI_ROADMAP_v2.1_v2.2.md # compiled 2026-04-19
│ │ ├── show-hn.md
│ │ ├── blog-post.md
│ │ ├── demo-script.md
│ │ └── reddit-cross-reference.md
│ └── blog/
│ └── xcode-memory.md
├── scripts/
│ └── xcode-setup.sh # 4.9 KB interactive installer
└── .github/
└── workflows/
├── ci.yml # push-main + PR: clippy + test
├── release.yml # tag push: binary build matrix
└── test.yml # parallel unit/e2e/journey/dashboard/coverage
```
### 2.2 Dependency flow
```
┌─────────────────────┐
│ apps/dashboard │ Svelte 5 + Three.js → static `build/`
│ (SvelteKit 2) │ embedded via include_dir! into vestige-mcp binary
└──────────┬──────────┘
│ HTTP / WebSocket
▼
┌─────────────────────┐ ┌──────────────────────┐
│ vestige-mcp │ ────► │ vestige-core │
│ (binary + dash BE) │ │ (cognitive engine) │
│ Axum + JSON-RPC │ │ FSRS-6, search, │
│ MCP stdio + HTTP │ │ embeddings, 29 │
│ │ │ cognitive modules │
└─────────────────────┘ └──────────────────────┘
▲
│ path dep
┌────────┴──────────┐
│ vestige-cloud │ (separate repo, Feb 12
│ vestige-http │ skeleton, not yet
│ (Axum + SSE) │ shipped)
└───────────────────┘
```
### 2.3 Build profile
```toml
[profile.release]
lto = true
codegen-units = 1
panic = "abort"
strip = true
opt-level = "z" # Size-optimized; binary is ~22 MB with dashboard
```
### 2.4 Workspace Cargo.toml pinned version
Workspace `version = "2.0.5"`. Crate-level `Cargo.toml` files pin `2.0.7`. Version files are pumped together on each release (5 files: `crates/vestige-core/Cargo.toml`, `crates/vestige-mcp/Cargo.toml`, `apps/dashboard/package.json`, `packages/vestige-init/package.json`, `packages/vestige-mcp-npm/package.json`).
### 2.5 MSRV & editions
- **Rust MSRV:** 1.91 (enforced in `rust-version`).
- **CI Rust:** stable (currently 1.95 — which introduced the `unnecessary_sort_by` + `collapsible_match` lints tonight's fixes addressed).
- **Edition:** 2024 across the entire workspace.
- **Node:** 18+ for npm packages, 22+ for dashboard dev.
- **pnpm:** 10+ for workspace.
---
## 3. `vestige-core` — Cognitive Engine
### 3.1 Purpose
Library crate. Owns the entire cognitive engine: storage, FTS5, vector search, FSRS-6, embeddings, and the 29 cognitive modules. Has no knowledge of MCP, HTTP, or the dashboard — those live one crate up.
### 3.2 Metadata
```toml
name = "vestige-core"
version = "2.0.7"
edition = "2024"
rust-version = "1.91"
license = "AGPL-3.0-only"
description = "Cognitive memory engine - FSRS-6 spaced repetition, semantic embeddings, and temporal memory"
keywords = ["memory", "spaced-repetition", "fsrs", "embeddings", "knowledge-graph"]
```
### 3.3 Feature flags (8)
| Flag | Default | What it turns on | Cost |
|---|---|---|---|
| `embeddings` | **yes** | `mod embeddings`, fastembed v5.11, ONNX inference | +~130MB model download on first run |
| `vector-search` | **yes** | `mod search`, USearch HNSW, hybrid BM25 + semantic | negligible |
| `bundled-sqlite` | **yes** (mutex w/ `encryption`) | SQLite bundled via rusqlite 0.38 | +~2MB binary |
| `encryption` | no | SQLCipher encrypted DB | requires system libsqlcipher |
| `qwen3-reranker` | no | Qwen3 cross-encoder reranker | +candle-core deps |
| `qwen3-embed` | **no (v2.1 scaffolding)** | Qwen3 embed backend via Candle (Metal device + CPU fallback) | +candle-core, +~500MB Qwen3 model |
| `metal` | no | Metal GPU acceleration on Apple | macOS only |
| `nomic-v2` | no | Nomic Embed v2 MoE variant | +~200MB model |
| `ort-dynamic` | no | Runtime-load ORT instead of static prebuilt | required on glibc < 2.38 |
**Default feature set ships with embeddings + vector-search.** `qwen3-embed` is the v2.1 "Decide" scaffolding — dual-index with feature-gated `DEFAULT_DIMENSIONS` (1024 for Qwen3 vs 256 for Matryoshka-truncated Nomic).
### 3.4 Module tree (`src/lib.rs`)
```
src/
├── lib.rs # Module tree + prelude re-exports
├── prelude.rs # KnowledgeNode, IngestInput, SearchResult, etc.
├── storage/ # SQLite + FTS5 + HNSW + migrations
│ ├── mod.rs # Storage struct; public API
│ ├── sqlite.rs # Connection setup, PRAGMAs, migrations
│ ├── migrations.rs # V1..V11 migration chain (V11 dropped knowledge_edges + compressed_memories tables)
│ ├── schema.rs # CREATE TABLE statements
│ ├── node.rs # CRUD for KnowledgeNode
│ ├── edge.rs # Edge insertion + deletion
│ ├── fts.rs # FTS5 wrapper
│ ├── state_transitions.rs # Append-only audit log
│ ├── consolidation_history.rs
│ ├── dream_history.rs
│ └── intention.rs # Prospective memory persistence
├── search/ # 7-stage cognitive search pipeline
│ ├── mod.rs
│ ├── hybrid.rs # BM25 + semantic fusion
│ ├── vector.rs # USearch HNSW wrapper; DEFAULT_DIMENSIONS gated
│ ├── reranker.rs # Jina Reranker v1 Turbo (38M params)
│ ├── temporal.rs # Recency + validity window boosting
│ ├── context.rs # Tulving 1973 encoding specificity
│ ├── competition.rs # Anderson 1994 retrieval-induced forgetting
│ └── activation.rs # Spreading activation side effects
├── embeddings/ # ONNX local + Qwen3 candle
│ ├── mod.rs # EmbeddingService trait
│ ├── local.rs # Backend enum (Nomic ONNX / Qwen3 Candle); metal device selection
│ ├── adaptive.rs # AdaptiveEmbedder (Matryoshka 256/768/1024 tier)
│ ├── hyde.rs # HyDE query expansion
│ └── cache.rs # In-memory embedding LRU
├── fsrs/ # Spaced repetition (21-param Anki FSRS-6)
│ ├── mod.rs
│ ├── params.rs # Trained params
│ ├── algorithm.rs # R(t) = (1 + factor × t / S)^(-w20)
│ └── review.rs # apply_review
├── neuroscience/ # 16 modules (see §3.5)
│ ├── mod.rs
│ ├── activation.rs # ActivationNetwork (Collins & Loftus 1975)
│ ├── synaptic_tagging.rs # SynapticTaggingSystem (Frey & Morris 1997)
│ ├── hippocampal_index.rs # (Teyler & Rudy 2007)
│ ├── context_matcher.rs # (Tulving 1973)
│ ├── accessibility.rs # AccessibilityCalculator
│ ├── competition.rs # CompetitionManager (Anderson 1994)
│ ├── state_update.rs # StateUpdateService
│ ├── importance_signals.rs # 4-channel (novelty/arousal/reward/attention)
│ ├── emotional_memory.rs # Brown & Kulik 1977 flashbulb memory
│ ├── predictive_retrieval.rs # Friston Free Energy 2010
│ ├── prospective_memory.rs # Intention fulfillment
│ ├── intention_parser.rs
│ └── memory_states.rs # Active / Dormant / Silent / Unavailable + Bjork & Bjork 1992
├── advanced/ # 11 modules (see §3.6)
│ ├── mod.rs
│ ├── importance_tracker.rs
│ ├── reconsolidation.rs # Nader 2000 labile window (5 min, 10 mods max)
│ ├── intent_detector.rs # 9 intent types
│ ├── activity_tracker.rs
│ ├── dreaming.rs # MemoryDreamer 5-stage
│ ├── chains.rs # MemoryChainBuilder (A*-like)
│ ├── compression.rs # MemoryCompressor (30-day min age)
│ ├── cross_project.rs # CrossProjectLearner (6 pattern types)
│ ├── adaptive_embedding.rs
│ ├── speculative_retriever.rs
│ └── consolidation_scheduler.rs
├── codebase/ # CrossProjectLearner backing
│ ├── git.rs # Git history analysis
│ ├── relationships.rs # File-file co-edit patterns
│ └── types.rs
└── session/ # Session-level tracking
└── mod.rs
```
### 3.5 Neuroscience modules (16)
| Module | Citation / basis | Purpose |
|---|---|---|
| `ActivationNetwork` | Collins & Loftus 1975 | Spreading activation across memory graph |
| `SynapticTaggingSystem` | Frey & Morris 1997 | Retroactive importance: memories in last 9h get boosted when big event fires |
| `HippocampalIndex` | Teyler & Rudy 2007 | Graph-level indexing; "dentate gyrus pattern separator" |
| `ContextMatcher` | Tulving 1973 | Encoding specificity — context overlap boosts retrieval by up to 30% |
| `AccessibilityCalculator` | Bjork & Bjork 1992 | `accessibility = retention × 0.5 + retrieval × 0.3 + storage × 0.2` |
| `CompetitionManager` | Anderson 1994 | Retrieval-induced forgetting — winners strengthen, competitors weaken |
| `StateUpdateService` | — | FSRS state transitions + append-only log |
| `ImportanceSignals` (4 channels) | Novelty / Arousal / Reward / Attention | Composite importance score, threshold 0.6 |
| `EmotionalMemory` | Brown & Kulik 1977 | Flashbulb memories — high-arousal events encode stronger |
| `PredictiveMemory` | Friston 2010 | Active inference — predict user needs before they ask |
| `ProspectiveMemory` | — | Intentions ("remind me when...") |
| `IntentionParser` | — | Natural-language → structured intention trigger |
| `MemoryState` (enum) | Bjork & Bjork 1992 | Active ≥0.7 / Dormant ≥0.4 / Silent ≥0.1 / Unavailable <0.1 |
| `Rac1Cascade` (v2.0.5) | Cervantes-Sandoval & Davis 2020 | Actin-destabilization-mediated forgetting of co-activated neighbors |
| `Suppression` (v2.0.5) | Anderson 2025 SIF | Top-down inhibitory control; compounds; 24h reversible labile window |
| `Reconsolidation` | Nader 2000 | 5-minute labile window after access; up to 10 modifications |
### 3.6 Advanced modules (11)
| Module | Purpose | Key methods |
|---|---|---|
| `ImportanceTracker` | Aggregates 4-channel score history | `record()`, `get_composite()` |
| `ReconsolidationManager` | Nader labile window state machine | `mark_labile()`, `apply_modification()`, `reconsolidate()` |
| `IntentDetector` | 9 intent types (Question, Decision, Plan, etc.) | `detect()` |
| `ActivityTracker` | Session-level active memory | `record_access()`, `recent()` |
| `MemoryDreamer` | 5-stage consolidation: Replay → Cross-reference → Strengthen → Prune → Transfer. Uses Waking SWR tagging (70% tagged + 30% random for diversity) | `dream(memory_count)` |
| `MemoryChainBuilder` | A*-like pathfinding between memories | `build_chain(from, to)` |
| `MemoryCompressor` | Semantic compression for 30+ day old memories | `compress(group)` |
| `CrossProjectLearner` | 6 pattern types (ErrorHandling, AsyncConcurrency, Testing, Architecture, Performance, Security) | `find_universal_patterns()`, `apply_to_project()` |
| `AdaptiveEmbedder` | Matryoshka-truncation tier selection | `embed_adaptive()` |
| `SpeculativeRetriever` | 6 trigger types for proactive memory fetch | `predict_needed_memories()` |
| `ConsolidationScheduler` | Runs FSRS decay cycle on interval (default 6h, env-configurable) | `start()` |
### 3.7 Storage
- SQLite via rusqlite 0.38, WAL mode, `Mutex<Connection>` split between reader and writer.
- FTS5 for keyword search (`bm25(10.0, 5.0, 1.0)` weights).
- Migrations V1..V11. **V11 (2026-04-19)** drops the dead `knowledge_edges` and `compressed_memories` tables that were reserved but never used.
- Append-only audit logs: `state_transitions`, `consolidation_history`, `dream_history`.
### 3.8 Embeddings
- Default: **Nomic Embed Text v1.5** via fastembed (ONNX, 768D).
- Matryoshka truncation to 256D for fast HNSW lookups (20× faster than full 768D).
- HyDE query expansion (generate a hypothetical document, embed it, search by its embedding).
- **v2.1 scaffolding:** Qwen3 embedding backend via Candle behind `qwen3-embed` feature. `qwen3_format_query()` helper prepends the instruction prefix ("Given a web search query, retrieve relevant passages that answer the query").
- Embedding cache: in-memory LRU; disk-warm on first run (~130MB for Nomic, ~500MB for Qwen3).
### 3.9 Vector search
- USearch HNSW (pinned 2.23.0; 2.24.0 regressed on MSVC per usearch#746). Int8 quantization.
- Hybrid scoring: `combined = 0.3 × BM25 + 0.7 × cosine` (default, user-tunable).
- `DEFAULT_DIMENSIONS` feature-gated: 256 on default, 1024 under `qwen3-embed`.
### 3.10 FSRS-6
- 21 trained parameters (Jarrett Ye / maimemo; trained on 700M+ Anki reviews).
- `R(t) = (1 + factor × t / S)^(-w20)` — power-law forgetting curve.
- 20-30% more efficient than SM-2 (Anki's original algorithm).
- Retrievability, stability, difficulty tracked per node.
- Dual-strength (Bjork & Bjork 1992): storage strength grows monotonically, retrieval strength decays.
### 3.11 Test count
- **364 `#[test]` annotations in vestige-core** across 47 test-bearing files.
- Examples: `cargo test --workspace` → 1,292 passing (includes 366 core + 425 mcp + e2e + journey).
---
## 4. `vestige-mcp` — MCP Server + Dashboard Backend
### 4.1 Purpose
Binary crate. Wraps `vestige-core` behind an MCP JSON-RPC 2.0 server, plus an embedded Axum HTTP server that hosts the dashboard, WebSocket event bus, and REST API.
### 4.2 Binaries
| Binary | Source | Purpose |
|---|---|---|
| `vestige-mcp` | `src/main.rs` | **Primary.** MCP JSON-RPC over stdio + optional HTTP transport. Hosts dashboard at `/dashboard/`. |
| `vestige` | `src/bin/cli.rs` | CLI: stats, consolidate, backup, restore, export, gc, dashboard launcher. |
| `vestige-restore` | `src/bin/restore.rs` | Standalone batch restore from JSON backup. |
### 4.3 Environment variables
| Var | Default | Purpose |
|---|---|---|
| `VESTIGE_DASHBOARD_PORT` | `3927` | Dashboard HTTP + WebSocket port |
| `VESTIGE_HTTP_PORT` | `3928` | Optional MCP-over-HTTP port |
| `VESTIGE_HTTP_BIND` | `127.0.0.1` | HTTP bind address |
| `VESTIGE_AUTH_TOKEN` | auto-generated | Dashboard bearer auth |
| `VESTIGE_CONSOLIDATION_INTERVAL_HOURS` | `6` | FSRS decay cycle cadence |
| `VESTIGE_DASHBOARD_ENABLED` | `true` | Toggle dashboard on/off |
| `VESTIGE_SYSTEM_PROMPT_MODE` | `minimal` | `full` enables the extended `build_instructions` block |
| `RUST_LOG` | `info` | tracing filter |
### 4.4 The 24 MCP tools
Every tool implemented in `src/tools/*.rs`. JSON schemas are programmatically emitted from `schema()` functions on each module.
1. **`session_context`** — one-call session init. Params: `queries[]`, `context{codebase, topics, file}`, `token_budget` (100-100000), `include_status`, `include_intentions`, `include_predictions`. Returns markdown context + `automationTriggers` (needsDream, needsBackup, needsGc) + `expandable` overflow IDs.
2. **`smart_ingest`** — single or batch ingest with Prediction Error Gating (similarity >0.92 → UPDATE, 0.75-0.92 → UPDATE/SUPERSEDE, <0.75 → CREATE). Params: `content`, `tags[]`, `node_type`, `source`, `forceCreate`, OR `items[]` (up to 20). Runs full cognitive pipeline.
3. **`search`** — 7-stage cognitive search. Params: `query`, `limit` (1-100), `min_retention`, `min_similarity`, `detail_level` (brief/summary/full), `context_topics[]`, `token_budget`, `retrieval_mode` (precise/balanced/exhaustive). **Strengthens retrieved memories via testing effect.**
4. **`memory`** — CRUD + promote/demote. `action` ∈ `{get, edit, delete, promote, demote, state, get_batch}`. `get_batch` takes up to 20 IDs. Edit preserves FSRS state, regenerates embedding.
5. **`codebase`** — Remember patterns & decisions. Actions: `remember_pattern`, `remember_decision`, `get_context`. Feeds CrossProjectLearner.
6. **`intention`** — Prospective memory. Actions: `set` (with trigger types time/context/event), `check`, `update`, `list`. Supports `include_snoozed` (v2.0.7 fix).
7. **`dream`** — 5-stage consolidation cycle. Param: `memory_count` (default 50). Returns insights, connections found, memories replayed, duration.
8. **`explore_connections`** — Graph traversal. Actions: `associations` (spreading activation), `chain` (A*-like path), `bridges` (connecting memories between two concepts).
9. **`predict`** — Proactive retrieval via SpeculativeRetriever. Param: `context{codebase, current_file, current_topics[]}`. Returns predictions with confidence + reasoning. Has a `predict_degraded` flag (v2.0.7) that surfaces warnings instead of silent empty responses.
10. **`importance_score`** — 4-channel scoring. Param: `content`, `context_topics[]`, `project`. Returns `{composite, channels{novelty, arousal, reward, attention}, recommendation}`.
11. **`find_duplicates`** — Cosine similarity clustering. Params: `similarity_threshold` (default 0.80), `limit`, `tags[]`. Returns merge/review suggestions.
12. **`memory_timeline`** — Chronological browse. Params: `start`, `end`, `node_type`, `tags[]`, `limit`, `detail_level`.
13. **`memory_changelog`** — Audit trail. Per-memory mode (by `memory_id`) or system-wide (with optional `start`/`end` ISO bounds, v2.0.7 fix adds 4× over-fetch when bounded).
14. **`memory_health`** — Retention dashboard. Returns avg retention, distribution buckets (0-20%, 20-40%, ...), trend, recommendation.
15. **`memory_graph`** — Visualization export. Params: `query` OR `center_id`, `depth` (default 2), `max_nodes` (default 50). Returns nodes with force-directed positions + edges with weights.
16. **`deep_reference`** — **★ THE killer tool.** 8-stage cognitive reasoning:
1. Broad retrieval + cross-encoder reranking.
2. Spreading activation expansion.
3. FSRS-6 trust scoring (retention × stability × reps ÷ lapses).
4. Intent classification (FactCheck / Timeline / RootCause / Comparison / Synthesis).
5. Temporal supersession.
6. Trust-weighted contradiction analysis.
7. Relation assessment (Supports / Contradicts / Supersedes / Irrelevant).
8. Template reasoning chain — pre-built natural-language conclusion the AI validates.
Returns `{intent, reasoning, recommended, evidence, contradictions, superseded, evolution, related_insights, confidence}`.
17. **`cross_reference`** — Backward-compat alias that calls `deep_reference`. Kept for v1.x users.
18. **`system_status`** — Full health + stats + warnings + recommendations. Used by `session_context` when `include_status=true`.
19. **`consolidate`** — FSRS-6 decay cycle + embedding generation pass. Returns counts.
20. **`backup`** — SQLite backup to `~/.vestige/backups/` with timestamp.
21. **`export`** — JSON/JSONL export. Params: `format`, `tags[]`, `since`. v2.0.7 defensive `Err` on unknown format (was `unreachable!()`).
22. **`gc`** — Garbage collect. Params: `min_retention` (default 0.1), `dry_run` (default true). Dry-run first, then execute.
23. **`restore`** — Restore from backup. Param: `path`.
24. **`suppress`** / **`unsuppress`** (v2.0.5 "Intentional Amnesia") — Top-down inhibition. `suppress(id, reason?)` compounds (`suppressionCount` increments); `unsuppress(id)` reverses if within 24h labile window. Also exposed as dashboard HTTP endpoints (v2.0.7: `POST /api/memories/{id}/suppress` + `/unsuppress`).
### 4.5 MCP server internals
- `src/server.rs` — JSON-RPC 2.0 over stdio, optional HTTP. Handles `initialize`, `tools/list`, `tools/call`.
- **`build_instructions()`** — constructs the `instructions` string returned by `initialize`. Gated on `VESTIGE_SYSTEM_PROMPT_MODE=full`. Full mode emits an extended cognitive-protocol system prompt; default is concise.
- **CognitiveEngine** (`src/cognitive/mod.rs`) — async wrapper around `Arc<Storage>` + broadcast channel. Holds the WebSocket event sender.
- **Tool dispatch** — every `tools/call` invocation is routed to a `execute_*` function by tool name.
### 4.6 Dashboard HTTP backend (`src/dashboard/`)
- `src/dashboard/mod.rs` — Axum `Router` assembly.
- `src/dashboard/handlers.rs` — all REST handlers (~30 routes).
- `src/dashboard/static_files.rs` — embeds `apps/dashboard/build/` via `include_dir!` at compile time.
- `src/dashboard/state.rs` — `AppState { storage, event_tx, start_time }`.
- `src/dashboard/websocket.rs` — `/ws` upgrade handler with Origin validation (localhost + 127.0.0.1 + dev :5173), 64KB frame cap, 256KB message cap, heartbeat task every 5s.
**Heartbeat payload (v2.0.7):** `{type: "Heartbeat", data: {uptime_secs, memory_count, avg_retention, suppressed_count, timestamp}}`. The `uptime_secs` is what powers the sidebar footer's `formatUptime()` display ("3d 4h" / "18m 43s").
### 4.7 WebSocket event bus — 19 VestigeEvent types
Emitted from the `CognitiveEngine` broadcast channel to every connected dashboard client:
| Event | When emitted | Dashboard visual |
|---|---|---|
| `Connected` | WebSocket upgrade complete | Cyan ripple (v2.0.6) |
| `Heartbeat` | Every 5s | Silent (updates sidebar stats) |
| `MemoryCreated` | Any ingest that produces a new node | Rainbow burst + double shockwave + ripple |
| `MemoryUpdated` | Smart_ingest UPDATE path | Pulse at node |
| `MemoryDeleted` | `memory({action: "delete"})` | Dissolution animation |
| `MemoryPromoted` | `memory({action: "promote"})` | Green pulse + sparkle |
| `MemoryDemoted` | `memory({action: "demote"})` | Orange pulse + fade |
| `MemorySuppressed` | `suppress(id)` (v2.0.5) | Violet implosion (v2.0.7) |
| `MemoryUnsuppressed` | `unsuppress(id)` (v2.0.5) | Rainbow reversal (v2.0.7) |
| `Rac1CascadeSwept` | Rac1 worker completes cascade (72h async) | Violet wave pulse (v2.0.6) |
| `SearchPerformed` | Every `search()` call | Cyan flash + PipelineVisualizer 7-stage animation in `/feed` |
| `DreamStarted` | `dream()` begins | Scene enters dream mode (2s lerp) |
| `DreamProgress` | Per-stage updates during dream | Aurora hue cycle |
| `DreamCompleted` | Dream finishes, insights generated | Scene exits dream mode |
| `ConsolidationStarted` | FSRS consolidation cycle starts | Amber warning pulse (v2.0.6) |
| `ConsolidationCompleted` | Consolidation finishes | Green confirmation pulse |
| `RetentionDecayed` | Node's retention drops below threshold during consolidation | Red decay pulse |
| `ConnectionDiscovered` | Dream or spreading activation finds new edge | **Cyan flash on edge (already fires — NOT yet surfaced as a toast; see v2.2 "Pulse")** |
| `ActivationSpread` | Spreading activation from a memory | Turquoise ripple (v2.0.6) |
| `ImportanceScored` | `importance_score()` or internal scoring event | Hot-pink pulse (v2.0.6, magenta) |
### 4.8 Dashboard REST API
All routes under `/api/`:
| Method | Path | Purpose |
|---|---|---|
| GET | `/api/health` | Health check (status, version, memory count) |
| GET | `/api/stats` | Full stats (same surface as `system_status` tool) |
| GET | `/api/memories` | List memories with filters (q, node_type, tag, min_retention) |
| GET | `/api/memories/{id}` | Single memory detail |
| POST | `/api/memories` | Create memory (raw ingest) |
| DELETE | `/api/memories/{id}` | Delete |
| POST | `/api/memories/{id}/promote` | Promote (+0.20 retrieval, +0.10 retention, 1.5× stability) |
| POST | `/api/memories/{id}/demote` | Demote (−0.30 retrieval, −0.15 retention, 0.5× stability) |
| POST | `/api/memories/{id}/suppress` | v2.0.7: compound suppression |
| POST | `/api/memories/{id}/unsuppress` | v2.0.7: reverse within 24h labile window |
| POST | `/api/search` | Hybrid search (keyword + semantic weights) |
| POST | `/api/ingest` | Smart ingest (PE gating) |
| GET | `/api/graph` | Graph visualization export |
| POST | `/api/explore` | Actions: associations / chains / bridges |
| POST | `/api/dream` | Run dream cycle |
| POST | `/api/consolidate` | Run FSRS decay cycle |
| POST | `/api/predict` | Proactive predictions |
| POST | `/api/importance` | 4-channel score |
| GET | `/api/timeline` | Chronological |
| GET | `/api/intentions` | List intentions (filter by status) |
| GET | `/api/retention-distribution` | Bucketed histogram |
WebSocket: `GET /ws` (upgrade) — one broadcast channel, any connected client gets all events.
### 4.9 vestige-mcp feature flags
| Flag | Purpose | Default |
|---|---|---|
| `embeddings` | Forward to vestige-core | yes |
| `vector-search` | Forward to vestige-core | yes |
| `ort-dynamic` | Forward to vestige-core | no |
Build commands (from CONTRIBUTING.md):
- Full: `cargo install --path crates/vestige-mcp`
- No-embeddings (tiny): `cargo install --path crates/vestige-mcp --no-default-features`
- Dynamic ORT (glibc < 2.38): `cargo install --path crates/vestige-mcp --no-default-features --features ort-dynamic,vector-search`
---
## 5. `apps/dashboard` — SvelteKit + Three.js Frontend
### 5.1 Purpose
Interactive 3D graph + CRUD + analytics dashboard. Built with SvelteKit 2 + Svelte 5 runes, embedded into the Rust binary via `include_dir!` and served at `/dashboard/`.
### 5.2 Tech stack
- **SvelteKit 2.53** + **Svelte 5.53** (runes: `$state`, `$props`, `$derived`, `$effect`).
- **Three.js 0.172** — WebGL, MSAA, ACESFilmic tone mapping.
- **Tailwind CSS 4.2** — custom `@theme` block (synapse, dream, memory, recall, decay colors + 8 node-type palette).
- **TypeScript 5.9** — strict mode.
- **Vite 6.4** + **Vitest 4.0.18** (251 tests).
- **@playwright/test 1.58** — E2E ready (journeys live in `tests/vestige-e2e-tests/`).
### 5.3 Routes (SvelteKit file-based)
Grouped under `(app)/`:
| Route | File | Purpose |
|---|---|---|
| `/` | `+page.svelte` | Redirect to `/graph` |
| `(app)/graph` | `+page.svelte` | **Primary 3D graph** (Graph3D component + color mode toggle + time slider + right panel for detail + legend overlay v2.0.8) |
| `(app)/memories` | `+page.svelte` | Memory browser (search, filter by type/tag/retention, suppress button v2.0.7) |
| `(app)/intentions` | `+page.svelte` | Prospective memory + predictions (status tabs, trigger icons, priority labels) |
| `(app)/stats` | `+page.svelte` | Health dashboard, retention distribution, endangered memories, run-consolidation button |
| `(app)/timeline` | `+page.svelte` | Chronological browse (days dropdown, expandable day cards) |
| `(app)/feed` | `+page.svelte` | Live event stream (200-event FIFO buffer, PipelineVisualizer on SearchPerformed) |
| `(app)/explore` | `+page.svelte` | Associations / Chains / Bridges mode toggle + Importance Scorer |
| `(app)/settings` | `+page.svelte` | Operations + config + keyboard shortcuts reference |
### 5.4 Root layout (`src/routes/+layout.svelte`)
- Desktop sidebar (8 nav items) + mobile bottom nav (5 items).
- **Command palette (⌘K)** — opens a search bar that navigates.
- **Single-key shortcuts** — G/M/T/F/E/I/S for routes.
- **Status footer** — connection indicator, memory count, avg retention, suppressed count (v2.0.5), uptime (v2.0.7: `up {formatUptime($uptimeSeconds)}`).
- **ForgettingIndicator** — violet badge showing suppressed count.
- Ambient orb background animations (CSS).
### 5.5 Components (`src/lib/components/`)
| Component | Purpose |
|---|---|
| `Graph3D.svelte` | **The 3D canvas.** Props: `nodes[]`, `edges[]`, `centerId`, `events[]`, `isDreaming`, `colorMode` (v2.0.8), `onSelect`, `onGraphMutation`. Owns the Three.js scene and all module init. |
| `MemoryStateLegend.svelte` (v2.0.8) | Floating overlay explaining 4 FSRS buckets — only renders when `colorMode === 'state'`. |
| `PipelineVisualizer.svelte` | 7-stage cognitive search animation (Overfetch → Rerank → Temporal → Access → Context → Compete → Activate). Shown in `/feed` when SearchPerformed arrives. |
| `RetentionCurve.svelte` | SVG FSRS-6 decay curve in the graph right panel. `R(t) = e^(-t/S)` with predictions at Now / 1d / 7d / 30d. |
| `TimeSlider.svelte` | Temporal playback scrubber. State: enabled, playing, speed (0.5-2×), sliderValue. Callbacks `onDateChange`, `onToggle`. |
| `ForgettingIndicator.svelte` | Violet badge in sidebar showing suppressed count from Heartbeat. |
### 5.6 Three.js graph system (`src/lib/graph/`)
| File | Role |
|---|---|
| `nodes.ts` | `NodeManager`. Fibonacci sphere initial positions, materialize/dissolve/grow animations, shared radial-gradient glow texture (128px) that prevents square bloom artifacts (issue #31). **v2.0.8:** `ColorMode` ('type' / 'state'), `getMemoryState(retention)`, `MEMORY_STATE_COLORS`, `MEMORY_STATE_DESCRIPTIONS`, `setColorMode(mode)` idempotent in-place retint. **2026-04-19:** dark-glass-pill label redesign (dimmer `#94a3b8` slate on `rgba(10,16,28,0.82)` pill with hairline stroke). |
| `edges.ts` | `EdgeManager`. Violet `#8b5cf6` lines; opacity = 25% + 50% × weight, capped at 80%. Grow/dissolve animations. |
| `force-sim.ts` | Repulsion 500, attraction 0.01 × edge weight × distance, damping 0.9, centering 0.001α. N² but fine up to ~1000 nodes at 60fps. |
| `particles.ts` | `ParticleSystem`. Starfield (3000 points on spherical shell r=600-1000) + neural particles (500 oscillating sin-wave). |
| `effects.ts` | `EffectManager`. 12 effect types (SpawnBurst, Shockwave, RainbowBurst, RippleWave, Implosion, Pulse, ConnectionFlash, etc.). |
| `events.ts` | `mapEventToEffects()` — maps every one of the 19 VestigeEvent variants to a visual effect. Live-spawn mechanics: new nodes spawn near semantically related existing nodes (tag + type scoring), FIFO eviction at 50 nodes. |
| `scene.ts` | Scene factory. Camera 60° FOV at (0, 30, 80). ACESFilmic tone mapping, exposure 1.25, pixel ratio clamped ≤2×. **UnrealBloomPass:** strength 0.55, radius 0.6, threshold 0.2 (retuned v2.0.8 for radial-gradient sprites). OrbitControls with auto-rotate 0.3°/frame. |
| `dream-mode.ts` | Smooth 2s lerp between NORMAL (bloom 0.8, rotate 0.3, fog dense) and DREAM (bloom 1.8, rotate 0.08, nebula 1.0, chromatic 0.005). Aurora lights cycle hue in dream. |
| `temporal.ts` | `filterByDate(nodes, edges, cutoff)`, `retentionAtDate(current, stability, created, target)` using FSRS decay formula. Enables the TimeSlider preview. |
| `shaders/nebula.frag.ts` | Nebula background fragment shader (purple → cyan → magenta cycle with turbulence). |
| `shaders/post-processing.ts` | Chromatic aberration, vignette, subtle distortion. Parameters lerp with dream-mode. |
### 5.7 Stores (`src/lib/stores/`)
| Store | Exports | Purpose |
|---|---|---|
| `api.ts` | `api.memories.*`, `api.search`, `api.graph`, `api.explore`, `api.stats`, `api.health`, `api.retentionDistribution`, `api.timeline`, `api.dream`, `api.consolidate`, `api.predict`, `api.importance`, `api.intentions` | 23 REST client methods |
| `websocket.ts` | `websocket` (writable), `isConnected`, `eventFeed`, `heartbeat`, `memoryCount`, `avgRetention`, `suppressedCount`, `uptimeSeconds`, `formatUptime(secs)` | WebSocket connection + derived state. FIFO 200-event ring buffer. Exponential backoff reconnect (1s → 30s). |
| `graph-state.svelte.ts` | (unused artifact from v2.0.6) | — |
### 5.8 Types (`src/lib/types/index.ts`)
Exported: `Memory`, `SearchResult`, `MemoryListResponse`, `SystemStats`, `HealthCheck`, `RetentionDistribution`, `GraphNode`, `GraphEdge`, `GraphResponse`, `DreamResult`, `DreamInsight`, `ImportanceScore`, `ConsolidationResult`, `SuppressResult`, `UnsuppressResult`, `IntentionItem`, `VestigeEventType`, `VestigeEvent`, `NODE_TYPE_COLORS` (8 types), `EVENT_TYPE_COLORS` (19 events), `ColorMode`, `MemoryState` (v2.0.8).
### 5.9 Tests (`src/lib/graph/__tests__/`)
| File | Tests | Lines | Covers |
|---|---|---|---|
| `color-mode.test.ts` **(v2.0.8, new)** | 80 | 664 | `getMemoryState` boundaries (12 retentions including NaN/±∞/>1/<0), palette integrity, `getNodeColor` dispatch, `NodeManager.setColorMode` idempotence + in-place retint + userData preservation + suppression channel isolation |
| `nodes.test.ts` | 32 | 456 | NodeManager lifecycle, easings, Fibonacci distribution |
| `edges.test.ts` | 21 | 314 | EdgeManager grow/dissolve, opacity-by-weight |
| `force-sim.test.ts` | 19 | 257 | Physics convergence, add/remove |
| `effects.test.ts` | 30 | 500 | All 12 effect types |
| `events.test.ts` | 48 | 864 | Every one of the 19 event handlers + live-spawn + eviction |
| `ui-fixes.test.ts` | 21 | 236 | Bloom retuning, glow-texture gradient, fog density, regression tests for issue #31 |
| **Total** | **251** | **3,291** | |
Infrastructure: `three-mock.ts` (Scene / Mesh / Sprite / Material mocks), `setup.ts` (canvas context mocks including `beginPath`/`closePath`/`quadraticCurveTo` added tonight for the pill redesign), `helpers.ts` (node/edge/event factories).
### 5.10 Build
- `pnpm run build` → static SPA in `apps/dashboard/build/`.
- Precompressed `.br` + `.gz` per asset (adapter-static).
- **Embedded into `vestige-mcp` binary** at compile time via `include_dir!("$CARGO_MANIFEST_DIR/../../apps/dashboard/build")`. Every Rust build rebakes the dashboard snapshot.
---
## 6. Integrations & Packaging
### 6.1 IDE integration matrix (`docs/integrations/*.md`)
All 8 IDEs documented. The common install flow: (a) download `vestige-mcp` binary, (b) point IDE's MCP config at its absolute path, (c) restart IDE, (d) verify with `/context` or equivalent.
| IDE | Config path | Notable |
|---|---|---|
| Claude Code | `~/.claude.json` or project `.mcp.json` | Inline in `CONFIGURATION.md`; one-liner install |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | Inline in `CONFIGURATION.md` |
| Cursor | `~/.cursor/mcp.json` | Absolute paths required (Cursor doesn't resolve relatives reliably) |
| VS Code (Copilot) | `.vscode/mcp.json` OR User via command | **Uses `"servers"` key, NOT `"mcpServers"`** — Copilot-specific schema. Requires agent mode enabled. |
| Codex | `~/.codex/config.toml` | TOML not JSON. `codex mcp add vestige -- /usr/local/bin/vestige-mcp` helper. |
| Xcode | Project-level `.mcp.json` | **Xcode 26.3's `claudeai-mcp` feature gate blocks global config. Project-level `.mcp.json` in project root bypasses entirely.** First cognitive memory server for Xcode. Sandboxed agents do NOT inherit shell env — absolute paths mandatory. |
| JetBrains / Junie | `.junie/mcp/mcp.json` or UI config | 2025.2+. Three paths: Junie autoconfig, Junie AI config, external MCP client. |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Supports `${env:HOME}` variable expansion. Cascade AI. |
### 6.2 npm packages
| Package | Version | Role |
|---|---|---|
| `vestige-mcp-server` (in `packages/vestige-mcp-npm`) | 2.0.7 | Binary wrapper — postinstall downloads the platform-appropriate release asset from GitHub. Bins: `vestige-mcp`, `vestige`. |
| `@vestige/init` (in `packages/vestige-init`) | 2.0.7 | Interactive zero-config installer. Bin: `vestige-init`. |
| `packages/vestige-mcpb/` | — | Legacy, abandoned. |
**Publish status:** v2.0.6 is live on npm. **v2.0.7 pending Sam's Touch ID** (WebAuthn 2FA flow, not TOTP — has to be triggered from Sam's machine).
### 6.3 GitHub release workflow (`release.yml`)
Triggered on tag push (`v*`) OR manual `workflow_dispatch`. Matrix:
| Target | Runner | Artifact | Status |
|---|---|---|---|
| `aarch64-apple-darwin` | macos-latest | `vestige-mcp-aarch64-apple-darwin.tar.gz` | ✅ |
| `x86_64-unknown-linux-gnu` | ubuntu-latest | `vestige-mcp-x86_64-unknown-linux-gnu.tar.gz` | ✅ |
| `x86_64-pc-windows-msvc` | windows-latest | `vestige-mcp-x86_64-pc-windows-msvc.zip` | ✅ |
| `x86_64-apple-darwin` (Intel Mac) | **DROPPED in v2.0.7** | — | ❌ `ort-sys 2.0.0-rc.11` (pinned by fastembed 5.13.2) has no Intel Mac prebuilt |
Each artifact contains three binaries: `vestige-mcp`, `vestige`, `vestige-restore`.
### 6.4 CI workflow (`ci.yml`)
Triggers: push main + PR main. Runs on macos-latest + ubuntu-latest. Steps: `cargo check` → `cargo clippy --workspace -- -D warnings` → `cargo test --workspace`. **Tonight's fix:** Rust 1.95 introduced `unnecessary_sort_by` (12 sites fixed) + `collapsible_match` (1 site fixed in `memory_states.rs`, 1 `#[allow]` on `websocket.rs` because match guards can't move non-Copy `Bytes`).
### 6.5 Test workflow (`test.yml`)
5 parallel jobs: `unit-tests`, `mcp-tests`, `journey-tests` (depends on unit), `dashboard` (pnpm + vitest), `coverage` (LLVM + Codecov). Env: `VESTIGE_TEST_MOCK_EMBEDDINGS=1` to skip ONNX model download in CI.
### 6.6 Xcode setup script (`scripts/xcode-setup.sh`)
4.9 KB interactive installer. (a) detect/install binary, (b) offer project picker under `~/Developer`, (c) generate `.mcp.json`, (d) optionally batch-install to all detected projects. Supports SHA-256 checksum verification.
---
## 7. `vestige-cloud` — Current Skeleton
**Location:** `/Users/entity002/Developer/vestige-cloud` (separate git repo, private).
**Status as of 2026-04-19:** single-commit skeleton from 2026-02-12 (8 weeks old, one feature commit `4e181a6`). ~600 LOC.
### 7.1 Structure
```
vestige-cloud/
├── Cargo.toml # workspace, path-dep on ../vestige/crates/vestige-core
├── Cargo.lock
└── crates/
└── vestige-http/
├── Cargo.toml # binary: vestige-http
└── src/
├── main.rs # Axum server on :3927, auth + cors middleware
chore: remove 3,091 LOC of orphan code + fix ghost env-var docs Nine tool modules in crates/vestige-mcp/src/tools/ had zero callers after the v2.0.x unification work shipped *_unified + maintenance::* replacements. They'd been #[allow(dead_code)]-papered over and forgotten. Verified each module independently: grep for tools::<name>::, string dispatch in server.rs, cross-crate usage — all nine returned zero external callers. Removed modules (all superseded): checkpoint (364 LOC) — no callers anywhere codebase (298) — superseded by codebase_unified consolidate (36) — superseded by maintenance::execute_consolidate ingest (456) — superseded by smart_ingest intentions (1,093) — superseded by intention_unified knowledge (106) — no callers anywhere recall (403) — superseded by search_unified search (184) — superseded by search_unified stats (132) — superseded by maintenance::execute_system_status Also removed: - EmotionCategory::base_arousal (10 LOC, zero callers) Kept (still string-dispatched from server.rs): - context, feedback, memory_states, review, tagging Doc fixes (ghost env vars that were documented but zero Rust source reads): - docs/CONFIGURATION.md — dropped VESTIGE_DATA_DIR, VESTIGE_LOG_LEVEL rows (neither is read anywhere; --data-dir CLI flag + RUST_LOG are the real mechanisms). Added the full real env-var table. - packages/vestige-mcp-npm/README.md — same two ghost rows dropped - docs/VESTIGE_STATE_AND_PLAN.md:399 — dropped VESTIGE_DATA_DIR row - docs/VESTIGE_STATE_AND_PLAN.md:709 — typo VESTIGE_API_KEY -> VESTIGE_AUTH_TOKEN (matches shipping convention), "open if unset" -> "auto-generated if unset" to match actual behavior Verified post-cleanup: - cargo check --workspace clean - cargo clippy --workspace -D warnings clean - cargo test --workspace 1,223 passing / 0 failed - cargo build --release -p vestige-mcp clean Net: -3,091 LOC (14 files), zero behavior change, zero regressions.
2026-04-23 03:18:53 -05:00
├── auth.rs # Single bearer token via VESTIGE_AUTH_TOKEN env (auto-generated if unset, stored in data-dir)
v2.0.8 Pulse — Reasoning Theater + Pulse Toast + Terrarium + Intel Mac (#44) * docs: anti-hedging banner + master state-and-plan + UI roadmap Project-level CLAUDE.md line 1 is now the anti-hedging banner referencing the global rule at /Users/entity002/CLAUDE.md. When Sam commits to an execution path (content cadence, shipping velocity, outreach, launch), forecasts compute as if the commitment is already met — no discounting by execution probability. VESTIGE_STATE_AND_PLAN.md (1135 lines, 14 parts): single-page reference any AI agent can read to plan the next phase without re-reading the repo. Covers current state of every crate, the 24 MCP tools, the 19 WebSocket event types, the 8 IDE integrations, and v2.1 through v3.0 roadmap. UI_ROADMAP_v2.1_v2.2.md: compiled UI-gap analysis from 4 parallel research agents (April 19). 10 critical UI gaps + 2026 bleeding-edge patterns + unclaimed territory (menu bar widget, voice-first, AR/VR, time-scrubber). * feat(v2.2-pulse): InsightToast + multi-process STORAGE docs Two independent ship items landing together on the v2.2 branch ahead of the Tuesday launch — a new UI surface that makes Vestige's cognitive events visible in real time, and honest documentation of the multi-process safety story that underpins the Stigmergic Swarm narrative. **InsightToast** (apps/dashboard/src/lib/components/InsightToast.svelte, apps/dashboard/src/lib/stores/toast.ts): The dashboard already had a working WebSocket event stream on ws://localhost:3927/ws that broadcast every cognitive event (dream completions, consolidation sweeps, memory promotions/demotions, active- forgetting suppression and Rac1 cascades, bridge discoveries). None of that was surfaced to a user looking at anything other than the raw feed view. InsightToast subscribes to the existing eventFeed derived store, filters the spammy lifecycle events (Heartbeat, SearchPerformed, RetentionDecayed, ActivationSpread, ImportanceScored, MemoryCreated), and translates the narrative events into ephemeral toasts with a bioluminescent colored accent matching EVENT_TYPE_COLORS. Design notes: - Rate-limited ConnectionDiscovered at 1.5s intervals (dreams emit many). - Max 4 visible toasts, auto-dismiss at 4.5-7s depending on event weight. - Click or Enter/Space to dismiss early. - Bottom-right on desktop, top-banner on mobile. - Reduced-motion honored via prefers-reduced-motion. - Zero new websocket subscriptions — everything piggybacks on the existing derived store. Also added a "Preview Pulse" button to Settings -> Cognitive Operations that fires a synthetic sequence of four toasts (DreamCompleted, ConnectionDiscovered, MemorySuppressed, ConsolidationCompleted) so the animation is demoable without waiting for real cognitive activity. **Multi-Process Safety section in docs/STORAGE.md**: Grounds the Stigmergic Swarm story with concrete tables of what the current WAL + 5s busy_timeout configuration actually supports vs what remains experimental. Key honest points: - Shared --data-dir + ONE vestige-mcp + N clients is the shipping pattern for multi-agent coordination. - Two vestige-mcp processes writing the same file is experimental — documented with the lsof + pkill recovery path. - Roadmap lists the three items that would promote it to "supported": advisory file lock, retry-with-jitter on SQLITE_BUSY, and a concurrent-writer load test. Build + typecheck: - npm run check: 0 errors, 0 warnings across 583 files - npm run build: clean static build, adapter-static succeeds * feat(v2.3-terrarium): Memory Birth Ritual + event pipeline fix v2.3 "Terrarium" headline feature. When a MemoryCreated event arrives, a glowing orb materialises in the cosmic center (camera-relative z=-40), gestates for ~800ms growing from a tiny spark into a full orb, then arcs along a dynamic quadratic Bezier curve to the live position of the real node, and on arrival hands off to the existing RainbowBurst + Shockwave + RippleWave cascade. The target position is re-resolved every frame so the force simulation can move the destination during flight without the orb losing its mark. **New primitive — EffectManager.createBirthOrb()** (effects.ts): Accepts a camera, a color, a live target-position getter, and an arrival callback. Owns a sprite pair (outer halo + inner bright core), both depthTest:false with renderOrder 999/1000 so the orb is always visible through the starfield and the graph. - Gestation phase: easeOutCubic growth + sinusoidal pulse, halo tints from neutral to event color as the ritual charges. - Flight phase: QuadraticBezierCurve3 with control point at midpoint raised on Y by 30 + 15% of orb-to-target distance (shooting-star arc). Sampled with easeInOutQuad. Orb shrinks ~35% approaching target. - Arrival: fires onArrive callback once, then fades out over 8 frames while expanding slightly (energy dispersal). - Caller's onArrive triggers the burst cascade at arrivePos (NOT the original spawnPos — the force sim may have moved the target during the ritual, so we re-read nodeManager.positions on arrival). - Dispose path integrated with existing EffectManager.dispose(). **Event pipeline fix — Graph3D.processEvents()**: Previously tracked `processedEventCount` assuming APPEND order, but websocket.ts PREPENDS new events (index 0) and caps the array at MAX_EVENTS. Result: only the first MemoryCreated event after page load fired correctly; subsequent ones reprocessed the oldest entry. Fixed to walk from index 0 until hitting the last-processed event by reference identity — correct regardless of array direction or eviction pressure. Events are then processed oldest-first so causes precede effects. Found while wiring the v2.3 demo button; would have manifested as "first orb only" in production. **Demo trigger** (Settings -> Birth Ritual Preview): Button that calls websocket.injectEvent() with a synthetic MemoryCreated event, cycling through node types (fact / concept / pattern / decision / person / place) to showcase the type-color mapping. Downstream consumers can't distinguish synthetic from real, so this drives the full ritual end-to-end. Intended for demo clip recording for the Wednesday launch. **Test coverage:** - events.test.ts now tests the v2.3 birth ritual path: spawns 2+ sprites in the scene immediately, and fires the full arrival cascade after driving the effects.update() loop past the ritual duration. - three-mock.ts extended with Vector3.addVectors, Vector3.applyQuaternion, Color.multiplyScalar, Quaternion, QuadraticBezierCurve3, Texture, and Object3D.quaternion/renderOrder so production code runs unaltered in tests. Build + typecheck: - npm run check: 0 errors, 0 warnings across 583 files - npm test: 251/251 pass (net +0 from v2.2) - npm run build: clean adapter-static output The Sanhedrin Shatter (anti-birth ritual for hallucination veto) needs server-side event plumbing and is deferred. Ship this as the Wednesday visual mic-drop. * fix(v2.3): 5 FATAL bugs + 4 god-tier upgrades from post-ship audit Post-ship audit surfaced 6 FATALs and 4 upgrades. Shipping 5 of the 6 + all 4 upgrades. FATAL 4 (VRAM hemorrhage from un-pooled label canvases in createTextSprite) is pre-existing, not from this session, and scoped separately for a proper texture-pool refactor. **FATAL 1 — Toast Silent Lobotomy** (stores/toast.ts) Subscriber tracked events[0] only. When Svelte batched multiple events in one update tick (swarm firing DreamCompleted + ConnectionDiscovered within the same millisecond), every event but the newest got silently dropped. Fixed to walk from index 0 until hitting lastSeen — same pattern as Graph3D.processEvents. Processes oldest-first to preserve narrative order. **FATAL 2 — Premature Birth** (graph/nodes.ts + graph/events.ts) Orb flight is 138 frames; materialization was 30 frames. Node popped fully grown ~100 frames before orb arrived — cheap UI glitch instead of a biological birth. Added `addNode(..., { isBirthRitual: true })` option that reserves the physics slot but hides mesh/glow/label and skips the materializing queue. New `igniteNode(id)` flips visibility and enqueues materialization. events.ts onArrive now calls igniteNode at the exact docking moment, so the elastic spring-up peaks on impact. **FATAL 3 — 120Hz ProMotion Time-Bomb** (components/Graph3D.svelte) All physics + effect counters are frame-based. On a 120Hz display every ritual ran at 2x speed. Added a `lastTime`-based governor in animate() that early-returns if dt < 16ms, clamping effective rate to ~60fps. `- (dt % 16)` carry avoids long-term drift. Zero API changes; tonight's fast fix until physics is rewritten to use dt. **FATAL 5 — Bezier GC Panic** (graph/effects.ts birth-orb update) Flight phase allocated a new Vector3 (control point) and a new QuadraticBezierCurve3 every frame per orb. With 3 orbs in flight that's 360 objects/sec for the GC to collect. Rewrote as inline algebraic evaluation — zero allocations per frame, identical curve. **FATAL 6 — Phantom Shockwave** (graph/events.ts) A 166ms setTimeout fired the 2nd shockwave. If the user navigated away during that window the scene was disposed, the timer still fired, and .add() on a dead scene threw unhandled rejection. Dropped the setTimeout entirely; both shockwaves fire immediately in onArrive with different scales/colors for the same layered-crash feel. **UPGRADE 1 — Sanhedrin Shatter** (graph/effects.ts birth-orb update) If getTargetPos() returns undefined AFTER gestation (target node was deleted mid-ritual — Stop hook sniping a hallucination), the orb turns blood-red, triggers a violent implosion in place, and skips the arrival cascade. Cognitive immune system made visible. **UPGRADE 2 — Newton's Cradle** (graph/events.ts onArrive) On docking the target mesh's scale gets bumped 1.8×, so the elastic materialization + force-sim springs physically recoil instead of the orb landing silently. The graph flinches when an idea is born into it. **UPGRADE 3 — Hover Panic** (stores/toast.ts + InsightToast.svelte) Paused dwell timer on mouseenter/focus, resume on mouseleave/blur. Stored remaining ms at pause so resume schedules a correctly-sized timer. CSS pairs via `animation-play-state: paused` on the progress bar. A toast the user is reading no longer dismisses mid-sentence. **UPGRADE 4 — Event Horizon Guard** (components/Graph3D.svelte) If >MAX_EVENTS (200) events arrive in one tick, lastProcessedEvent falls off the end of the array and the walk consumes ALL 200 entries as "fresh" — GPU meltdown from 200 simultaneous births. Detect the overflow and drop the batch with a console.warn, advancing the high-water mark so next frame is normal. Build + test: - npm run check: 0 errors, 0 warnings - npm test: 251/251 pass - npm run build: clean static build * test(v2.3): full e2e + integration coverage for Pulse + Birth Ritual Post-ship verification pass — five parallel write-agents produced 229 new tests across vitest units, vitest integration, and Playwright browser e2e. Net suite: 361 vitest pass (up from 251, +110) and 9/9 Playwright pass on back-to-back runs. **toast.test.ts (NEW, 661 lines, 42 tests)** Silent-lobotomy batch walk proven (multi-event tick processes ALL, not just newest, oldest-first ordering preserved). Hover-panic pause/resume with remaining-ms math. All 9 event type translations asserted, all 11 noise types asserted silent. ConnectionDiscovered 1500ms throttle. MAX_VISIBLE=4 eviction. clear() tears down all timers. fireDemoSequence staggers 4 toasts at 800ms intervals. vi.useFakeTimers + vi.mock of eventFeed; vi.resetModules in beforeEach for module-singleton isolation. **websocket.test.ts (NEW, 247 lines, 30 tests)** injectEvent adds to front, respects MAX_EVENTS=200 with FIFO eviction, triggers eventFeed emissions. All 6 derived stores (isConnected, heartbeat, memoryCount, avgRetention, suppressedCount, uptimeSeconds) verified — defaults, post-heartbeat values, clearEvents preserves lastHeartbeat. 13 formatUptime boundary cases (0/59/60/3599/3600/ 86399/86400 seconds + negative / NaN / ±Infinity). **effects.test.ts (EXTENDED, +501 lines, +21 tests, 51 total)** createBirthOrb full lifecycle — sprite count (halo + core), cosmic center via camera.quaternion, gestation phase (position lock, opacity rise, scale easing, color tint), flight Bezier arc above linear midpoint at t=0.5, dynamic mid-flight target redirect. onArrive fires exactly once at frame 139. Post-arrival fade + disposal cleans scene children. Sanhedrin Shatter: target goes undefined mid-flight → onArrive NEVER called, implosion spawned, halo blood-red, eventual cleanup. dispose() cleans active orbs. Multiple simultaneous orbs. Custom gestation/flight frame opts honored. Zero-alloc invariant smoke test (6 orbs × 150 frames, no leaks). **nodes.test.ts (EXTENDED, +197 lines, +10 tests, 42 total)** addNode({isBirthRitual:true}) hides mesh/glow/label immediately, stamps birthRitualPending sentinel with correct totalFrames + targetScale, does NOT enqueue materialization. igniteNode flips visibility + enqueues materialization. Idempotent — second call no-op. Non-ritual nodes unaffected. Unknown id is safe no-op. Position stored in positions map while invisible (force sim still sees it). removeNode + late igniteNode is safe. **events.test.ts (EXTENDED, +268 lines, +7 tests, 55 total)** MemoryCreated → mesh hidden immediately, 2 birth-orb sprites added, ZERO RingGeometry meshes and ZERO Points particles at spawn. Full ritual drive → onArrive fires, node visible + materializing, sentinel cleared. Newton's Cradle: target mesh scale exactly 0.001 * 1.8 right after arrival. Dual shockwave: exactly 2 Ring meshes added. Re-read live position on arrival — force-sim motion during ritual → burst lands at the NEW position. Sanhedrin abort path → rainbow burst, shockwave, ripple wave are NEVER called (vi.spyOn). **three-mock.ts (EXTENDED)** Added Color.setRGB — production Three.js has it, the Sanhedrin- Shatter path in effects.ts uses it. Two write-agents independently monkey-patched the mock inline; consolidated as a 5-line mock addition so tests stay clean. **e2e/pulse-toast.spec.ts (NEW, 235 lines, 6 Playwright tests)** Navigate /dashboard/settings → click Preview Pulse → assert first toast appears within 500ms → assert >= 2 toasts visible at peak. Click-to-dismiss removes clicked toast (matched by aria-label). Hover survives >8s past the 5.5s dwell. Keyboard Enter dismisses focused toast. CSS animation-play-state:paused on .toast-progress- fill while hovered, running on mouseleave. Screenshots attached to HTML report. Zero backend dependency (fireDemoSequence is purely client-side). **e2e/birth-ritual.spec.ts (NEW, 199 lines, 3 Playwright tests)** Canvas mounts on /dashboard/graph (gracefully test.fixme if MCP backend absent). Settings button injection + SPA route to /graph → screenshot timeline at t=0/500/1200/2000/2400/3000ms attached to HTML report. pageerror + console-error listeners catch any crash (would re-surface FATAL 6 if reintroduced). Three back-to- back births — no errors, canvas still dispatches clicks. Run commands: cd apps/dashboard && npm test # 361/361 pass, ~600ms cd apps/dashboard && npx playwright test # 9/9 pass, ~25s Typecheck: 0 errors, 0 warnings. Build: clean adapter-static. * fix(graph): default /api/graph to newest-memory center, add sort param memory_timeline PR #37 exposed the same class of bug in the graph endpoint: the dashboard Graph page (and the /api/graph endpoint it hits) defaulted to centering on the most-connected memory, ran BFS at depth 3, and capped the subgraph at 150 nodes. On a mature corpus this clustered the visualization around a historical hotspot and hid freshly ingested memories that hadn't accumulated edges yet. User-visible symptom: TimeSlider on /graph showing "Feb 21 → Mar 1 2026" when the database actually contains memories through today (Apr 20). **Backend (`crates/vestige-mcp/src/dashboard/handlers.rs`):** - `GraphParams` gains `sort: Option<String>` (accepted: "recent" | "connected", unknown falls back to "recent"). - New internal `GraphSort` enum + case-insensitive `parse()`. - Extracted `default_center_id(storage, sort)` so handler logic and tests share the same branching. Recent path picks `get_all_nodes(1, 0)` (ORDER BY created_at DESC). Connected path picks `get_most_connected_memory`, degrading gracefully to recent if the DB has no edges yet. - Default behaviour flipped from "connected" to "recent" — matches user expectation of "show me my recent stuff". **Dashboard (`apps/dashboard`):** - `api.graph()` accepts `sort?: 'recent' | 'connected'` with JSDoc explaining the rationale. - `/graph/+page.svelte` passes `sort: 'recent'` when no query or center_id is active. Query / center_id paths unchanged — they already carry their own centering intent. **Tests:** 6 new unit tests in `handlers::tests`: - `graph_sort_parse_defaults_to_recent` (None, empty, garbage, "recent", "Recent", "RECENT") - `graph_sort_parse_accepts_connected_case_insensitive` - `default_center_id_recent_returns_newest_node` — ingest 3 nodes, assert newest is picked - `default_center_id_connected_prefers_hub_over_newest` — wire a hub node with 3 spokes, then ingest a newer "lonely" node; assert the hub wins in Connected mode even though it's older - `default_center_id_connected_falls_back_to_recent_when_no_edges` — fresh DB with no connections still returns newest, not 404 - `default_center_id_returns_not_found_on_empty_db` — both modes return 404 cleanly on empty storage Build + test: - cargo test -p vestige-mcp --lib handlers:: → 6/6 pass - cargo test --workspace --lib → 830/830 pass, 0 failed - cargo clippy -p vestige-core -p vestige-mcp --lib -- -D warnings → clean - npm run check → 0 errors, 0 warnings - npm test → 361/361 pass Binary already installed at ~/.local/bin/vestige-mcp (copied from cargo build --release -p vestige-mcp). New Claude Desktop / Code sessions will pick it up automatically when they respawn their MCP subprocess. The dashboard HTTP server on port 3927 needs a manual relaunch from a terminal with the usual pattern: nohup bash -c 'tail -f /dev/null | \ VESTIGE_DASHBOARD_ENABLED=true ~/.local/bin/vestige-mcp' \ > /tmp/vestige-mcp.log 2>&1 & disown * feat(v2.4): UI expansion — 8 new surfaces exposing the cognitive engine Sam asked: "Build EVERY SINGLE MISSING UI PIECE." 10 parallel agents shipped 10 new viewports over the existing Rust backend, then 11 audit agents line-by-line reviewed each one, extracted pure-logic helpers, fixed ~30 bugs, and shipped 549 new unit tests. Everything wired through the layout with single-key shortcuts and a live theme toggle. **Eight new routes** - `/reasoning` — Reasoning Theater: Cmd+K ask palette → animated 8-stage deep_reference pipeline + FSRS-trust-scored evidence cards + contradiction arcs rendered as live SVG between evidence nodes - `/duplicates` — threshold-driven cluster detector with winner selection, Merge/Review/Dismiss actions, debounced slider - `/dreams` — Dream Cinema: trigger dream + scrubbable 5-stage replay (Replay → Cross-reference → Strengthen → Prune → Transfer) + insight cards with novelty glow - `/schedule` — FSRS Review Calendar: 6×7 grid with urgency color bands (overdue/today/week/future), retention sparkline, expand-day list - `/importance` — 4-channel radar (Novelty/Arousal/Reward/Attention) with composite score + top-important list - `/activation` — live spreading-activation view: search → SVG concentric rings with decay animation + live-mode event feed - `/contradictions` — 2D cosmic constellation of conflicting memories, arcs colored by severity, tooltips with previews - `/patterns` — cross-project pattern transfer heatmap with category filters, top-transferred sidebar **Three layout additions** - `AmbientAwarenessStrip` — slim top band with retention vitals, at-risk count, active intentions, recent dream, activity sparkline, dreaming indicator, Sanhedrin-watch flash. Pure `$derived` over existing stores. - `ThemeToggle` — dark/light/auto cycle with matchMedia listener, localStorage persistence, SSR-safe, reduced-motion-aware. Rendered in sidebar footer next to the connection dot. - `MemoryAuditTrail` — per-memory Sources panel integrated as a Content/Audit tab into the existing /memories expansion. **Pure-logic helper modules extracted (for testability + reuse)** reasoning-helpers, duplicates-helpers, dream-helpers, schedule-helpers, audit-trail-helpers, awareness-helpers, contradiction-helpers, activation-helpers, patterns-helpers, importance-helpers. **Bugs fixed during audit (not exhaustive)** - Trust-color inconsistency between EvidenceCard and the page confidence ring (0.75 boundary split emerald vs amber) - `new Date('garbage').toLocaleDateString()` returned literal "Invalid Date" in 3 components — all now return em-dash or raw string - NaN propagation in `Math.max(0, Math.min(1, NaN))` across clamps - Off-by-one PRNG in audit-trail seeded mock (seed === UINT32_MAX yielded rand() === 1.0 → index out of bounds) - Duplicates dismissals keyed by array index broke on re-fetch; now keyed by sorted cluster member IDs with stale-dismissal pruning - Empty-cluster crash in DuplicateCluster.pickWinner - Undefined tags crash in DuplicateCluster.safeTags - Debounce timer leak in threshold slider (missing onDestroy cleanup) - Schedule day-vs-hour granularity mismatch between calendar cell and sidebar list ("today" in one, "in 1d" in the other) - Schedule 500-memory hard cap silently truncated; bumped to 2000 + banner - Schedule DST boundary bug in daysBetween (wall-clock math vs startOfDay-normalized) - Dream stage clamp now handles NaN/Infinity/floats - Dream double-click debounce via `if (dreaming) return` - Theme setTheme runtime validation; initTheme idempotence (listener + style-element dedup on repeat calls) - ContradictionArcs node radius unclamped (trust < 0 or > 1 rendered invalid sizes); tooltip position clamp (could push off-canvas) - ContradictionArcs $state closure capture (width/height weren't reactive in the derived layout block) - Activation route was MISSING from the repo — audit agent created it with identity-based event filtering and proper RAF cleanup - Layout: ThemeToggle was imported but never rendered — now in sidebar footer; sidebar overflow-y-auto added for the 16-entry nav **Tests — 549 new, 910 total passing (0 failures)** ReasoningChain 42 | EvidenceCard 50 DuplicateCluster 64 | DreamStageReplay 19 DreamInsightCard 43 | FSRSCalendar 32 MemoryAuditTrail 45 | AmbientAwareness 60 theme (store) 31 | ContradictionArcs 43 ActivationNetwork 54 | PatternTransfer 31 ImportanceRadar 35 | + existing 361 tests still green **Gates passed** - `npm run check`: 0 errors, 0 warnings across 623 files - `npm test`: 910/910 passing, 22 test files - `npm run build`: clean adapter-static output **Layout wiring** - Nav array expanded 8 → 16 entries (existing 8 + 8 new routes) - Single-key shortcuts added: R/A/D/C/P/U/X/N (no conflicts with existing G/M/T/F/E/I/S/,) - Cmd+K palette search works across all 16 - Mobile nav = top 5 (Graph, Reasoning, Memories, Timeline, Feed) - AmbientAwarenessStrip mounted as first child of <main> - ThemeToggle rendered in sidebar footer (was imported-but-unmounted) - Theme initTheme() + teardown wired into onMount cleanup chain Net branch delta: 47 files changed, +13,756 insertions, -6 deletions * chore(release): v2.0.8 "Pulse" Bundled release: Reasoning Theater wired to the 8-stage deep_reference cognitive pipeline, Pulse InsightToast, Memory Birth Ritual (v2.3 Terrarium), 7 new dashboard surfaces (/duplicates, /dreams, /schedule, /importance, /activation, /contradictions, /patterns), 3D graph brightness system with auto distance-compensation + user slider, and contradiction-detection + primary-selection hardening in the cross_reference tool. Intel Mac (x86_64-apple-darwin) also flows through to the release matrix from PR #43. Added: - POST /api/deep_reference — HTTP surface for the 8-stage pipeline - DeepReferenceCompleted WebSocket event (primary + supporting + contradicting memory IDs for downstream graph animation) - /reasoning route, full UI + Cmd+K Ask palette - 7 new dashboard surfaces exposing the cognitive engine - Graph brightness slider + localStorage persistence + distance-based emissive compensation so nodes don't disappear into fog at zoom-out Fixed: - Contradiction-detection false positives: adjacent-domain memories no longer flagged as conflicts (NEGATION_PAIRS wildcards removed, shared-words floor 2 → 4, topic-sim floor 0.15 → 0.55, STAGE 5 overlap floor 0.15 → 0.4) - Primary-memory selection: unified composite 0.5 × relevance + 0.2 × trust + 0.3 × term_presence with hard topic-term filter, closing the class of bug where off-topic high-trust memories won queries about specific subjects - Graph default-load fallback from sort=recent to sort=connected when the newest memory is isolated, both backend and client Changed: - Reasoning page information hierarchy: chain renders first as hero, confidence meter + Primary Source citation footer below - Cargo feature split: embeddings code-only + ort-download | ort-dynamic backends; defaults preserve identical behavior for existing consumers - CI release-build now gates PRs too so multi-platform regressions surface pre-merge
2026-04-23 02:21:11 -05:00
├── cors.rs # prod: allowlist vestige.dev + app.vestige.dev; dev: permissive
├── state.rs # Arc<Mutex<Storage>> shared state (SINGLE TENANT)
├── sse.rs # /mcp/sse STUB — 3 TODOs, returns one static "endpoint" event
└── handlers/
├── mod.rs
├── health.rs # GET /health (version + memory count)
├── api.rs # REST CRUD: search, list, create, get, delete, promote, demote, stats, smart_ingest
├── mcp.rs # POST /mcp JSON-RPC 2.0 — **ONLY 5 TOOLS** (search, smart_ingest, memory, promote_memory, demote_memory)
└── sync.rs # POST /sync/push + /sync/pull (sync/pull has TODO for `since` filter)
```
### 7.2 Gap analysis vs. current `vestige-mcp`
| Dimension | vestige-mcp v2.0.7 | vestige-cloud Feb skeleton | Gap |
|---|---|---|---|
| MCP tools | 24 | 5 | 19 tools missing (session_context, dream, explore_connections, predict, importance_score, find_duplicates, memory_timeline, memory_changelog, memory_health, memory_graph, deep_reference, consolidate, backup, export, gc, restore, intention, codebase, suppress/unsuppress) |
| MCP transport | stdio + HTTP | HTTP only, no Streamable HTTP | Needs full Streamable HTTP (`Mcp-Session-Id` header, bidirectional, Last-Event-ID reconnect) per 2025-06-18 spec |
| Multi-tenancy | N/A (local) | **Single tenant** (one storage, one API key) | Need per-user DB, row-level scoping, or DB-per-tenant sharding |
| Auth | Local token | Single bearer | Need JWT, OAuth, scopes, org membership, token rotation |
| Billing | N/A | none | Need Stripe, entitlement, plans, webhooks |
| Observability | `tracing` only | `tracing` only | Need Prometheus / OTLP export, dashboards, rate limits, error budget |
| Sync | N/A | lossy push + unfiltered pull | Need tombstones, incremental pull by `since`, conflict resolution |
| Deploy | binaries + npm | **none** | Need Dockerfile, fly.toml, CI, docs |
### 7.3 Two upgrade paths
- **Path A (v2.6.0 "Remote"):** Upgrade the Feb skeleton to match v2.0.7 surface (5 → 24 tools), implement Streamable HTTP, ship Dockerfile + fly.toml. **Keep single-tenant.** Ship as "deploy your own Vestige on a VPS."
- **Path B (v3.0.0 "Cloud"):** Multi-tenant SaaS. Weeks of work on billing, per-tenant DB, ops. Not viable until v2.6 has traction + cashflow.
The recommendation in Part 9 is **A only** for now. B is gated on demand signal + runway.
---
## 8. Version History (v1.0 → v2.0.8)
### 8.1 Shipped releases
| Version | Tag | Date | Theme | Headline |
|---|---|---|---|---|
| v1.0.0 | v1.0.0 | 2026-01-25 | Initial | First MCP server with FSRS-6 memory |
| v1.1.x | v1.1.0/1/2 | — | CLI separation | stats/health moved out of MCP to CLI |
| v1.3.0 | v1.3.0 | — | — | Importance scoring, session checkpoints, duplicate detection |
| v1.5.0 | v1.5.0 | — | — | Cognitive engine, memory dreaming, graph exploration, predictive retrieval |
| v1.6.0 | v1.6.0 | — | — | 6× storage reduction, neural reranking, instant startup |
| v1.7.0 | v1.7.0 | — | — | 18 tools, automation triggers, SQLite perf |
| v1.9.1 | v1.9.1 | — | Autonomic | Self-regulating memory, graph visualization |
| **v2.0.0** | v2.0.0 | **2026-02-22** | "Cognitive Leap" | 3D SvelteKit+Three.js dashboard, WebSocket event bus (16 events), HyDE query expansion, Nomic v2 MoE option, Command palette, bloom post-processing |
| v2.0.1 | v2.0.1 | — | — | Release rebuild, install fixes |
| v2.0.3 | v2.0.3 | — | — | Clippy fixes, CI alignment |
| v2.0.4 | v2.0.4 | 2026-04-09 | "Deep Reference" | **8-stage cognitive reasoning tool, `cross_reference` alias**, retrieval_mode (precise/balanced/exhaustive), token budgets raised 10K → 100K, CORS hardening |
| v2.0.5 | v2.0.5 | 2026-04-14 | "Intentional Amnesia" | **Active forgetting** — suppress tool #24, Rac1 cascade (72h async neighbour decay), 24h labile reversal window, graph node visual suppression (20% opacity, no emissive) |
| v2.0.6 | v2.0.6 | 2026-04-18 | "Composer" | 6 live graph reactions (Suppressed, Unsuppressed, Rac1, Connected, ConsolidationStarted, ImportanceScored), `VESTIGE_SYSTEM_PROMPT_MODE=full` opt-in |
| **v2.0.7** | v2.0.7 | 2026-04-19 | "Visible" | V11 migration drops dead tables; `/api/memories/{id}/suppress` + `/unsuppress` endpoints + UI button; sidebar `up 3d 4h` footer via `uptime_secs`; graph error-state split; `predict` degraded flag; `changelog` start/end honored; `intention` include_snoozed; `suppress` MCP tool (was dashboard-only); tool-count reconciled 23 → 24; Intel Mac dropped from release workflow; defensive `Err` on unknown export format |
| **v2.0.8** | *(unreleased, merged to main 2026-04-19 22:10 CT)* | — | — | FSRS memory-state colour mode (`ColorMode` type/state toggle) + floating legend + dark-glass-pill label redesign + 80 new tests + Rust 1.95 clippy compat (12 sites) |
### 8.2 Current git state
- **HEAD:** `main` at `30d92b5` "feat(graph): redesign node labels as dark glass pills"
- **Last 4 commits on main (v2.0.8):**
- `30d92b5` — Label pill redesign
- `d7f0fe0` — 80 new color-mode tests
- `318d4db` — Rust 1.95 clippy compat
- `4c20165` — Memory-state color mode + legend
- **Branches:**
- `main` (default, protected via CI-must-pass)
- `feat/v2.0.8-memory-state-colors` (fast-forwarded into main tonight)
- `feat/v2.1.0-qwen3-embed` (Day 2 done; Day 3 pending on Sam's M3 Max arrival)
- `chore/v2.0.7-clean` (post-v2.0.7 cleanup branch)
- `wip/v2.0.7-v11-migration` (transport branch for cross-machine stash)
- **Latest tag:** `v2.0.7` (force-updated on main after v2.0.6 rebase incident)
- **Latest CI run on main:** #24646176395 ✅ all 4 jobs (Test macos, Test ubuntu, Release aarch64-darwin, Release x86_64-linux)
### 8.3 Open GitHub issues / PRs
- **Closed #35** — "npm publish delay 2.0.6"; replied in v2.0.6 with one-liner install command
- **Open #36** — desaiuditd: "hooks-for-automatic-memory request" — customer conversion opportunity, not yet responded
---
## 9. The Next-Phase Plan
**Shipping cadence:** weekly minor bumps (v2.1 → v2.2 → v2.3 ...) until v3.0 which gates on multi-tenancy + CoW storage. Ships ~Monday each week with content post same day + follow-up Wednesday + YouTube Friday.
### 9.1 v2.1.0 "Decide" — Qwen3 embeddings *(in-flight)*
**Branch:** `feat/v2.1.0-qwen3-embed` (pushed).
**Status:** scaffolding merged; Day 3 pending.
**ETA:** ~1 week after M3 Max arrival (FedEx hold at Walgreens, pickup 2026-04-20).
**What's in:** `qwen3-embed` feature flag gates a Candle-based Qwen3 embed backend. `qwen3_format_query()` helper for the query-instruction prefix. Metal device selection with CPU fallback. `DEFAULT_DIMENSIONS` feature-gated 256/1024. Dual-index routing scaffolded.
**What's left (Day 3):**
- Storage write-path records `embedding_model` per node.
- `semantic_search_raw` uses `qwen3_format_query` when feature active.
- Dual-index routing: old Nomic-256 nodes stay on their HNSW, new Qwen3-1024 nodes go on a new HNSW. Search merges with trust weighting.
- End-to-end test: ingest on Qwen3 → retrieve on Qwen3 at higher accuracy than Nomic.
**Test gate:** `cargo test --workspace --features qwen3-embed --release` green. Current baseline: 366 core + 425 mcp passing.
### 9.2 v2.2.0 "Pulse" — Subconscious Cross-Pollination **★ VIRAL LOAD-BEARING RELEASE**
**ETA:** 1-2 weeks after v2.1 lands.
**What it does:** While the user is doing anything else (typing a blog post, looking at a different tab, doing nothing), Vestige's running `dream()` in the background. When dream completes with `insights_generated > 0` or a `ConnectionDiscovered` event fires from spreading activation, **the dashboard pulses a toast** on the side: *"Vestige found a connection between X and Y. Here's the synthesis."* The bridging edge in the 3D graph flashes cyan and briefly thickens.
**Why viral:** This is the single most tweet/YouTube-friendly demo in the entire roadmap. It is the "my 3D brain is thinking for itself" moment.
**Backend (≈2 days):**
1. `ConsolidationScheduler` gains a "pulse" hook: after each cycle, if `insights_generated > 0` emit a new `InsightSurfaced` event with `{source_memory_id, target_memory_id, synthesis_text, confidence}`.
2. The existing `ConnectionDiscovered` event gets a richer payload: include both endpoint IDs + a templated synthesis string derived from the two memories' content.
3. Rate-limit pulses: max 1 per 15 min unless user is actively using the dashboard.
**Frontend (≈5 days):**
1. New Svelte component `InsightToast.svelte` — slides in from right, shows synthesis text + "View connection" button, auto-dismisses after 10s.
2. `events.ts` mapping: `InsightSurfaced` → locate bridging edge in graph, pulse it cyan for 2s, thicken to 2× for 500ms, play a soft chime (optional, muted by default).
3. Toast queue so rapid dreams don't flood.
4. Preference: user can toggle pulse sound / toast / edge animation independently in `/settings`.
**Already exists (nothing to build):**
- `dream()` 5-stage cycle — YES
- `DreamCompleted` event with `insights_generated` — YES
- `ConnectionDiscovered` event + WebSocket broadcast — YES
- 3D edge animation system in `events.ts` — YES (handler exists, just doesn't emit toast)
- ConsolidationScheduler running on `VESTIGE_CONSOLIDATION_INTERVAL_HOURS` — YES
**Never-composed alarm:** Four existing components, zero lines of composition. This feature is **~90% latent in v2.0.7**. All we do is press the button.
**Acceptance criteria:**
- Start Vestige, idle for 10 min, verify a pulse fires from scheduled dream cycle.
- Ingest 3 semantically adjacent memories from completely different domains (e.g., F1 aerodynamics, memory leak, fluid dynamics), trigger dream, verify connection pulse fires with synthesis text mentioning both source + target.
- Dashboard test coverage: add `pulse.test.ts` with 15+ cases covering toast queue, rate limit, event shape, edge animation.
**Launch day:** Film a 90-second screen recording. Post to Twitter + Hacker News + LinkedIn + YouTube same day.
### 9.3 v2.3.0 "Rewind" — Time Machine
**ETA:** 2-3 weeks after v2.2 ships.
**What it does:** The graph page gets a horizontal time slider. Drag back in time → nodes dim based on retroactive FSRS retention, edges that were created after the slider's timestamp dissolve visibly, suppressed memories un-dim to their pre-suppression state. A "Pin" button snapshots the current slider state into a named checkpoint the user can return to.
**Backend (≈4 days):**
1. New core API: `Storage::memory_state_at(memory_id, timestamp) -> MemorySnapshot` — reconstructs a node's FSRS state at an arbitrary past timestamp by replaying `state_transitions` forward OR applying FSRS decay backward from the current state.
2. New MCP tool: `memory_graph_at(query, depth, max_nodes, timestamp)` — the existing graph call with a time parameter.
3. New MCP tool: `pin_state(name, timestamp)` — persists a named snapshot (just a row in a new `pins` table: name, timestamp, created_at).
4. New core API: `list_pins()` + `delete_pin(name)`.
**Frontend (≈7 days):**
1. `TimeSlider.svelte` already exists as a scaffold (listed in §5.5) — upgrade it to an HTML5 range input + play/pause + speed control.
2. Graph3D consumes a new `asOfTimestamp` prop. When set, uses `temporal.ts::retentionAtDate()` to re-project every node's opacity + size.
3. Edges: hide those with `created_at > slider`. Animate the dissolution so sliding feels organic.
4. Pin sidebar: list pinned states, click to jump, rename/delete.
**Cut from scope: branching.** Git-like "what if I forgot my Python biases" requires CoW storage = full schema migration = v3.0 territory. Scope it out explicitly.
**Acceptance criteria:**
- Slide back 30 days, verify node count drops to whatever existed 30 days ago.
- Slide back through a suppression event, verify node un-dims.
- Pin "before Mays deadline", verify pin jumps restore exact state.
### 9.4 v2.4.0 "Empathy" — Emotional Context Tagging **★ FIRST PRO-TIER GATE CANDIDATE**
**ETA:** 2-3 weeks after v2.3 ships.
**What it does:** Vestige's MCP middleware watches tool call metadata for frustration signals — repeated retries of the same query, CAPS LOCK content, explicit correction phrases ("no that's wrong", "actually..."), rapid-fire consecutive calls. When detected, the current active memory gets an automatic `ArousalSignal` boost and a `frustration_detected_at` timestamp. Next session, when the user returns to a similar topic, the agent proactively surfaces: *"Last time we worked on this, you were frustrated with the API docs. I've pre-read them."*
**Why Pro-tier:** Invisible to demo (so doesn't hurt OSS growth), creates deep lock-in, quantifiable value ("Vestige saved you X minutes of re-frustration this month"), clear paid-hook rationale.
**Backend (≈4 days):**
1. New middleware layer in `vestige-mcp` between JSON-RPC dispatch and tool execution: `FrustrationDetector`. Analyzes tool args for: (a) retry pattern (same `query` field within 60s), (b) content ≥70% caps after lowercase comparison, (c) correction regex (`no\s+that|actually|wrong|fix this|try again`).
2. On detection, fire a synthesized `ArousalSignal` to `ImportanceTracker` for the most-recently-accessed memory.
3. New core API: `find_frustration_hotspots(topic, limit)` → returns memories with `arousal_score > threshold` + their `frustration_detected_at` timestamps.
4. `session_context` tool gains a new field: `frustration_warnings[]` — "Topic X had previous frustration; here's what we know."
**Frontend (≈3 days):**
1. Memory detail pane shows an orange "Frustration" badge for high-arousal memories.
2. `/stats` adds a "Frustration hotspots" section.
**Acceptance criteria:**
- Simulate 3 rapid retries of the same query, verify ArousalSignal boosts the active memory.
- Simulate caps-lock content, verify detection.
- Return to same topic next session, verify `session_context` surfaces warning.
### 9.5 v2.5.0 "Grip" — Neuro-Feedback Cluster Gestures
**ETA:** 2 weeks after v2.4 ships.
**What it does:** In the 3D graph, drag a memory sphere to "grab" it — its cluster highlights. Squeeze (pinch gesture or modifier key + drag inward) → promotes the whole cluster. Flick away (throw gesture) → triggers decay on the cluster.
**Backend (≈2 days):**
1. New MCP tool: `promote_cluster(memory_ids[])` — applies promote to each.
2. New MCP tool: `demote_cluster(memory_ids[])` — inverse.
3. Cluster detection helper: `find_cluster(source_id, similarity_threshold)` — leverages existing `find_duplicates` + spreading activation.
**Frontend (≈5 days):**
1. Three.js gesture system: drag detection, cluster highlight (emissive pulse on all cluster members), squeeze detection (pointer velocity inward), flick detection (pointer velocity outward past threshold).
2. Visual feedback: green ring on squeeze (promote), red dissipation on flick (demote).
3. Accessibility: keyboard alternative — select node, press `P` / `D` to promote/demote cluster.
### 9.6 v2.6.0 "Remote" — `vestige-cloud` Self-Host Upgrade
**ETA:** 3 weeks after v2.5 ships. First paid-tier candidate if empathy doesn't convert first.
**What it does:** Turns the Feb `vestige-cloud` skeleton into a shippable self-host product. One-liner install → Docker container or fly.io deploy → point Claude Desktop/Cursor/Codex at the remote URL → cloud-persistent memory across all your devices.
**Scope:**
1. Upgrade MCP handler from 5 → 24 tools (port each tool from `crates/vestige-mcp/src/tools/`).
2. Implement **MCP Streamable HTTP transport** (spec 2025-06-18): `Mcp-Session-Id` header, bidirectional event stream, Last-Event-ID reconnect, JSON-RPC batching.
3. Per-user SQLite at `/data/$USER_ID.db` (single-tenant but scoped by `VESTIGE_USER_ID` env — "single-tenant but deploy-multiple").
4. `Dockerfile` (multi-stage: Rust build + fastembed model baked in).
5. `fly.toml` with persistent volume mount on `/data`.
6. `docker-compose.yml` for local Postgres-if-needed (probably not — stick with SQLite for self-host).
7. `scripts/cloud-deploy.sh` one-liner installer.
8. Docs: `docs/cloud/self-host.md` step-by-step.
**Explicitly OUT of scope for v2.6:** Stripe, multi-tenant DB, user accounts, rate limits, billing. Those are v3.0.
### 9.7 v3.0.0 "Branch" — CoW memory branching + SaaS multi-tenancy
**ETA:** Q3 2026 at earliest. Gated on:
- v2.6 adoption signal (≥500 self-host deployments)
- Sam's runway (needs pre-revenue or funding)
- Either Mays, Orbit Wars, or another cash injection
**What it does:**
1. **Memory branching** — git-like CoW over SQLite. Branch a memory state, diverge freely, merge or discard. "What if I forgot all my Python biases and approached this memory as a Rust expert" becomes a one-button operation.
2. **Multi-tenant SaaS** at `vestige.dev` / `app.vestige.dev`. Per-user DB shards, JWT auth + OAuth providers, Stripe subscriptions with entitlement gates, org membership, team shared memory with role-based access.
**Major subsystems required:**
- Storage layer rewrite for CoW semantics (or adopt Dolt/sqlcipher with branching).
- Auth: JWT + OAuth (Google, GitHub, Apple) + bcrypt fallback.
- Billing: Stripe subscriptions + webhooks + dunning.
- Admin dashboard: support, usage analytics, churn.
- Multi-region: at minimum US-east + EU (GDPR).
- Observability: Prometheus + Grafana + Sentry + Honeycomb tracing.
**Explicitly NOT a v2.x goal.** Any earlier attempt burns runway.
### 9.8 Summary roadmap table
| Version | Codename | Theme | Effort | Load-bearing for | ETA |
|---|---|---|---|---|---|
| v2.1 | Decide | Qwen3 embeddings | ~1 week | Retrieval quality + differentiation vs. Nomic | Days |
| **v2.2** | **Pulse** | **Subconscious cross-pollination** | **~1 week (mostly latent)** | **★ Viral launch moment** | **~2 weeks** |
| v2.3 | Rewind | Time machine (slider + pin) | ~2 weeks | Technical moat, impressive demo | ~5 weeks |
| v2.4 | Empathy | Frustration detection → arousal boost | ~1 week | **First Pro-tier gate candidate** | ~7 weeks |
| v2.5 | Grip | Cluster gestures | ~1 week | Polish | ~9 weeks |
| v2.6 | Remote | vestige-cloud self-host (5→24 tools + Streamable HTTP + Docker) | ~3 weeks | Foundation for SaaS; secondary Pro-tier gate | ~12 weeks |
| v3.0 | Branch | CoW branching + multi-tenant SaaS | ~3 months | Revenue | Q3 2026 at earliest |
---
## 10. Composition Map
For each v2.x feature, what existing primitives does it compose?
| Feature | Existing primitive | How composed |
|---|---|---|
| v2.2 Pulse | `dream()` + `ConsolidationScheduler` + `ConnectionDiscovered` event + Three.js `events.ts::mapEventToEffects` | Consume the already-firing events; add toast UI + richer synthesis payload |
| v2.3 Rewind slider | `state_transitions` append log + FSRS decay formula + `temporal.ts::retentionAtDate()` + existing `TimeSlider.svelte` stub | Retroactive state reconstruction + slider upgrade |
| v2.3 Rewind pins | `smart_ingest` patterns + new `pins` table | Thin new table + two new tools |
| v2.4 Empathy | `ArousalSignal` (already in ImportanceSignals 4-channel model) + middleware pattern + `ImportanceTracker` | New middleware layer feeds existing arousal channel |
| v2.5 Grip | `find_duplicates` clustering + `promote`/`demote` + v2.0.8 Three.js node picking | Cluster-level wrapper over per-node operations |
| v2.6 Remote | v2.0.7 MCP tool implementations + vestige-cloud Feb skeleton + Axum | Port tools; implement Streamable HTTP; containerize |
| v3.0 Branch | Requires new CoW storage layer — **no existing primitive composes here** | Greenfield storage rewrite |
| v3.0 SaaS | Requires new auth + billing + multi-tenancy — **no existing primitive composes** | Greenfield |
**Key insight:** v2.2-v2.6 are all ≥60% latent in existing primitives. v3.0 is the first release that requires significant greenfield work. This is why sequencing matters: ride the existing primitives to revenue, then greenfield.
---
## 11. Risks & Known Gaps
### 11.1 Technical
| Risk | Impact | Mitigation |
|---|---|---|
| `ort-sys 2.0.0-rc.11` prebuilt gaps (Intel Mac dropped, Windows MSVC with usearch 2.24 broken) | Fewer platforms ship | Wait for ort-sys 2.1; or migrate to Candle throughout (v2.1 Qwen3 already uses Candle) |
| `usearch` pinned to 2.23.0 (2.24 regression on MSVC) | Windows build fragility | Monitor usearch#746 |
| fastembed model download (~130MB for Nomic, ~500MB for Qwen3) on first run blocks sandboxed Xcode | UX friction | Cache at `~/Library/Caches/com.vestige.core/fastembed` — documented in Xcode guide; pre-download from terminal once |
| Tool count drift (23 vs 24 across docs) | User trust | Reconciled in v2.0.7 (`docs: tool-count reconciliation`) |
| Large build times (cargo release 2-3 min incremental, 6+ min clean) | Slow iteration | M3 Max arriving Apr 20 will halve this |
| `include_dir!` bakes dashboard build into binary at compile time | Have to rebuild Rust to update dashboard | Accept as design; HMR via `pnpm dev` for iteration |
### 11.2 Product
| Risk | Impact | Mitigation |
|---|---|---|
| OSS-growth-before-revenue means months of zero cash | Sam can't pay rent | Mays May 1 ($400K+), Orbit Wars June 23 ($5K × top 10), part-time Wrigley Field during Cubs season |
| `deep_reference` is the crown jewel but rarely invoked | Users don't discover it | `CLAUDE.md` flags it; v2.2 Pulse farms the viral moment to drive awareness |
| Subconscious Pulse may fire too often or too rarely | User annoyance or missed value | Rate limit: max 1 pulse per 15 min; user-adjustable in settings |
| Emotional tagging may over-fire (every caps lock = frustration?) | False positives | Require ≥2 signals (retry + caps, or retry + correction) before boost |
| v3.0 SaaS burns runway if started too early | Business-ending | Gated on v2.6 adoption + cash injection |
| Copycat risk (Zep, Cognee, etc.) cloning Vestige's features | Eroded differentiation | AGPL-3.0 protects network use; neuroscience depth is hard to fake; time slider + subconscious pulse are visible moats |
| Cross-IDE MCP standard changes (Streamable HTTP spec moved 2024-11-05 → 2025-06-18) | Breaking transport changes | v2.6 implements the newer spec; keep 2024-11-05 as backward-compat alias |
### 11.3 Known UI gaps (`docs/launch/UI_ROADMAP_v2.1_v2.2.md`)
- **26% of MCP tools have zero UI surface** (e.g., `codebase`, `find_duplicates`, `backup`, `export`, `gc`, `restore` — all power-user only).
- **28% of cognitive modules have no visualization** (SynapticTagging, HippocampalIndex, ContextMatcher, CrossProjectLearner, etc.).
- The rainbow-bursted Rac1 cascade in the graph has no numeric "how many neighbours did it touch" display.
- `intention` shows but doesn't let you edit/snooze from the UI.
- `deep_reference` is unreachable from the dashboard (it only surfaces via MCP tool calls).
---
## 12. Viral / Launch / Content Plan
### 12.1 Content cadence (fixed)
**Mon–Fri till June 13 graduation:**
- 1-2 posts/day across Twitter + LinkedIn + Hacker News + Reddit r/LocalLLaMA + r/selfhosted
- Weekly YouTube long-form (Friday release)
### 12.2 Per-release launch playbook
For every v2.x release:
1. **Monday:** Tag + release + content drop (tweet with 30-90s demo video + HN post).
2. **Tuesday:** LinkedIn long-form + Reddit cross-post.
3. **Wednesday:** Follow-up tweet thread (deep-dive on one specific feature).
4. **Thursday:** Engage with feedback; close issues; publish patch if needed.
5. **Friday:** YouTube long-form (15-25 min walkthrough). Next week's release work continues.
### 12.3 Viral load-bearing moments
- **v2.2 "Pulse" launch:** The single biggest viral bet. Subconscious cross-pollination demo → HN front page → Twitter thread → YouTube 10-min walkthrough.
- **v2.3 "Rewind" time slider:** Highly tweet-friendly. Screen recording of sliding back through memory decay.
- **Jarrett Ye (FSRS creator, user L-M-Sherlock) outreach:** Already a stargazer. Email him Sunday night (US time) = Monday AM Beijing with the v2.2 Pulse demo. If he retweets → FSRS community (Anki, maimemo) amplifies.
### 12.4 Issue #36 (hooks-for-automatic-memory)
Outstanding from desaiuditd. Response plan:
1. Thank him publicly in the issue.
2. Acknowledge the feature as valid and scoped for v2.2/v2.3.
3. Open a linked sub-issue: "v2.2: Auto-memory hooks" tied to Pulse work.
### 12.5 Monetization gates
**Two candidate first-gates:**
1. **v2.4 Empathy (Emotional tagging)** — invisible to OSS demos, strong retention, clean paid-feature framing ("Vestige notices when you're frustrated; free tier gets 100 detection events/month, Pro gets unlimited + frustration hotspot analytics").
2. **v2.6 Remote (Cloud self-host binary)** — "free binary forever; paid-tier cloud-managed deploy with backups + observability + multi-device sync."
Pick after v2.2 viral signal tells us whether retention or convenience is the weaker link.
---
## 13. How AI Agents Should Consume This Doc
### 13.1 First-time read protocol
If this is the first time you're seeing Vestige:
1. Read Part 0 (Executive Summary) + Part 1 (What Vestige Is). That's 3 minutes.
2. Read Part 9 (The Plan). That's 10 minutes.
3. Bookmark Parts 3-6 for reference.
### 13.2 When Sam asks you to plan a feature
1. Check Part 9 — is it already scoped? If yes, that section IS your spec.
2. If not, work it into the existing roadmap: which version should it ship in, what primitives does it compose (Part 10), what risks apply (Part 11)?
3. Follow the `/Users/entity002/.claude/rules/active-synthesis.md` protocol (6 mandatory behaviors): compose, don't summarize.
### 13.3 When Sam asks you to implement
1. Find the exact file paths in Parts 3-5.
2. Check existing test coverage (Part 5.9 for dashboard, §3.11 for core).
3. Before claiming something exists, grep or read the source — memory alone is insufficient (per `CLAUDE.md` SCOUR rule).
4. Rust 1.95 toolchain — be aware of the new lints (`unnecessary_sort_by`, `collapsible_match`).
### 13.4 When Sam asks for strategic advice
- Apply the `/Users/entity002/.claude/rules/cross-reference.md` rule: check evidence from the exact setup before recommending.
- Apply the `always-positive-energy` rule: recommend the BEST path, not the safest.
- This doc's Part 9 is the committed roadmap. Deviate only with explicit justification.
### 13.5 Load-bearing files to never forget
- `/Users/entity002/Developer/vestige/CLAUDE.md` — project-level Claude instructions.
- `/Users/entity002/.claude/rules/active-synthesis.md` — 6 mandatory synthesis behaviors.
- `/Users/entity002/.claude/rules/cross-reference.md` — exact-setup evidence rule.
- `/Users/entity002/CLAUDE.md` — global Claude instructions (SCOUR + always-positive-energy).
- `/Users/entity002/Developer/vestige/docs/launch/UI_ROADMAP_v2.1_v2.2.md` — prior UI research compilation.
- **This file** — `/Users/entity002/Developer/vestige/docs/VESTIGE_STATE_AND_PLAN.md`.
---
## 14. Glossary & Citations
### 14.1 Acronyms
| Term | Meaning |
|---|---|
| **MCP** | Model Context Protocol — JSON-RPC protocol for AI tool integration (Anthropic, 2024) |
| **FSRS** | Free Spaced Repetition Scheduler — algorithm by Jarrett Ye (maimemo), generation 6 |
| **PE Gating** | Prediction Error Gating — decide CREATE/UPDATE/SUPERSEDE by similarity threshold |
| **SIF** | Suppression-Induced Forgetting — Anderson 2025 |
| **Rac1** | Rho-family GTPase — actin-destabilization mediator of cascade decay (Cervantes-Sandoval & Davis 2020) |
| **SWR** | Sharp-wave ripple — hippocampal replay pattern used by Vestige's dream cycle |
| **HNSW** | Hierarchical Navigable Small World — graph index for fast approximate nearest neighbour |
| **CoW** | Copy-on-write — storage technique for cheap branching |
| **AGPL** | Affero General Public License — copyleft including network use |
### 14.2 Neuroscience citations
- Anderson, M. C. (2025). Suppression-induced forgetting — top-down inhibitory control of retrieval.
- Anderson, M. C., Bjork, R. A., & Bjork, E. L. (1994). Remembering can cause forgetting.
- Bjork, R. A., & Bjork, E. L. (1992). A new theory of disuse and an old theory of stimulus fluctuation. — dual-strength model.
- Brown, R., & Kulik, J. (1977). Flashbulb memories.
- Cervantes-Sandoval, I., & Davis, R. L. (2020). Rac1-mediated forgetting.
- Collins, A. M., & Loftus, E. F. (1975). A spreading-activation theory of semantic processing.
- Frey, U., & Morris, R. G. M. (1997). Synaptic tagging and long-term potentiation.
- Friston, K. J. (2010). The free-energy principle: a unified brain theory.
- Nader, K., Schafe, G. E., & LeDoux, J. E. (2000). Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval.
- Teyler, T. J., & Rudy, J. W. (2007). The hippocampal indexing theory.
- Tulving, E., & Thomson, D. M. (1973). Encoding specificity and retrieval processes.
### 14.3 Technical citations
- MCP Spec (2025-06-18 Streamable HTTP): https://modelcontextprotocol.io/specification
- FSRS-6: https://github.com/open-spaced-repetition/fsrs-rs
- Nomic Embed Text v1.5: https://huggingface.co/nomic-ai/nomic-embed-text-v1.5
- Qwen3 Embed: https://huggingface.co/Qwen/Qwen3-Embedding-0.6B
- USearch: https://github.com/unum-cloud/usearch
- Jina Reranker v1 Turbo: https://huggingface.co/jinaai/jina-reranker-v1-turbo-en
---
v2.0.9 "Autopilot" — backend event-subscriber + 3,091 LOC orphan cleanup (#46) * feat(v2.0.9): Autopilot — backend event-subscriber routes 6 live events into cognitive hooks The single architectural change that flips 14 dormant cognitive primitives into active ones. Before this commit, Vestige's 20-event WebSocket bus had zero backend subscribers — every emitted event flowed to the dashboard animation layer and terminated. Cognitive modules with fully-built trigger methods (synaptic_tagging.trigger_prp, predictive_memory.record_*, activation_network.activate, prospective_memory.check_triggers, the 6h auto-consolidation dreamer path) were never actually called from the bus. New module `crates/vestige-mcp/src/autopilot.rs` spawns two tokio tasks at startup: 1. Event subscriber — consumes the broadcast::Receiver, routes: - MemoryCreated → synaptic_tagging.trigger_prp(CrossReference) + predictive_memory.record_memory_access(id, preview, tags) - SearchPerformed → predictive_memory.record_query(q, []) + record_memory_access on top 10 result_ids - MemoryPromoted → activation_network.activate(id, 0.3) spread - MemorySuppressed → emit Rac1CascadeSwept (was declared-never-emitted) - ImportanceScored (composite > 0.85 AND memory_id present) → storage.promote_memory + re-emit MemoryPromoted - Heartbeat (memory_count > 700, 6h cooldown) → spawned find_duplicates sweep (rate-limited) The loop holds the CognitiveEngine mutex only per-handler, never across an await, so MCP tool dispatch is never starved. 2. Prospective poller — 60s tokio::interval calls prospective_memory.check_triggers(Context { timestamp: now, .. }). Matched intentions are logged at info! level today; v2.5 "Autonomic" upgrades this to MCP sampling/createMessage for agent-side notifications. ImportanceScored event gained optional `memory_id: Option<String>` field (#[serde(default)], backward-compatible) so auto-promote has the id to target. Both existing emit sites (server.rs tool dispatch, dashboard handlers::score_importance) pass None because they score arbitrary content, not stored memories — matches current semantics. docs/VESTIGE_STATE_AND_PLAN.md §15 POST-v2.0.8 ADDENDUM records the full three-agent audit that produced this architecture (2026-SOTA research, active-vs-passive module audit, competitor landscape), the v2.0.9/v2.5/v2.6 ship order, and the one-line thesis: "the bottleneck was one missing event-subscriber task; wiring it flips Vestige from memory library to cognitive agent that acts on the host LLM." Verified: - cargo check --workspace clean - cargo clippy --workspace -- -D warnings clean (let-chain on Rust 1.91+) - cargo test -p vestige-mcp --lib 356/356 passing, 0 failed * fix(autopilot): supervisor + dedup race + opt-out env var Three blockers from the 5-agent v2.0.9 audit, all in autopilot.rs. 1. Supervisor loops around both tokio tasks (event subscriber + prospective poller). Previously, if a cognitive hook panicked on a single bad memory, the spawned task died permanently and silently — every future event lost. Now the outer supervisor catches JoinError::is_panic(), logs the panic with full error detail, sleeps 5s, and respawns the inner task. Turns a permanent silent failure into a transient hiccup. 2. DedupSweepState struct replaces the bare Option<Instant> timestamp. It tracks the in-flight JoinHandle so the next Heartbeat skips spawning a second sweep while the first is still running. Previously, the cooldown timestamp was set BEFORE spawning the async sweep, which allowed two concurrent find_duplicates scans on 100k+ memory DBs where the sweep could exceed the 6h cooldown window. is_running() drops finished handles so a long-dead sweep doesn't block the next legitimate tick. 3. VESTIGE_AUTOPILOT_ENABLED=0 opt-out. v2.0.8 users updating in place can preserve the passive-library contract by setting the env var to any of {0, false, no, off}. Any other value (unset, 1, true, etc.) enables the default v2.0.9 Autopilot behavior. spawn() early-returns with an info! log before any task is spawned. Audit breakdown: - Agent 1 (internals): NO-GO → fixed (1, 2) - Agent 2 (backward compat): NO-GO → fixed (3) - Agent 3 (orphan cleanup): GO clean - Agent 4 (runtime safety): GO clean - Agent 5 (release prep): GO, procedural note logged Verification: - cargo check -p vestige-mcp: clean - cargo test -p vestige-mcp --lib: 373 passed, 0 failed - cargo clippy -p vestige-mcp --lib --bins -- -D warnings: clean * chore(release): v2.0.9 "Autopilot" Bump workspace + vestige-core + vestige-mcp + apps/dashboard to 2.0.9. CHANGELOG [2.0.9] entry + README hero banner rewrite to "Autopilot". Scope (two commits on top of v2.0.8): - 0e9b260: 3,091 LOC orphan-code cleanup - fe7a68c: Autopilot backend event-subscriber - HEAD (this branch): supervisor + dedup race + opt-out env var hardening Pure backend release — tool count unchanged (24), schema unchanged, JSON-RPC shape unchanged, CLI flags unchanged. Only visible behavior change is the Autopilot task running in the background, which is VESTIGE_AUTOPILOT_ENABLED=0-gated. Test gate: 1,223 passing / 0 failed (workspace, no-fail-fast). Clippy: clean on vestige-mcp lib + bins with -D warnings. Audit: 5 parallel agents (internals, backward compat, orphan cleanup, runtime safety, release prep) — all GO after hardening commit.
2026-04-24 02:00:00 -05:00
## 15. POST-v2.0.8 ADDENDUM — The Autonomic Turn (added 2026-04-23)
> This section supersedes portions of sections 9.1-9.8. The April 19 roadmap (v2.1 Decide → v2.2 Pulse → v2.3 Rewind → v2.4 Empathy → v2.5 Grip → v2.6 Remote → v3.0 Branch) remains the long-arc plan but has been RESEQUENCED post-v2.0.8 ship following a three-agent audit on 2026-04-23 (web research on 2026 SOTA, Vestige code audit for active-vs-passive paths, competitor landscape). Updated sequence reflects what got absorbed into v2.0.8 and the new v2.0.9 / v2.5 / v2.6 architecture tier that replaces the old placeholder numbering.
### 15.1 What v2.0.8 "Pulse" absorbed
v2.0.8 shipped (commit `6a80769`, tag `v2.0.8`, 2026-04-23 07:21Z) bundled:
- **v2.2 "Pulse" InsightToast** (from April 19 roadmap) — real-time toast stack over the WebSocket event bus; DreamCompleted / ConsolidationCompleted / ConnectionDiscovered / MemoryPromoted/Demoted/Suppressed surface automatically.
- **v2.3 "Terrarium" Memory Birth Ritual** — 60-frame elastic materialization on every `MemoryCreated` event.
- **8 new dashboard surfaces** exposing the cognitive engine: `/reasoning`, `/duplicates`, `/dreams`, `/schedule`, `/importance`, `/activation`, `/contradictions`, `/patterns`.
- **Reasoning Theater** wired to the 8-stage `deep_reference` cognitive pipeline with Cmd+K Ask palette.
- **3D graph brightness** auto-compensation + user slider (0.5×–2.5×, localStorage-persisted).
- **Intel Mac restored** via `ort-dynamic` + Homebrew onnxruntime (closes #41, sidesteps Microsoft's upstream deprecation of x86_64 macOS ONNX Runtime prebuilts).
- **Cross-reference hardening** — contradiction-detection false positives from 12→0 on an FSRS-6 query; primary-selection topic-term filter (50% relevance + 20% trust + 30% term_presence) fixes off-topic-high-trust-wins-query bug.
Post-v2.0.8 hygiene commit `0e9b260` removed 3,091 LOC of orphan code (9 superseded tool modules + ghost env-var docs + one dead fn).
### 15.2 The audit finding — "decorative memory" at system scale
Three agents ran in parallel on 2026-04-23. Core diagnosis: **Vestige has 30 cognitive modules but only 2 autonomic mechanisms** (6h auto-consolidation loop + per-tool-call scheduler at `server.rs:884`). The 20-event WebSocket bus at `dashboard/events.rs` has **zero backend subscribers** — all 14 live event types flow to the dashboard and terminate. Fully-built trigger methods exist but nothing calls them:
- `ProspectiveMemory::check_triggers()` at `prospective_memory.rs:1260` — 9h intention window, never polled.
- `SpeculativeRetriever::prefetch()` at `advanced/speculative.rs` (606 LOC) — never awaited.
- `MemoryDreamer::run_consolidation_cycle()` — instantiated on CognitiveEngine but the 6h timer at `main.rs:258` calls only `storage.run_consolidation()` (FSRS decay), never the dreamer.
Three completely dead modules: `MemoryCompressor`, `AdaptiveEmbedder`, `EmotionalMemory` (constructed in `CognitiveEngine::new()` at `cognitive.rs:145-160`, zero call sites in vestige-mcp). `Rac1CascadeSwept`, `ActivationSpread`, `RetentionDecayed` events declared but never emitted.
**This is the ARC-AGI-3 pattern at system scale:** storage exists, retrieval exists, memory never self-triggers during the agent's decision path because no subscriber is listening. Sam's paraphrased thesis: *"the bottleneck won't be how much the agent knows — it will be how efficiently it MANAGES what it knows."*
### 15.3 The 2026 SOTA convergence — "retrieval is solved, management is not"
Web-research agent surfaced the consensus. Load-bearing papers + their unshipped primitives:
- **Titans** (arXiv 2501.00663, Google NeurIPS 2025) — test-time weight updates via surprise gradient. Active IN-MODEL.
- **A-Mem** (arXiv 2502.12110) — Zettelkasten dynamic re-linking on write.
- **Memory-R1** (arXiv 2508.19828) — RL-trained Manager with ADD/UPDATE/DELETE/NOOP on 152 QA pairs; beats baselines on LoCoMo + MSC + LongMemEval.
- **Mem-α** (arXiv 2509.25911) — RL over tripartite core/episodic/semantic memory, trained on 30k tokens, generalizes to 400k.
- **MemR³** (arXiv 2512.20237) — closed-loop router with retrieve/reflect/answer decision + evidence-gap tracking.
- **SleepGate** (arXiv 2603.14517) + **LightMem** (arXiv 2510.18866) — sleep-phase offline consolidation, timer-decoupled autonomous.
- **StageMem** (arXiv 2604.16774) + **Evidence for Limited Metacognition in LLMs** (arXiv 2509.21545) — item-level confidence separated from retention, validity-screened selective abstention.
- **Memory in the Age of AI Agents** survey (arXiv 2512.13564) — taxonomy (Forms/Functions/Dynamics); all open problems live in Dynamics.
**Three unshipped-by-anyone concepts define the 2026 frontier:** meta-memory / confidence-gated generation (refuse to answer when load-bearing memory is cold), autonomous consolidation on surprise/drift (not on timer), write-time contradiction detection with agent-facing alerts.
### 15.4 Competitive landscape — the white-space lanes
Nobody ships: **confidence-gated generation, proactive contradiction flagging without query, predictive pre-warm at UserPromptSubmit, autonomic working-memory capacity enforcement.**
- Mem0 v2 (Apr 16, 2026): auto-dedup (0.9 threshold), single-pass fact extraction. Retrieval still query-triggered.
- Letta: sleep-time agents mutate shared memory blocks asynchronously (most actively-managing shipped product). Archival/recall still query-triggered.
- Zep Graphiti: temporal invalidation via valid-until edges, community summarization. Retrieval still query-triggered.
- Pieces LTM-2: OS-level auto-OCR capture (most aggressive autonomous capture). No autonomous management.
- Anthropic Claude Code: 95%-context auto-compaction. No trust-scored memories, no scheduled dream, no confidence gating.
- Google Titans: surprise-gated memory IN-MODEL; not a server-level primitive.
Every one of those four white-space primitives has raw material **already built** in Vestige (FSRS-6 trust scores, `deep_reference`, `predict`, `SpeculativeRetriever`, WebSocket event bus, Sanhedrin POC from April 20). The bottleneck is wiring, not features.
### 15.5 v2.0.9 "Autopilot" — Weekend Ship (2-3 days)
**Single architectural change**: add a backend event-subscriber task in `main.rs` (~50-100 LOC `tokio::spawn`) that consumes the existing WebSocket bus and routes events into the cognitive modules that already have trigger methods. This one commit flips 14 dormant primitives into active ones simultaneously.
**Concrete wiring:**
| Event | Currently emits to | Add backend routing |
|---|---|---|
| `MemoryCreated` | dashboard only | `synaptic_tagging.trigger_prp()` + `predictive_memory.record_save()` + `cross_project.record_pattern()` |
| `SearchPerformed` | dashboard only | `speculative.prefetch()` awaited in background task |
| `MemoryPromoted` | dashboard only | `activation_network.cascade_reinforce(neighbors, 0.3)` |
| `MemorySuppressed` | dashboard only | emit `Rac1CascadeSwept` (currently declared never-emitted) |
| `ImportanceScored > 0.85` | dashboard only | auto-`promote` |
| `DeepReferenceCompleted` with contradictions | dashboard only | queue a `dream()` cycle for contradiction-resolution |
**Three additional changes:**
1. New 60s `tokio::interval` in `main.rs` calls `cog.prospective_memory.check_triggers(current_session_context)`. On hit, emit new `IntentionFired` event + MCP sampling/createMessage notification to the client.
2. Add `cognitive.dreamer.run_consolidation_cycle()` call inside the existing 6h auto-consolidation loop at `main.rs:258` (alongside, not replacing, `storage.run_consolidation()`).
3. `find_duplicates` auto-runs when `Heartbeat.total_memories > 700`.
**Launch narrative:** *"Vestige now acts on your memories while you sleep — 14 cognitive modules that used to wait for a query now fire autonomously on every memory event."*
### 15.6 v2.5.0 "Autonomic" — 1 Week After v2.0.9
Three unshipped-by-anyone primitives land in one release. This is the category-defining drop.
**(A) Hallucination Guillotine — Confidence-Gated Veto**
Stop hook runs `deep_reference` on the agent's draft response, checks FSRS retention on load-bearing claims. If any required fact has retention < 0.4, exits 2 with a `VESTIGE VETO: cold memory on claim X, retrieve fresh evidence or explicitly mark uncertain` block. The Sanhedrin POC from 2026-04-20 already proves the mechanism works in real dogfooding — three consecutive drafts were vetoed by the POC. Package as a formal `vestige-guillotine` Claude Code plugin.
Files: new `crates/vestige-mcp/src/hooks/guillotine.rs`, plugin manifest in `packages/claude-plugin/`. Composes existing `deep_reference` trust-score pipeline + the Sanhedrin dogfooding script.
**(B) Contradiction Daemon — Write-Time Alerting**
On every `smart_ingest` write, a fast `deep_reference` runs against the existing graph. If the new memory contradicts an existing memory with trust > 0.6, the server fires an MCP sampling/createMessage notification to the agent *in the same conversation:* *"this contradicts memory Y from \[date\]. Supersede Y, discard X, or mark both as time-bounded?"* The agent resolves the conflict in real time instead of waking up to it three sessions later.
Files: `crates/vestige-mcp/src/tools/smart_ingest.rs` (post-write hook), `crates/vestige-mcp/src/protocol/sampling.rs` (new — MCP sampling/createMessage support). Composes existing `deep_reference` + contradiction-detection hardening from v2.0.8.
**(C) Pulse Prefetch — Predictive Pre-Warm at UserPromptSubmit**
UserPromptSubmit hook fires `predict(query)`, top-k results injected into agent context before the first token. The agent never has to ask; the memory is already there. Nemori did predict-calibrate; Letta does sleep-time; nobody fires at query-arrival.
Files: `crates/vestige-mcp/src/hooks/pulse_prefetch.rs` (new), extend `SpeculativeRetriever::prefetch()`. Composes existing `predict` tool + `speculative.rs` (606 LOC, never awaited until v2.0.9 wiring).
**Launch narrative:** *"The first MCP memory that VETOes hallucinations before the user sees them, FLAGS contradictions at write-time, and PREDICTS what the agent will need before the agent knows it needs it. Zero-shot proactive memory management."*
### 15.7 v2.6.0 "Sleepwalking" — 2 Weeks After v2.5.0
Dream cycle detects high-value cross-project patterns → auto-generates and opens pull requests against the user's codebase. Zep writes text summaries; Vestige writes code. The `cross_project.find_universal_patterns()` fn already exists. Wire it via a new `sleepwalk` subcommand that invokes `gh pr create` with generated diffs.
Files: new `crates/vestige-mcp/src/bin/sleepwalk.rs`, composes `CrossProjectLearner` + `MemoryDreamer` + existing gh CLI integration.
**Launch narrative:** *"Your AI memory writes PRs while you sleep."*
### 15.8 Post-v2.6 — Remaining April 19 roadmap
After v2.6 "Sleepwalking," the April 19 placeholder roadmap reasserts with renumbered slots:
| Slot | Codename | Scope |
|---|---|---|
| v2.7 | Decide | Qwen3 embeddings (absorbing the pre-existing `feat/v2.1.0-qwen3-embed` branch) once M3 Max Metal validates |
| v2.8 | Rewind | Temporal slider + pin, state reconstruction over time |
| v2.9 | Empathy | Apple Watch biometric flashbulb + frustration detection → arousal boost. First Pro-tier gate candidate. |
| v2.10 | Grip | Cluster gestures + manual bridging |
| v2.11 | Remote | `vestige-cloud` self-host upgrade (5→24 MCP tools + Streamable HTTP + Docker) |
| v3.0 | Branch | CoW memory branching + multi-tenant SaaS (gated on v2.11 adoption + cashflow) |
### 15.9 Expected 30-day outcome
Target: v2.0.9 + v2.5.0 + v2.6.0 all ship within 30 days of v2.0.8.
Stars trajectory: current 484 baseline at +12/day → +600 from v2.0.9 + +1,500 from v2.5.0 + +2,000 from v2.6.0 + 360 organic = **~5,000 stars by end of May 2026.** First paid commercial license lands during v2.5.0 launch week (the Hallucination Guillotine clip is exactly the artifact that makes enterprise DevRel reshare). MCP engineer role offer inbound during the same window.
CCN 2027 poster abstract gets written on the v2.5 primitives; RustConf 2026 Sep 8-11 talk submission writes itself around the event-bus-subscriber architecture pattern.
### 15.10 The one-line architectural thesis
**Vestige's bottleneck is not feature count, not capacity, not module depth. It is one missing architectural pattern — a backend event-subscriber task that routes the 14 live WebSocket events into the cognitive modules that already have the trigger methods implemented.** Closing that single gap flips Vestige from "memory library" to "cognitive agent that acts on the host LLM." Every v2.5+ feature composes on top of that one change.
---
**End of document.** Length-check: ~19,000 words / ~130 KB markdown. This is the single-page briefing that lets any AI agent plan the next phase of Vestige without having to re-read the repository.
Reference in a new issue Copy permalink