checkpoint
Save and summarize project context to Redis before clearing Claude's memory, enabling persistent long-term memory across sessions.
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/index.ts:126-135 (handler)MCP tool handler for the 'checkpoint' tool. Parses input using CheckpointInputSchema and calls ProjectBrain.checkpoint with context and token_count.case 'checkpoint': { const input = CheckpointInputSchema.parse(args); const result = await this.brain.checkpoint( input.context, input.token_count ); return { content: [{ type: 'text', text: result }], }; }
- src/index.ts:57-75 (registration)Registration of the 'checkpoint' tool in the MCP ListTools handler, defining name, description, and inputSchema.{ 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 CheckpointInput used for validation in the tool handler.export const CheckpointInputSchema = z.object({ context: z.string(), token_count: z.number().nonnegative(), });
- src/core/ProjectBrain.ts:120-183 (helper)Core implementation of checkpoint logic in ProjectBrain class. Merges new context with existing state using LLM, updates Redis state with locking, saves history asynchronously.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}`); } }