ctx-purge

---
name: ctx-purge
description: |
  Purge the context-mode knowledge base. Permanently deletes all indexed content
  and resets session stats. This is destructive and cannot be undone.
  Trigger: /context-mode:ctx-purge
user-invocable: true
---

# Context Mode Purge

Permanently deletes session data for this project. Two scopes are supported (issue #520):

- **Project scope** (`scope: "project"`): wipes EVERYTHING — knowledge base, all session DB rows for every session, events markdown, and stats.
- **Session scope** (`sessionId: "<id>"` or `scope: "session"`): wipes ONLY the matching session's rows + FTS5 chunks. Sibling sessions, project stats, and the FTS5 store file are preserved.

## Instructions

1. **Decide the scope first** with the user:
   - "Wipe just one session?" → ask for the `sessionId`.
   - "Wipe the whole project?" → confirm scope:'project' (this is the destructive, irreversible default).
2. **Warn the user about scope:'project'**. Everything will be deleted:
   - FTS5 knowledge base (all indexed content from `ctx_index`, `ctx_fetch_and_index`, `ctx_batch_execute`)
   - Session events DB (analytics, metadata, resume snapshots) for ALL sessions in the project
   - Session events markdown file
   - In-memory session stats + persisted stats file
3. Call the `mcp__context-mode__ctx_purge` MCP tool with the chosen parameters:
   - Scoped: `{ confirm: true, sessionId: "<id>" }` — implies scope:'session'.
   - Project: `{ confirm: true, scope: "project" }` — explicit destructive form.
   - Bare `{ confirm: true }` still works but emits a deprecation warning. Prefer the explicit forms.
4. Report the result to the user — the response lists exactly what was deleted and (for scoped purges) confirms that other sessions and project stats were preserved.

## Schema rules

- `confirm: true` is always required.
- `sessionId` and `scope: "project"` together is REJECTED as ambiguous (the sessionId implies session scope; combining with project scope contradicts intent).
- `scope: "session"` without `sessionId` throws — sessionId is required.

## When to Use

- **Scoped (per-session)**: scratch acceptance scenarios, drill replays, isolating a polluted session without losing the main working session's stats.
- **Project**: KB contains stale or incorrect content polluting search results, switching between unrelated projects in the same session, completely fresh start.

## Important

- `ctx_purge` is the **only** way to delete session data. No other mechanism exists.
- `ctx_stats` is read-only — shows statistics only.
- `/clear` and `/compact` do NOT affect any context-mode data.
- There is no undo. Re-index content if you need it again.