@ulrichc1/sparn 1.2.2 → 1.4.0

package/dist/index.d.ts

@@ -2,15 +2,15 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
  * Core memory entry types for Sparn's context optimization engine.
- * Maps to neuroscience-inspired memory model with decay and state transitions.
+ * Memory model with time-based decay and state transitions.
  */
 /**
  * Confidence state for memory entries.
- * Based on multi-state synapse model from neuroscience.
+ * Entries are classified as silent, ready, or active based on score.
  */
 type ConfidenceState = 'silent' | 'ready' | 'active';
 /**
- * Represents a single context memory entry with neuroscience-inspired metadata.
+ * Represents a single context memory entry with optimization metadata.
  *
  * State transitions:
  * - score ≤ 0.3 → silent (not included in context)
@@ -66,8 +66,8 @@ interface StateDistribution {
 
 /**
  * KV Memory Store Module
- * Implements hippocampal key-value storage with dual index/value tables.
- * Maps to: Hippocampal Key-Value — the hippocampus separates what to store from how to retrieve it.
+ * Key-value storage with dual index/value tables.
+ * Separates what to store (content) from how to retrieve it (index with scores and state).
  */
 
 /**
@@ -84,6 +84,13 @@ interface OptimizationStats {
 /**
  * KV Memory interface.
  */
+/**
+ * FTS5 search result with rank score.
+ */
+interface FTSResult {
+    entry: MemoryEntry;
+    rank: number;
+}
 interface KVMemory {
     /** Store a memory entry */
     put(entry: MemoryEntry): Promise<void>;
@@ -105,6 +112,8 @@ interface KVMemory {
     getOptimizationStats(): Promise<OptimizationStats[]>;
     /** Clear all optimization statistics */
     clearOptimizationStats(): Promise<void>;
+    /** Full-text search using FTS5 */
+    searchFTS(query: string, limit?: number): Promise<FTSResult[]>;
 }
 /**
  * Create KV Memory store with SQLite backend.
@@ -202,6 +211,10 @@ interface DecayConfig {
     defaultTTL: number;
     /** Decay threshold for pruning (0.0-1.0, default: 0.95) */
     decayThreshold: number;
+    /** Minutes within which entries get a recency boost (default: 30) */
+    recencyBoostMinutes?: number;
+    /** Multiplier for recency boost at age 0 (default: 1.3) */
+    recencyBoostMultiplier?: number;
 }
 /**
  * Confidence state threshold configuration.
@@ -245,6 +258,8 @@ interface RealtimeConfig {
     windowSize: number;
     /** Consolidation interval in hours, or null for disabled (default: null) */
     consolidationInterval: number | null;
+    /** Use precise GPT tokenizer for token counting (default: false) */
+    preciseTokenCounting?: boolean;
 }
 /**
  * Complete Sparn configuration.
@@ -259,6 +274,8 @@ interface SparnConfig {
     autoConsolidate: number | null;
     /** Real-time optimization settings */
     realtime: RealtimeConfig;
+    /** Additional BTSP pattern regex strings (default: []) */
+    btspPatterns?: string[];
 }
 /**
  * Default configuration values.
@@ -283,7 +300,7 @@ declare function createClaudeCodeAdapter(memory: KVMemory, config: SparnConfig):
 /**
  * Generic Adapter - Agent-agnostic optimization pipeline
  *
- * Orchestrates all 6 neuroscience modules to optimize context memory.
+ * Orchestrates all optimization modules to process context memory.
  */
 
 /**
@@ -297,7 +314,6 @@ declare function createGenericAdapter(memory: KVMemory, config: SparnConfig): Ag
 /**
  * BTSP Embedder - Implements behavioral timescale synaptic plasticity
  *
- * Neuroscience: One-shot learning from critical events (errors, conflicts).
  * Application: Detect high-importance patterns and mark for permanent retention.
  */
 
@@ -321,11 +337,15 @@ interface BTSPEmbedder {
  * Create a BTSP embedder instance
  * @returns BTSPEmbedder instance
  */
-declare function createBTSPEmbedder(): BTSPEmbedder;
+interface BTSPEmbedderConfig {
+    /** Additional regex pattern strings to detect BTSP events */
+    customPatterns?: string[];
+}
+declare function createBTSPEmbedder(config?: BTSPEmbedderConfig): BTSPEmbedder;
 
 /**
  * Sparse pruner types.
- * Implements sparse coding principle from neuroscience.
+ * Relevance filtering: keep only the most important entries.
  */
 
 /**
@@ -342,13 +362,64 @@ interface PruneResult {
     prunedTokens: number;
 }
 
+/**
+ * Shared TF-IDF utilities
+ *
+ * Centralized text tokenization and TF-IDF scoring used by
+ * sparse-pruner, budget-pruner, incremental-optimizer, and sleep-compressor.
+ */
+
+/**
+ * Tokenize text into lowercase words
+ */
+declare function tokenize(text: string): string[];
+/**
+ * Calculate term frequency with sqrt capping
+ */
+declare function calculateTF(term: string, tokens: string[]): number;
+/**
+ * Calculate inverse document frequency across entries
+ */
+declare function calculateIDF(term: string, allEntries: MemoryEntry[]): number;
+/**
+ * Calculate TF-IDF score for an entry relative to a corpus
+ */
+declare function calculateTFIDF(entry: MemoryEntry, allEntries: MemoryEntry[]): number;
+/**
+ * Pre-computed TF-IDF index for O(1) document frequency lookups.
+ * Eliminates O(n^2) bottleneck when scoring multiple entries.
+ */
+interface TFIDFIndex {
+    /** Map of term -> number of documents containing the term */
+    documentFrequency: Map<string, number>;
+    /** Total number of documents in the corpus */
+    totalDocuments: number;
+}
+/**
+ * Build a pre-computed TF-IDF index from a set of entries.
+ * Iterates all entries once to build document frequency map.
+ *
+ * @param entries - Corpus of memory entries
+ * @returns Pre-computed index for use with scoreTFIDF()
+ */
+declare function createTFIDFIndex(entries: MemoryEntry[]): TFIDFIndex;
+/**
+ * Score an entry using a pre-computed TF-IDF index.
+ * Uses pre-computed document frequencies instead of re-tokenizing all entries.
+ *
+ * @param entry - Entry to score
+ * @param index - Pre-computed TF-IDF index from createTFIDFIndex()
+ * @returns TF-IDF score (higher = more distinctive)
+ */
+declare function scoreTFIDF(entry: MemoryEntry, index: TFIDFIndex): number;
+
 /**
  * Budget-Aware Pruner - Token budget optimization
  *
  * Unlike SparsePruner which keeps top N% entries, BudgetPruner fits entries
  * within a target token budget using priority scoring that combines:
  * - TF-IDF relevance
- * - Engram decay
+ * - Time-based decay
  * - Confidence state multipliers
  * - BTSP bypass (always included)
  *
@@ -383,9 +454,10 @@ interface BudgetPruner {
      * Calculate priority score for an entry
      * @param entry - Entry to score
      * @param allEntries - All entries for TF-IDF calculation
+     * @param index - Optional pre-computed TF-IDF index
      * @returns Priority score (higher = more important)
      */
-    priorityScore(entry: MemoryEntry, allEntries: MemoryEntry[]): number;
+    priorityScore(entry: MemoryEntry, allEntries: MemoryEntry[], index?: TFIDFIndex): number;
 }
 /**
  * Create a budget-aware pruner instance
@@ -409,10 +481,10 @@ declare function createBudgetPrunerFromConfig(realtimeConfig: RealtimeConfig, de
 }): BudgetPruner;
 
 /**
- * Confidence States - Implements multi-state synapses
+ * Confidence States - Entry classification by score
  *
- * Neuroscience: Synapses exist in three states: silent, ready (potentiated), active.
- * Application: Classify memory entries by score into silent/ready/active states.
+ * Entries exist in three states: silent, ready, active.
+ * Classifies memory entries by score into silent/ready/active states.
  */
 
 interface ConfidenceStatesConfig {
@@ -524,6 +596,17 @@ interface IncrementalOptimizer {
         updateCount: number;
         lastFullOptimization: number;
     };
+    /**
+     * Serialize optimizer state to JSON string for persistence
+     * @returns JSON string of the state
+     */
+    serializeState(): string;
+    /**
+     * Deserialize optimizer state from JSON string
+     * @param json - JSON string to restore from
+     * @returns true if successful, false on error
+     */
+    deserializeState(json: string): boolean;
 }
 /**
  * Create an incremental optimizer instance
@@ -566,6 +649,17 @@ interface ContextPipelineStats {
     };
 }
 interface ContextPipeline {
+    /**
+     * Serialize optimizer state for persistence
+     * @returns JSON string of the optimizer state
+     */
+    serializeOptimizerState(): string;
+    /**
+     * Restore optimizer state from persistence
+     * @param json - JSON string to restore from
+     * @returns true if successful
+     */
+    deserializeOptimizerState(json: string): boolean;
     /**
      * Ingest new content into the pipeline
      * @param content - Raw content string
@@ -601,10 +695,153 @@ interface ContextPipeline {
 declare function createContextPipeline(config: ContextPipelineConfig): ContextPipeline;
 
 /**
- * Engram Scorer - Implements engram theory (memory decay)
+ * Debt Tracker - Technical debt management
  *
- * Neuroscience: Memories fade over time without reinforcement.
- * Application: Apply exponential decay formula to memory scores based on age and access count.
+ * Tracks technical debt with mandatory repayment dates,
+ * severity levels, and token cost estimates.
+ * Stored in SQLite alongside the main memory.db.
+ */
+type DebtSeverity = 'P0' | 'P1' | 'P2';
+type DebtStatus = 'open' | 'in_progress' | 'resolved';
+interface TechDebt {
+    id: string;
+    description: string;
+    created_at: number;
+    repayment_date: number;
+    severity: DebtSeverity;
+    token_cost: number;
+    files_affected: string[];
+    status: DebtStatus;
+    resolution_tokens?: number;
+    resolved_at?: number;
+}
+interface DebtStats {
+    total: number;
+    open: number;
+    in_progress: number;
+    resolved: number;
+    overdue: number;
+    totalTokenCost: number;
+    resolvedTokenCost: number;
+    repaymentRate: number;
+}
+interface DebtTracker {
+    /** Add a new tech debt item */
+    add(debt: Omit<TechDebt, 'id' | 'created_at' | 'status'>): Promise<TechDebt>;
+    /** List all debts, optionally filtered */
+    list(filter?: {
+        status?: DebtStatus;
+        severity?: DebtSeverity;
+        overdue?: boolean;
+    }): Promise<TechDebt[]>;
+    /** Get a specific debt by ID */
+    get(id: string): Promise<TechDebt | null>;
+    /** Update debt status */
+    resolve(id: string, resolutionTokens?: number): Promise<void>;
+    /** Update debt status to in_progress */
+    start(id: string): Promise<void>;
+    /** Delete a debt item */
+    remove(id: string): Promise<void>;
+    /** Get debt statistics */
+    stats(): Promise<DebtStats>;
+    /** Get P0 debts for CLAUDE.md inclusion */
+    getCritical(): Promise<TechDebt[]>;
+    /** Close database */
+    close(): Promise<void>;
+}
+/**
+ * Create a debt tracker instance
+ */
+declare function createDebtTracker(dbPath: string): DebtTracker;
+
+/**
+ * Dependency Graph Analyzer
+ *
+ * Analyzes TypeScript/JavaScript import/export relationships to build
+ * a dependency graph. Uses regex-based parsing (no AST dependency needed)
+ * for lightweight, fast analysis.
+ *
+ * Integrates with engram scoring to identify hot paths and prioritize
+ * files for context loading.
+ */
+interface DependencyNode {
+    filePath: string;
+    exports: string[];
+    imports: DependencyEdge[];
+    callers: string[];
+    engram_score: number;
+    lastModified: number;
+    tokenEstimate: number;
+}
+interface DependencyEdge {
+    source: string;
+    target: string;
+    symbols: string[];
+}
+interface GraphAnalysis {
+    entryPoints: string[];
+    hotPaths: string[];
+    orphans: string[];
+    totalTokens: number;
+    optimizedTokens: number;
+}
+interface DependencyGraphConfig {
+    /** Project root directory */
+    projectRoot: string;
+    /** Maximum depth for traversal (default: Infinity) */
+    maxDepth?: number;
+    /** File extensions to analyze (default: ['.ts', '.tsx', '.js', '.jsx']) */
+    extensions?: string[];
+    /** Directories to ignore (default: ['node_modules', 'dist', '.git', '.sparn']) */
+    ignoreDirs?: string[];
+}
+interface DependencyGraph {
+    /** Build the full dependency graph */
+    build(): Promise<Map<string, DependencyNode>>;
+    /** Get graph analysis with entry points, hot paths, orphans */
+    analyze(): Promise<GraphAnalysis>;
+    /** Get subgraph focused on a specific module/pattern */
+    focus(pattern: string): Promise<Map<string, DependencyNode>>;
+    /** Get files needed starting from an entry point, up to maxDepth */
+    getFilesFromEntry(entryPoint: string, maxDepth?: number): Promise<string[]>;
+    /** Get the full node map (after build) */
+    getNodes(): Map<string, DependencyNode>;
+}
+/**
+ * Create a dependency graph analyzer
+ */
+declare function createDependencyGraph(config: DependencyGraphConfig): DependencyGraph;
+
+/**
+ * Docs Generator - Auto-generate CLAUDE.md
+ *
+ * Scans repo structure, uses dependency graph data, and generates
+ * a compact CLAUDE.md optimized for AI agent context loading.
+ */
+
+interface DocsGeneratorConfig {
+    projectRoot: string;
+    /** Include dependency graph summary */
+    includeGraph?: boolean;
+    /** Include debt tracker info */
+    includeDebt?: boolean;
+    /** Custom sections to append */
+    customSections?: string[];
+}
+interface DocsGenerator {
+    /** Generate CLAUDE.md content */
+    generate(graph?: DependencyGraph): Promise<string>;
+}
+/**
+ * Create a docs generator
+ */
+declare function createDocsGenerator(config: DocsGeneratorConfig): DocsGenerator;
+
+/**
+ * Engram Scorer - Implements time-based memory decay
+ *
+ * Older entries fade over time unless reinforced by access.
+ * Applies exponential decay formula to memory scores based on age and access count.
  *
  * Formula: decay = 1 - e^(-age/TTL)
  * Score adjustment: score_new = score_old * (1 - decay) + (accessCount bonus)
@@ -643,11 +880,139 @@ interface EngramScorer {
  * @param config - Scorer configuration
  * @returns EngramScorer instance
  */
-declare function createEngramScorer(config: EngramScorerConfig): EngramScorer;
+declare function createEngramScorer(config: EngramScorerConfig & {
+    recencyBoostMinutes?: number;
+    recencyBoostMultiplier?: number;
+}): EngramScorer;
+
+/**
+ * Metrics and Telemetry System
+ *
+ * Tracks performance metrics and optimization statistics:
+ * - Optimization duration and throughput
+ * - Token savings and reduction rates
+ * - Memory usage and cache hit rates
+ * - Daemon uptime and session counts
+ */
+interface OptimizationMetric {
+    timestamp: number;
+    duration: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    entriesProcessed: number;
+    entriesKept: number;
+    cacheHitRate: number;
+    memoryUsage: number;
+}
+interface DaemonMetric {
+    startTime: number;
+    sessionsWatched: number;
+    totalOptimizations: number;
+    totalTokensSaved: number;
+    averageLatency: number;
+    memoryUsage: number;
+}
+interface MetricsSnapshot {
+    timestamp: number;
+    optimization: {
+        totalRuns: number;
+        totalDuration: number;
+        totalTokensSaved: number;
+        averageReduction: number;
+        p50Latency: number;
+        p95Latency: number;
+        p99Latency: number;
+    };
+    cache: {
+        hitRate: number;
+        totalHits: number;
+        totalMisses: number;
+        size: number;
+    };
+    daemon: {
+        uptime: number;
+        sessionsWatched: number;
+        memoryUsage: number;
+    };
+}
+interface MetricsCollector {
+    /**
+     * Record an optimization metric
+     */
+    recordOptimization(metric: OptimizationMetric): void;
+    /**
+     * Update daemon metrics
+     */
+    updateDaemon(metric: Partial<DaemonMetric>): void;
+    /**
+     * Get current metrics snapshot
+     */
+    getSnapshot(): MetricsSnapshot;
+    /**
+     * Export metrics as JSON
+     */
+    export(): string;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+}
+/**
+ * Create a metrics collector instance
+ */
+declare function createMetricsCollector(): MetricsCollector;
+/**
+ * Get or create the global metrics collector
+ */
+declare function getMetrics(): MetricsCollector;
+
+/**
+ * Search Engine - Hybrid FTS5 + ripgrep search
+ *
+ * Deterministic search without embeddings:
+ * 1. FTS5 for full-text search with stemming (porter tokenizer)
+ * 2. ripgrep fallback for exact pattern/regex matching
+ * 3. Fusion scoring with dedup across both sources
+ */
+interface SearchResult {
+    filePath: string;
+    lineNumber: number;
+    content: string;
+    score: number;
+    context: string[];
+    engram_score: number;
+}
+interface SearchOpts {
+    maxResults?: number;
+    fileGlob?: string;
+    useRipgrep?: boolean;
+    includeContext?: boolean;
+}
+interface IndexStats {
+    filesIndexed: number;
+    totalLines: number;
+    duration: number;
+}
+interface SearchEngine {
+    /** Initialize the search database */
+    init(projectRoot: string): Promise<void>;
+    /** Index files into FTS5 */
+    index(paths?: string[]): Promise<IndexStats>;
+    /** Search using hybrid FTS5 + ripgrep */
+    search(query: string, opts?: SearchOpts): Promise<SearchResult[]>;
+    /** Re-index all files */
+    refresh(): Promise<IndexStats>;
+    /** Close the database */
+    close(): Promise<void>;
+}
+/**
+ * Create a search engine instance
+ */
+declare function createSearchEngine(dbPath: string): SearchEngine;
 
 /**
  * Sleep compressor (consolidation) types.
- * Implements sleep replay principle from neuroscience.
+ * Periodic consolidation removes decayed entries and merges duplicates.
  */
 
 /**
@@ -682,11 +1047,10 @@ interface DuplicateGroup {
 }
 
 /**
- * Sleep Compressor - Implements sleep replay principle
+ * Sleep Compressor - Periodic consolidation
  *
- * Neuroscience: During sleep, the brain consolidates memories by replaying important ones
- * and discarding irrelevant information.
- * Application: Periodic consolidation removes decayed entries and merges duplicates.
+ * Removes decayed entries and merges duplicates to keep the memory store lean.
+ * Runs on demand or on a scheduled interval via the daemon.
  */
 
 interface SleepCompressor {
@@ -716,10 +1080,10 @@ interface SleepCompressor {
 declare function createSleepCompressor(): SleepCompressor;
 
 /**
- * Sparse Pruner - Implements sparse coding principle
+ * Sparse Pruner - Relevance filtering
  *
- * Neuroscience: Only 2-5% of neurons fire at any given time.
- * Application: Keep only top 5% most relevant context entries by TF-IDF score.
+ * Keeps only the top 2-5% most relevant context entries by TF-IDF score.
+ * Low-scoring entries are pruned to reduce token usage.
  */
 
 interface SparsePrunerConfig {
@@ -748,6 +1112,91 @@ interface SparsePruner {
  */
 declare function createSparsePruner(config: SparsePrunerConfig): SparsePruner;
 
+/**
+ * Workflow Planner - Plan/Exec/Verify separation
+ *
+ * Separates AI agent workflows into discrete phases:
+ * - Planning: Identify files needed, search queries, and steps
+ * - Execution: Apply constraints (max reads, token budget)
+ * - Verification: Check step completion and run tests
+ *
+ * Reduces token waste by preventing re-planning loops.
+ */
+interface SparnPlan {
+    id: string;
+    created_at: number;
+    task_description: string;
+    steps: PlanStep[];
+    token_budget: {
+        planning: number;
+        estimated_execution: number;
+        max_file_reads: number;
+    };
+    files_needed: string[];
+    search_queries: string[];
+    status: 'draft' | 'ready' | 'executing' | 'completed' | 'failed';
+}
+interface PlanStep {
+    order: number;
+    action: 'read' | 'write' | 'search' | 'test' | 'verify';
+    target: string;
+    description: string;
+    dependencies: number[];
+    estimated_tokens: number;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+    result?: string;
+}
+interface PlanExecConstraints {
+    maxFileReads: number;
+    tokenBudget: number;
+    allowReplan: boolean;
+}
+interface PlanVerifyResult {
+    planId: string;
+    stepsCompleted: number;
+    stepsFailed: number;
+    stepsSkipped: number;
+    totalSteps: number;
+    tokensBudgeted: number;
+    tokensUsed: number;
+    success: boolean;
+    details: Array<{
+        step: number;
+        action: string;
+        target: string;
+        status: string;
+    }>;
+}
+interface WorkflowPlanner {
+    /** Create a new plan */
+    createPlan(taskDescription: string, filesNeeded: string[], searchQueries: string[], steps: Omit<PlanStep, 'status' | 'result'>[], tokenBudget?: {
+        planning: number;
+        estimated_execution: number;
+        max_file_reads: number;
+    }): Promise<SparnPlan>;
+    /** Load an existing plan */
+    loadPlan(planId: string): Promise<SparnPlan | null>;
+    /** List all plans */
+    listPlans(): Promise<Array<{
+        id: string;
+        task: string;
+        status: string;
+        created: number;
+    }>>;
+    /** Update a plan step status */
+    updateStep(planId: string, stepOrder: number, status: PlanStep['status'], result?: string): Promise<void>;
+    /** Start execution of a plan */
+    startExec(planId: string): Promise<PlanExecConstraints>;
+    /** Verify plan completion */
+    verify(planId: string): Promise<PlanVerifyResult>;
+    /** Get the plans directory */
+    getPlansDir(): string;
+}
+/**
+ * Create a workflow planner
+ */
+declare function createWorkflowPlanner(projectRoot: string): WorkflowPlanner;
+
 /**
  * Daemon Process Manager - Background process lifecycle management
  *
@@ -913,13 +1362,13 @@ declare function createSessionWatcher(config: SessionWatcherConfig): SessionWatc
 /**
  * Sparn MCP Server - Model Context Protocol server implementation
  *
- * Exposes Sparn's neuroscience-inspired context optimization as MCP tools,
- * enabling integration with Claude Desktop, VS Code, and other MCP clients.
+ * Exposes Sparn context optimization as MCP tools, enabling integration
+ * with Claude Desktop, VS Code, and other MCP clients.
  *
  * Tools:
  * - sparn_optimize: Optimize context with configurable options
  * - sparn_stats: Get optimization statistics
- * - sparn_consolidate: Run memory consolidation (sleep replay)
+ * - sparn_consolidate: Run memory consolidation
  */
 
 /**
@@ -967,6 +1416,47 @@ declare function parseClaudeCodeContext(context: string): MemoryEntry[];
  * @returns Memory entry
  */
 declare function createEntry(content: string, type: BlockType, baseTime: number): MemoryEntry;
+/**
+ * Parsed JSONL message structure
+ */
+interface JSONLMessage {
+    role?: string;
+    content?: string | Array<{
+        type: string;
+        text?: string;
+        name?: string;
+        input?: unknown;
+        content?: string | Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+    type?: string;
+    tool_use?: {
+        name: string;
+        input: unknown;
+    };
+    tool_result?: {
+        content: string | Array<{
+            type: string;
+            text?: string;
+        }>;
+    };
+}
+/**
+ * Parse a single JSONL line into a message
+ * @param line - Single JSON line
+ * @returns Parsed message or null on failure
+ */
+declare function parseJSONLLine(line: string): JSONLMessage | null;
+/**
+ * Parse JSONL context into memory entries
+ * Handles Claude Code transcript format (one JSON object per line)
+ *
+ * @param context - Raw JSONL context string
+ * @returns Array of memory entries, or empty array if parsing fails
+ */
+declare function parseJSONLContext(context: string): MemoryEntry[];
 /**
  * Parse generic context (fallback for non-Claude-Code agents)
  * Splits on double newlines, treats as paragraphs
@@ -1017,23 +1507,32 @@ declare function createLogger(verbose?: boolean): Logger;
 
 /**
  * Token estimation utilities.
- * Uses whitespace heuristic (~90% accuracy vs GPT tokenizer).
+ * Supports both heuristic (~90% accuracy) and precise (GPT tokenizer, ~95%+ accuracy) modes.
  */
 /**
- * Estimate token count for text using heuristic.
+ * Enable or disable precise token counting using GPT tokenizer.
+ * When enabled, estimateTokens() uses gpt-tokenizer for ~95%+ accuracy on code.
+ * When disabled (default), uses fast whitespace heuristic.
  *
- * Approximation: 1 token ≈ 4 chars or 0.75 words
- * Provides ~90% accuracy compared to GPT tokenizer, sufficient for optimization heuristics.
+ * @param enabled - Whether to use precise counting
+ */
+declare function setPreciseTokenCounting(enabled: boolean): void;
+/**
+ * Count tokens precisely using GPT tokenizer.
  *
  * @param text - Text to count
- * @returns Estimated token count
+ * @returns Exact token count
+ */
+declare function countTokensPrecise(text: string): number;
+/**
+ * Estimate token count for text.
  *
- * @example
- * ```typescript
- * const tokens = estimateTokens('Hello world');
- * console.log(tokens); // ~2
- * ```
+ * In default (heuristic) mode: ~90% accuracy, very fast.
+ * In precise mode: ~95%+ accuracy using GPT tokenizer.
+ *
+ * @param text - Text to count
+ * @returns Estimated token count
  */
 declare function estimateTokens(text: string): number;
 
-export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FilePosition, type FileTracker, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type RealtimeConfig, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparnMcpServerOptions, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createSessionWatcher, createSleepCompressor, createSparnMcpServer, createSparsePruner, estimateTokens, hashContent, parseClaudeCodeContext, parseGenericContext };
+export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BTSPEmbedderConfig, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DebtSeverity, type DebtStats, type DebtStatus, type DebtTracker, type DecayConfig, type DependencyEdge, type DependencyGraph, type DependencyGraphConfig, type DependencyNode, type DocsGenerator, type DocsGeneratorConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FTSResult, type FilePosition, type FileTracker, type GraphAnalysis, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type IndexStats, type JSONLMessage, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type MetricsCollector, type MetricsSnapshot, type OptimizationResult, type OptimizeOptions, type PlanExecConstraints, type PlanStep, type PlanVerifyResult, type PruneResult, type PruningConfig, type RealtimeConfig, type SearchEngine, type SearchOpts, type SearchResult, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparnMcpServerOptions, type SparnPlan, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type TFIDFIndex, type TechDebt, type UIConfig, type WorkflowPlanner, calculateIDF, calculateTF, calculateTFIDF, countTokensPrecise, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createDebtTracker, createDependencyGraph, createDocsGenerator, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createMetricsCollector, createSearchEngine, createSessionWatcher, createSleepCompressor, createSparnMcpServer, createSparsePruner, createTFIDFIndex, createWorkflowPlanner, estimateTokens, getMetrics, hashContent, parseClaudeCodeContext, parseGenericContext, parseJSONLContext, parseJSONLLine, scoreTFIDF, setPreciseTokenCounting, tokenize };