Vestige

The cognitive engine that gives AI a brain.

Your AI forgets everything between sessions. Vestige fixes that.

Built on 130 years of memory research — FSRS-6 spaced repetition, prediction error gating, synaptic tagging, spreading activation, memory dreaming — all running in a single Rust binary with a 3D neural visualization dashboard. 100% local. Zero cloud.

Quick Start | Dashboard | How It Works | Tools | Docs

What's New in v2.0 "Cognitive Leap"

• 3D Memory Dashboard — SvelteKit + Three.js neural visualization with real-time WebSocket events, bloom post-processing, force-directed graph layout. Watch your AI's mind in real-time.
• WebSocket Event Bus — Every cognitive operation broadcasts events: memory creation, search, dreaming, consolidation, retention decay
• HyDE Query Expansion — Template-based Hypothetical Document Embeddings for dramatically improved search quality on conceptual queries
• Nomic v2 MoE (experimental) — fastembed 5.11 with optional Nomic Embed Text v2 MoE (475M params, 8 experts) + Metal GPU acceleration. Default: v1.5 (8192 token context)
• Command Palette — Cmd+K navigation, keyboard shortcuts, responsive mobile layout, PWA installable
• FSRS Decay Visualization — SVG retention curves with predicted decay at 1d/7d/30d, endangered memory alerts
• 29 cognitive modules — 1,238 tests, 79,600+ LOC

Quick Start

# 1. Install (macOS Apple Silicon)
curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-aarch64-apple-darwin.tar.gz | tar -xz
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/

# 2. Connect to Claude Code
claude mcp add vestige vestige-mcp -s user

# 3. Test it
# "Remember that I prefer TypeScript over JavaScript"
# ...new session...
# "What are my coding preferences?"
# → "You prefer TypeScript over JavaScript."

macOS (Intel):

curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-x86_64-apple-darwin.tar.gz | tar -xz
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-x86_64-unknown-linux-gnu.tar.gz | tar -xz
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/

Windows: Download from Releases

npm:

npm install -g vestige-mcp-server

Build from source (requires Rust 1.91+):

git clone https://github.com/samvallad33/vestige && cd vestige
cargo build --release -p vestige-mcp
# Optional: enable Metal GPU acceleration on Apple Silicon
cargo build --release -p vestige-mcp --features metal

Works Everywhere

Vestige speaks MCP — the universal protocol for AI tools. One brain, every IDE.

🧠 3D Memory Dashboard

Vestige v2.0 ships with a real-time 3D visualization of your AI's memory. Every memory is a glowing node in 3D space. Watch connections form, memories pulse when accessed, and the entire graph come alive during dream consolidation.

Features:

• Force-directed 3D graph with 1000+ nodes at 60fps
• Bloom post-processing for cinematic neural network aesthetic
• Real-time WebSocket events: memories pulse on access, burst on creation, fade on decay
• Dream visualization: graph enters purple dream mode, replayed memories light up sequentially
• FSRS retention curves: see predicted memory decay at 1d, 7d, 30d
• Command palette (Cmd+K), keyboard shortcuts, responsive mobile layout
• Installable as PWA for quick access

Tech: SvelteKit 2 + Svelte 5 + Three.js + Tailwind CSS 4 + WebSocket

The dashboard runs automatically at http://localhost:3927/dashboard when the MCP server starts.

Architecture

┌─────────────────────────────────────────────────────┐
│  SvelteKit Dashboard (apps/dashboard)                │
│  Three.js 3D Graph · WebGL + Bloom · Real-time WS   │
├─────────────────────────────────────────────────────┤
│  Axum HTTP + WebSocket Server (port 3927)            │
│  15 REST endpoints · WS event broadcast              │
├─────────────────────────────────────────────────────┤
│  MCP Server (stdio JSON-RPC)                         │
│  21 tools · 29 cognitive modules                     │
├─────────────────────────────────────────────────────┤
│  Cognitive Engine                                    │
│  ┌──────────┐ ┌──────────┐ ┌───────────────┐       │
│  │ FSRS-6   │ │ Spreading│ │ Prediction    │       │
│  │ Scheduler│ │ Activation│ │ Error Gating  │       │
│  └──────────┘ └──────────┘ └───────────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌───────────────┐       │
│  │ Memory   │ │ Synaptic │ │ Hippocampal   │       │
│  │ Dreamer  │ │ Tagging  │ │ Index         │       │
│  └──────────┘ └──────────┘ └───────────────┘       │
├─────────────────────────────────────────────────────┤
│  Storage Layer                                       │
│  SQLite + FTS5 · USearch HNSW · Nomic Embed v1.5    │
│  Optional: Nomic v2 MoE · Qwen3 Reranker · Metal   │
└─────────────────────────────────────────────────────┘

Why Not Just Use RAG?

RAG is a dumb bucket. Vestige is an active organ.

🔬 The Cognitive Science Stack

This isn't a key-value store with an embedding model bolted on. Vestige implements real neuroscience:

Prediction Error Gating — The hippocampal bouncer. When new information arrives, Vestige compares it against existing memories. Redundant? Merged. Contradictory? Superseded. Novel? Stored with high synaptic tag priority.

FSRS-6 Spaced Repetition — 21 parameters governing the mathematics of forgetting. Frequently-used memories stay strong. Unused memories naturally decay. Your context window stays clean.

HyDE Query Expansion (v2.0) — Template-based Hypothetical Document Embeddings. Expands queries into 3-5 semantic variants, embeds all variants, and searches with the centroid embedding for dramatically better recall on conceptual queries.

Synaptic Tagging — A memory that seemed trivial this morning can be retroactively tagged as critical tonight. Based on Frey & Morris, 1997.

Spreading Activation — Search for "auth bug" and find the related JWT library update from last week. Memories form a graph, not a flat list. Based on Collins & Loftus, 1975.

Dual-Strength Model — Every memory has storage strength (encoding quality) and retrieval strength (accessibility). A deeply stored memory can be temporarily hard to retrieve — just like real forgetting. Based on Bjork & Bjork, 1992.

Memory Dreaming — Like sleep consolidation. Replays recent memories to discover hidden connections, strengthen important patterns, and synthesize insights. Dream-discovered connections persist to a graph database. Based on the Active Dreaming Memory framework.

Waking SWR Tagging — Promoted memories get sharp-wave ripple tags for preferential replay during dream consolidation. 70/30 tagged-to-random ratio. Based on Buzsaki, 2015.

Autonomic Regulation — Self-regulating memory health. Auto-promotes frequently accessed memories. Auto-GCs low-retention memories. Consolidation triggers on 6h staleness or 2h active use.

Full science documentation ->

🛠 21 MCP Tools

Context Packets

Core Memory

Cognitive Engine

Autonomic

Scoring & Dedup

Maintenance

Make Your AI Use Vestige Automatically

Add this to your CLAUDE.md:

## Memory

At the start of every session:
1. Search Vestige for user preferences and project context
2. Save bug fixes, decisions, and patterns without being asked
3. Create reminders when the user mentions deadlines

Full CLAUDE.md templates ->

Technical Details

Optional Features

# Metal GPU acceleration (Apple Silicon — faster embedding inference)
cargo build --release -p vestige-mcp --features metal

# Nomic Embed Text v2 MoE (475M params, 305M active, 8 experts)
cargo build --release -p vestige-mcp --features nomic-v2

# Qwen3 Reranker (Candle backend, high-precision cross-encoder)
cargo build --release -p vestige-mcp --features qwen3-reranker

# SQLCipher encryption
cargo build --release -p vestige-mcp --no-default-features --features encryption,embeddings,vector-search

CLI

vestige stats                    # Memory statistics
vestige stats --tagging          # Retention distribution
vestige stats --states           # Cognitive state breakdown
vestige health                   # System health check
vestige consolidate              # Run memory maintenance
vestige restore <file>           # Restore from backup
vestige dashboard                # Open 3D dashboard in browser

Documentation

Troubleshooting

Ensure vestige-mcp is in your PATH:

which vestige-mcp
# Or use the full path:
claude mcp add vestige /usr/local/bin/vestige-mcp -s user

First run downloads ~130MB from Hugging Face. If behind a proxy:

export HTTPS_PROXY=your-proxy:port

Cache: macOS ~/Library/Caches/com.vestige.core/fastembed | Linux ~/.cache/vestige/fastembed

The dashboard starts automatically on port 3927 when the MCP server runs. Check:

curl http://localhost:3927/api/health
# Should return {"status":"healthy",...}

More troubleshooting ->

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

AGPL-3.0 — free to use, modify, and self-host. If you offer Vestige as a network service, you must open-source your modifications.