@claudetools/tools 0.8.2 → 0.8.4

package/dist/context/importance-scorer.js

@@ -0,0 +1,187 @@
+// =============================================================================
+// ClaudeTools Memory - Importance Scorer
+// =============================================================================
+// Dynamic importance scoring for automatic context management with decay
+//
+// Algorithm:
+// - Base importance (critical: 1.0, high: 0.7, normal: 0.4)
+// - Exponential time decay (half-life: 30 minutes)
+// - Reference boost (recently-referenced facts stay longer)
+// - Recency boost (newer injections weighted higher)
+//
+// Score range: 0.0 to 1.0
+// =============================================================================
+// -----------------------------------------------------------------------------
+// Configuration
+// -----------------------------------------------------------------------------
+const SCORING_CONFIG = {
+    // Base importance weights
+    BASE_IMPORTANCE: {
+        critical: 1.0,
+        high: 0.7,
+        normal: 0.4,
+    },
+    // Time decay settings
+    TIME_DECAY_HALF_LIFE_MINUTES: 30,
+    // Reference boost settings
+    REFERENCE_BOOST_DECAY_MINUTES: 10, // 10 minutes = 600,000ms
+    REFERENCE_BOOST_MIN: 0.3,
+    // Component weights (must sum to 1.0)
+    WEIGHTS: {
+        baseWithDecay: 0.5,
+        referenceBoost: 0.3,
+        recencyBoost: 0.2,
+    },
+};
+// -----------------------------------------------------------------------------
+// Importance Scorer
+// -----------------------------------------------------------------------------
+export class ImportanceScorer {
+    /**
+     * Calculate dynamic importance score for a single fact
+     *
+     * @param fact - The injected fact to score
+     * @param session - Current session state
+     * @returns Importance score between 0.0 and 1.0
+     */
+    calculateImportance(fact, session) {
+        const scored = this.calculateWithBreakdown(fact, session);
+        return scored.score;
+    }
+    /**
+     * Calculate importance with component breakdown for debugging
+     *
+     * @param fact - The injected fact to score
+     * @param session - Current session state
+     * @returns Scored fact with breakdown
+     */
+    calculateWithBreakdown(fact, session) {
+        const now = Date.now();
+        // 1. Base importance from metadata
+        const importance = this.extractImportanceLevel(fact);
+        const baseImportance = SCORING_CONFIG.BASE_IMPORTANCE[importance];
+        // 2. Time decay (exponential with half-life)
+        const minutesSinceInjection = (now - fact.injected_at.getTime()) / 60000;
+        const timeDecay = Math.exp((-0.693 * minutesSinceInjection) /
+            SCORING_CONFIG.TIME_DECAY_HALF_LIFE_MINUTES);
+        // 3. Reference boost (facts that were recently referenced stay longer)
+        const referenceBoost = this.calculateReferenceBoost(fact, now);
+        // 4. Recency of injection (newer facts weighted higher in session)
+        const recencyBoost = this.calculateRecencyBoost(fact, session, now);
+        // Combine components with weights
+        const score = baseImportance * timeDecay * SCORING_CONFIG.WEIGHTS.baseWithDecay +
+            referenceBoost * SCORING_CONFIG.WEIGHTS.referenceBoost +
+            recencyBoost * SCORING_CONFIG.WEIGHTS.recencyBoost;
+        return {
+            fact,
+            score: Math.max(0, Math.min(1, score)), // Clamp to [0, 1]
+            breakdown: {
+                base: baseImportance,
+                timeDecay,
+                referenceBoost,
+                recencyBoost,
+            },
+        };
+    }
+    /**
+     * Score all facts in a session
+     *
+     * @param session - Session state with injected facts
+     * @returns Array of scored facts sorted by score (descending)
+     */
+    scoreAllFacts(session) {
+        return session.injected_facts
+            .map((fact) => this.calculateWithBreakdown(fact, session))
+            .sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Get facts that should be evicted (lowest importance scores)
+     *
+     * @param session - Session state
+     * @param count - Number of facts to evict
+     * @returns Facts to evict (lowest scores first)
+     */
+    getEvictionCandidates(session, count) {
+        const scored = this.scoreAllFacts(session);
+        return scored
+            .slice(-count) // Take last N (lowest scores)
+            .map((s) => s.fact);
+    }
+    /**
+     * Get facts above a minimum importance threshold
+     *
+     * @param session - Session state
+     * @param minScore - Minimum score threshold (0.0 to 1.0)
+     * @returns Facts above threshold
+     */
+    getFactsAboveThreshold(session, minScore) {
+        const scored = this.scoreAllFacts(session);
+        return scored.filter((s) => s.score >= minScore).map((s) => s.fact);
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Extract importance level from fact metadata
+     */
+    extractImportanceLevel(fact) {
+        const metadata = fact.metadata;
+        if (!metadata) {
+            return 'normal';
+        }
+        // Check explicit importance flags
+        if (metadata.critical)
+            return 'critical';
+        if (metadata.important)
+            return 'high';
+        // Check category-based importance
+        if (metadata.category === 'architecture')
+            return 'critical';
+        if (metadata.category === 'pattern')
+            return 'high';
+        if (metadata.category === 'decision')
+            return 'high';
+        return 'normal';
+    }
+    /**
+     * Calculate reference boost
+     * Recently-referenced facts get a boost to stay in context longer
+     */
+    calculateReferenceBoost(fact, now) {
+        if (!fact.last_referenced) {
+            return 0;
+        }
+        const minutesSinceReference = (now - fact.last_referenced.getTime()) / 60000;
+        const decayMs = SCORING_CONFIG.REFERENCE_BOOST_DECAY_MINUTES * 60000;
+        const timeSinceReference = now - fact.last_referenced.getTime();
+        // Linear decay from 1.0 to min over decay period
+        const boost = Math.max(SCORING_CONFIG.REFERENCE_BOOST_MIN, 1 - timeSinceReference / decayMs);
+        return boost;
+    }
+    /**
+     * Calculate recency boost
+     * Newer injections in the session get a boost
+     */
+    calculateRecencyBoost(fact, session, now) {
+        const sessionDuration = now - session.started_at.getTime();
+        if (sessionDuration <= 0) {
+            return 1; // Session just started, all facts are equally recent
+        }
+        const factAge = now - fact.injected_at.getTime();
+        const recency = 1 - factAge / sessionDuration;
+        return Math.max(0, Math.min(1, recency)); // Clamp to [0, 1]
+    }
+}
+// -----------------------------------------------------------------------------
+// Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create a new importance scorer instance
+ */
+export function createImportanceScorer() {
+    return new ImportanceScorer();
+}
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
+// Types are exported inline above via 'export interface' and 'export type'

package/dist/context/index.d.ts

@@ -0,0 +1,9 @@
+export { UsageEstimator, usageEstimator, estimateTokens, isContextNearLimit, getContextFill, MODEL_CONTEXT_LIMITS, DEFAULT_MODEL_LIMIT, type TokenUsage, type UsageSnapshot, } from './usage-estimator.js';
+export { ImportanceScorer, createImportanceScorer, type InjectedFact, type SessionState, type ScoredImportance, type ImportanceLevel, } from './importance-scorer.js';
+export { SessionStore, getSessionStore, closeSessionStore, CONTEXT_LIMITS, type ModelType, type Exchange, type PersistedSessionState, } from './session-store.js';
+export { type DeduplicationTracker, InMemoryDeduplicationTracker, createDeduplicationTracker, } from './deduplication.js';
+export { EvictionEngine, createEvictionEngine, type EvictionResult, type EvictionPlan, } from './eviction-engine.js';
+export { HealthMonitor, createHealthMonitor, getHealthMonitor, resetHealthMonitor, type HealthStatus, type DriftRecord, } from './health-monitor.js';
+export { ExchangeSummariser, createExchangeSummariser, type SessionStateWithExchanges, type SummarisationResult, type AIEnvironment, } from './exchange-summariser.js';
+export { EmergencyEviction, createEmergencyEviction, type EmergencyResult, type EmergencyConfig, } from './emergency-eviction.js';
+export { getSessionStateJSON, } from './session-helper.js';

package/dist/context/index.js

@@ -0,0 +1,16 @@
+// =============================================================================
+// Context Module Exports
+// =============================================================================
+//
+// Automatic context management, token usage tracking, and injection control.
+//
+// =============================================================================
+export { UsageEstimator, usageEstimator, estimateTokens, isContextNearLimit, getContextFill, MODEL_CONTEXT_LIMITS, DEFAULT_MODEL_LIMIT, } from './usage-estimator.js';
+export { ImportanceScorer, createImportanceScorer, } from './importance-scorer.js';
+export { SessionStore, getSessionStore, closeSessionStore, CONTEXT_LIMITS, } from './session-store.js';
+export { InMemoryDeduplicationTracker, createDeduplicationTracker, } from './deduplication.js';
+export { EvictionEngine, createEvictionEngine, } from './eviction-engine.js';
+export { HealthMonitor, createHealthMonitor, getHealthMonitor, resetHealthMonitor, } from './health-monitor.js';
+export { ExchangeSummariser, createExchangeSummariser, } from './exchange-summariser.js';
+export { EmergencyEviction, createEmergencyEviction, } from './emergency-eviction.js';
+export { getSessionStateJSON, } from './session-helper.js';

package/dist/context/session-helper.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get current session state for injection budget calculation
+ *
+ * Returns JSON with estimated_fill and context_limit for the current session.
+ * If no session found or error occurs, returns empty object for graceful degradation.
+ *
+ * Usage from bash:
+ *   SESSION_STATE=$(node -e "import('./session-helper.js').then(m => m.getSessionStateJSON('$SESSION_ID'))")
+ */
+export declare function getSessionStateJSON(sessionId: string): Promise<void>;

package/dist/context/session-helper.js

@@ -0,0 +1,51 @@
+// =============================================================================
+// Session Helper - Bridge between hooks and SessionStore
+// =============================================================================
+// Provides a simple CLI interface for bash hooks to query session state
+// =============================================================================
+import { getSessionStore } from './session-store.js';
+import { mcpLogger } from '../logger.js';
+/**
+ * Get current session state for injection budget calculation
+ *
+ * Returns JSON with estimated_fill and context_limit for the current session.
+ * If no session found or error occurs, returns empty object for graceful degradation.
+ *
+ * Usage from bash:
+ *   SESSION_STATE=$(node -e "import('./session-helper.js').then(m => m.getSessionStateJSON('$SESSION_ID'))")
+ */
+export async function getSessionStateJSON(sessionId) {
+    try {
+        const store = getSessionStore();
+        const session = await store.getSession(sessionId);
+        if (!session) {
+            // No session found - return empty object for graceful degradation
+            console.log('{}');
+            return;
+        }
+        // Return minimal state needed for budget calculation
+        const state = {
+            estimated_fill: session.estimated_fill,
+            context_limit: session.context_limit,
+        };
+        console.log(JSON.stringify(state));
+    }
+    catch (error) {
+        // Error occurred - log for debugging but return empty for graceful degradation
+        mcpLogger.error('SESSION_HELPER', `Failed to get session state: ${error}`);
+        console.log('{}');
+    }
+}
+// CLI entry point
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const sessionId = process.argv[2];
+    if (!sessionId) {
+        console.error('Usage: session-helper.ts <session_id>');
+        process.exit(1);
+    }
+    getSessionStateJSON(sessionId).catch((error) => {
+        mcpLogger.error('SESSION_HELPER', `Error: ${error}`);
+        console.log('{}');
+        process.exit(0); // Exit 0 for graceful degradation
+    });
+}

package/dist/context/session-store.d.ts

@@ -0,0 +1,94 @@
+import type { InjectedFact } from './importance-scorer.js';
+/**
+ * Model types supported by Claude Code
+ */
+export type ModelType = 'sonnet' | 'opus' | 'haiku';
+/**
+ * Context window limits by model (in tokens)
+ */
+export declare const CONTEXT_LIMITS: Record<ModelType, number>;
+/**
+ * An exchange (turn) in the conversation
+ */
+export interface Exchange {
+    turn: number;
+    user_tokens: number;
+    assistant_tokens: number;
+    tool_tokens: number;
+    summarised_at: Date | null;
+}
+/**
+ * Complete session state for persistence
+ * Extends the in-memory SessionState with additional persistence fields
+ */
+export interface PersistedSessionState {
+    session_id: string;
+    started_at: Date;
+    model: ModelType;
+    context_limit: number;
+    injected_facts: InjectedFact[];
+    exchanges: Exchange[];
+    estimated_fill: number;
+    last_updated: Date;
+}
+export declare class SessionStore {
+    private db;
+    private dbPath;
+    constructor(dbPath?: string);
+    /**
+     * Create tables if they don't exist
+     */
+    private initializeSchema;
+    /**
+     * Create a new session
+     */
+    createSession(sessionId: string, model: ModelType): Promise<PersistedSessionState>;
+    /**
+     * Get session state by ID
+     */
+    getSession(sessionId: string): Promise<PersistedSessionState | null>;
+    /**
+     * Update session state
+     */
+    updateSession(sessionId: string, updates: Partial<Pick<PersistedSessionState, 'estimated_fill'>>): Promise<void>;
+    /**
+     * Add an injected fact to the session
+     */
+    addInjectedFact(sessionId: string, fact: InjectedFact): Promise<void>;
+    /**
+     * Add an exchange to the session
+     */
+    addExchange(sessionId: string, exchange: Exchange): Promise<void>;
+    /**
+     * Update last_referenced for a fact
+     */
+    updateFactReference(sessionId: string, edgeId: string): Promise<void>;
+    /**
+     * Mark an exchange as summarised
+     */
+    markExchangeSummarised(sessionId: string, turn: number): Promise<void>;
+    /**
+     * Delete a session and all its data
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * List all active sessions
+     */
+    listSessions(): Promise<Array<Pick<PersistedSessionState, 'session_id' | 'started_at' | 'model' | 'last_updated'>>>;
+    /**
+     * Clean up old sessions (older than N days)
+     */
+    cleanupOldSessions(daysOld?: number): Promise<number>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+}
+/**
+ * Get or create the singleton session store instance
+ */
+export declare function getSessionStore(): SessionStore;
+/**
+ * Close the singleton instance (for cleanup)
+ */
+export declare function closeSessionStore(): void;

package/dist/context/session-store.js

@@ -0,0 +1,286 @@
+// =============================================================================
+// Session State Store - Local SQLite storage for context management
+// =============================================================================
+// Stores session state including injected facts, exchanges, and token estimates
+// for automatic context window management in Claude Code sessions.
+// =============================================================================
+import Database from 'better-sqlite3';
+import { mcpLogger } from '../logger.js';
+import * as path from 'path';
+import * as fs from 'fs';
+import { getConfigDir } from '../helpers/config-manager.js';
+/**
+ * Context window limits by model (in tokens)
+ */
+export const CONTEXT_LIMITS = {
+    sonnet: 200_000,
+    opus: 200_000,
+    haiku: 200_000,
+};
+// -----------------------------------------------------------------------------
+// Session Store Implementation
+// -----------------------------------------------------------------------------
+export class SessionStore {
+    db;
+    dbPath;
+    constructor(dbPath) {
+        // Default to ~/.claudetools/sessions.db
+        this.dbPath = dbPath || path.join(getConfigDir(), 'sessions.db');
+        // Ensure directory exists
+        const dir = path.dirname(this.dbPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Open database
+        this.db = new Database(this.dbPath);
+        this.db.pragma('journal_mode = WAL'); // Better concurrency
+        this.db.pragma('foreign_keys = ON');
+        // Initialize schema
+        this.initializeSchema();
+    }
+    /**
+     * Create tables if they don't exist
+     */
+    initializeSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id TEXT PRIMARY KEY,
+        started_at TEXT NOT NULL,
+        model TEXT NOT NULL CHECK(model IN ('sonnet', 'opus', 'haiku')),
+        context_limit INTEGER NOT NULL,
+        estimated_fill REAL NOT NULL DEFAULT 0,
+        last_updated TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS injected_facts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        fact_data TEXT NOT NULL,
+        injected_at TEXT NOT NULL,
+        last_referenced TEXT,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE IF NOT EXISTS exchanges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        turn INTEGER NOT NULL,
+        user_tokens INTEGER NOT NULL,
+        assistant_tokens INTEGER NOT NULL,
+        tool_tokens INTEGER NOT NULL,
+        summarised_at TEXT,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+      );
+
+      -- Indexes for performance
+      CREATE INDEX IF NOT EXISTS idx_injected_facts_session
+        ON injected_facts(session_id);
+      CREATE INDEX IF NOT EXISTS idx_exchanges_session
+        ON exchanges(session_id);
+      CREATE INDEX IF NOT EXISTS idx_exchanges_turn
+        ON exchanges(session_id, turn);
+    `);
+        mcpLogger.debug('MEMORY', `Initialized session database at ${this.dbPath}`);
+    }
+    /**
+     * Create a new session
+     */
+    async createSession(sessionId, model) {
+        const now = new Date().toISOString();
+        const contextLimit = CONTEXT_LIMITS[model];
+        const stmt = this.db.prepare(`
+      INSERT INTO sessions (session_id, started_at, model, context_limit, estimated_fill, last_updated)
+      VALUES (?, ?, ?, ?, 0, ?)
+    `);
+        stmt.run(sessionId, now, model, contextLimit, now);
+        mcpLogger.debug('MEMORY', `Created session ${sessionId} for model ${model}`);
+        return {
+            session_id: sessionId,
+            started_at: new Date(now),
+            model,
+            context_limit: contextLimit,
+            injected_facts: [],
+            exchanges: [],
+            estimated_fill: 0,
+            last_updated: new Date(now),
+        };
+    }
+    /**
+     * Get session state by ID
+     */
+    async getSession(sessionId) {
+        const session = this.db
+            .prepare('SELECT * FROM sessions WHERE session_id = ?')
+            .get(sessionId);
+        if (!session) {
+            return null;
+        }
+        // Load injected facts
+        const factRows = this.db
+            .prepare('SELECT * FROM injected_facts WHERE session_id = ? ORDER BY injected_at')
+            .all(sessionId);
+        // Load exchanges
+        const exchanges = this.db
+            .prepare('SELECT * FROM exchanges WHERE session_id = ? ORDER BY turn')
+            .all(sessionId);
+        // Parse fact data from JSON
+        const facts = factRows.map((row) => {
+            const fact = JSON.parse(row.fact_data);
+            return {
+                ...fact,
+                injected_at: new Date(row.injected_at),
+                last_referenced: row.last_referenced ? new Date(row.last_referenced) : undefined,
+            };
+        });
+        return {
+            session_id: session.session_id,
+            started_at: new Date(session.started_at),
+            model: session.model,
+            context_limit: session.context_limit,
+            injected_facts: facts,
+            exchanges: exchanges.map((e) => ({
+                turn: e.turn,
+                user_tokens: e.user_tokens,
+                assistant_tokens: e.assistant_tokens,
+                tool_tokens: e.tool_tokens,
+                summarised_at: e.summarised_at ? new Date(e.summarised_at) : null,
+            })),
+            estimated_fill: session.estimated_fill,
+            last_updated: new Date(session.last_updated),
+        };
+    }
+    /**
+     * Update session state
+     */
+    async updateSession(sessionId, updates) {
+        const now = new Date().toISOString();
+        const fields = ['last_updated = ?'];
+        const values = [now];
+        if (updates.estimated_fill !== undefined) {
+            fields.push('estimated_fill = ?');
+            values.push(updates.estimated_fill);
+        }
+        values.push(sessionId);
+        const stmt = this.db.prepare(`
+      UPDATE sessions
+      SET ${fields.join(', ')}
+      WHERE session_id = ?
+    `);
+        stmt.run(...values);
+        mcpLogger.debug('MEMORY', `Updated session ${sessionId}`);
+    }
+    /**
+     * Add an injected fact to the session
+     */
+    async addInjectedFact(sessionId, fact) {
+        // Store the fact as JSON, excluding the temporal fields we track separately
+        const { injected_at, last_referenced, ...factData } = fact;
+        const stmt = this.db.prepare(`
+      INSERT INTO injected_facts (session_id, fact_data, injected_at, last_referenced)
+      VALUES (?, ?, ?, ?)
+    `);
+        stmt.run(sessionId, JSON.stringify(factData), injected_at.toISOString(), last_referenced ? last_referenced.toISOString() : null);
+        mcpLogger.debug('MEMORY', `Added fact ${fact.edge_id} to session ${sessionId}`);
+    }
+    /**
+     * Add an exchange to the session
+     */
+    async addExchange(sessionId, exchange) {
+        const stmt = this.db.prepare(`
+      INSERT INTO exchanges (session_id, turn, user_tokens, assistant_tokens, tool_tokens, summarised_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(sessionId, exchange.turn, exchange.user_tokens, exchange.assistant_tokens, exchange.tool_tokens, exchange.summarised_at ? exchange.summarised_at.toISOString() : null);
+        mcpLogger.debug('MEMORY', `Added exchange turn ${exchange.turn} to session ${sessionId}`);
+    }
+    /**
+     * Update last_referenced for a fact
+     */
+    async updateFactReference(sessionId, edgeId) {
+        const now = new Date().toISOString();
+        // Need to find the fact by parsing JSON - SQLite JSON functions
+        const stmt = this.db.prepare(`
+      UPDATE injected_facts
+      SET last_referenced = ?
+      WHERE session_id = ? AND json_extract(fact_data, '$.edge_id') = ?
+    `);
+        stmt.run(now, sessionId, edgeId);
+    }
+    /**
+     * Mark an exchange as summarised
+     */
+    async markExchangeSummarised(sessionId, turn) {
+        const now = new Date().toISOString();
+        const stmt = this.db.prepare(`
+      UPDATE exchanges
+      SET summarised_at = ?
+      WHERE session_id = ? AND turn = ?
+    `);
+        stmt.run(now, sessionId, turn);
+    }
+    /**
+     * Delete a session and all its data
+     */
+    async deleteSession(sessionId) {
+        const stmt = this.db.prepare('DELETE FROM sessions WHERE session_id = ?');
+        stmt.run(sessionId);
+        mcpLogger.debug('MEMORY', `Deleted session ${sessionId}`);
+    }
+    /**
+     * List all active sessions
+     */
+    async listSessions() {
+        const sessions = this.db
+            .prepare('SELECT session_id, started_at, model, last_updated FROM sessions ORDER BY started_at DESC')
+            .all();
+        return sessions.map((s) => ({
+            session_id: s.session_id,
+            started_at: new Date(s.started_at),
+            model: s.model,
+            last_updated: new Date(s.last_updated),
+        }));
+    }
+    /**
+     * Clean up old sessions (older than N days)
+     */
+    async cleanupOldSessions(daysOld = 7) {
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - daysOld);
+        const stmt = this.db.prepare(`
+      DELETE FROM sessions
+      WHERE started_at < ?
+    `);
+        const result = stmt.run(cutoffDate.toISOString());
+        mcpLogger.info('MEMORY', `Cleaned up ${result.changes} sessions older than ${daysOld} days`);
+        return result.changes;
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        this.db.close();
+        mcpLogger.debug('MEMORY', 'Closed session database connection');
+    }
+}
+// -----------------------------------------------------------------------------
+// Singleton Instance
+// -----------------------------------------------------------------------------
+let storeInstance = null;
+/**
+ * Get or create the singleton session store instance
+ */
+export function getSessionStore() {
+    if (!storeInstance) {
+        storeInstance = new SessionStore();
+    }
+    return storeInstance;
+}
+/**
+ * Close the singleton instance (for cleanup)
+ */
+export function closeSessionStore() {
+    if (storeInstance) {
+        storeInstance.close();
+        storeInstance = null;
+    }
+}