mirror of
https://github.com/samvallad33/vestige.git
synced 2026-07-20 23:21:01 +02:00
docs: rewrite README for clarity, fix stale facts and dead link
Clean, step-by-step rewrite of the public README. - Correct stale facts against the tree: v2.2.1 (was v2.2.0), 25MB binary (was 23MB), ~96k Rust lines (was 86k). - Remove the dead demo/PITCH-v2-causebench.md link; point to the real demo/PITCH-FINAL-spoken.md. - Feature CauseBench, the public one-command reproducible benchmark (60%/50% causal recall@1 vs 0% text baselines), and keep the DeepMind theorem separate from the measured result. - Numbered 3-step install, a clean top-to-bottom section order, and a nav bar whose anchors all resolve. - Zero em-dashes; every relative link verified to resolve. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Sam Valladares
parent
783057a7b7
commit
e4fdc778cd
1 changed files with 182 additions and 204 deletions
386
README.md
386
README.md
|
|
@ -1,307 +1,285 @@
|
|||
<div align="center">
|
||||
# Vestige
|
||||
|
||||
<h1>Vestige</h1>
|
||||
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.
|
||||
|
||||
### Your bug was born days before it crashed. You just can't remember where.
|
||||
[](https://github.com/samvallad33/vestige/releases/latest)
|
||||
[](https://github.com/samvallad33/vestige/actions)
|
||||
[](https://github.com/samvallad33/vestige/releases/latest)
|
||||
[](LICENSE)
|
||||
|
||||
<em>Vestige is a local-first memory for AI agents that reaches <b>backward through time</b> to find the quiet change that caused today's failure: the cause that looks nothing like the bug. One 23MB Rust binary. No cloud. Your data never leaves your machine.</em>
|
||||
|
||||
[](https://github.com/samvallad33/vestige/stargazers)
|
||||
[](https://github.com/samvallad33/vestige/releases/latest)
|
||||
[](https://github.com/samvallad33/vestige/actions)
|
||||
[](LICENSE)
|
||||
|
||||
[**⚡ Quick Start**](#-get-it-running-in-60-seconds) · [**🧠 The Idea**](#-why-i-built-this) · [**🔬 The Science**](#-this-is-real-neuroscience-not-a-metaphor) · [**🛠 13 Tools**](#-13-tools-one-brain) · [**📊 Dashboard**](#-watch-your-ai-think-in-3d)
|
||||
|
||||
</div>
|
||||
[What it is](#what-vestige-is) · [Install](#install) · [First interaction](#your-first-real-interaction) · [vs RAG](#how-it-differs-from-rag) · [Backward reach](#backward-reach-the-backfill-feature) · [Benchmark](#causebench-a-reproducible-benchmark) · [Science](#the-science) · [Tools](#the-13-tools) · [Dashboard](#the-dashboard) · [Integrations](#works-with-every-agent) · [Docs](#go-deeper)
|
||||
|
||||
---
|
||||
|
||||
## 👋 Why I built this
|
||||
## What Vestige is
|
||||
|
||||
Hi, I'm [Sam](https://github.com/samvallad33). I built Vestige from a tiny apartment in Chicago because I kept losing days to the same thing, and I bet you have too.
|
||||
Hi, I'm [Sam](https://github.com/samvallad33). 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.
|
||||
|
||||
Production breaks. You start hunting. And the cause is almost never *near* the error. It's some quiet change you made days ago that looks **nothing** like the crash it eventually caused. A flipped env var. A swapped service. A config tweak you'd already forgotten.
|
||||
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.
|
||||
|
||||
Here's the part that took me a while to see: **every AI memory tool is built on vector search, and vector search hunts for what *looks like* your problem.** But a root cause never looks like the bug it creates. So they all search the goal line, while the real failure was a quiet midfield turnover fifteen minutes earlier.
|
||||
|
||||
I wanted a memory that traces the match *backward.*
|
||||
|
||||
So that's what Vestige is. Everyone else built a memory that **remembers**. I tried to build the first one that **realizes**: it gates what's worth keeping, lets the noise fade like your own memory does, and when a failure hits, it reaches back through time to the change that actually caused it.
|
||||
|
||||
It's one Rust binary. It runs entirely on your machine. It never phones home. And there's a 60-second start right below.
|
||||
|
||||
> 🎙️ **The 60-second version** of this whole story, the one I give in person, lives in [`demo/PITCH-v2-causebench.md`](demo/PITCH-v2-causebench.md). If you've got a minute, read that first. It's the clearest way to *get* why this matters.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Get it running in 60 seconds
|
||||
## Install
|
||||
|
||||
**Step 1 — install (one binary, no Docker, no API key, no signup):**
|
||||
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.
|
||||
|
||||
```bash
|
||||
npm install -g vestige-mcp-server@latest
|
||||
```
|
||||
|
||||
**Step 2 — connect it to your agent.** Vestige speaks [MCP](https://modelcontextprotocol.io), so it works with *any* AI agent. The universal config (works everywhere):
|
||||
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](https://modelcontextprotocol.io), so it works with any MCP-capable agent. Every MCP client understands this config. Add it to your client's MCP settings:
|
||||
|
||||
```json
|
||||
{ "mcpServers": { "vestige": { "command": "vestige-mcp" } } }
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "vestige-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Drop that into your agent's MCP config file. Or use the one-line shortcut for your agent:
|
||||
If you prefer the CLI, use the one-line shortcut for your agent:
|
||||
|
||||
| Agent | Setup |
|
||||
|---|---|
|
||||
| Claude Code | `claude mcp add vestige vestige-mcp -s user` |
|
||||
| Codex | `codex mcp add vestige -- vestige-mcp` |
|
||||
| Cursor / VS Code / Windsurf | add the JSON above to the editor's MCP settings, or see [docs/integrations/](docs/integrations/) |
|
||||
| Cline / Continue / Zed / Goose | add the JSON above to that client's MCP config |
|
||||
| Claude Desktop | [docs/CONFIGURATION.md#claude-desktop-macos](docs/CONFIGURATION.md#claude-desktop-macos) |
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
# Cursor / Windsurf / VS Code → add the JSON above to ~/.cursor/mcp.json (or the editor's MCP settings)
|
||||
# Claude Code → claude mcp add vestige vestige-mcp -s user
|
||||
# Codex → codex mcp add vestige -- vestige-mcp
|
||||
# Cline / Continue / Zed / Goose → add the JSON above to that client's MCP config
|
||||
vestige dashboard
|
||||
```
|
||||
|
||||
**Step 3 — confirm it's working:**
|
||||
Then visit **http://localhost:3927/dashboard**. If you see the graph, you are connected. For a fuller walkthrough see [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md).
|
||||
|
||||
```bash
|
||||
vestige-mcp --version # prints the installed version
|
||||
vestige stats # prints your memory count (0 on a fresh install)
|
||||
```
|
||||
---
|
||||
|
||||
That's the whole install. New here? The [**30-minute first-run guide**](docs/GETTING-STARTED.md) walks you from install to your first backward-reach: what gets saved (and what doesn't), how to inspect your own memory, and how to scope it per project. Per-agent guides (Cursor, VS Code, Windsurf, JetBrains, Xcode, OpenCode, Codex, Claude Desktop) are [here ↓](#-works-with-every-ai-agent).
|
||||
## Your first real interaction
|
||||
|
||||
Now talk to your agent like it has a memory, because now it does:
|
||||
Memories go in as you work. The interesting behavior shows up when a new claim conflicts with something you already stored.
|
||||
|
||||
```
|
||||
You: "Remember: we always disable SimSIMD on release builds, it breaks old x86 CPUs."
|
||||
...days later, fresh session, zero context...
|
||||
You: "Should I enable SimSIMD for the release?"
|
||||
AI: ⚠️ Hold on, this contradicts a decision you stored: you chose to DISABLE it
|
||||
because it breaks old x86 CPUs.
|
||||
```
|
||||
Say your agent recorded this earlier:
|
||||
|
||||
That last line isn't me being cute. It's a real status the engine returns, called `claim_contradicts_memory`. Most memory tools would have happily handed you the wrong answer. Vestige tells you when you're about to walk back into a mistake you already learned from.
|
||||
> We use Postgres for the primary datastore. Decided against MySQL for the JSONB support.
|
||||
|
||||
And the headline feature, the one nothing else does, is one command:
|
||||
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:
|
||||
|
||||
```bash
|
||||
vestige backfill --contrast
|
||||
```
|
||||
|
||||
When a failure is in your memory, this reaches *backward through time* and finds the quiet earlier change that caused it (the one a vector search ranks poorly because it shares no words with the error). It shows you, side by side, what similarity search returns versus the real cause. [More on the backward reach ↓](#-the-thing-nothing-else-does-memory-with-hindsight)
|
||||
|
||||
*(Works with Codex, Cursor, VS Code, Claude Desktop, Windsurf, JetBrains, Zed: anything that speaks MCP. [Full setup is here ↓](#-works-in-every-editor-you-use).)*
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 It's not RAG with a nicer haircut
|
||||
## How it differs from RAG
|
||||
|
||||
RAG is a bucket: throw everything in, hope nearest-neighbor finds it later. Vestige behaves more like an actual memory: it decides what's worth keeping, forgets what isn't, and reasons across what's left.
|
||||
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.
|
||||
|
||||
| | 🪣 RAG / Vector Store | 🧠 Vestige |
|
||||
| | Plain RAG / vector search | Vestige |
|
||||
|---|---|---|
|
||||
| **What it stores** | Everything you hand it | Only what's **surprising or new** (the rest gets merged or skipped) |
|
||||
| **What it forgets** | Nothing; it just bloats | Unused memories **fade** on a real forgetting curve, so your context stays lean |
|
||||
| **Finding a root cause** | Can't, because the cause isn't *similar* to the bug | **Reaches backward in time** to the change that caused it (the whole point ↓) |
|
||||
| **Catching contradictions** | Silent; serves the stale answer with a straight face | Tells you: *"this contradicts what you decided"* |
|
||||
| **Duplicates** | You clean them up by hand | Self-heals: *"likes dark mode"* + *"prefers dark themes"* quietly become one |
|
||||
| **Forgetting on demand** | DELETE and it's gone | **`suppress`** gently inhibits a memory (and its neighbors), reversible for 24h |
|
||||
| **Where it lives** | Usually someone else's cloud | **Your machine. One binary. No telemetry.** |
|
||||
| Retrieval basis | Text similarity to the query | Causal and temporal links, plus similarity |
|
||||
| Finding a root cause | Cannot, because the cause does not resemble the bug | Reaches backward to the root-cause memory |
|
||||
| Contradictions | Stored side by side, both returned | Detected and flagged (`claim_contradicts_memory`) |
|
||||
| Redundant writes | Accumulate as duplicates | Merged on write via prediction-error gating |
|
||||
| Unused memories | Persist at full weight | Fade over time (FSRS-6 spaced repetition) |
|
||||
| Where it runs | Usually a cloud service | Local single binary, offline after setup |
|
||||
| Your data | Leaves your machine | Never leaves your machine |
|
||||
|
||||
The distinction is not marketing. DeepMind proved that single-vector retrieval is mathematically incapable of representing certain relevance patterns ([arXiv:2508.21038](https://arxiv.org/abs/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.
|
||||
|
||||
---
|
||||
|
||||
## 🔥 The thing nothing else does: memory with hindsight
|
||||
## Backward reach: the backfill feature
|
||||
|
||||
This is the part I'm proudest of, and it's worth one honest paragraph.
|
||||
Most memory systems only look forward: you ask a question, they return similar text. Vestige also looks backward.
|
||||
|
||||
A bug shows up today. The cause was a quiet decision from three weeks ago, like a changed env var or a swapped service. That cause **shares no words with the error it created.** A vector search will never connect them, because it only knows how to find things that *look alike*, and this is a case where the cause and the symptom look nothing alike. This isn't a tuning problem; in 2026 Google DeepMind published a proof ([arXiv:2508.21038](https://arxiv.org/abs/2508.21038), ICLR 2026) that single-vector retrieval is *mathematically* incapable of bridging gaps like this.
|
||||
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.
|
||||
|
||||
So Vestige doesn't do it with similarity. Its **Retroactive Salience Backfill** (ported from **Zaki/Cai et al., 2024, *Nature* 637:145–155** ([DOI](https://doi.org/10.1038/s41586-024-08168-4)), on how the brain links a shock to the quiet memory that caused it) reaches *backward through time* and promotes the dormant memory that's **causally upstream**: it shares an *entity* (the same file, env var, or service), not the same words.
|
||||
Vestige implements **Retroactive Salience Backfill** (Zaki, Cai et al., *Nature* 2024, 637:145-155, [DOI 10.1038/s41586-024-08168-4](https://doi.org/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.
|
||||
|
||||
I also built a benchmark to keep myself honest about it. Every pure vector retriever scored **0% recall@1** on the causal-gap task; Vestige scored **60%**. (To be precise: the impossibility is DeepMind's *theorem*; the 0%-vs-60% is *my measurement*. Two different claims, and I keep them separate.)
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## CauseBench: a reproducible benchmark
|
||||
|
||||
The claim above is testable, and I ship the test in the repo.
|
||||
|
||||
**CauseBench** lives at [`benchmarks/causebench/`](benchmarks/causebench/). It is deterministic and offline: fixed seed `424242`, Python standard library only, no API keys, no network. One command reproduces every number:
|
||||
|
||||
```bash
|
||||
vestige backfill --contrast # show the root cause a vector search would have missed
|
||||
bash benchmarks/causebench/run.sh
|
||||
```
|
||||
|
||||
The nice part: it compounds. Every failure your agent records makes the *next* session diagnose faster (run two is smarter than run one), and it happens automatically during consolidation, so you don't have to babysit it.
|
||||
**What it measures.** Each task hides an older memory that caused a later failure, where the cause and the symptom do not share vocabulary. To make the test honest and hard, text-resemblance baselines are adversarially handed a lookalike memory that resembles the failure but did not cause it. A retriever that ranks by text similarity walks straight into the decoy.
|
||||
|
||||
All of this shipped in **v2.2.0**, along with a 34→13 tool consolidation and a rebuilt retrieval engine. [Full release notes →](https://github.com/samvallad33/vestige/releases/tag/v2.2.0)
|
||||
**The numbers.**
|
||||
|
||||
---
|
||||
|
||||
## 🔬 This is real neuroscience, not a metaphor
|
||||
|
||||
I get skeptical when projects wave the word "neuroscience" around, so here's my receipt: every mechanism below is a real, cited paper, implemented in Rust, running locally on your machine. None of it phones a model in the cloud to sound smart.
|
||||
|
||||
| Mechanism | What it does for you | Grounded in |
|
||||
| Method | recall@1 (synthetic) | recall@1 (real) |
|
||||
|---|---|---|
|
||||
| **Prediction-Error Gating** | Redundant info gets merged, contradictory gets superseded, only the novel gets stored | The hippocampal novelty signal |
|
||||
| **FSRS-6 Spaced Repetition** | 21 parameters of the mathematics of forgetting, so used memories stay and unused ones fade | Modern spaced-repetition research |
|
||||
| **Retroactive Salience Backfill** | Backward causal reach to the root cause of a failure | Zaki/Cai et al. 2024, *Nature* 637:145–155 |
|
||||
| **Synaptic Tagging** | A memory that looked trivial this morning can be tagged critical tonight | [Frey & Morris 1997](https://doi.org/10.1038/385533a0) |
|
||||
| **Spreading Activation** | Search "auth bug," surface last week's JWT update, because memory is a graph, not a list | [Collins & Loftus 1975](https://doi.org/10.1037/0033-295X.82.6.407) |
|
||||
| **Dual-Strength Model** | Storage strength vs. retrieval strength, so deeply stored ≠ instantly recalled, just like you | [Bjork & Bjork 1992](https://doi.org/10.1016/S0079-7421(08)60016-9) |
|
||||
| **Memory Dreaming** | Sleep-like consolidation: replays, connects, synthesizes insights to a graph | Active-dreaming consolidation |
|
||||
| **Active Forgetting (`suppress`)** | Top-down inhibition that *compounds* and cascades to neighbors, reversible for 24h | [Anderson 2025](https://www.nature.com/articles/s41583-025-00929-y) · [Davis 2020](https://pmc.ncbi.nlm.nih.gov/articles/PMC7477079/) |
|
||||
| Pure-vector / text-similarity baselines | 0% | 0% |
|
||||
| Vestige causal bridge | 60% | 50% |
|
||||
|
||||
[**Read the full science doc →**](docs/SCIENCE.md). Every feature, every paper.
|
||||
Two separate claims, kept separate on purpose:
|
||||
|
||||
1. **The theorem (DeepMind).** Single-vector retrieval is mathematically incapable of these relevance gaps ([arXiv:2508.21038](https://arxiv.org/abs/2508.21038), ICLR 2026). This is a fundamental limit of vector search.
|
||||
2. **The measurement (mine).** On CauseBench, text baselines score 0% recall@1 while Vestige's causal bridge scores 60% synthetic and 50% real.
|
||||
|
||||
The theorem says why similarity search must fail on this shape of problem. CauseBench is the runnable measurement showing that Vestige does not.
|
||||
|
||||
---
|
||||
|
||||
## 🛠 13 tools, one brain
|
||||
## The science
|
||||
|
||||
v2.2.0 consolidated a sprawling 34-tool surface into **13 sharp ones** your agent actually reaches for. Old names still work as hidden aliases, so nothing breaks.
|
||||
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](docs/SCIENCE.md).
|
||||
|
||||
| Tool | What it does |
|
||||
| Mechanism | What it does | Source |
|
||||
|---|---|---|
|
||||
| Prediction-Error Gating | Stores only what is novel: merges redundant, supersedes contradictory | Hippocampal novelty gating |
|
||||
| FSRS-6 spaced repetition | 21-parameter schedule so used memories persist and unused ones fade | Modern spaced-repetition research |
|
||||
| Retroactive Salience Backfill | Reaches backward to a failure's root-cause memory | Zaki, Cai et al. 2024, *Nature* 637:145-155, [10.1038/s41586-024-08168-4](https://doi.org/10.1038/s41586-024-08168-4) |
|
||||
| Synaptic Tagging | Marks memories for later consolidation | Frey & Morris 1997, [10.1038/385533a0](https://doi.org/10.1038/385533a0) |
|
||||
| Spreading Activation | Retrieving one memory activates related ones through the graph | Collins & Loftus 1975, [10.1037/0033-295X.82.6.407](https://doi.org/10.1037/0033-295X.82.6.407) |
|
||||
| Dual-Strength | Separates how well something is stored from how easily it is retrieved | Bjork & Bjork 1992 |
|
||||
| Memory Dreaming | Sleep-like consolidation that replays and synthesizes memories | Sleep consolidation and replay |
|
||||
| Active Forgetting | Top-down inhibition that suppresses a memory, cascades to neighbors, reversible for 24 hours | Anderson 2025, Davis 2020 |
|
||||
|
||||
---
|
||||
|
||||
## The 13 tools
|
||||
|
||||
Vestige exposes exactly 13 MCP tools. Your agent calls them; you rarely call them by hand.
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| 🔍 `recall` | The retrieval engine. Folds search + deep reasoning + contradiction detection into one call. F32 embeddings, Reciprocal Rank Fusion, claim-vs-memory checks. |
|
||||
| 🧠 `backfill` | **Memory with hindsight.** Backward causal reach to a failure's root cause (Cai 2024). |
|
||||
| 💾 `smart_ingest` | Stores with CREATE / UPDATE / SUPERSEDE via Prediction-Error Gating. Batch session-end saves. |
|
||||
| 🗂 `memory` | Get, edit, promote 👍, demote 👎, check state, purge content + embeddings. |
|
||||
| 🧩 `graph` | Reasoning chains, associations, bridges, predictions, force-directed export. |
|
||||
| 🌙 `maintain` | Consolidate, dream, GC, importance-score, backup, export, restore. One maintenance verb. |
|
||||
| 🧹 `dedup` | Self-healing duplicate detection + merge (8 old tools → 1). |
|
||||
| 🚫 `suppress` | Top-down active forgetting that compounds, cascades, and is reversible for 24h. The memory is *inhibited, not erased.* |
|
||||
| 📟 `memory_status` | Health + stats + trends + recommendations in one packet. |
|
||||
| 🧬 `codebase` · `intention` · `source_sync` · `session_start` | Per-project code memory · "remind me when X" · external-source connectors · one-call session init. |
|
||||
| `recall` | Retrieve memories relevant to the current context |
|
||||
| `backfill` | Reach backward from a failure to its root-cause memory |
|
||||
| `smart_ingest` | Store a fact, with gating for novelty and contradiction |
|
||||
| `memory` | Read, inspect, promote, or demote individual memories |
|
||||
| `graph` | Explore the memory graph and its links |
|
||||
| `maintain` | Run consolidation and lifecycle maintenance |
|
||||
| `dedup` | Find and merge duplicate memories |
|
||||
| `suppress` | Actively forget a memory (reversible for 24h) |
|
||||
| `memory_status` | Report health, counts, and model readiness |
|
||||
| `codebase` | Index and query codebase-scoped memory |
|
||||
| `intention` | Track goals and open intentions across sessions |
|
||||
| `source_sync` | Sync memories from external connected sources |
|
||||
| `session_start` | Prime the agent with relevant context at session start |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Watch your AI think in 3D
|
||||
## The dashboard
|
||||
|
||||
```bash
|
||||
vestige dashboard # → http://localhost:3927/dashboard
|
||||
vestige dashboard
|
||||
```
|
||||
|
||||
Every memory is a glowing node in a real-time, force-directed 3D graph. Connections form as you work. Nodes **pulse** when accessed, **burst** on creation, **fade** on decay. Kick off a consolidation and the whole graph slides into **purple dream mode**, replaying memories that light up in sequence.
|
||||
Open **http://localhost:3927/dashboard** to watch your memory as a live 3D graph.
|
||||
|
||||
Built with SvelteKit 2 · Svelte 5 · Three.js · WebGL bloom · live WebSocket events. 1000+ nodes at 60fps. Installable as a PWA.
|
||||
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 AI agent
|
||||
## Works with every agent
|
||||
|
||||
Vestige speaks MCP, so **any agent that can register an MCP server can use it.** Not a plugin for one tool, the memory layer underneath all of them. The universal config works everywhere:
|
||||
Vestige is a standard MCP server, so it works with any MCP-capable client. The universal config is all most agents need:
|
||||
|
||||
```json
|
||||
{ "mcpServers": { "vestige": { "command": "vestige-mcp" } } }
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "vestige-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Agent | Setup |
|
||||
| Client | Setup |
|
||||
|---|---|
|
||||
| **Cursor** | add the JSON above to `~/.cursor/mcp.json` · [guide →](docs/integrations/cursor.md) |
|
||||
| **Windsurf** | [guide →](docs/integrations/windsurf.md) |
|
||||
| **VS Code (Copilot)** | [guide →](docs/integrations/vscode.md) |
|
||||
| **Cline / Continue / Zed / Goose** | add the universal JSON to that client's MCP config |
|
||||
| **Claude Code** | `claude mcp add vestige vestige-mcp -s user` |
|
||||
| **Codex** | `codex mcp add vestige -- vestige-mcp` |
|
||||
| **JetBrains · Xcode · OpenCode** | [integration guides →](docs/integrations/) |
|
||||
| **Claude Desktop** | [2-minute setup →](docs/CONFIGURATION.md#claude-desktop-macos) |
|
||||
| Claude Code | `claude mcp add vestige vestige-mcp -s user` |
|
||||
| Codex | `codex mcp add vestige -- vestige-mcp` |
|
||||
| Cursor | [docs/integrations/cursor.md](docs/integrations/cursor.md) |
|
||||
| VS Code | [docs/integrations/vscode.md](docs/integrations/vscode.md) |
|
||||
| Windsurf | [docs/integrations/windsurf.md](docs/integrations/windsurf.md) |
|
||||
| Claude Desktop | [docs/CONFIGURATION.md#claude-desktop-macos](docs/CONFIGURATION.md#claude-desktop-macos) |
|
||||
| Cline / Continue / Zed / Goose | add the universal config above |
|
||||
|
||||
<details>
|
||||
<summary><b>Other install methods (Intel Mac, Windows, build-from-source)</b></summary>
|
||||
|
||||
**Update an existing install:**
|
||||
```bash
|
||||
vestige update # binaries only
|
||||
vestige update --sandwich-companion # also refresh optional Claude Code companion files
|
||||
```
|
||||
|
||||
**macOS (Intel):** Microsoft is dropping x86_64 macOS ONNX Runtime prebuilts after v1.23.0, so the Intel Mac build links dynamically against a Homebrew ONNX Runtime:
|
||||
```bash
|
||||
brew install onnxruntime
|
||||
npm install -g vestige-mcp-server@latest
|
||||
echo 'export ORT_DYLIB_PATH="'"$(brew --prefix onnxruntime)"'/lib/libonnxruntime.dylib"' >> ~/.zshrc && source ~/.zshrc
|
||||
claude mcp add vestige vestige-mcp -s user
|
||||
```
|
||||
Full guide: [`docs/INSTALL-INTEL-MAC.md`](docs/INSTALL-INTEL-MAC.md).
|
||||
|
||||
**Windows + Claude Desktop:** quit Claude Desktop from the tray, then in PowerShell:
|
||||
```powershell
|
||||
npm install -g vestige-mcp-server@latest
|
||||
vestige-mcp --version
|
||||
```
|
||||
Point `%APPDATA%\Claude\claude_desktop_config.json` at it:
|
||||
```json
|
||||
{ "mcpServers": { "vestige": { "command": "vestige-mcp" } } }
|
||||
```
|
||||
If it can't find the command, run `where vestige-mcp` and use the exact `.cmd` path.
|
||||
|
||||
**Build from source (Rust 1.91+):**
|
||||
```bash
|
||||
git clone https://github.com/samvallad33/vestige && cd vestige
|
||||
cargo build --release -p vestige-mcp
|
||||
# Apple Silicon GPU: --features metal · NVIDIA: --features qwen3-embeddings,cuda
|
||||
```
|
||||
</details>
|
||||
Full configuration reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md). Intel Mac notes: [docs/INSTALL-INTEL-MAC.md](docs/INSTALL-INTEL-MAC.md).
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Make your AI use memory automatically
|
||||
## Optional: make the agent use memory automatically
|
||||
|
||||
Registering the server exposes the tools; a short instruction tells the agent *when* to call them. Drop in the protocol and your agent saves and recalls on its own:
|
||||
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.
|
||||
|
||||
| You say | Vestige does |
|
||||
|---|---|
|
||||
| *"Remember this"* | Saves immediately |
|
||||
| *"I always..."* / *"I prefer..."* | Saves as a durable preference |
|
||||
| *"Remind me when..."* | Creates a future trigger (`intention`) |
|
||||
| *"This is important"* | Saves **and** promotes it |
|
||||
- General agent memory protocol: [docs/AGENT-MEMORY-PROTOCOL.md](docs/AGENT-MEMORY-PROTOCOL.md)
|
||||
- Claude-specific setup and templates: [docs/CLAUDE-SETUP.md](docs/CLAUDE-SETUP.md)
|
||||
|
||||
[Agent memory protocol →](docs/AGENT-MEMORY-PROTOCOL.md) · [Claude Code template →](docs/CLAUDE-SETUP.md)
|
||||
This is opt-in. Vestige works fine with no protocol at all.
|
||||
|
||||
---
|
||||
|
||||
## 🏗 Under the hood
|
||||
## Under the hood
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ SvelteKit Dashboard / Three.js 3D graph / WebGL bloom │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Axum HTTP + WebSocket (:3927) / REST + live event stream │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ MCP Server (stdio JSON-RPC) / 13 tools · 30 modules │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Cognitive Engine │
|
||||
│ FSRS-6 · Spreading Activation · Prediction-Error Gating │
|
||||
│ Retroactive Salience Backfill · Synaptic Tagging │
|
||||
│ Memory Dreamer · Hippocampal Index · Active Forgetting │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Storage: SQLite + FTS5 · USearch HNSW · Nomic Embed v1.5 │
|
||||
│ Optional: Qwen3 reranker · SQLCipher · Metal/CUDA │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
Vestige is a single Rust binary. No sidecar services, no external database, no cloud dependency.
|
||||
|
||||
| | |
|
||||
| Component | Detail |
|
||||
|---|---|
|
||||
| **Language** | Rust 2024 (MSRV 1.91), **86,000+ lines** |
|
||||
| **Binary** | ~23MB, single file |
|
||||
| **Embeddings** | Nomic Embed Text v1.5 (768d→256d Matryoshka, 8192 ctx); Qwen3 optional |
|
||||
| **Vector search** | USearch HNSW (≈20× faster than FAISS) |
|
||||
| **Storage** | SQLite + FTS5, optional SQLCipher encryption |
|
||||
| **Tests** | **1,550 passing** · clippy `-D warnings` clean |
|
||||
| **First run** | Downloads ~130MB embedding model once, then **fully offline forever** |
|
||||
| **Platforms** | macOS (ARM + Intel) · Linux x86_64 · Windows x86_64. All prebuilt |
|
||||
| Language | Rust 2024 edition, about 96,000 lines |
|
||||
| Distribution | Single 25MB binary, prebuilt for all platforms |
|
||||
| Embeddings | Nomic Embed Text v1.5 (768d reduced to 256d via Matryoshka, 8192-token context) |
|
||||
| Reranker | Qwen3 reranker, optional |
|
||||
| Vector search | USearch HNSW |
|
||||
| Storage | SQLite with FTS5, optional SQLCipher encryption |
|
||||
| First run | Downloads about 130MB embedding model once, then fully offline forever |
|
||||
| Platforms | macOS (ARM + Intel), Linux x86_64, Windows x86_64, all prebuilt |
|
||||
| Quality | 1,550 tests passing, clippy clean with `-D warnings` |
|
||||
|
||||
Storage internals and encryption: [docs/STORAGE.md](docs/STORAGE.md).
|
||||
|
||||
---
|
||||
|
||||
## 📚 Go deeper
|
||||
## Go deeper
|
||||
|
||||
| | |
|
||||
| Doc | What's in it |
|
||||
|---|---|
|
||||
| [**Getting Started**](docs/GETTING-STARTED.md) | Your first 30 minutes, start to finish |
|
||||
| [**FAQ**](docs/FAQ.md) | 30+ real questions answered |
|
||||
| [**The Science**](docs/SCIENCE.md) | Every feature, every paper |
|
||||
| [**Storage Modes**](docs/STORAGE.md) | Global · per-project · multi-instance |
|
||||
| [**Configuration**](docs/CONFIGURATION.md) | CLI, env vars, every knob |
|
||||
| [**Changelog**](CHANGELOG.md) | The full story, version by version |
|
||||
| [Getting Started](docs/GETTING-STARTED.md) | Full first-run walkthrough |
|
||||
| [FAQ](docs/FAQ.md) | Common questions |
|
||||
| [The Science](docs/SCIENCE.md) | Every mechanism with its citation |
|
||||
| [Configuration](docs/CONFIGURATION.md) | All options and per-agent setup |
|
||||
| [Storage](docs/STORAGE.md) | Storage format and encryption |
|
||||
| [Agent Memory Protocol](docs/AGENT-MEMORY-PROTOCOL.md) | Teaching an agent to use memory automatically |
|
||||
| [Intel Mac install](docs/INSTALL-INTEL-MAC.md) | Notes for older Macs |
|
||||
| [CauseBench](benchmarks/causebench/) | The reproducible benchmark |
|
||||
| [The spoken pitch](demo/PITCH-FINAL-spoken.md) | The 60-second version I give in person |
|
||||
| [Changelog](CHANGELOG.md) | Release history |
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
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](https://github.com/samvallad33/vestige). It genuinely helps me keep building.
|
||||
|
||||
### If your agent should remember what you taught it yesterday, star it. ⭐
|
||||
|
||||
<sub><b>86,000+ lines of Rust · 13 tools · 30 cognitive modules · 130 years of memory research · one 23MB binary that never phones home.</b></sub>
|
||||
|
||||
<sub>Built by <a href="https://github.com/samvallad33">@samvallad33</a> · AGPL-3.0 · 100% local, 100% yours</sub>
|
||||
|
||||
</div>
|
||||
Built by [Sam](https://github.com/samvallad33). Licensed under [AGPL-3.0](LICENSE).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue