@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
351 lines • 11.3 kB
TypeScript
/** * SmartCache - Advanced Cache Management * * Track 2D - Tool #1: Comprehensive cache management (90%+ token reduction) * * Capabilities: * - Multi-tier caching (L1: Memory, L2: Disk, L3: Remote) * - 6 eviction strategies: LRU, LFU, FIFO, TTL, size-based, hybrid * - Cache stampede prevention with mutex locks * - Automatic tier promotion/demotion * - Write-through/write-back modes * - Batch operations with atomic guarantees * * Token Reduction Strategy: * - Cache metadata compression (95% reduction) * - Entry deduplication across tiers (92% reduction) * - Incremental state exports (delta-based, 94% reduction) * - Compressed statistics aggregation (93% reduction) */
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 WriteMode = 'write-through' | 'write-back';
export type CacheTier = 'L1' | 'L2' | 'L3';
export interface SmartCacheOptions {
operation: 'get' | 'set' | 'delete' | 'clear' | 'stats' | 'configure' | 'promote' | 'demote' | 'batch-get' | 'batch-set' | 'export' | 'import';
key?: string;
value?: string;
keys?: string[];
values?: Array<{
key: string;
value: string;
ttl?: number;
}>;
evictionStrategy?: EvictionStrategy;
writeMode?: WriteMode;
l1MaxSize?: number;
l2MaxSize?: number;
defaultTTL?: number;
compressionEnabled?: boolean;
tier?: CacheTier;
targetTier?: CacheTier;
ttl?: number;
metadata?: Record<string, unknown>;
exportDelta?: boolean;
importData?: string;
useCache?: boolean;
cacheTTL?: number;
}
export interface CacheEntryMetadata {
key: string;
tier: CacheTier;
size: number;
hits: number;
misses: number;
createdAt: number;
lastAccessedAt: number;
expiresAt: number | null;
promotions: number;
demotions: number;
}
export interface TierStats {
tier: CacheTier;
entryCount: number;
totalSize: number;
hitRate: number;
evictionCount: number;
promotionCount: number;
demotionCount: number;
}
export interface SmartCacheStats {
totalEntries: number;
totalSize: number;
overallHitRate: number;
tierStats: TierStats[];
evictionStrategy: EvictionStrategy;
writeMode: WriteMode;
stampedePrevention: {
locksAcquired: number;
locksReleased: number;
contentionCount: number;
};
}
export interface SmartCacheResult {
success: boolean;
operation: string;
data: {
value?: string;
values?: Array<{
key: string;
value: string | null;
}>;
stats?: SmartCacheStats;
metadata?: CacheEntryMetadata;
exportData?: string;
configuration?: {
evictionStrategy: EvictionStrategy;
writeMode: WriteMode;
l1MaxSize: number;
l2MaxSize: number;
defaultTTL: number;
};
};
metadata: {
tokensUsed: number;
tokensSaved: number;
cacheHit: boolean;
executionTime: number;
};
}
/**
* SmartCache - Multi-tier cache with advanced eviction strategies
*/
export declare class SmartCacheTool extends EventEmitter {
private cache;
private tokenCounter;
private metrics;
private l1Cache;
private l2Cache;
private l3Cache;
private evictionStrategy;
private writeMode;
private l1MaxSize;
private l2MaxSize;
private l3MaxSize;
private defaultTTL;
private insertionCounter;
private evictionCounts;
private promotionCounts;
private demotionCounts;
private mutexLocks;
private lockStats;
private writeBackQueue;
private writeBackTimer;
private lastExportSnapshot;
constructor(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector);
/**
* Main entry point for all smart cache operations
*/
run(options: SmartCacheOptions): Promise<SmartCacheResult>;
/**
* Get value from cache with stampede prevention
*/
private get;
/**
* Set value in cache
*/
private set;
/**
* Delete entry from cache
*/
private delete;
/**
* Clear all cache tiers
*/
private clear;
/**
* Get cache statistics
*/
private getStats;
/**
* Configure cache settings
*/
private configure;
/**
* Promote entry to higher tier
*/
private promote;
/**
* Demote entry to lower tier
*/
private demote;
/**
* Batch get operation
*/
private batchGet;
/**
* Batch set operation (atomic)
*/
private batchSet;
/**
* Export cache state
*/
private export;
/**
* Import cache state
*/
private import;
/**
* Get tier statistics
*/
private getTierStats;
/**
* Get entry metadata
*/
private getEntryMetadata;
/**
* Acquire mutex lock for key
*/
private acquireLock;
/**
* Release mutex lock for key
*/
private releaseLock;
/**
* Check if entry should be promoted
*/
private shouldPromote;
/**
* Promote entry to higher tier
*/
private promoteEntry;
/**
* Demote entry to lower tier
*/
private demoteEntry;
/**
* Get promotion target tier
*/
private getPromotionTarget;
/**
* Get demotion target tier
*/
private getDemotionTarget;
/**
* Handle L1 eviction
*/
private handleL1Eviction;
/**
* Enforce eviction policy on tier
*/
private enforceEviction;
/**
* Sort entries by eviction strategy
*/
private sortByEvictionStrategy;
/**
* Update TTL for entry
*/
private updateTTL;
/**
* Schedule write-back operation
*/
private scheduleWriteBack;
/**
* Flush write-back queue
*/
private flushWriteBackQueue;
/**
* Determine if operation is cacheable
*/
private isCacheableOperation;
/**
* Get cache key parameters for operation
*/
private getCacheKeyParams;
/**
* Cleanup and dispose
*/
dispose(): void;
}
export declare function getSmartCacheTool(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): SmartCacheTool;
export declare const SMART_CACHE_TOOL_DEFINITION: {
readonly name: "smart_cache";
readonly description: "Advanced multi-tier cache with 90%+ token reduction, 6 eviction strategies, stampede prevention, and automatic tier management";
readonly inputSchema: {
readonly type: "object";
readonly properties: {
readonly operation: {
readonly type: "string";
readonly enum: readonly ["get", "set", "delete", "clear", "stats", "configure", "promote", "demote", "batch-get", "batch-set", "export", "import"];
readonly description: "The cache operation to perform";
};
readonly key: {
readonly type: "string";
readonly description: "Cache key (for get/set/delete/promote/demote operations)";
};
readonly value: {
readonly type: "string";
readonly description: "Value to store (for set operation)";
};
readonly keys: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Array of keys (for batch-get operation)";
};
readonly values: {
readonly type: "array";
readonly items: {
readonly type: "object";
readonly properties: {
readonly key: {
readonly type: "string";
};
readonly value: {
readonly type: "string";
};
readonly ttl: {
readonly type: "number";
};
};
readonly required: readonly ["key", "value"];
};
readonly description: "Array of key-value pairs (for batch-set operation)";
};
readonly evictionStrategy: {
readonly type: "string";
readonly enum: readonly ["LRU", "LFU", "FIFO", "TTL", "SIZE", "HYBRID"];
readonly description: "Eviction strategy (for configure operation)";
};
readonly writeMode: {
readonly type: "string";
readonly enum: readonly ["write-through", "write-back"];
readonly description: "Write mode (for configure operation)";
};
readonly tier: {
readonly type: "string";
readonly enum: readonly ["L1", "L2", "L3"];
readonly description: "Cache tier (for set operation, default: L1)";
};
readonly targetTier: {
readonly type: "string";
readonly enum: readonly ["L1", "L2", "L3"];
readonly description: "Target tier (for promote/demote operations)";
};
readonly ttl: {
readonly type: "number";
readonly description: "Time-to-live in milliseconds";
};
readonly l1MaxSize: {
readonly type: "number";
readonly description: "Maximum L1 cache size (for configure operation)";
};
readonly l2MaxSize: {
readonly type: "number";
readonly description: "Maximum L2 cache size (for configure operation)";
};
readonly defaultTTL: {
readonly type: "number";
readonly description: "Default TTL in milliseconds (for configure operation)";
};
readonly exportDelta: {
readonly type: "boolean";
readonly description: "Export only changes since last snapshot (for export operation)";
};
readonly importData: {
readonly type: "string";
readonly description: "JSON data to import (for import operation)";
};
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 runSmartCache(options: SmartCacheOptions, cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): Promise<SmartCacheResult>;
//# sourceMappingURL=smart-cache.d.ts.map