Vestige: a local-first memory layer for AI agents that traces failures backward

The problem Vestige is aimed at: an agent that cannot remember why

The README states the failure plainly: agents "re-learn the same lessons", recommend a change you already tested and rejected, re-derive a fix that was already written down, and treat every session as if the last one never happened. That is a retrieval problem, but not the kind vector search solves. When a build breaks, the cause is often a version pin, a config choice or an unflagged assumption set weeks earlier. The text of that decision shares almost no vocabulary with the error message in front of you, so similarity ranking puts it far down the list or misses it entirely.

Vestige is built for that gap. It is a memory server for MCP-capable agents (the README names Claude Code, Claude Desktop, Codex and Cursor) that writes memories as you work and retrieves them later. The intended user is a developer or a small team running coding agents on their own machines, who wants the memory to stay there. The README is explicit that there is no cloud, no API keys and no telemetry, and that data never leaves the machine.

How the memory graph works: prediction-error gating, FSRS-6 and backfill

Three mechanisms are described in the README, and they operate at different points in a memory's life.

On write, prediction-error gating decides whether a new memory is worth keeping as a separate node. Redundant writes are merged rather than accumulated, so the store does not grow a dozen near-identical entries for the same decision. Contradicted memories are handled differently: the README lists a claim_contradicts_memory tool, meaning a new claim that conflicts with an old one is detected and flagged rather than silently overwriting it or sitting beside it unremarked.

Over time, unused memories fade. The project applies FSRS-6, the spaced-repetition scheduler, to memory strength, so a memory nobody retrieves loses weight instead of persisting at full strength forever. The package description and the topics list both name FSRS-6, and the v2.8.0 release is titled "Strong memories stay whole", which suggests the fading rule is tuned to avoid breaking up memories that are still being used.

The third mechanism is the one the project is named around in spirit. Retroactive Salience Backfill implements a finding the README cites from Zaki, Cai et al., Nature 2024, 637:145-155: when a memory turns out to matter, the salience of the earlier memories that led to it is raised, so the causal chain becomes retrievable even though the surface text never matched. In practice that means the store persists a causal edge between the later failure and the earlier decision, and the retrieval path can follow it. The README is careful about the output: every backfill result ships with a receipt naming the evidence path, and the project reports "receipt-backed candidate causes, never an unverifiable verdict". That distinction matters if you plan to act on the result. Vestige names suspects; it does not decide.

Installing Vestige and connecting it to an MCP client

The README says you need Node.js. There is no compile step for the supported platforms: prebuilt binaries cover macOS ARM and Intel, Linux x86_64 and Windows x86_64. Install the published package globally.

npm install -g vestige-mcp-server@latest

The postinstall step downloads the matching prebuilt vestige-mcp binary. The Dockerfile in the repository confirms this and adds a constraint worth knowing: the base image must be glibc (Debian), not musl or Alpine, because the downloaded binary is built for x86_64-unknown-linux-gnu and will not run on an Alpine image.

Then point your client at the server. The README says every MCP client understands this config, which goes in that client's MCP settings.

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

Some clients have a one-line setup instead. For Claude Code the README gives claude mcp add vestige vestige-mcp -s user, and for Codex, codex mcp add vestige -- vestige-mcp. Cursor, VS Code, Windsurf, Claude Desktop, Cline, Continue, Zed and Goose are covered in the docs directory.

To verify the install, run the dashboard command.

vestige dashboard

The README says to open http://localhost:3927/dashboard. The first run downloads a 130MB embedding model and, in the background, a roughly 150MB reranker. After that, the README states Vestige is fully offline. Budget for that first download if you are installing on a machine with restricted egress, and note that the dashboard listens on port 3927 on localhost.

The backfill claim and what the benchmark release actually contains

The README's central demonstration is a labeled fixture store seeded with a seven-month backdated timeline. A SIGSEGV on startup in an arm64 container is traced to a version pin set 23 days earlier that shares zero words with the failure. The README states that similarity ranking placed the pin fourth, backfill reached back and ranked it first, persisted the causal edge, and sealed the receipt. The incident is fictional; the README says so directly, and says the engine is not. A 58 second walkthrough video is linked.

A separate benchmark release, benchmark-before-you-change-that-2026-09-06, is described as "Before You Change That, benchmark evidence". The README section titled "The receipts: Silent Rotation" describes the test: three coding agents fix one failing e2e test, and the fix needs the currently live signing key id, randomized per trial from a 50-key keyring, present in no file the agents can read. It exists only in the memory layer. The dangerous outcome is converging on a planted decoy where tests pass and the merge is clean. The README says the test ships with all 246 agent transcripts it produced.

That is a stronger form of evidence than a demo, because the transcripts are included and the decoy is the interesting failure. It is still a benchmark designed by the project's author, run against the project's own engine. Treat the numbers as a claim you can reproduce with the shipped transcripts, not as an independent result.

Where Vestige is the wrong tool

The README makes the boundary unusually clear, and it is worth taking at face value. RAG, in the project's own framing, "retrieves text that resembles the query" and is "the right tool when the answer looks like the question". If your use case is document question answering, or an agent that needs to find the passage a user is asking about, similarity search is cheaper to operate and simpler to reason about. Vestige adds a causal graph, a salience scheduler and a write-time merge step, and none of that pays off when the answer already looks like the query.

The second boundary is deployment shape. Vestige is local-first by design. There is no hosted service described in the README, and the Dockerfile exists so that registries can start the server and run the standard MCP stdio introspection exchange, not to provide a shared multi-tenant deployment. If several agents on different machines need one memory, the README does not describe how that is done. The v2.7.1 release title, "The first cloud write is never unconditional", hints that some cloud path exists, but the README does not document it, and you should not assume a sync story from a release title.

The third limitation is the output itself. Backfill returns candidate causes with receipts. It does not return a verdict, and the README says so. If your workflow needs a decision rather than a ranked suspect with an evidence path, that step is yours to build.

Finally, installation assumes Node.js and, on first run, a large model download. An air-gapped machine with no route to the model host is a problem the README does not address.

Vestige compared with a plain vector store

The natural alternative is a vector database in front of your agent, which is what most memory layers are. The difference is not the embedding model. Both sides embed and both sides rank. The difference is what the index is built over and what happens at write time.

A vector store keeps every write and returns the nearest neighbours of the query. Vestige gates writes on prediction error, merges redundant ones, flags contradictions through claim_contradicts_memory, and decays unused entries with FSRS-6. Retrieval is then a combination of similarity and causal plus temporal links, which is what makes a backfill query possible at all. The README also points at a mathematical argument on the other side: it cites arXiv:2508.21038, work attributed to DeepMind and accepted at ICLR 2026, as proving single-vector retrieval incapable of certain relevance patterns. That is a claim about a class of architectures, not about any particular vendor, and it is the strongest technical reason the project gives for building retrieval differently rather than tuning embeddings harder.

The trade-off runs the other way too. A vector store is a well-understood component with many implementations and no opinion about your agent's lifecycle. Vestige is a single Rust workspace with its own store format, its own scheduler and its own notion of what a memory is. You are adopting an opinionated data model, and the cost of changing your mind later is the cost of migrating a graph, not re-pointing a client at a different index.

Licence, upgrade cost and the maintenance picture

Vestige is licensed AGPL-3.0. The package.json records "AGPL-3.0-only" and the Cargo workspace does the same. This is a strong copyleft licence, and the practical question for most teams is what happens when the memory server is distributed as part of a larger product rather than run internally. The repository ships a LICENSE file and a SECURITY.md; it does not ship a separate commercial licence, and the README's consulting section is an advisory offer, not a licensing exception. If you plan to embed Vestige in something you ship, that is a question for your own counsel, not something the repository answers.

The maintenance picture is current rather than historical. The repository is not archived, and the last push was on 2026-09-09. Releases have been frequent and versioned: v2.8.0 on 2026-09-05, v2.7.1 on 2026-09-02, and a benchmark release on 2026-09-07. The workspace version in Cargo.toml and package.json is 3.0.0, ahead of the last tagged release, which is normal for a repository between tags but means the version you install from npm may not match the version in the tree.

Upgrade cost is mostly the model download. The README says the embedding model and reranker are fetched once on first run and that the system is offline afterward. A version bump that changes the model would mean another download on every machine, and the README does not describe a model-versioning or migration policy for existing stores. The Dockerfile also pins the install to vestige-mcp-server@latest, which means a container rebuild can pull a newer binary than the one you validated. Pin the package version in your own image if that matters.

Editorial conclusion

Adopt Vestige if your agent already runs over MCP, you want memory on local disk with no API keys, and the failure mode you care about is an agent repeating a decision you already rejected. Do not adopt it if you need a hosted, multi-tenant memory service, if you cannot run Node.js on the machines that host your agents, or if AGPL-3.0 does not fit how you distribute your own product. Before rolling it out, run npm install -g vestige-mcp-server@latest on one machine, confirm the dashboard answers on http://localhost:3927/dashboard, and run vestige backfill --contrast against a store you have seeded with a known past decision, so you can see whether the causal edge it persists matches what you know happened.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. samvallad33/vestige on GitHub