Skip to main content
Glama
zademy

Context Mode

Official
by zademy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Purge Knowledge Base

ctx_purge
DestructiveIdempotent

Permanently delete indexed session or project content from Context Mode; cannot be undone. Requires confirm:true and exactly one scope: sessionId for one session or scope:'project' for all.

Instructions

DESTRUCTIVE: permanently delete indexed content. Cannot be undone. Requires confirm:true and exactly one scope.

WHEN:

  • User explicitly asks to clear a specific session ('purge this session', 'wipe this conversation')

  • User explicitly asks to reset the whole project ('reset everything', 'wipe the knowledge base')

WHEN NOT:

  • User says 'reset', 'clear', or 'wipe' without naming a scope -> ask which scope before calling

  • User wants to free memory -> recommend ctx_stats first

SCOPES (pass exactly one):

  • Per-session: ctx_purge(confirm: true, sessionId: "") — deletes that session's events and chunks; siblings and stats preserved.

  • Per-project: ctx_purge(confirm: true, scope: "project") — wipes the FTS5 knowledge base, every session DB row, events markdown, and resets stats. Preview with ctx_stats first.

CONTRACT:

  • confirm:true is required; confirm:false returns 'purge cancelled'.

  • sessionId and scope:'project' together return 'ambiguous - pick one'.

  • scope:'session' without sessionId throws.

  • Bare {confirm:true} is deprecated: maps to scope:'project' with a warning; will hard-error later.

RETURNS: A summary of removed rows + the resolved scope.

EXAMPLE: ctx_purge(confirm: true, sessionId: "7c8a-1234-5678-9abc-def012345678")

Input Schema

NameRequiredDescriptionDefault
scopeNoExplicit scope selector. 'session' REQUIRES sessionId. 'project' wipes the entire project (FTS5 + every session + stats). Omit only for the deprecated bare-{confirm:true} back-compat path.
confirmYesMUST be true. Destructive operation; false returns 'purge cancelled'.
sessionIdNoUUID of a single session. Pairs with confirm:true to wipe only that session's events + per-session FTS5 chunks. Sibling sessions and the stats file are preserved. MUST NOT be combined with scope:'project'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond: it states the operation cannot be undone, enumerates precisely what each scope destroys (session events + FTS5 chunks vs. the entire FTS5 base + every session row + stats reset), documents the confirm contract and exact error strings, and discloses the deprecated bare-{confirm:true} path. All of this is non-derivable context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the DESTRUCTIVE warning and uses clear headers for WHEN/WHEN NOT/SCOPES/CONTRACT/RETURNS/EXAMPLE. Each section carries distinct information, though the CONTRACT restates a couple of facts (confirm:false behavior) already present in the schema descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive 3-param tool with no output schema, the description covers everything an agent needs: scope semantics, mutual-exclusion rules, the confirm gate, error outcomes, a worked invocation example, and a RETURNS note. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the CONTRACT section adds meaning beyond the schema: exact returned error strings ('purge cancelled', 'ambiguous - pick one'), the exception thrown by scope:'session' without sessionId, and the deprecation/warning behavior of bare {confirm:true}. Only mild redundancy with the schema's own enum/description text keeps it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific verb and resource ('permanently delete indexed content') with an explicit destructiveness qualifier, and the scope/contract sections make clear how it differs from siblings like ctx_stats, ctx_index, and ctx_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Dedicated WHEN and WHEN NOT blocks give explicit triggers ('purge this session') and explicit exclusions plus a routing action ('ask which scope', 'recommend ctx_stats first'). This is exactly the when/when-not/alternatives triad.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools