<div align="center">

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

</div>

---

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."

<details> <summary>Other platforms & install methods</summary>

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

</details>

---

Works Everywhere

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

| IDE | Setup | |-----|-------| | Claude Code | claude mcp add vestige vestige-mcp -s user | | Claude Desktop | 2-min setup | | Xcode 26.3 | Integration guide | | Cursor | Integration guide | | VS Code (Copilot) | Integration guide | | JetBrains | Integration guide | | Windsurf | Integration guide |

---

🧠 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.

| | RAG / Vector Store | Vestige | |---|---|---| | Storage | Store everything | Prediction Error Gating — only stores what's surprising or new | | Retrieval | Nearest-neighbor | 7-stage pipeline — HyDE expansion + reranking + spreading activation | | Decay | Nothing expires | FSRS-6 — memories fade naturally, context stays lean | | Duplicates | Manual dedup | Self-healing — auto-merges "likes dark mode" + "prefers dark themes" | | Importance | All equal | 4-channel scoring — novelty, arousal, reward, attention | | Sleep | No consolidation | Memory dreaming — replays, connects, synthesizes insights | | Health | No visibility | Retention dashboard — distributions, trends, recommendations | | Visualization | None | 3D neural graph — real-time WebSocket-powered Three.js | | Privacy | Usually cloud | 100% local — your data never leaves your machine |

---

🔬 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

| Tool | What It Does | |------|-------------| | session_context | One-call session init — replaces 5 calls with token-budgeted context, automation triggers, expandable IDs |

Core Memory

| Tool