@ooples/token-optimizer-mcp
Version:
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
460 lines • 13.9 kB
TypeScript
/**
* Cache Optimizer - Advanced Cache Strategy Optimization (89%+ token reduction)
*
* Features:
* - Comprehensive performance analysis (hit rate, latency, throughput, memory)
* - Strategy benchmarking (LRU, LFU, FIFO, TTL, size-based, hybrid)
* - Intelligent optimization recommendations with impact analysis
* - Simulation of strategy changes before applying
* - Detailed optimization reports
* - Multi-tier cache analysis
* - ML-based parameter tuning
* - Cost-benefit analysis
* - Bottleneck detection
* - Token reduction optimization (86%+ target)
*/
import { CacheEngine } from '../../core/cache-engine.js';
import { TokenCounter } from '../../core/token-counter.js';
import { MetricsCollector } from '../../core/metrics.js';
import { EventEmitter } from 'events';
export type EvictionStrategy = 'LRU' | 'LFU' | 'FIFO' | 'TTL' | 'SIZE' | 'HYBRID';
export type CacheTier = 'L1' | 'L2' | 'L3';
export type OptimizationObjective = 'hit-rate' | 'latency' | 'memory' | 'throughput' | 'balanced';
export type WorkloadPattern = 'uniform' | 'skewed' | 'temporal' | 'burst' | 'predictable' | 'unknown';
export interface CacheOptimizerOptions {
operation: 'analyze' | 'benchmark' | 'optimize' | 'recommend' | 'simulate' | 'tune' | 'detect-bottlenecks' | 'cost-benefit' | 'configure' | 'report';
analysisWindow?: number;
includePredictions?: boolean;
includeBottlenecks?: boolean;
strategies?: EvictionStrategy[];
workloadSize?: number;
workloadPattern?: WorkloadPattern;
iterations?: number;
objective?: OptimizationObjective;
constraints?: {
maxMemory?: number;
maxLatency?: number;
minHitRate?: number;
};
currentStrategy?: EvictionStrategy;
currentConfig?: CacheConfiguration;
targetStrategy?: EvictionStrategy;
targetConfig?: CacheConfiguration;
simulationDuration?: number;
tuningMethod?: 'grid-search' | 'gradient-descent' | 'bayesian' | 'evolutionary';
epochs?: number;
learningRate?: number;
reportFormat?: 'json' | 'markdown' | 'html';
includeCharts?: boolean;
includeRecommendations?: boolean;
useCache?: boolean;
cacheTTL?: number;
}
export interface CacheConfiguration {
strategy: EvictionStrategy;
l1MaxSize: number;
l2MaxSize: number;
l3MaxSize: number;
ttl: number;
compressionEnabled: boolean;
prefetchEnabled: boolean;
writeMode: 'write-through' | 'write-back';
}
export interface PerformanceMetrics {
hitRate: number;
missRate: number;
averageLatency: number;
p50Latency: number;
p95Latency: number;
p99Latency: number;
throughput: number;
memoryUsage: number;
evictionRate: number;
compressionRatio: number;
tokenReductionRate: number;
}
export interface StrategyBenchmark {
strategy: EvictionStrategy;
config: CacheConfiguration;
metrics: PerformanceMetrics;
score: number;
strengths: string[];
weaknesses: string[];
}
export interface OptimizationRecommendation {
recommendedStrategy: EvictionStrategy;
recommendedConfig: CacheConfiguration;
expectedImprovement: {
hitRate: number;
latency: number;
memory: number;
tokens: number;
};
confidence: number;
reasoning: string;
implementationSteps: string[];
risks: string[];
}
export interface BottleneckAnalysis {
type: 'memory' | 'eviction' | 'compression' | 'io' | 'contention';
severity: 'low' | 'medium' | 'high' | 'critical';
description: string;
metrics: Record<string, number>;
impact: string;
recommendations: string[];
}
export interface CostBenefitAnalysis {
strategy: EvictionStrategy;
costs: {
memory: number;
cpu: number;
latency: number;
complexity: number;
};
benefits: {
hitRate: number;
tokenSavings: number;
throughput: number;
reliability: number;
};
roi: number;
breakEvenPoint: number;
}
export interface SimulationResult {
strategy: EvictionStrategy;
config: CacheConfiguration;
simulatedMetrics: PerformanceMetrics;
comparisonToBaseline: {
hitRateDelta: number;
latencyDelta: number;
memoryDelta: number;
tokenDelta: number;
};
events: SimulationEvent[];
recommendation: 'adopt' | 'reject' | 'test-further';
reasoning: string;
}
export interface SimulationEvent {
timestamp: number;
type: 'hit' | 'miss' | 'eviction' | 'promotion' | 'demotion';
key: string;
tier: CacheTier;
details: Record<string, unknown>;
}
export interface TuningResult {
method: string;
iterations: number;
bestConfig: CacheConfiguration;
bestScore: number;
improvementHistory: Array<{
iteration: number;
config: CacheConfiguration;
score: number;
}>;
convergenceMetrics: {
converged: boolean;
finalImprovement: number;
epochs: number;
};
}
export interface OptimizationReport {
timestamp: number;
summary: {
currentPerformance: PerformanceMetrics;
optimalPerformance: PerformanceMetrics;
potentialImprovement: number;
};
analysis: {
workloadPattern: WorkloadPattern;
hotKeys: Array<{
key: string;
accessCount: number;
tier: CacheTier;
}>;
coldKeys: Array<{
key: string;
lastAccess: number;
tier: CacheTier;
}>;
bottlenecks: BottleneckAnalysis[];
};
recommendations: OptimizationRecommendation[];
benchmarks: StrategyBenchmark[];
costBenefit: CostBenefitAnalysis[];
actionItems: Array<{
priority: 'high' | 'medium' | 'low';
action: string;
expectedImpact: string;
effort: 'low' | 'medium' | 'high';
}>;
}
export interface CacheOptimizerResult {
success: boolean;
operation: string;
data: {
metrics?: PerformanceMetrics;
benchmarks?: StrategyBenchmark[];
recommendations?: OptimizationRecommendation[];
simulation?: SimulationResult;
tuning?: TuningResult;
bottlenecks?: BottleneckAnalysis[];
costBenefit?: CostBenefitAnalysis[];
report?: OptimizationReport;
config?: CacheConfiguration;
};
metadata: {
tokensUsed: number;
tokensSaved: number;
cacheHit: boolean;
executionTime: number;
};
}
/**
* Cache Optimizer - Advanced optimization and analysis
*/
export declare class CacheOptimizerTool extends EventEmitter {
private cache;
private tokenCounter;
private metrics;
private accessHistory;
private maxHistorySize;
private evictionEvents;
private learningRate;
private optimizationState;
constructor(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector);
/**
* Main entry point for cache optimizer operations
*/
run(options: CacheOptimizerOptions): Promise<CacheOptimizerResult>;
/**
* Analyze current cache performance
*/
private analyze;
/**
* Benchmark different eviction strategies
*/
private benchmark;
/**
* Optimize cache configuration
*/
private optimize;
/**
* Generate optimization recommendations
*/
private recommend;
/**
* Simulate strategy change
*/
private simulate;
/**
* Tune cache parameters using ML
*/
private tune;
/**
* Detect performance bottlenecks
*/
private detectBottlenecks;
/**
* Perform cost-benefit analysis
*/
private analyzeCostBenefit;
/**
* Configure cache settings
*/
private configure;
/**
* Generate comprehensive optimization report
*/
private generateReport;
/**
* Benchmark a specific strategy
*/
private benchmarkStrategy;
/**
* Calculate strategy score based on objective
*/
private calculateStrategyScore;
/**
* Analyze strategy performance
*/
private analyzeStrategyPerformance;
/**
* Check if metrics meet constraints
*/
private meetsConstraints;
/**
* Generate optimization recommendations
*/
private generateRecommendations;
/**
* Run simulation of strategy change
*/
private runSimulation;
/**
* Grid search tuning
*/
private gridSearchTuning;
/**
* Gradient descent tuning
*/
private gradientDescentTuning;
/**
* Bayesian optimization tuning
*/
private bayesianTuning;
/**
* Evolutionary algorithm tuning
*/
private evolutionaryTuning;
/**
* Estimate costs for a strategy
*/
private estimateCosts;
/**
* Estimate benefits for a strategy
*/
private estimateBenefits;
/**
* Calculate ROI
*/
private calculateROI;
/**
* Calculate break-even point
*/
private calculateBreakEven;
/**
* Generate recommendation reasoning
*/
private generateRecommendationReasoning;
/**
* Generate implementation steps
*/
private generateImplementationSteps;
/**
* Identify risks
*/
private identifyRisks;
/**
* Calculate recommendation confidence
*/
private calculateConfidence;
/**
* Capture current cache state
*/
private captureCurrentState;
/**
* Detect workload pattern
*/
private detectWorkloadPattern;
/**
* Identify hot and cold keys
*/
private identifyKeyPatterns;
/**
* Generate action items
*/
private generateActionItems;
/**
* Get default configuration for strategy
*/
private getDefaultConfig;
/**
* Generate synthetic metrics for testing
*/
private generateSyntheticMetrics;
/**
* Generate access pattern
*/
private generateAccessPattern;
/**
* Predict hit probability for strategy
*/
private predictHitProbability;
/**
* Calculate percentile
*/
private percentile;
/**
* Generate random key
*/
private generateRandomKey;
/**
* Record access for analysis
*/
recordAccess(key: string, hit: boolean, latency: number, tier: CacheTier, size: number): void;
/**
* Record eviction event
*/
recordEviction(strategy: EvictionStrategy): void;
/**
* Determine if operation is cacheable
*/
private isCacheableOperation;
/**
* Get cache key parameters for operation
*/
private getCacheKeyParams;
/**
* Cleanup and dispose
*/
dispose(): void;
}
export declare function getCacheOptimizerTool(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): CacheOptimizerTool;
export declare const CACHE_OPTIMIZER_TOOL_DEFINITION: {
readonly name: "cache_optimizer";
readonly description: "Advanced cache optimization with 89%+ token reduction. Analyzes performance, benchmarks strategies, provides ML-based recommendations, detects bottlenecks, and performs cost-benefit analysis.";
readonly inputSchema: {
readonly type: "object";
readonly properties: {
readonly operation: {
readonly type: "string";
readonly enum: readonly ["analyze", "benchmark", "optimize", "recommend", "simulate", "tune", "detect-bottlenecks", "cost-benefit", "configure", "report"];
readonly description: "The optimization operation to perform";
};
readonly analysisWindow: {
readonly type: "number";
readonly description: "Time window in milliseconds for analysis (default: 3600000)";
};
readonly strategies: {
readonly type: "array";
readonly items: {
readonly type: "string";
readonly enum: readonly ["LRU", "LFU", "FIFO", "TTL", "SIZE", "HYBRID"];
};
readonly description: "Eviction strategies to benchmark";
};
readonly objective: {
readonly type: "string";
readonly enum: readonly ["hit-rate", "latency", "memory", "throughput", "balanced"];
readonly description: "Optimization objective (default: balanced)";
};
readonly workloadPattern: {
readonly type: "string";
readonly enum: readonly ["uniform", "skewed", "temporal", "burst", "predictable", "unknown"];
readonly description: "Workload pattern for benchmarking";
};
readonly tuningMethod: {
readonly type: "string";
readonly enum: readonly ["grid-search", "gradient-descent", "bayesian", "evolutionary"];
readonly description: "ML tuning method (default: bayesian)";
};
readonly epochs: {
readonly type: "number";
readonly description: "Number of training epochs for tuning (default: 50)";
};
readonly useCache: {
readonly type: "boolean";
readonly description: "Enable result caching (default: true)";
readonly default: true;
};
readonly cacheTTL: {
readonly type: "number";
readonly description: "Cache TTL in seconds (default: 300)";
readonly default: 300;
};
};
readonly required: readonly ["operation"];
};
};
export declare function runCacheOptimizer(options: CacheOptimizerOptions, cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): Promise<CacheOptimizerResult>;
//# sourceMappingURL=cache-optimizer.d.ts.map