Vestige
### Your AI has the memory of a goldfish. Vestige gives it a hippocampus.
Local-first cognitive memory for AI agents. 130 years of neuroscience, compiled into one 23MB Rust binary. Zero cloud. Your data never leaves your machine.
[](https://github.com/samvallad33/vestige/stargazers)
[](https://github.com/samvallad33/vestige/releases/latest)
[](https://github.com/samvallad33/vestige/actions)
[](LICENSE)
[**โก Quick Start**](#-60-second-start) ยท [**๐ง Why It's Different**](#-why-this-isnt-rag-with-a-fancy-name) ยท [**๐ฌ The Science**](#-this-is-real-neuroscience-not-a-metaphor) ยท [**๐ 13 Tools**](#-13-tools-one-brain) ยท [**๐ Dashboard**](#-watch-your-ai-think-in-3d)
---
> ### The moment that made this real
>
> You spent 40 minutes last Tuesday explaining to your agent why the staging connection pooler corrupts data during migrations. You moved on.
>
> Today โ new session, new context window โ it cheerfully suggests *disabling the pooler during a migration.* The lesson is gone. The agent that "remembers everything" remembers **nothing** that matters.
>
> **Vestige is the fix.** Not a bigger context window. Not a vector dump. A memory that **decides what to keep, reaches backward to find the root cause of a failure, and tells you when you're about to contradict something you already learned.**
---
## โก 60-second start
```bash
npm install -g vestige-mcp-server@latest # 1. install (one binary, no Docker, no API key)
claude mcp add vestige vestige-mcp -s user # 2. connect to Claude Code
```
That's it. Now talk to your agent like it has a memory โ because now it does:
```
You: "Remember: we always disable SimSIMD on release builds, it breaks old x86 CPUs."
...days later, fresh session, zero context...
You: "Should I enable SimSIMD for the release?"
AI: โ ๏ธ Your claim contradicts a stored decision โ you decided to DISABLE it (it breaks old x86 CPUs).
```
> That last line is **`claim_contradicts_memory`** โ a real status the engine returns. Most memory systems give you confident silence. Vestige tells you when you're about to repeat a mistake. *(Works with Codex, Cursor, VS Code, Claude Desktop, Windsurf, JetBrains, Zed โ anything that speaks MCP. [Full setup โ](#-works-in-every-editor-you-use))*
---
## ๐ง Why this isn't "RAG with a fancy name"
RAG is a bucket. You throw everything in and hope nearest-neighbor finds it later. Vestige is an **active organ** โ it gates what enters, lets the unimportant fade, and reasons across what's left.
| | ๐ชฃ RAG / Vector Store | ๐ง Vestige |
|---|---|---|
| **What it stores** | Everything you give it | Only what's **surprising or new** (Prediction-Error Gating โ the hippocampal bouncer) |
| **What it forgets** | Nothing โ bloats forever | Unused memories **decay** on the real FSRS-6 forgetting curve; context stays lean |
| **Finding the root cause** | Can't โ the cause isn't *similar* to the bug | **Reaches backward in time** to the causally-upstream memory (the headline v2.2 feature โ) |
| **Contradictions** | Silent โ happily serves the stale answer | Returns **`claim_contradicts_memory`** and shows you the conflict |
| **Duplicates** | You dedup by hand | Self-heals: *"likes dark mode"* + *"prefers dark themes"* โ merged |
| **Forgetting on demand** | DELETE only | **`suppress`** โ compounding top-down inhibition, neighbor cascade, reversible for 24h |
| **Consolidation** | None | **Dreams** โ replays memories, finds hidden connections, synthesizes insights |
| **Where it lives** | Usually someone else's cloud | **100% on your machine.** One binary. No telemetry. |
---
## ๐ฅ The feature no other AI memory has: Memory with hindsight
Here's the thing vector search **structurally cannot do.**
A bug appears today. The root cause was a quiet decision you made *three weeks ago* โ a changed env var, a config tweak, a service you swapped. That root cause is **not similar to the bug.** It shares no keywords. A vector search will never surface it, because it's not *similar* โ it's *causally upstream.*
Vestige's **Retroactive Salience Backfill** โ a faithful port of **Zaki/Cai et al., 2024, *Nature* 637:145โ155** (offline ensemble co-reactivation links memories across days) โ does what your brain does after a failure: it **reaches backward through time**, finds the dormant memory that *caused* this, and promotes it โ because they share an **entity** (the same file, env var, or service), not because they share words.
```bash
vestige backfill --contrast # show the root cause a vector search would have missed
```
> **Run 2 is smarter than run 1.** Every failure your agent records makes the *next* session diagnose faster. That compounding is the moat โ and it runs automatically inside consolidation, no babysitting.
This shipped in **v2.2.0** alongside a 34โ13 tool consolidation and a rebuilt retrieval engine. [Full release notes โ](https://github.com/samvallad33/vestige/releases/tag/v2.2.0)
---
## ๐ฌ This is real neuroscience, not a metaphor
Every mechanism below is a cited paper, implemented in Rust, running locally. This is the difference between *"we use embeddings"* and *a memory system.*
| Mechanism | What it does for you | Grounded in |
|---|---|---|
| **Prediction-Error Gating** | Redundant info gets merged, contradictory gets superseded, only the novel gets stored | The hippocampal novelty signal |
| **FSRS-6 Spaced Repetition** | 21 parameters of the mathematics of forgetting โ used memories stay, unused fade | Modern spaced-repetition research |
| **Retroactive Salience Backfill** | Backward causal reach to the root cause of a failure | Zaki/Cai et al. 2024, *Nature* 637:145โ155 |
| **Synaptic Tagging** | A memory that looked trivial this morning can be tagged critical tonight | [Frey & Morris 1997](https://doi.org/10.1038/385533a0) |
| **Spreading Activation** | Search "auth bug," surface last week's JWT update โ memory is a graph, not a list | [Collins & Loftus 1975](https://doi.org/10.1037/0033-295X.82.6.407) |
| **Dual-Strength Model** | Storage strength vs. retrieval strength โ deeply stored โ instantly recalled, just like you | [Bjork & Bjork 1992](https://doi.org/10.1016/S0079-7421(08)60016-9) |
| **Memory Dreaming** | Sleep-like consolidation: replays, connects, synthesizes insights to a graph | Active-dreaming consolidation |
| **Active Forgetting (`suppress`)** | Top-down inhibition that *compounds* and cascades to neighbors โ reversible for 24h | [Anderson 2025](https://www.nature.com/articles/s41583-025-00929-y) ยท [Davis 2020](https://pmc.ncbi.nlm.nih.gov/articles/PMC7477079/) |
[**Read the full science doc โ**](docs/SCIENCE.md) โ every feature, every paper.
---
## ๐ 13 tools, one brain
v2.2.0 consolidated a sprawling 34-tool surface into **13 sharp ones** your agent actually reaches for. Old names still work as hidden aliases โ nothing breaks.
| Tool | What it does |
|---|---|
| ๐ `recall` | The retrieval engine โ folds search + deep reasoning + contradiction detection into one call. F32 embeddings, Reciprocal Rank Fusion, claim-vs-memory checks. |
| ๐ง `backfill` | **Memory with hindsight** โ backward causal reach to a failure's root cause (Cai 2024). |
| ๐พ `smart_ingest` | Stores with CREATE / UPDATE / SUPERSEDE via Prediction-Error Gating. Batch session-end saves. |
| ๐ `memory` | Get, edit, promote ๐, demote ๐, check state, purge content + embeddings. |
| ๐งฉ `graph` | Reasoning chains, associations, bridges, predictions, force-directed export. |
| ๐ `maintain` | Consolidate, dream, GC, importance-score, backup, export, restore โ one maintenance verb. |
| ๐งน `dedup` | Self-healing duplicate detection + merge (8 old tools โ 1). |
| ๐ซ `suppress` | Top-down active forgetting โ compounds, cascades, reversible 24h. The memory is *inhibited, not erased.* |
| ๐ `memory_status` | Health + stats + trends + recommendations in one packet. |
| ๐งฌ `codebase` ยท `intention` ยท `source_sync` ยท `session_start` | Per-project code memory ยท "remind me when X" ยท external-source connectors ยท one-call session init. |
---
## ๐ Watch your AI think in 3D
```bash
vestige dashboard # โ http://localhost:3927/dashboard
```
Every memory is a glowing node in a real-time, force-directed 3D graph. Connections form as you work. Nodes **pulse** when accessed, **burst** on creation, **fade** on decay. Kick off a consolidation and the whole graph slides into **purple dream mode**, replaying memories that light up in sequence.
Built with SvelteKit 2 ยท Svelte 5 ยท Three.js ยท WebGL bloom ยท live WebSocket events. 1000+ nodes at 60fps. Installable as a PWA.
---
## ๐งฉ Works in every editor you use
Vestige speaks MCP, so any client that can register a stdio MCP server can use it.
| Editor | One-liner |
|---|---|
| **Claude Code** | `claude mcp add vestige vestige-mcp -s user` |
| **Codex** | `codex mcp add vestige -- vestige-mcp` |
| **Cursor / VS Code / Windsurf / JetBrains / Xcode / OpenCode** | [Integration guides โ](docs/integrations/) |
| **Claude Desktop** | [2-minute setup โ](docs/CONFIGURATION.md#claude-desktop-macos) |
Other install methods (Intel Mac, Windows, build-from-source)
**Update an existing install:**
```bash
vestige update # binaries only
vestige update --sandwich-companion # also refresh optional Claude Code companion files
```
**macOS (Intel):** Microsoft is dropping x86_64 macOS ONNX Runtime prebuilts after v1.23.0, so the Intel Mac build links dynamically against a Homebrew ONNX Runtime:
```bash
brew install onnxruntime
npm install -g vestige-mcp-server@latest
echo 'export ORT_DYLIB_PATH="'"$(brew --prefix onnxruntime)"'/lib/libonnxruntime.dylib"' >> ~/.zshrc && source ~/.zshrc
claude mcp add vestige vestige-mcp -s user
```
Full guide: [`docs/INSTALL-INTEL-MAC.md`](docs/INSTALL-INTEL-MAC.md).
**Windows + Claude Desktop:** quit Claude Desktop from the tray, then in PowerShell:
```powershell
npm install -g vestige-mcp-server@latest
vestige-mcp --version
```
Point `%APPDATA%\Claude\claude_desktop_config.json` at it:
```json
{ "mcpServers": { "vestige": { "command": "vestige-mcp" } } }
```
If it can't find the command, run `where vestige-mcp` and use the exact `.cmd` path.
**Build from source (Rust 1.91+):**
```bash
git clone https://github.com/samvallad33/vestige && cd vestige
cargo build --release -p vestige-mcp
# Apple Silicon GPU: --features metal ยท NVIDIA: --features qwen3-embeddings,cuda
```
---
## ๐ Make your AI use memory automatically
Registering the server exposes the tools; a short instruction tells the agent *when* to call them. Drop in the protocol and your agent saves and recalls on its own:
| You say | Vestige does |
|---|---|
| *"Remember this"* | Saves immediately |
| *"I always..."* / *"I prefer..."* | Saves as a durable preference |
| *"Remind me when..."* | Creates a future trigger (`intention`) |
| *"This is important"* | Saves **and** promotes it |
[Agent memory protocol โ](docs/AGENT-MEMORY-PROTOCOL.md) ยท [Claude Code template โ](docs/CLAUDE-SETUP.md)
---
## ๐ Under the hood
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ SvelteKit Dashboard โ Three.js 3D graph ยท WebGL bloom โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Axum HTTP + WebSocket (:3927) โ REST + live event stream โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ MCP Server (stdio JSON-RPC) โ 13 tools ยท 30 modules โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Cognitive Engine โ
โ FSRS-6 ยท Spreading Activation ยท Prediction-Error Gating โ
โ Retroactive Salience Backfill ยท Synaptic Tagging โ
โ Memory Dreamer ยท Hippocampal Index ยท Active Forgetting โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Storage โ SQLite + FTS5 ยท USearch HNSW ยท Nomic Embed v1.5โ
โ Optional: Qwen3 reranker ยท SQLCipher ยท Metal/CUDA โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
| | |
|---|---|
| **Language** | Rust 2024 (MSRV 1.91) โ **86,000+ lines** |
| **Binary** | ~23MB, single file |
| **Embeddings** | Nomic Embed Text v1.5 (768dโ256d Matryoshka, 8192 ctx); Qwen3 optional |
| **Vector search** | USearch HNSW (โ20ร faster than FAISS) |
| **Storage** | SQLite + FTS5, optional SQLCipher encryption |
| **Tests** | **1,550 passing** ยท clippy `-D warnings` clean |
| **First run** | Downloads ~130MB embedding model once, then **fully offline forever** |
| **Platforms** | macOS (ARM + Intel) ยท Linux x86_64 ยท Windows x86_64 โ all prebuilt |
---
## ๐ Go deeper
| | |
|---|---|
| [**FAQ**](docs/FAQ.md) | 30+ real questions answered |
| [**The Science**](docs/SCIENCE.md) | Every feature, every paper |
| [**Storage Modes**](docs/STORAGE.md) | Global ยท per-project ยท multi-instance |
| [**Configuration**](docs/CONFIGURATION.md) | CLI, env vars, every knob |
| [**Changelog**](CHANGELOG.md) | The full story, version by version |
---
### If your agent should remember what you taught it yesterday โ star it. โญ
86,000+ lines of Rust ยท 13 tools ยท 30 cognitive modules ยท 130 years of memory research ยท one 23MB binary that never phones home.
Built by @samvallad33 ยท AGPL-3.0 ยท 100% local, 100% yours