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

Other platforms & install methods

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.

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	What It Does
`search`	7-stage cognitive search — HyDE expansion + keyword + semantic + reranking + temporal + competition + spreading activation
`smart_ingest`	Intelligent storage with CREATE/UPDATE/SUPERSEDE via Prediction Error Gating. Batch mode for session-end saves
`memory`	Get, delete, check state, promote (thumbs up), demote (thumbs down)
`codebase`	Remember code patterns and architectural decisions per-project
`intention`	Prospective memory — "remind me to X when Y happens"

Cognitive Engine

Tool	What It Does
`dream`	Memory consolidation — replays memories, discovers connections, synthesizes insights, persists graph
`explore_connections`	Graph traversal — reasoning chains, associations, bridges between memories
`predict`	Proactive retrieval — predicts what you'll need next based on context and activity

Autonomic

Tool	What It Does
`memory_health`	Retention dashboard — distribution, trends, recommendations
`memory_graph`	Knowledge graph export — force-directed layout, up to 200 nodes

Scoring & Dedup

Tool	What It Does
`importance_score`	4-channel neuroscience scoring (novelty, arousal, reward, attention)
`find_duplicates`	Detect and merge redundant memories via cosine similarity

Maintenance

Tool	What It Does
`system_status`	Combined health + stats + cognitive state + recommendations
`consolidate`	Run FSRS-6 decay cycle (also auto-runs every 6 hours)
`memory_timeline`	Browse chronologically, grouped by day
`memory_changelog`	Audit trail of state transitions
`backup` / `export` / `gc`	Database backup, JSON export, garbage collection
`restore`	Restore from JSON backup

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

You Say	AI Does
"Remember this"	Saves immediately
"I prefer..." / "I always..."	Saves as preference
"Remind me..."	Creates a future trigger
"This is important"	Saves + promotes

Full CLAUDE.md templates ->

Technical Details

Metric	Value
Language	Rust 2024 edition (MSRV 1.91)
Codebase	79,600+ lines, 1,238 tests
Binary size	~20MB
Embeddings	Nomic Embed Text v1.5 (768d → 256d Matryoshka, 8192 context)
Vector search	USearch HNSW (20x faster than FAISS)
Reranker	Jina Reranker v1 Turbo (38M params, +15-20% precision)
Storage	SQLite + FTS5 (optional SQLCipher encryption)
Dashboard	SvelteKit 2 + Svelte 5 + Three.js + Tailwind CSS 4
Transport	MCP stdio (JSON-RPC 2.0) + WebSocket
Cognitive modules	29 stateful (16 neuroscience, 11 advanced, 2 search)
First run	Downloads embedding model (~130MB), then fully offline
Platforms	macOS (ARM/Intel), Linux (x86_64), Windows

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

Document	Contents
FAQ	30+ common questions answered
Science	The neuroscience behind every feature
Storage Modes	Global, per-project, multi-instance
CLAUDE.md Setup	Templates for proactive memory
Configuration	CLI commands, environment variables
Integrations	Xcode, Cursor, VS Code, JetBrains, Windsurf
Changelog	Version history

Troubleshooting

"Command not found" after installation

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

Embedding model download fails

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

Dashboard not loading

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.

Built by @samvallad33
_{79,600+ lines of Rust · 29 cognitive modules · 130 years of memory research · one 22MB binary}

Name		Name	Last commit message	Last commit date
Latest commit History 87 Commits
.github		.github
apps/dashboard		apps/dashboard
crates		crates
docs		docs
packages		packages
scripts		scripts
tests/e2e		tests/e2e
.agentaudit-report.json		.agentaudit-report.json
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLAUDE.md.template		CLAUDE.md.template
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
demo.sh		demo.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Vestige

The cognitive engine that gives AI a brain.

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

Quick Start

Works Everywhere

🧠 3D Memory Dashboard

Architecture

Why Not Just Use RAG?

🔬 The Cognitive Science Stack

🛠 21 MCP Tools

Context Packets

Core Memory

Cognitive Engine

Autonomic

Scoring & Dedup

Maintenance

Make Your AI Use Vestige Automatically

Technical Details

Optional Features

CLI

Documentation

Troubleshooting

Contributing

License

About

Uh oh!

Releases 11

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Vestige

The cognitive engine that gives AI a brain.

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

Quick Start

Works Everywhere

🧠 3D Memory Dashboard

Architecture

Why Not Just Use RAG?

🔬 The Cognitive Science Stack

🛠 21 MCP Tools

Context Packets

Core Memory

Cognitive Engine

Autonomic

Scoring & Dedup

Maintenance

Make Your AI Use Vestige Automatically

Technical Details

Optional Features

CLI

Documentation

Troubleshooting

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages