@claudetools/tools 0.8.2 → 0.8.4

package/dist/context/emergency-eviction.js

@@ -0,0 +1,226 @@
+// =============================================================================
+// Emergency Context Eviction
+// =============================================================================
+// Triggered at 70% context fill - aggressive context reduction protocol
+//
+// Emergency Protocol:
+// 1. Immediately summarise last 5 exchanges (if not already summarised)
+// 2. Evict ALL normal importance facts
+// 3. If still > 65%, compress critical facts to essential summaries
+// 4. Log warning to user about context pressure
+// 5. Return to safe fill level (< 50%)
+//
+// This is the last-resort mechanism before context overflow.
+// =============================================================================
+import { ImportanceScorer } from './importance-scorer.js';
+import { mcpLogger } from '../logger.js';
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    emergencyThreshold: 0.70,
+    targetFill: 0.50,
+    criticalCompressionThreshold: 0.65,
+};
+// Emergency thresholds for importance levels
+const IMPORTANCE_THRESHOLDS = {
+    critical: 1.0, // Critical facts have base importance 1.0
+    high: 0.7, // High importance facts have base 0.7
+    normal: 0.4, // Normal importance facts have base 0.4
+};
+// -----------------------------------------------------------------------------
+// Emergency Eviction Engine
+// -----------------------------------------------------------------------------
+export class EmergencyEviction {
+    config;
+    scorer;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.scorer = new ImportanceScorer();
+    }
+    /**
+     * Check if session is in emergency state
+     */
+    isEmergency(session) {
+        return session.estimated_fill >= this.config.emergencyThreshold;
+    }
+    /**
+     * Run emergency eviction protocol
+     *
+     * Steps:
+     * 1. Summarise recent exchanges
+     * 2. Evict normal importance facts
+     * 3. If still critical, compress high importance facts
+     * 4. If still critical, compress critical facts (last resort)
+     *
+     * @param session - Current session state
+     * @returns Emergency result with actions taken
+     */
+    async runEmergencyEviction(session) {
+        const actionsToken = [];
+        let evictedCount = 0;
+        let summarisedExchanges = 0;
+        let compressedCritical = 0;
+        let currentFill = session.estimated_fill;
+        // Check if emergency
+        if (!this.isEmergency(session)) {
+            return {
+                wasEmergency: false,
+                actionsToken: ['No emergency - fill below threshold'],
+                evictedCount: 0,
+                summarisedExchanges: 0,
+                compressedCritical: 0,
+                newEstimatedFill: currentFill,
+                userWarning: '',
+            };
+        }
+        mcpLogger.warn('MEMORY', `🚨 EMERGENCY EVICTION: Context at ${(currentFill * 100).toFixed(1)}%`);
+        // Step 1: Summarise recent exchanges (if not already summarised)
+        const unsummarisedCount = this.getUnsummarisedExchangeCount(session);
+        if (unsummarisedCount > 0) {
+            const toSummarise = Math.min(5, unsummarisedCount);
+            summarisedExchanges = toSummarise;
+            // Note: Actual summarisation happens via ExchangeSummariser
+            // Here we just track what WOULD be summarised
+            actionsToken.push(`Summarised ${toSummarise} exchanges`);
+            // Estimate token savings from summarisation (rough: 70% reduction)
+            const savedTokens = this.estimateExchangeTokens(session, toSummarise) * 0.7;
+            currentFill = this.recalculateFill(session, currentFill, -savedTokens);
+            mcpLogger.info('MEMORY', `Summarised ${toSummarise} exchanges, new fill: ${(currentFill * 100).toFixed(1)}%`);
+        }
+        // Step 2: Evict ALL normal importance facts
+        if (currentFill > this.config.targetFill) {
+            const normalFacts = this.getFactsByImportance(session, 'normal');
+            evictedCount += normalFacts.length;
+            if (normalFacts.length > 0) {
+                actionsToken.push(`Evicted ${normalFacts.length} normal importance facts`);
+                const savedTokens = this.estimateFactTokens(normalFacts);
+                currentFill = this.recalculateFill(session, currentFill, -savedTokens);
+                mcpLogger.info('MEMORY', `Evicted ${normalFacts.length} normal facts, new fill: ${(currentFill * 100).toFixed(1)}%`);
+            }
+        }
+        // Step 3: If still critical, evict high importance facts
+        if (currentFill > this.config.criticalCompressionThreshold) {
+            const highFacts = this.getFactsByImportance(session, 'high');
+            evictedCount += highFacts.length;
+            if (highFacts.length > 0) {
+                actionsToken.push(`Evicted ${highFacts.length} high importance facts`);
+                const savedTokens = this.estimateFactTokens(highFacts);
+                currentFill = this.recalculateFill(session, currentFill, -savedTokens);
+                mcpLogger.warn('MEMORY', `⚠️  Evicted ${highFacts.length} high importance facts, new fill: ${(currentFill * 100).toFixed(1)}%`);
+            }
+        }
+        // Step 4: Last resort - compress critical facts
+        if (currentFill > this.config.criticalCompressionThreshold) {
+            const criticalFacts = this.getFactsByImportance(session, 'critical');
+            if (criticalFacts.length > 0) {
+                // Compress to essential summaries (keep 30% of tokens)
+                compressedCritical = criticalFacts.length;
+                actionsToken.push(`Compressed ${criticalFacts.length} critical facts to summaries`);
+                const originalTokens = this.estimateFactTokens(criticalFacts);
+                const savedTokens = originalTokens * 0.7; // Save 70% via compression
+                currentFill = this.recalculateFill(session, currentFill, -savedTokens);
+                mcpLogger.error('MEMORY', `🔥 CRITICAL: Compressed ${criticalFacts.length} critical facts, new fill: ${(currentFill * 100).toFixed(1)}%`);
+            }
+        }
+        // Generate user warning
+        const userWarning = this.generateUserWarning(session.estimated_fill, currentFill, evictedCount, summarisedExchanges, compressedCritical);
+        return {
+            wasEmergency: true,
+            actionsToken,
+            evictedCount,
+            summarisedExchanges,
+            compressedCritical,
+            newEstimatedFill: currentFill,
+            userWarning,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Get facts by importance level
+     */
+    getFactsByImportance(session, level) {
+        const threshold = IMPORTANCE_THRESHOLDS[level];
+        return session.injected_facts.filter((fact) => {
+            const scored = this.scorer.calculateWithBreakdown(fact, session);
+            // Match facts at this exact importance tier
+            if (level === 'normal') {
+                return scored.breakdown.base === IMPORTANCE_THRESHOLDS.normal;
+            }
+            else if (level === 'high') {
+                return scored.breakdown.base === IMPORTANCE_THRESHOLDS.high;
+            }
+            else {
+                return scored.breakdown.base === IMPORTANCE_THRESHOLDS.critical;
+            }
+        });
+    }
+    /**
+     * Get count of unsummarised exchanges
+     */
+    getUnsummarisedExchangeCount(session) {
+        return session.exchanges.filter((e) => !e.summarised_at).length;
+    }
+    /**
+     * Estimate tokens for a set of exchanges
+     */
+    estimateExchangeTokens(session, count) {
+        // Get last N unsummarised exchanges
+        const unsummarised = session.exchanges
+            .filter((e) => !e.summarised_at)
+            .slice(-count);
+        return unsummarised.reduce((sum, e) => sum + e.user_tokens + e.assistant_tokens + e.tool_tokens, 0);
+    }
+    /**
+     * Estimate tokens for a set of facts
+     * More realistic estimate: ~500 tokens per fact average
+     * (includes context, entities, relationships, metadata)
+     */
+    estimateFactTokens(facts) {
+        // TODO: Use actual token estimation when available
+        return facts.length * 500;
+    }
+    /**
+     * Recalculate fill percentage after token change
+     */
+    recalculateFill(session, currentFill, tokenDelta) {
+        const currentTokens = currentFill * session.context_limit;
+        const newTokens = Math.max(0, currentTokens + tokenDelta);
+        return newTokens / session.context_limit;
+    }
+    /**
+     * Generate user-facing warning message
+     */
+    generateUserWarning(originalFill, newFill, evictedCount, summarisedExchanges, compressedCritical) {
+        const parts = [];
+        parts.push(`Context pressure high (${(originalFill * 100).toFixed(1)}% → ${(newFill * 100).toFixed(1)}%).`);
+        if (summarisedExchanges > 0) {
+            parts.push(`Summarised ${summarisedExchanges} exchanges.`);
+        }
+        if (evictedCount > 0) {
+            parts.push(`Evicted ${evictedCount} facts.`);
+        }
+        if (compressedCritical > 0) {
+            parts.push(`⚠️  CRITICAL: Compressed ${compressedCritical} important facts to summaries.`);
+        }
+        if (newFill > 0.6) {
+            parts.push('Context still high - consider ending session soon.');
+        }
+        return parts.join(' ');
+    }
+}
+// -----------------------------------------------------------------------------
+// Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create emergency eviction instance with optional config
+ */
+export function createEmergencyEviction(config) {
+    return new EmergencyEviction(config);
+}
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
+// Types are exported inline above via 'export interface'

package/dist/context/eviction-engine.d.ts

@@ -0,0 +1,76 @@
+import { ImportanceScorer, type InjectedFact } from './importance-scorer.js';
+import type { PersistedSessionState } from './session-store.js';
+/**
+ * Result of an eviction operation
+ */
+export interface EvictionResult {
+    evictedCount: number;
+    evictedFacts: InjectedFact[];
+    newEstimatedFill: number;
+    summaryGenerated?: string;
+}
+/**
+ * Plan for eviction before execution
+ */
+export interface EvictionPlan {
+    factsToEvict: Array<{
+        fact: InjectedFact;
+        score: number;
+    }>;
+    expectedFillAfter: number;
+    includesCritical: boolean;
+}
+export declare class EvictionEngine {
+    private scorer;
+    constructor(scorer?: ImportanceScorer);
+    /**
+     * Check if eviction should be triggered
+     *
+     * @param session - Current session state
+     * @returns True if eviction is needed
+     */
+    shouldEvict(session: PersistedSessionState): boolean;
+    /**
+     * Get an eviction plan without executing it
+     * Useful for preview/confirmation before eviction
+     *
+     * @param session - Current session state
+     * @returns Eviction plan with facts to evict and expected results
+     */
+    getEvictionPlan(session: PersistedSessionState): EvictionPlan;
+    /**
+     * Execute eviction on a session
+     * Removes lowest-scored facts to reduce estimated fill
+     *
+     * @param session - Current session state
+     * @returns Eviction result with details of what was evicted
+     */
+    runEviction(session: PersistedSessionState): Promise<EvictionResult>;
+    /**
+     * Get eviction statistics for a session
+     * Useful for monitoring and debugging
+     *
+     * @param session - Current session state
+     * @returns Statistics about eviction potential
+     */
+    getEvictionStats(session: PersistedSessionState): {
+        currentFill: number;
+        shouldEvict: boolean;
+        criticalFactCount: number;
+        normalFactCount: number;
+        averageScore: number;
+        lowestScore: number;
+        highestScore: number;
+    };
+    /**
+     * Check if a fact is marked as critical
+     */
+    private isCritical;
+}
+/**
+ * Create a new eviction engine instance
+ *
+ * @param scorer - Optional importance scorer (creates new one if not provided)
+ * @returns Eviction engine instance
+ */
+export declare function createEvictionEngine(scorer?: ImportanceScorer): EvictionEngine;

package/dist/context/eviction-engine.example.d.ts

@@ -0,0 +1,7 @@
+declare function checkIfEvictionNeeded(sessionId: string): Promise<void>;
+declare function previewEvictionPlan(sessionId: string): Promise<void>;
+declare function executeEviction(sessionId: string): Promise<void>;
+declare function automaticEvictionLoop(sessionId: string): Promise<void>;
+declare function getEvictionStatistics(sessionId: string): Promise<void>;
+declare function sessionLifecycleExample(): Promise<void>;
+export { checkIfEvictionNeeded, previewEvictionPlan, executeEviction, automaticEvictionLoop, getEvictionStatistics, sessionLifecycleExample, };

package/dist/context/eviction-engine.example.js

@@ -0,0 +1,144 @@
+// =============================================================================
+// Eviction Engine Usage Examples
+// =============================================================================
+// This file demonstrates how to use the EvictionEngine for automatic context
+// window management in ClaudeTools Memory.
+// =============================================================================
+import { createEvictionEngine, } from './eviction-engine.js';
+import { getSessionStore } from './session-store.js';
+// -----------------------------------------------------------------------------
+// Example 1: Basic Eviction Check
+// -----------------------------------------------------------------------------
+async function checkIfEvictionNeeded(sessionId) {
+    const store = getSessionStore();
+    const session = await store.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    const engine = createEvictionEngine();
+    // Check if eviction should run
+    if (engine.shouldEvict(session)) {
+        console.log(`⚠️  Eviction needed (fill: ${(session.estimated_fill * 100).toFixed(1)}%)`);
+    }
+    else {
+        console.log(`✓ Context healthy (fill: ${(session.estimated_fill * 100).toFixed(1)}%)`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Example 2: Preview Eviction Plan
+// -----------------------------------------------------------------------------
+async function previewEvictionPlan(sessionId) {
+    const store = getSessionStore();
+    const session = await store.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    const engine = createEvictionEngine();
+    const plan = engine.getEvictionPlan(session);
+    console.log('Eviction Plan:');
+    console.log(`  Facts to evict: ${plan.factsToEvict.length}`);
+    console.log(`  Current fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+    console.log(`  Expected fill after: ${(plan.expectedFillAfter * 100).toFixed(1)}%`);
+    console.log(`  Includes critical facts: ${plan.includesCritical}`);
+    if (plan.factsToEvict.length > 0) {
+        console.log('\nFacts to evict:');
+        plan.factsToEvict.forEach(({ fact, score }, idx) => {
+            console.log(`  ${idx + 1}. ${fact.edge_id} (score: ${score.toFixed(3)})`);
+        });
+    }
+}
+// -----------------------------------------------------------------------------
+// Example 3: Execute Eviction
+// -----------------------------------------------------------------------------
+async function executeEviction(sessionId) {
+    const store = getSessionStore();
+    const session = await store.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    const engine = createEvictionEngine();
+    // Run eviction
+    const result = await engine.runEviction(session);
+    console.log('Eviction completed:');
+    console.log(`  Evicted: ${result.evictedCount} facts`);
+    console.log(`  New fill: ${(result.newEstimatedFill * 100).toFixed(1)}%`);
+    // Update session state (in real usage, you'd persist this)
+    // session.estimated_fill = result.newEstimatedFill;
+    // session.injected_facts = session.injected_facts.filter(
+    //   f => !result.evictedFacts.find(ef => ef.edge_id === f.edge_id)
+    // );
+    // await store.updateSession(sessionId, { estimated_fill: result.newEstimatedFill });
+}
+// -----------------------------------------------------------------------------
+// Example 4: Automatic Eviction Loop
+// -----------------------------------------------------------------------------
+async function automaticEvictionLoop(sessionId) {
+    const store = getSessionStore();
+    const engine = createEvictionEngine();
+    let session = await store.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    console.log(`Starting automatic eviction loop for session ${sessionId}`);
+    // Keep evicting until fill is below threshold
+    while (engine.shouldEvict(session)) {
+        console.log(`\nFill at ${(session.estimated_fill * 100).toFixed(1)}% - evicting...`);
+        const result = await engine.runEviction(session);
+        console.log(`  Evicted ${result.evictedCount} facts`);
+        console.log(`  New fill: ${(result.newEstimatedFill * 100).toFixed(1)}%`);
+        // Update session (in real usage, you'd persist to store)
+        session.estimated_fill = result.newEstimatedFill;
+        session.injected_facts = session.injected_facts.filter((f) => !result.evictedFacts.find((ef) => ef.edge_id === f.edge_id));
+    }
+    console.log('\n✓ Eviction complete - context healthy');
+}
+// -----------------------------------------------------------------------------
+// Example 5: Get Eviction Statistics
+// -----------------------------------------------------------------------------
+async function getEvictionStatistics(sessionId) {
+    const store = getSessionStore();
+    const session = await store.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    const engine = createEvictionEngine();
+    const stats = engine.getEvictionStats(session);
+    console.log('Eviction Statistics:');
+    console.log(`  Current fill: ${(stats.currentFill * 100).toFixed(1)}%`);
+    console.log(`  Should evict: ${stats.shouldEvict ? 'YES' : 'NO'}`);
+    console.log(`  Critical facts: ${stats.criticalFactCount}`);
+    console.log(`  Normal facts: ${stats.normalFactCount}`);
+    console.log(`  Average score: ${stats.averageScore.toFixed(3)}`);
+    console.log(`  Score range: ${stats.lowestScore.toFixed(3)} - ${stats.highestScore.toFixed(3)}`);
+}
+// -----------------------------------------------------------------------------
+// Example 6: Integration with Session Lifecycle
+// -----------------------------------------------------------------------------
+async function sessionLifecycleExample() {
+    const store = getSessionStore();
+    const engine = createEvictionEngine();
+    // Create a new session
+    const session = await store.createSession('example-session', 'sonnet');
+    console.log('Session created:', session.session_id);
+    // Simulate adding facts and tracking fill
+    // ... (facts would be added via store.addInjectedFact)
+    // At each turn, check if eviction is needed
+    if (engine.shouldEvict(session)) {
+        console.log('Running eviction...');
+        const result = await engine.runEviction(session);
+        // Update session state
+        await store.updateSession(session.session_id, {
+            estimated_fill: result.newEstimatedFill,
+        });
+        console.log(`Evicted ${result.evictedCount} facts`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Export examples for testing/demo purposes
+// -----------------------------------------------------------------------------
+export { checkIfEvictionNeeded, previewEvictionPlan, executeEviction, automaticEvictionLoop, getEvictionStatistics, sessionLifecycleExample, };

package/dist/context/eviction-engine.js

@@ -0,0 +1,176 @@
+// =============================================================================
+// ClaudeTools Memory - Eviction Engine
+// =============================================================================
+// Automatic fact eviction for context window management
+//
+// Triggers when estimated_fill > 0.60, targets reduction to < 0.50
+// Evicts lowest-scored facts first, protects critical facts unless fill > 0.85
+// =============================================================================
+import { ImportanceScorer } from './importance-scorer.js';
+import { mcpLogger } from '../logger.js';
+// -----------------------------------------------------------------------------
+// Configuration
+// -----------------------------------------------------------------------------
+const EVICTION_CONFIG = {
+    // Trigger eviction when estimated fill exceeds this threshold
+    TRIGGER_THRESHOLD: 0.60,
+    // Target fill level after eviction
+    TARGET_FILL: 0.50,
+    // Allow evicting critical facts only when fill is above this
+    CRITICAL_EVICTION_THRESHOLD: 0.85,
+    // Minimum number of facts to evict per operation (prevent thrashing)
+    MIN_EVICTION_COUNT: 3,
+};
+// -----------------------------------------------------------------------------
+// Eviction Engine
+// -----------------------------------------------------------------------------
+export class EvictionEngine {
+    scorer;
+    constructor(scorer) {
+        this.scorer = scorer || new ImportanceScorer();
+    }
+    /**
+     * Check if eviction should be triggered
+     *
+     * @param session - Current session state
+     * @returns True if eviction is needed
+     */
+    shouldEvict(session) {
+        return session.estimated_fill > EVICTION_CONFIG.TRIGGER_THRESHOLD;
+    }
+    /**
+     * Get an eviction plan without executing it
+     * Useful for preview/confirmation before eviction
+     *
+     * @param session - Current session state
+     * @returns Eviction plan with facts to evict and expected results
+     */
+    getEvictionPlan(session) {
+        // Calculate how much we need to evict
+        const currentFill = session.estimated_fill;
+        const targetFill = EVICTION_CONFIG.TARGET_FILL;
+        const fillToReduce = currentFill - targetFill;
+        // Score all facts
+        const scoredFacts = this.scorer
+            .scoreAllFacts(session)
+            .sort((a, b) => a.score - b.score); // Lowest scores first
+        // Determine critical eviction threshold
+        const allowCriticalEviction = currentFill > EVICTION_CONFIG.CRITICAL_EVICTION_THRESHOLD;
+        // Filter candidates
+        let candidates = scoredFacts;
+        if (!allowCriticalEviction) {
+            // Exclude critical facts
+            candidates = scoredFacts.filter((sf) => !this.isCritical(sf.fact));
+        }
+        // Calculate number of facts to evict
+        // Assume average fact contributes equally to fill
+        const avgFillPerFact = session.injected_facts.length > 0
+            ? currentFill / session.injected_facts.length
+            : 0.01; // Default small contribution
+        let factsToEvictCount = Math.max(EVICTION_CONFIG.MIN_EVICTION_COUNT, Math.ceil(fillToReduce / avgFillPerFact));
+        // Don't evict more than available candidates
+        factsToEvictCount = Math.min(factsToEvictCount, candidates.length);
+        // Select facts to evict
+        const factsToEvict = candidates
+            .slice(0, factsToEvictCount)
+            .map((sf) => ({
+            fact: sf.fact,
+            score: sf.score,
+        }));
+        // Calculate expected fill after eviction
+        const expectedFillAfter = Math.max(0, currentFill - factsToEvictCount * avgFillPerFact);
+        // Check if plan includes critical facts
+        const includesCritical = factsToEvict.some((f) => this.isCritical(f.fact));
+        return {
+            factsToEvict,
+            expectedFillAfter,
+            includesCritical,
+        };
+    }
+    /**
+     * Execute eviction on a session
+     * Removes lowest-scored facts to reduce estimated fill
+     *
+     * @param session - Current session state
+     * @returns Eviction result with details of what was evicted
+     */
+    async runEviction(session) {
+        const plan = this.getEvictionPlan(session);
+        // Extract facts to evict
+        const evictedFacts = plan.factsToEvict.map((f) => f.fact);
+        // Log eviction operation
+        mcpLogger.info('MEMORY', `Evicting ${evictedFacts.length} facts from session ${session.session_id} (fill: ${(session.estimated_fill * 100).toFixed(1)}% → ${(plan.expectedFillAfter * 100).toFixed(1)}%)`);
+        // Log if critical facts are being evicted
+        if (plan.includesCritical) {
+            mcpLogger.warn('MEMORY', `Eviction includes critical facts (fill > ${EVICTION_CONFIG.CRITICAL_EVICTION_THRESHOLD * 100}%)`);
+        }
+        // Debug: log each evicted fact
+        for (const { fact, score } of plan.factsToEvict) {
+            mcpLogger.debug('MEMORY', `  Evicting: ${fact.edge_id} (score: ${score.toFixed(3)}, critical: ${this.isCritical(fact)})`);
+        }
+        return {
+            evictedCount: evictedFacts.length,
+            evictedFacts,
+            newEstimatedFill: plan.expectedFillAfter,
+            summaryGenerated: undefined, // Future: could generate a summary of evicted context
+        };
+    }
+    /**
+     * Get eviction statistics for a session
+     * Useful for monitoring and debugging
+     *
+     * @param session - Current session state
+     * @returns Statistics about eviction potential
+     */
+    getEvictionStats(session) {
+        const scoredFacts = this.scorer.scoreAllFacts(session);
+        const criticalCount = scoredFacts.filter((sf) => this.isCritical(sf.fact)).length;
+        const scores = scoredFacts.map((sf) => sf.score);
+        const avgScore = scores.length > 0
+            ? scores.reduce((sum, s) => sum + s, 0) / scores.length
+            : 0;
+        return {
+            currentFill: session.estimated_fill,
+            shouldEvict: this.shouldEvict(session),
+            criticalFactCount: criticalCount,
+            normalFactCount: session.injected_facts.length - criticalCount,
+            averageScore: avgScore,
+            lowestScore: scores.length > 0 ? Math.min(...scores) : 0,
+            highestScore: scores.length > 0 ? Math.max(...scores) : 0,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Check if a fact is marked as critical
+     */
+    isCritical(fact) {
+        const metadata = fact.metadata;
+        if (!metadata)
+            return false;
+        // Check explicit critical flag
+        if (metadata.critical)
+            return true;
+        // Check category-based critical status
+        if (metadata.category === 'architecture')
+            return true;
+        return false;
+    }
+}
+// -----------------------------------------------------------------------------
+// Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create a new eviction engine instance
+ *
+ * @param scorer - Optional importance scorer (creates new one if not provided)
+ * @returns Eviction engine instance
+ */
+export function createEvictionEngine(scorer) {
+    return new EvictionEngine(scorer);
+}
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
+// Types are exported inline above via 'export interface'

package/dist/context/example-usage.d.ts

@@ -0,0 +1 @@
+export {};