ctx-purge

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:
2. "Wipe just one session?" → ask for the sessionId.
3. "Wipe the whole project?" → confirm scope:'project' (this is the destructive, irreversible default).
4. Warn the user about scope:'project'. Everything will be deleted:
5. FTS5 knowledge base (all indexed content from ctx_index, ctx_fetch_and_index, ctx_batch_execute)
6. Session events DB (analytics, metadata, resume snapshots) for ALL sessions in the project
7. Session events markdown file
8. In-memory session stats + persisted stats file
9. Call the mcp__context-mode__ctx_purge MCP tool with the chosen parameters:
10. Scoped: { confirm: true, sessionId: "<id>" } — implies scope:'session'.
11. Project: { confirm: true, scope: "project" } — explicit destructive form.
12. Bare { confirm: true } still works but emits a deprecation warning. Prefer the explicit forms.
13. 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.