vestige/docs/GETTING-STARTED.md

Getting Started with Vestige

Your first 30 minutes, start to finish. By the end you'll have Vestige installed, connected to your agent, storing memories, and you'll know how to look at exactly what it kept.

Vestige is local-first: one binary, your data on your disk, no account, no cloud.

---

1. Install and connect (5 minutes)

Install is one command and connecting is one JSON block. The canonical, always-current steps live in the README so this guide never drifts from them:

• Install + connect →
• Using a specific editor? Pick your per-agent guide — Cursor, VS Code, Windsurf, JetBrains, Xcode, OpenCode, Codex — or the Claude Desktop 2-minute setup.

Confirm it's alive:

vestige-mcp --version     # prints the installed version
vestige stats             # 0 memories on a fresh install

---

2. What Vestige saves (and what it doesn't)

This is the thing most people get wrong on day one, so it's worth 60 seconds.

Vestige does not record everything you type. It is not a transcript logger. A memory is written when:

• You ask your agent to remember something ("remember: we disable SimSIMD on release builds"), or
• Your agent decides a fact is worth keeping and calls the memory tool, or
• You ingest deliberately from the CLI: vestige ingest "...".

Every write goes through prediction-error gating — near-duplicates of what you already know are down-weighted, so the store doesn't fill with restatements of the same fact. What you get is a curated set of durable facts, decisions, and the occasional "this didn't work," not a firehose of your chat history.

If you want the deeper model (FSRS-6 decay, spreading activation, the science), see The Science. You don't need it to start.

---

3. Try the one thing nothing else does

The headline feature is a backward reach through time. Store a decision, then later store a failure, and Vestige can surface the earlier decision as the cause — even though the two share no words.

vestige ingest "We switched the prod cache from Redis to an in-memory LRU to cut costs."
# ...later...
vestige ingest "Prod is dropping sessions under load and users are getting logged out."

vestige backfill --contrast

--contrast shows you, side by side, what a plain similarity search returns versus the real causal cause. That contrast is the whole pitch — more on the mechanism in the README.

You can also just talk to your agent normally; it will write and recall memories for you through MCP. The CLI is for when you want to drive it directly.

---

4. Inspect what's stored

Vestige is built to be looked at. Nothing is hidden in an opaque index.

• Quick counts: vestige stats

• Health check (coverage, warnings): vestige health

• Recall + reasoning over your memories: vestige recall "your question"

• Full export to JSON/JSONL (grep it, diff it, back it up): vestige export memories.jsonl --format jsonl

• The 3D dashboard — watch your memory as a living graph:

  vestige dashboard          # opens http://localhost:3927
  

  (When running as the MCP server, enable it with VESTIGE_DASHBOARD_ENABLED=1.)

Because the store is a single SQLite database, you can also open it with any SQLite browser if you want the raw truth.

---

5. Scope it: global vs per-project

By default Vestige uses one global memory in your OS data directory. For a project-local memory that lives with the repo, point it at a directory:

vestige stats --data-dir ./.vestige          # this project's memory
VESTIGE_DATA_DIR=./.vestige vestige-mcp       # run the server against it

Precedence is --data-dir > VESTIGE_DATA_DIR > OS per-user default. Full details, including multi-instance setups, are in Storage Modes and Configuration.

---

Where to go next

Want to…	Read
Understand a specific feature or the research	The Science
Tune knobs, env vars, ports	Configuration
Global vs per-project vs multi-instance	Storage Modes
Make your agent use memory automatically	README → automatic memory
Ask a real question	FAQ

Welcome. Vestige gets more useful the longer you use it — that's the point.