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 · Receipts · 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.

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.

If a global pnpm install skipped its postinstall hook, the command launcher retries the local binary installation on its first invocation. It reports that recovery on stderr, preserving MCP stdout for protocol messages.

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.

After a successful tool call, Vestige persists a retrieval receipt when that call has one, then records any Memory PR review evidence. That evidence is a post-commit record of the completed call; it is not a pre-execution block on the tool.

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.