checkpoint
Save and summarize project context to persistent memory before clearing workspace, enabling continuity across sessions by merging new information with existing state.
Instructions
Save current context to Redis before running /clear. Merges new context with existing project state using LLM-based summarization.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | The current work context to checkpoint (summary of recent work, decisions, files) | |
| token_count | Yes | Current token budget usage |
Implementation Reference
- src/core/ProjectBrain.ts:120-183 (handler)Core handler function that executes the checkpoint logic: locks state, merges new context using LLM summarizer, updates Redis state, saves async history, and returns success message.async checkpoint(context: string, tokenCount: number): Promise<string> { const sessionId = this.ensureInitialized(); const startTime = Date.now(); try { logger.info('Starting checkpoint', { sessionId, tokenCount }); // Update state with locking const updatedState = await this.redis.updateStateWithLock( sessionId, async (oldState) => { // Merge old state with new context using LLM const merged = await this.merger.merge(oldState, context, tokenCount); // Update token count merged.meta.token_budget_used = tokenCount; // Validate and clean active files merged.active_context.active_files = await this.filterExistingFilesWithCache( merged.active_context.active_files ); return merged; } ); // Save to checkpoint history (async, non-blocking) const duration = Date.now() - startTime; const historyEntry: CheckpointHistory = { version: updatedState.meta.version, timestamp: updatedState.meta.last_checkpoint, merge_duration_ms: duration, token_count: tokenCount, context_ratio: tokenCount / 200000, // Assuming 200k token limit state: updatedState, }; // Fire and forget - don't await this.redis.saveCheckpointHistory(sessionId, historyEntry).catch((error) => { this.historyFailureCount++; logger.warn('Failed to save checkpoint history (non-critical)', { error, failureCount: this.historyFailureCount }); if (this.historyFailureCount >= this.MAX_HISTORY_FAILURES) { logger.error('Multiple checkpoint history failures detected. Rollback may not work correctly.'); } }); // Refresh session lock await this.redis.refreshSessionLock(sessionId); logger.info('Checkpoint completed successfully', { version: updatedState.meta.version, duration, }); return `Checkpoint saved successfully (version ${updatedState.meta.version}, ${duration}ms)`; } catch (error) { logger.error('Checkpoint failed', { error, sessionId }); throw new Error(`Checkpoint failed: ${error}`); } }
- src/index.ts:57-75 (registration)MCP tool registration in ListTools handler: defines name 'checkpoint', description, and input schema.{ name: 'checkpoint', description: 'Save current context to Redis before running /clear. Merges new context with existing project state using LLM-based summarization.', inputSchema: { type: 'object', properties: { context: { type: 'string', description: 'The current work context to checkpoint (summary of recent work, decisions, files)', }, token_count: { type: 'number', description: 'Current token budget usage', }, }, required: ['context', 'token_count'], }, },
- src/types/schema.ts:95-98 (schema)Zod schema for validating checkpoint tool input parameters (context and token_count).export const CheckpointInputSchema = z.object({ context: z.string(), token_count: z.number().nonnegative(), });
- src/index.ts:126-135 (handler)MCP CallToolRequestSchema handler dispatch for 'checkpoint': parses input, calls ProjectBrain.checkpoint, formats response.case 'checkpoint': { const input = CheckpointInputSchema.parse(args); const result = await this.brain.checkpoint( input.context, input.token_count ); return { content: [{ type: 'text', text: result }], }; }