Vestige – Local‑first memory for AI‑assisted developers

What it is – Vestige is an open‑source, locally‑run memory layer that lets large‑language‑model (LLM) coding agents (Claude Code, Claude Desktop, Codex, Cursor, etc.) store and retrieve “memories” about a codebase. It records decisions, configuration choices, and other contextual facts as you work, then later surfaces the most relevant pieces when a failure occurs, using causal‑temporal links rather than plain similarity search.

---

Core ideas (from the README)

Concept	How Vestige implements it
Prediction‑Error Gating	Only novel facts are written; redundant facts are merged and contradictory ones are flagged.
Retroactive Salience Backfill	When a bug is reported, Vestige walks backward through the memory graph, raising the salience of earlier facts that contributed to the failure.
Spaced‑repetition fading (FSRS‑6)	Unused memories gradually lose weight, keeping the store compact.
Dual‑strength storage	Separate “storage strength” (how firmly a fact is kept) and “retrieval strength” (how easily it is found).
Offline operation	After a one‑time download of a 130 MB embedding model and a ~150 MB reranker, everything runs locally with no network calls.

---

Main user‑visible features

• Automatic write‑back: Any MCP‑compatible agent can call smart_ingest to store a fact; Vestige decides whether it is novel, merges duplicates, or marks contradictions.
• Focused recall: recall returns memories that are causally linked to the current code context, not just text‑similar.
• Backfill: vestige backfill --contrast starts from a failure and surfaces the earliest memory that likely caused it, together with a receipt that shows the evidence path.
• Dashboard: A WebGPU visualizer (vestige dashboard) shows the memory graph in real‑time (1000+ nodes at 60 fps) and can export a short video or a “brain print” that represents the graph shape without exposing the actual data.
• Project projection: Durable decisions can be exported into a Markdown rules file (e.g., CLAUDE.md) for the agent to respect in future sessions.
• Pro tier (optional, $19 / month): Encrypted, cross‑device continuity using XChaCha20‑Poly1305 and Argon2id; the free tier remains fully offline and unlimited.

---

Installation & quick start (as described)

1. Install the MCP server globally with Node:

   npm install -g vestige-mcp-server@latest
   

2. Add the server to your agent’s MCP config (JSON shown in the README). The README lists the exact commands for Claude Code, Codex, Cursor, Claude Desktop, etc.
3. Run vestige dashboard and open http://localhost:3927/dashboard.
4. On first run the binary downloads the embedder and reranker; after that the tool works completely offline.

---

How it differs from plain RAG

RAG (vector similarity)	Vestige
Retrieves items that look like the query text.	Retrieves items linked by causal + temporal relationships, then re‑ranks with similarity.
No notion of contradiction; duplicates accumulate.	Detects contradictions, merges duplicates, and fades unused memories.
Data usually stored in a cloud service.	All data stays on the developer’s machine (SQLite, optional SQLCipher encryption).
Cannot point to the root cause of a bug that looks unrelated to the symptom.	backfill can trace back to the decision that set up the failure, providing a receipt‑backed candidate cause.

---

Benchmarks & evidence (as reported)

• Silent Rotation benchmark – 246 agent transcripts were used to compare three setups: no memory, dense‑cosine RAG, and Vestige.
• Results (23 trials per setup) showed Vestige converging on the correct fix in 20/23 trials, with zero wrong convergences, whereas RAG converged correctly in only 4/23 and produced wrong fixes in 12/23.
• The benchmark can be reproduced in seconds with a provided Python script (see benchmark/silent-rotation).

---

Technical stack (from the “Under the hood” table)

• Engine: Rust (≈145 k LOC), compiled to a single ~25 MB binary, >2 000 tests, clippy clean.
• Retrieval: Nomic Embed v1.5 (Matryoshka 768→256), USearch HNSW index, SQLite FTS5; optional Qwen‑3 reranker.
• Storage: SQLite (optional SQLCipher for encryption).
• Embedding models: Downloaded once, then offline forever.

---

Who would benefit?

• Developers who use LLM coding assistants and repeatedly hit the same “agent amnesia” problem.
• Teams that need an audit trail of decisions made by AI agents (receipts provide reproducible evidence).
• Users who require strict data‑privacy (all processing stays on‑device, no API keys needed).

---

Limitations & open points (as acknowledged)

• The system relies on the quality of the underlying embedder and optional reranker; if those models are poor, similarity ranking may still miss relevant facts.
• The “backfill” mechanism is only as good as the causal links that have been recorded; missing a key decision means it cannot be retrieved later.
• The Pro tier is the only way to sync memory across machines; the free tier is single‑device only.
• Benchmarks are presented by the authors; independent replication would be needed for broader confidence.

---

License

• AGPL‑3.0 (full source available; commercial use must comply with the copyleft terms).

---

Bottom line – Vestige is a genuine, research‑backed tool that adds a causal, local memory graph to LLM coding agents, aiming to eliminate repeated mistakes by remembering why a decision was made and surfacing that context when a failure occurs.