Claude Infinite Context

Instructions

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 }],
    };
  }