Vestige

Local-first long-term memory for AI agents, delivered over MCP. Vestige remembers your decisions, catches contradictions before they cost you, and traces a failure back to the older memory that actually caused it. One 25MB Rust binary. No cloud. Your data never leaves your machine.

What it is · Install · First interaction · vs RAG · Backward reach · Benchmark · Science · Tools · Dashboard · Integrations · Pro · Docs

What Vestige is

Hi, I'm Sam. I built Vestige because my agents kept re-learning the same lessons. They would recommend a change I had already tested and rejected, re-derive a fix that was already written down, and treat every session as if the last one never happened.

Vestige is the memory layer that fixes that. It runs locally as an MCP server, so any MCP-capable agent (Claude Code, Claude Desktop, Codex, Cursor, and others) can write memories during a session and retrieve them later. Your data lives in a SQLite file on your own machine. After a one-time model download it works fully offline, with no API keys and no telemetry.

The part that makes it more than a note store: Vestige models memory on real cognitive science. It merges what is redundant, supersedes what is contradicted, keeps what you actually use, and lets unused memories fade. Most importantly, when a failure hits it can reach backward to the earlier decision that caused it, even when the cause and the symptom share no vocabulary. The cause never looks like the bug.

Related MCP server: Agent Memory

Install

Three steps. You need Node.js installed (for the npm command) and nothing else.

1. Install the server

No Docker, no API key, no signup.

npm install -g vestige-mcp-server@latest

This installs the vestige-mcp command. Prebuilt binaries ship for macOS (Apple Silicon and Intel), Linux x86_64, and Windows x86_64, so there is no compile step.

2. Connect it to your agent

Vestige speaks MCP, so it works with any MCP-capable agent. Every MCP client understands this config. Add it to your client's MCP settings:

{
  "mcpServers": {
    "vestige": {
      "command": "vestige-mcp"
    }
  }
}

If you prefer the CLI, use the one-line shortcut for your agent:

3. Verify

On first run, Vestige downloads its embedding model once (about 130MB). After that it never needs the network again. To confirm the server is healthy, open the dashboard:

vestige dashboard

Then visit http://localhost:3927/dashboard. If you see the graph, you are connected. For a fuller walkthrough see docs/GETTING-STARTED.md.

Your first real interaction

Memories go in as you work. The interesting behavior shows up when a new claim conflicts with something you already stored.

Say your agent recorded this earlier:

We use Postgres for the primary datastore. Decided against MySQL for the JSONB support.

Later, someone tells the agent the opposite:

Our primary datastore is MySQL.

When the agent tries to store that, Vestige does not silently append it. The engine returns a claim_contradicts_memory status and surfaces the older, conflicting memory, so the agent can resolve the conflict instead of quietly holding two incompatible facts.

The other command you will reach for is backfill. When something breaks, run:

vestige backfill --contrast

This walks backward from the failure to the earlier memory that most plausibly caused it, and shows you the contrast between what you believed then and what went wrong now. That backward reach is the feature the rest of this README builds up to.

How it differs from RAG

RAG retrieves text that resembles your query. That is the right tool when the answer looks like the question. It is the wrong tool when the cause of a problem looks nothing like the symptom.

The distinction is not marketing. DeepMind proved that single-vector retrieval is mathematically incapable of representing certain relevance patterns (arXiv:2508.21038, ICLR 2026). That theorem is about the limits of the vector-only approach. The measured gap on the task below is my own.

Backward reach: the backfill feature

Most memory systems only look forward: you ask a question, they return similar text. Vestige also looks backward.

When a failure lands, the useful memory is rarely the one that resembles the error message. It is an older decision, made in different words, that set the failure up. A config choice from three weeks ago. A library pin. An assumption nobody wrote down as risky at the time.

Vestige implements Retroactive Salience Backfill (Zaki, Cai et al., Nature 2024, 637:145-155, DOI 10.1038/s41586-024-08168-4). When a memory turns out to matter, the system reaches backward and raises the salience of the earlier memories that led to it, so the causal chain becomes retrievable even though the surface text never matched.

In practice you run vestige backfill --contrast. Vestige returns the earlier memory that most plausibly caused the current failure, alongside the contradiction between then and now. It finds the cause you would not have thought to search for.

Silent Rotation: a reproducible benchmark

The claim above is testable, and the test ships with every transcript it produced.

Silent Rotation lives at benchmarks/silent-rotation/. Three coding agents fix one failing end-to-end test in a TypeScript monorepo. The fix needs the currently live signing key id, which is randomized per trial from a 50-key keyring and appears in no file the agents can read. It exists only in the memory layer.

Reproduce the central result in two seconds. Python standard library only, no API keys, no network:

git clone -b benchmark/silent-rotation --depth 1 https://github.com/samvallad33/vestige.git
cd vestige/benchmarks/silent-rotation
python3 tests/bm25_baseline.py results/runA-trial-1/corpus-export.json --no-dense

What it measures. A fleet either converges on the correct key, converges on a planted decoy, or splits and fails to merge. The second outcome is the dangerous one: tests pass, the merge is clean, and production breaks.

The numbers. 6 models, 25 trials, 246 published agent transcripts.

Two separate claims, kept separate on purpose:

1. The theorem (DeepMind). Single-vector retrieval is mathematically incapable of these relevance gaps (arXiv:2508.21038, ICLR 2026). This is a fundamental limit of vector search.

2. The measurement (mine). On the verbatim queries the agents actually typed, the causal memory ranks 7th of 8 under both dense cosine and BM25, while the decoy ranks 1st.

The caveats are published alongside the results, including the trials where a plain cosine baseline ties Vestige and the trial Vestige loses.

The science

Every mechanism below is a cited result, implemented in Rust, running locally. None of it calls a cloud model to sound smart. Full write-up in docs/SCIENCE.md.

The 13 tools

Vestige exposes exactly 13 MCP tools. Your agent calls them; you rarely call them by hand.

The dashboard

vestige dashboard

Open http://localhost:3927/dashboard to watch your memory as a live 3D graph.

It is built with SvelteKit 2 and Svelte 5, rendering with WebGPU and Three.js with bloom, driven by a live WebSocket feed, holding 1000+ nodes at 60fps. Memories appear, link, strengthen, and fade in real time as your agent works. It installs as a PWA if you want it as a standalone app.

Works with every agent

Vestige is a standard MCP server, so it works with any MCP-capable client. The universal config is all most agents need:

{
  "mcpServers": {
    "vestige": {
      "command": "vestige-mcp"
    }
  }
}

Full configuration reference: docs/CONFIGURATION.md. Intel Mac notes: docs/INSTALL-INTEL-MAC.md.

Optional: make the agent use memory automatically

By default your agent calls the tools when it decides to. If you want memory to be a standing habit (recall at the start of a task, save durable facts as they land), give the agent a short protocol.

• General agent memory protocol: docs/AGENT-MEMORY-PROTOCOL.md

• Claude-specific setup and templates: docs/CLAUDE-SETUP.md

This is opt-in. Vestige works fine with no protocol at all.

Vestige Pro

Everything above is free forever and never metered. The engine runs on your machine, with no account, no quota, and no upsell inside the product.

Vestige Pro is for when that memory needs to follow you. It is managed, end-to-end encrypted continuity of your memory graph and your accountability history (Black Box traces, receipts, memory PRs) across every machine you work on. You record a decision on the laptop, and the agent on the desktop already knows it.

Zero-knowledge is the design, not a setting. You pick one passphrase, you use the same one on every device, and it never leaves your machine. The server stores bytes it cannot read, and the client refuses to sync anything in plaintext. If you lose that passphrase, the encrypted data is unrecoverable, by me and by anyone else. That is the property you are paying for, not a gap in it.

Availability. Checkout is not open yet, so there is nothing to buy today and no payment link here pretending otherwise. The client half already ships in this release, which is why vestige sync --cloud exists and tells you what it needs. Subscriptions open shortly. To catch the announcement, watch Releases or follow Discussions.

Under the hood

Vestige is a single Rust binary. No sidecar services, no external database, no cloud dependency.

Storage internals and encryption: docs/STORAGE.md.

Go deeper

If Vestige saves you from one repeated mistake, that is the whole point: never solve the same problem twice. If it earns a place in your setup, star it on GitHub. It genuinely helps me keep building.

Built by Sam. Licensed under AGPL-3.0.