vestige/README.md

Vestige

The open-source cognitive engine for AI.

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 — all running in a single Rust binary, 100% local.

What's New in v1.8.0

• One-call session init — new session_context tool replaces 5 calls (~15K → ~500 tokens)
• Token budgeting — token_budget parameter on search and session_context for cost control
• Reader/writer split — concurrent SQLite reads via WAL mode, Arc<Storage> everywhere
• int8 vectors — 2x memory savings with <1% recall loss
• FTS5 porter stemmer — 15-30% better keyword search via stemming

See CHANGELOG for full version history.

---

Give Your AI a Brain in 30 Seconds

# 1. Install
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
claude mcp add vestige vestige-mcp -s user

# 3. Test
# "Remember that I prefer TypeScript over JavaScript"
# New session → "What are my coding preferences?"
# It remembers.

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:

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

Build from source:

git clone https://github.com/samvallad33/vestige && cd vestige
cargo build --release
sudo cp target/release/{vestige-mcp,vestige,vestige-restore} /usr/local/bin/

npm:

npm install -g vestige-mcp

---

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

Fix a bug in VS Code. Open Xcode. Your AI already knows about the fix.

---

Why Not Just Use RAG?

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

	RAG / Vector Store	Vestige
Storage	Store everything, retrieve everything	Prediction Error Gating — only stores what's surprising or new
Retrieval	Nearest-neighbor similarity	Spreading activation — finds related memories through association chains
Decay	Nothing ever expires	FSRS-6 — memories fade like yours do, keeping context lean
Duplicates	Manual dedup or none	Self-healing — automatically merges "likes dark mode" + "prefers dark themes"
Importance	All memories are equal	Synaptic tagging — retroactively strengthens memories that turn out to matter
Privacy	Usually cloud-dependent	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 bouncer for your brain. When new information arrives, Vestige compares it against existing memories. Redundant? Merged. Contradictory? Superseded. Novel? Stored. Just like the hippocampus.

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.

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 memory about the JWT library update you saved last week. Memories form a graph, not a flat list. Based on Collins & Loftus, 1975.

Dual-Strength Model — Every memory has two values: storage strength (how well it's encoded) and retrieval strength (how easily it surfaces). A memory can be deeply stored but temporarily hard to retrieve — just like real forgetting. Based on Bjork & Bjork, 1992.

Memory States — Active, Dormant, Silent, Unavailable. Memories transition between states based on usage patterns, exactly like human cognitive architecture.

Memory Dreaming (v1.5.0) — Like sleep consolidation. Replays recent memories to discover hidden connections, strengthen important patterns, and synthesize insights. Based on the Active Dreaming Memory framework.

ACT-R Activation (v1.5.0) — Retrieval strength depends on BOTH recency AND frequency of access, computed from full access history. A memory accessed 50 times over 3 weeks is stronger than one accessed once yesterday. Based on Anderson, 1993.

Automatic Consolidation (v1.5.0) — FSRS-6 decay runs automatically every 6 hours + inline every 100 tool calls. Episodic memories auto-merge into semantic summaries. Cross-memory reinforcement strengthens neighbors on access. No manual maintenance needed.

Full science documentation →

---

Tools — 19 MCP Tools

Context Packets (v1.8.0)

Tool	What It Does
session_context	One-call session init — replaces 5 calls with a single token-budgeted response. Returns context, automation triggers, and expandable memory IDs

Core Memory

Tool	What It Does
search	7-stage cognitive search — keyword + semantic + convex fusion + reranking + temporal boost + competition + spreading activation. Optional token_budget for cost control
smart_ingest	Intelligent storage with automatic CREATE/UPDATE/SUPERSEDE via Prediction Error Gating. Batch mode for session-end saves
memory	Get, delete, check state, promote (thumbs up), or 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 via replay — discovers hidden connections, synthesizes insights
explore_connections	Graph traversal — reasoning chains, associations via spreading activation, bridges between memories
predict	Proactive retrieval — predicts what memories you'll need next based on context and activity patterns

Scoring & Dedup

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

Maintenance & Data

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

---

Make Your AI Use Vestige Automatically

Add this to your CLAUDE.md and your AI becomes proactive:

## 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 + strengthens

Full CLAUDE.md templates →

---

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

---

Technical Details

• Language: Rust (52,000+ lines, 1,100+ tests)
• Binary size: ~20MB
• Embeddings: Nomic Embed Text v1.5 (768-dim, local ONNX inference via fastembed)
• Vector search: USearch HNSW (20x faster than FAISS)
• Storage: SQLite + FTS5 (optional SQLCipher encryption)
• Transport: MCP stdio (JSON-RPC 2.0)
• Dependencies: Zero runtime dependencies beyond the binary
• First run: Downloads embedding model (~130MB), then fully offline
• Platforms: macOS (ARM/Intel), Linux (x86_64), Windows

---

Documentation

Document	Contents
FAQ	30+ answers to common questions
How It Works	The neuroscience behind every feature
Storage Modes	Global, per-project, multi-instance setup
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 locations:

• macOS: ~/Library/Caches/com.vestige.core/fastembed
• Linux: ~/.cache/vestige/fastembed
• Windows: %LOCALAPPDATA%\vestige\cache\fastembed

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