release: v2.2.1 — Windows embeddings fix + backfill safety + first-run guide (#105)

* patch(backfill-safety): VESTIGE_BACKFILL_AUTOFIRE gate (default OFF) + bounded promote_memory_backfill Off-by-default env gate around step-8.5 auto-fire in run_consolidation (decouples backfill from consolidation cadence). New promote_memory_backfill caps stability at MIN(stability*1.5, stability+365.0) (the bound retroactive_backfill.rs:300 already computes but discarded); both backfill entry points use it. Fixes the false 'capped' comment. Cloud-sync excluded at build (--no-default-features). Pending upstream PR to samvallad33/vestige. omega-backfill-safety-v2.2.0 off tag v2.2.0 (3bcd4667). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * release: v2.2.1 — Windows embeddings fix + backfill safety + first-run guide Board-clearing patch release. Fixes: - #101 Windows embeddings: release.yml already restores vector-search on the x86_64-pc-windows-msvc target (merged in #102); this release rebuilds the Windows binary so users actually get working embeddings. - #103 Retroactive Salience Backfill safety (from community PR #104, adjusted): * promote_memory_backfill bounds the stability multiply to MIN(stability*1.5, stability+365.0) on both auto-fire and manual paths. * VESTIGE_BACKFILL_AUTOFIRE gate — default ON (preserves the shipped/documented v2.2.0 behavior), disable with 0/false/off/no. Env value is trimmed. * Corrected the false "capped" comment and the promote_memory_backfill doc. * Added 3 tests: +365 cap binds, *1.5 multiply below crossover, gate parsing. Docs: - #83 First-Run: new docs/GETTING-STARTED.md + README pointer. - Consolidated roadmap issues #82,#84-#92 into docs/ROADMAP.md (Tracked Issues). - Documented VESTIGE_BACKFILL_AUTOFIRE in docs/CONFIGURATION.md. - CHANGELOG v2.2.1 entry. Version bumped to 2.2.1 across all manifests + Cargo.lock + dashboard build. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Peter Lauzon <inbijiburu@protonmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 22:01:01 +02:00 · 2026-07-02 12:02:42 -05:00 · 2026-07-02 12:02:42 -05:00 · f7530af3db
commit f7530af3db
parent 9d15cce7ab
391 changed files with 5130 additions and 4359 deletions
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@ -45,6 +45,7 @@ Qwen3 currently uses Hugging Face Hub's Candle loader directly, so use the stand
 | `VESTIGE_AUTH_TOKEN` | auto-generated | Dashboard + MCP HTTP bearer auth |
 | `VESTIGE_DASHBOARD_ENABLED` | `false` | Set `true` or `1` to enable the web dashboard |
 | `VESTIGE_CONSOLIDATION_INTERVAL_HOURS` | `6` | FSRS-6 decay cycle cadence |
+| `VESTIGE_BACKFILL_AUTOFIRE` | `on` | Retroactive Salience Backfill auto-fire during consolidation. On by default; set `0`/`false`/`off`/`no` to disable. The manual `backfill` tool + CLI stay available either way. When on, promotion is bounded (`stability = MIN(stability * 1.5, stability + 365)`) |

 > **Storage location precedence:** `--data-dir <path>` wins over `VESTIGE_DATA_DIR`; if neither is set, Vestige uses your OS's per-user data directory: `~/Library/Application Support/com.vestige.core/` on macOS, `~/.local/share/vestige/core/` on Linux, `%APPDATA%\vestige\core\` on Windows. Custom paths are directories, are created if missing, expand a leading `~`, and store the database at `<dir>/vestige.db`.

--- a/docs/GETTING-STARTED.md
+++ b/docs/GETTING-STARTED.md
@ -0,0 +1,126 @@
+# 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 →](../README.md#-get-it-running-in-60-seconds)**
+- Using a specific editor? Pick your per-agent guide —
+  [Cursor](integrations/cursor.md), [VS Code](integrations/vscode.md),
+  [Windsurf](integrations/windsurf.md), [JetBrains](integrations/jetbrains.md),
+  [Xcode](integrations/xcode.md), [OpenCode](integrations/opencode.md),
+  [Codex](integrations/codex.md) — or the
+  **[Claude Desktop 2-minute setup](CONFIGURATION.md#claude-desktop-macos)**.
+
+Confirm it's alive:
+
+```bash
+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](SCIENCE.md)**. 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.
+
+```bash
+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](../README.md#-the-thing-nothing-else-does-memory-with-hindsight)**.
+
+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:
+
+  ```bash
+  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:
+
+```bash
+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](STORAGE.md)** and
+**[Configuration](CONFIGURATION.md)**.
+
+---
+
+## Where to go next
+
+| Want to… | Read |
+|---|---|
+| Understand a specific feature or the research | [The Science](SCIENCE.md) |
+| Tune knobs, env vars, ports | [Configuration](CONFIGURATION.md) |
+| Global vs per-project vs multi-instance | [Storage Modes](STORAGE.md) |
+| Make your agent use memory automatically | [README → automatic memory](../README.md#-make-your-ai-use-memory-automatically) |
+| Ask a real question | [FAQ](FAQ.md) |
+
+Welcome. Vestige gets more useful the longer you use it — that's the point.
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@ -126,6 +126,68 @@ Target: turn "I have 300 notes" into a reliable workflow.
 | Review queue | Users can approve, edit, split, merge, or reject proposed memories. |
 | Post-import health pass | Vestige recommends consolidation, duplicate review, or tag cleanup after import. |

+## Tracked Issues (Consolidated 2026-07-02)
+
+The following roadmap issues were consolidated here and closed so the issue tracker
+reflects active work, not a standing backlog. Nothing is lost — each entry keeps its
+scope, the backend anchors that already exist, and why it is deferred. Most are
+deferred behind the dashboard focus; several are security/data-integrity boundaries
+that are deliberately *not* shipped half-done.
+
+### A. Reliability & Trust surfaces
+
+- **Agent Reliability Record** (was #84) — Unify traces, receipts, contradictions,
+  and composed-graph events into one per-run record with 5 evidence states
+  (supported / missing / stale / contradicted / suppressed) + Markdown export.
+  Backend already exists (`crates/vestige-core/src/trace/`). Remaining work is the
+  dashboard record view — see the dashboard Discussion.
+- **Trust Zones + Memory Quarantine** (was #85) — Provenance/trust class on nodes,
+  score-capping for weak-provenance content, quarantine of untrusted sources.
+  Security boundary; unsafe half-done, and depends on ACL Memory primitives that
+  don't exist yet. Deferred post-dashboard.
+- **ComposeBench** (was #86) — Reliability benchmark across 8 scenarios. Will reuse
+  the existing `benchmarks/causebench/` harness pattern; the ACL scenario is gated
+  on ACL Memory. Deferred.
+
+### B. Access & Governance boundary
+
+- **ACL Memory for source-aware connectors** (was #82) — Source-authorization-aware
+  memory: connector-ingested memories preserve upstream access rules and retrieval
+  fails closed for unauthorized callers. A hard security boundary with no foundation
+  today (no per-caller identity model; `search()` takes no subject). Must be designed
+  as one deliberate pass, not sliced. Design + user-permission-shape input welcome in
+  the Discussion.
+- **Team Pro Reliability Foundation** (was #92) — Commercial team tier (RBAC/SSO/SCIM,
+  admin review, audit export, team lanes, Postgres, hosted backups). A product-strategy
+  meta-issue, upstream of coding; depends on ACL Memory + HTTP/Postgres plans.
+
+### C. Ingest & Projection integrity
+
+- **Markdown + Rules Projection** (was #87) — Project memories into client-native
+  rule files (AGENTS.md, CLAUDE.md, `.cursor/rules`, Windsurf, Cline) with provenance
+  and an optional bidirectional re-import. The re-import leg is a data-integrity
+  boundary (must never silently overwrite user files). Target-format priorities are an
+  open user question — Discussion.
+- **Code Memory Workflow** (was #88) — First-class, inspectable code memory
+  (patterns/decisions with file+line provenance) kept separate from prose. The typed
+  model exists (`crates/vestige-core/src/codebase/`) but is unpersisted/unwired; needs
+  schema + a review/prune dashboard surface.
+- **Guided Import + Review Queue** (was #89) — Dry-run import → proposed memories →
+  approve/edit/split/merge/reject queue → post-import health pass. Ingest/corruption
+  boundary; needs a real no-write dry run + review-queue state machine.
+- **Goals + Milestones** (was #90) — A durable, non-decaying goal/milestone primitive
+  (paralleling the intentions subsystem) with lifecycle states and evidence/blockers.
+  A create-only slice would ship the primitive without its defining non-decay
+  guarantee, so it waits for the full build.
+
+### D. Dashboard productization
+
+- **ComposedGraph Productization** (was #91) — The MCP/CLI/storage backend already
+  ships in v2.2 (`crates/vestige-mcp/src/tools/composed_graph.rs`, all 7 modes). The
+  remaining slice is the dashboard surface: composition history, the never-composed
+  frontier, and closed doors. This is the natural first move in the dashboard focus —
+  shape it in the Discussion.
+
 ## Non-Goals

 - Do not auto-store every conversation turn by default.