vestige/docs/ROADMAP.md

# Vestige Roadmap

> Public adoption roadmap for making Vestige easier to start, easier to trust,
> and easier to configure.

Last updated: June 7, 2026

Vestige already has the core primitives for durable local memory: `search`,
`session_context`, `smart_ingest`, `memory`, `intention`, `codebase`,
`deep_reference`, suppression, portable storage, and the dashboard. The next
product step is reducing first-user confusion so more people can get value from
those primitives without inventing their own fragile memory vocabulary.

This roadmap turns early community feedback into a staged plan.

## Principles

- Make first use obvious. A new user should know what to import, how atomic each
  memory should be, and which tool to use for current session context.
- Keep memory legible. Agents and humans should understand whether a memory was
  created, reinforced, updated, superseded, suppressed, or purged.
- Prefer progressive disclosure. The default MCP response should be lean, with
  explicit ways to request more detail.
- Keep local-first behavior. New onboarding, code memory, and configuration
  features must not require a cloud service.
- Optimize for many users. Defaults should work for non-experts, while power
  users can tune fields, merge behavior, and formats.

## Already Shipped, Needs Clearer Guidance

| Area | Current State | Next Documentation Fix |
|------|---------------|------------------------|
| Session startup | `session_context` combines memories, intentions, status, predictions, and codebase context. | Update all agent setup templates to make `session_context` the default startup call. |
| Batch memory saves | `smart_ingest` batch mode defaults to `batchMergePolicy="force_create"` so caller-separated items stay separate. | Document when to use batch force-create vs smart merge. |
| Device migration | `portable-export`, `portable-import`, and `sync` preserve exact Vestige storage state. | Separate device migration from first-time document import so users do not confuse them. |
| Supersede semantics | Supersede demotes the old memory and creates a new one; it does not purge the old memory. | Add plain-language vocabulary for create, update, supersede, suppress, demote, and purge. |

## Phase 1: Onboarding And Memory Hygiene

Target: make the first 30 minutes with Vestige hard to mess up.

| Work | Outcome |
|------|---------|
| First-time memory migration guide | Users can import notes/docs without Claude tagging everything as `verified` or flattening unrelated facts together. |
| Atomic memory guide | Clear examples for one fact, one preference, one decision, one bug fix, one source note, and one code pattern per memory. |
| Default tag vocabulary | Recommended tags for source quality, confidence, project, type, urgency, and lifecycle without overloading words like `verified`. |
| Smart vs force-create guide | Agents know when to use `forceCreate`, `batchMergePolicy="force_create"`, or normal PE gating. |
| Updated agent templates | Claude, Codex, Cursor, VS Code, Xcode, OpenCode, JetBrains, and Windsurf templates start with `session_context` and use the same memory vocabulary. |

Planned docs:

- `docs/MIGRATION.md`
- `docs/MEMORY-HYGIENE.md`
- revised `docs/AGENT-MEMORY-PROTOCOL.md`
- revised `docs/CLAUDE-SETUP.md`

## Phase 2: Configurable Output

Target: let users control context cost without losing important evidence.

| Work | Outcome |
|------|---------|
| Field masks for MCP results | Users can drop fields they never want in model context, such as temporal hints, scores, or timestamps. |
| Output profiles | Presets like `lean`, `default`, `audit`, and `research` tune result size and metadata detail. |
| Markdown output mode | Users can request compact Markdown summaries when that is more context-efficient than JSON. |
| Context reinstatement controls | `contextReinstatement` becomes opt-in or configurable, and temporal hints are based on stored memory context when available. |
| Per-tool defaults | Users can define default detail level, result limit, and response shape for search, timeline, codebase, and session context. |

Likely implementation paths:

- config file under the active Vestige data directory
- environment-variable override for simple deployments
- MCP parameters still win over defaults for one-off calls

## Phase 3: Merge And Supersede Controls

Target: make memory mutation predictable.

| Work | Outcome |
|------|---------|
| Merge policy configuration | Users can keep some tags or node types atomic while allowing others to merge. |
| Prediction Error threshold knobs | Advanced users can tune create/update/reinforce boundaries without recompiling. |
| Merge previews before mutation | Agents can show what would change before updating an existing durable memory. |
| Safer consolidation dedup | Consolidation respects user-configured atomic tags and source boundaries. |
| Friendlier lifecycle labels | Agent-facing copy explains that superseded memories are old versions, not destroyed records. |

## Phase 4: Code Memory

Target: make code memories useful without blending source code, docstrings, and
human project notes into one noisy search space.

| Work | Outcome |
|------|---------|
| Code memory import guide | Developers know when to save patterns/decisions versus code entities or docstrings. |
| Exposed code entity workflow | The existing core `CodeEntity` concept becomes usable through MCP or CLI. |
| Docstring/code symbol ingestion | Users can ingest functions, types, modules, docstrings, and call-site notes with source file provenance. |
| Code/prose retrieval separation | Search can filter or rank code memories separately from user preferences and project decisions. |
| Codebase dashboard review | Developers can inspect imported code memories and remove noisy entries. |

## Phase 5: Goals And Milestones

Target: support durable direction without pretending every future task is just a
reminder.

| Work | Outcome |
|------|---------|
| Goal primitive | Non-fading, manually pivoted goals that survive normal memory decay. |
| Milestone tracking | Goals can have milestones, status, evidence, and blockers. |
| Goal-aware session context | `session_context` can include active goals when relevant. |
| Manual pivot semantics | Agents can update goals only when the user explicitly pivots, completes, or cancels them. |
| Dashboard surface | Users can inspect active, completed, paused, and cancelled goals. |

This is distinct from `intention`: intentions are reminders triggered by time,
topic, file, event, or context. Goals are longer-lived direction and should not
fire as reminders unless the user attaches an intention.

## Phase 6: Guided Import Tools

Target: turn "I have 300 notes" into a reliable workflow.

| Work | Outcome |
|------|---------|
| Import dry run | Vestige previews proposed memories, tags, node types, and merge decisions before writing. |
| Source-aware import | Imported memories keep file/source provenance and confidence metadata. |
| Chunking strategies | Users choose atomic facts, section summaries, decision records, or source notes. |
| 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.
- Do not require cloud services for memory creation, search, or configuration.
- Do not hide irreversible deletion. `purge` must stay explicit.
- Do not make code ingestion pollute general personal memory by default.
- Do not make advanced tuning required for ordinary users.

## How To Read This Roadmap

This is directional, not a release guarantee. The priority is adoption: fewer
surprises, clearer defaults, and better tool descriptions before adding complex
new surfaces. Community feedback that reveals a confusing first-use path should
usually become either a documentation fix, a safer default, or a guided workflow.