Vestige: Local-First Agent Memory That Retrieves Causes, Not Lookalikes

The failure mode Vestige was built around

The README states the problem in one line: agents 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 the ordinary amnesia case, and it is the easier half. The harder half is what the project calls the cause that never looks like the bug. A SIGSEGV on startup in an arm64 container, traced to a version pin set 23 days earlier, shares almost no vocabulary with the crash. Any retrieval system built on text similarity will rank the pin low, because the pin does not read like a segfault. Vestige's claim is that it can reach backward through the timeline and rank that pin first, with a receipt naming the evidence path. The intended user is an engineer running an MCP-capable agent (Claude Code, Claude Desktop, Codex, Cursor and others are named) who wants the memory layer to live on their own disk. The README is explicit that the product is local-first: no cloud, no API keys, no telemetry.

Prediction-error gating, contradiction flags and FSRS-6 decay

Three mechanisms do the day-to-day work, and they map onto three different failure modes of a naive memory store. Redundant writes are merged on write, which the README calls prediction-error gating: if a new memory does not add information beyond what is already stored, it does not accumulate as a separate row. Contradictions are detected rather than silently co-stored, surfaced through a tool named claim_contradicts_memory. Unused memories fade rather than persisting at full weight, using FSRS-6 spaced repetition, the scheduling family borrowed from flashcard software. The fourth mechanism is the one the project is named for. Retroactive Salience Backfill raises the salience of earlier memories once a later memory turns out to matter, so the causal chain becomes retrievable even when the surface text never matched. The README attributes the idea to Zaki, Cai et al., Nature 2024, 637:145-155. The design consequence is worth stating plainly: retrieval in Vestige is not one ranking function over one index. It is similarity plus causal and temporal links, with a separate backfill pass that can reorder what similarity alone would have returned.

What the backfill command actually promises

The README is careful about the boundary here, and that care is the most interesting thing in the document. Vestige reports receipt-backed candidate causes, never an unverifiable verdict. The demo fixture is described as fictional and seeded into a store with a seven month backdated timeline, while the engine itself is real. In that run, similarity ranked the version pin fourth; backfill reached back, ranked it first, persisted the causal edge, and sealed the receipt. The phrasing it names the suspects, it never calls the verdict is a deliberate limit. A tool that guesses a root cause and states it confidently is worse than one that hands you a ranked list with the evidence attached, because the confident wrong answer is the one an agent will act on. If you are evaluating Vestige, the thing to inspect is the receipt format, not the ranking. The README points at vestige backfill --contrast as the command to run against your own store.

Install, first run, and the 280MB you download once

The install path assumes Node.js and nothing else. npm install -g vestige-mcp-server@latest, then a standard MCP client block: the server name vestige with command vestige-mcp. Client-specific shortcuts are given for Claude Code (claude mcp add vestige vestige-mcp -s user) and Codex (codex mcp add vestige -- vestige-mcp); Cursor, VS Code, Windsurf, Claude Desktop, Cline, Continue, Zed and Goose are routed to docs/integrations/ or docs/CONFIGURATION.md. There is no Docker step and no compile step on macOS ARM and Intel, Linux x86_64 and Windows x86_64, because the binary is prebuilt. Android under Termux builds from source, per docs/INSTALL-TERMUX.md. Verification is vestige dashboard, then http://localhost:3927/dashboard in a browser. The first run downloads a 130MB embedding model and, in the background, a roughly 150MB reranker. After that the README says Vestige is fully offline, forever. Budget for that first-run download on a metered or restricted network; it is the only network dependency the documentation describes, and it is a one-time cost rather than a per-query one.

Where similarity search is still the right answer

The README's comparison table sets vector search against Vestige on six rows, and the honest reading is that the two tools answer different questions. RAG retrieves text that resembles the query, which the README itself concedes is the right tool when the answer looks like the question. For document search, code search, or a knowledge base where the user's phrasing tracks the content, a vector index is simpler and has a far larger ecosystem. Vestige's advantage only appears when the cause of a problem looks nothing like the symptom, and that condition is not universal. The README also cites DeepMind work (arXiv:2508.21038, ICLR 2026) arguing that single-vector retrieval is mathematically incapable of certain relevance patterns. That is a claim about a class of patterns, not a claim that vector search is generally broken, and the README does not pretend otherwise. The real alternative to weigh is not RAG versus Vestige in the abstract. It is whether you want to maintain a second local process, a SQLite store, and a 25MB binary alongside your existing retrieval stack, in exchange for causal linking on the subset of queries where similarity fails.

The benchmark ships its transcripts, which cuts both ways

The Silent Rotation benchmark is the most falsifiable thing in the repository, and it is worth reading closely. Three coding agents fix one failing e2e test. The fix requires 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 release tagged benchmark-before-you-change-that-2026-09-06 is described as benchmark evidence, and the README says the test ships with all 246 agent transcripts it produced. Shipping transcripts is the right instinct: it lets a sceptic re-read the runs rather than trust a headline number. It also means the benchmark is a constructed scenario with a randomized secret, not a field study of production incidents. The demo fixture is labelled fictional. Nothing in the supplied material reports how backfill behaves on a store with years of genuine, messy history, or what the false-positive rate looks like when the causal edge does not exist and the engine still has to rank something.

Licence, consulting and what AGPL-3.0 means for your deployment

Vestige is AGPL-3.0. For an individual running the binary locally against their own agent, that is unremarkable. For a company that wants to embed the memory server inside a product it distributes, or to expose a modified version as a network service, AGPL-3.0 carries obligations that permissive licences do not, and those obligations are a question for your own legal counsel rather than for this article. The README also carries a consulting section offering advisory retainers for AI developer tool startups, multi-agent frameworks and enterprise teams, with specialisations listed as context optimisation, causal agent memory design and air-gapped AI governance, and a contact address. Read that as a signal about how the project is funded. It does not change the licence, but it does mean some of the deeper integration work is positioned as paid engagement rather than as documentation. Verify the licence text in the LICENSE file against your intended use before you build on it.

Upgrade surface and what to check before you commit

The release cadence visible in the material is fast: v2.7.1 on 2026-09-02, v2.8.0 on 2026-09-05, and a benchmark release on 2026-09-07, with the last push to main on 2026-09-09. Release titles are behavioural rather than cosmetic, for example the first cloud write is never unconditional in v2.7.1 and strong memories stay whole in v2.8.0, which suggests the storage and merge semantics have been moving recently. That is a maintenance consideration: if you pin vestige-mcp-server, read the release notes between your pinned version and latest before upgrading, because changes to merge or salience behaviour can alter what your store returns. The upgrade path itself is the npm global install, so there is no migration tooling described, and the local SQLite store is the thing you would want to back up first. The repository is not archived and the default branch is main. Before adopting, confirm three things from the material rather than from this article: that your MCP client is on the supported list, that you can absorb the one-time model download, and that the receipt printed by vestige backfill --contrast on your own data names a memory you would have wanted surfaced.

Editorial conclusion

Adopt Vestige if you run an MCP-capable coding agent on a workstation or an air-gapped machine, you are willing to accept AGPL-3.0, and the failures you care about are the ones where the cause does not resemble the symptom, such as a version pin or a config choice made weeks earlier. Do not adopt it if your retrieval problem is ordinary document search, if you need a hosted service with an SLA, or if your organisation cannot ship AGPL code. Before committing, run the install, open the dashboard at http://localhost:3927/dashboard, and run vestige backfill --contrast against a store seeded with your own incident history to see whether the receipt it prints names a memory you would actually have wanted.

Official sources

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