vestige/docs/VESTIGE_STATE_AND_PLAN.md

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)
1. What Vestige Is
2. Workspace Architecture
3. vestige-core — Cognitive Engine
4. vestige-mcp — MCP Server + Dashboard Backend
5. apps/dashboard — SvelteKit + Three.js Frontend
6. Integrations & Packaging
7. vestige-cloud — Current Skeleton
8. Version History (v1.0 → v2.0.8)
9. The Next-Phase Plan
10. Composition Map
11. Risks & Known Gaps
12. Viral / Launch / Content Plan
13. How AI Agents Should Consume This Doc
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

[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

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
            ├── auth.rs              # Single bearer token via VESTIGE_AUTH_TOKEN env (auto-generated if unset, stored in data-dir)
            ├── 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

---

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.