@ulrichc1/sparn 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,567 @@
+/**
+ * Core memory entry types for Sparn's context optimization engine.
+ * Maps to neuroscience-inspired memory model with decay and state transitions.
+ */
+/**
+ * Confidence state for memory entries.
+ * Based on multi-state synapse model from neuroscience.
+ */
+type ConfidenceState = 'silent' | 'ready' | 'active';
+/**
+ * Represents a single context memory entry with neuroscience-inspired metadata.
+ *
+ * State transitions:
+ * - score ≤ 0.3 → silent (not included in context)
+ * - 0.3 < score ≤ 0.7 → ready (included if space permits)
+ * - score > 0.7 → active (always included)
+ * - isBTSP = true → active (bypass score check)
+ */
+interface MemoryEntry {
+    /** Unique identifier (UUID v4) */
+    id: string;
+    /** The actual memory content/context data */
+    content: string;
+    /** SHA-256 hash of content for deduplication */
+    hash: string;
+    /** Unix timestamp (seconds) of creation */
+    timestamp: number;
+    /** Current engram score (0.0-1.0) */
+    score: number;
+    /** Time-to-live in seconds remaining */
+    ttl: number;
+    /** Confidence state */
+    state: ConfidenceState;
+    /** Number of times accessed/retrieved */
+    accessCount: number;
+    /** User-defined tags for categorization */
+    tags: string[];
+    /** Additional key-value pairs */
+    metadata: Record<string, unknown>;
+    /** Flag indicating one-shot learned entry (BTSP) */
+    isBTSP: boolean;
+}
+/**
+ * Query filters for memory store operations.
+ */
+interface MemoryQueryFilters {
+    state?: ConfidenceState;
+    minScore?: number;
+    maxScore?: number;
+    tags?: string[];
+    isBTSP?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * State distribution aggregation.
+ */
+interface StateDistribution {
+    active: number;
+    ready: number;
+    silent: number;
+    total: number;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * Optimization statistics record.
+ */
+interface OptimizationStats {
+    id: number;
+    timestamp: number;
+    tokens_before: number;
+    tokens_after: number;
+    entries_pruned: number;
+    duration_ms: number;
+}
+/**
+ * KV Memory interface.
+ */
+interface KVMemory {
+    /** Store a memory entry */
+    put(entry: MemoryEntry): Promise<void>;
+    /** Retrieve a memory entry by ID */
+    get(id: string): Promise<MemoryEntry | null>;
+    /** Query entries by filters */
+    query(filters: MemoryQueryFilters): Promise<MemoryEntry[]>;
+    /** Delete a memory entry */
+    delete(id: string): Promise<void>;
+    /** List all entry IDs */
+    list(): Promise<string[]>;
+    /** Compact database (remove expired entries) */
+    compact(): Promise<number>;
+    /** Close database connection */
+    close(): Promise<void>;
+    /** Record optimization statistics */
+    recordOptimization(stats: Omit<OptimizationStats, 'id'>): Promise<void>;
+    /** Get all optimization statistics */
+    getOptimizationStats(): Promise<OptimizationStats[]>;
+    /** Clear all optimization statistics */
+    clearOptimizationStats(): Promise<void>;
+}
+/**
+ * Create KV Memory store with SQLite backend.
+ *
+ * Initializes database with dual table schema:
+ * - entries_index: Fast lookups (id, hash, timestamp, score, ttl, state, accessCount, isBTSP)
+ * - entries_value: Content storage (id, content, tags, metadata)
+ *
+ * @param dbPath - Path to SQLite database file
+ * @returns KVMemory instance
+ */
+declare function createKVMemory(dbPath: string): Promise<KVMemory>;
+
+/**
+ * Agent adapter interface types.
+ * Enables agent-agnostic design per Article IV.
+ */
+
+/**
+ * Options for optimization operations.
+ */
+interface OptimizeOptions {
+    /** Dry-run mode (don't modify memory store) */
+    dryRun?: boolean;
+    /** Verbose output */
+    verbose?: boolean;
+    /** Custom pruning threshold (overrides config) */
+    threshold?: number;
+}
+/**
+ * Result of an optimization operation.
+ */
+interface OptimizationResult {
+    /** Optimized context text */
+    optimizedContext: string;
+    /** Token count before optimization */
+    tokensBefore: number;
+    /** Token count after optimization */
+    tokensAfter: number;
+    /** Reduction percentage (0.0-1.0) */
+    reduction: number;
+    /** Total entries processed */
+    entriesProcessed: number;
+    /** Entries kept after optimization */
+    entriesKept: number;
+    /** Optimization duration in milliseconds */
+    durationMs: number;
+    /** State distribution after optimization */
+    stateDistribution: StateDistribution;
+    /** Optional: Detailed per-entry information (when verbose=true) */
+    details?: Array<{
+        id: string;
+        score: number;
+        state: string;
+        isBTSP: boolean;
+        tokens: number;
+    }>;
+}
+/**
+ * Agent adapter interface.
+ * All agent-specific logic must implement this contract.
+ */
+interface AgentAdapter {
+    /**
+     * Optimize context using this agent's strategy.
+     *
+     * @param context - Input context (plain text)
+     * @param options - Optimization options
+     * @returns Optimization result
+     */
+    optimize(context: string, options?: OptimizeOptions): Promise<OptimizationResult>;
+}
+
+/**
+ * Configuration types for Sparn behavior customization.
+ */
+/**
+ * Agent adapter type.
+ */
+type AgentType = 'claude-code' | 'generic';
+/**
+ * Pruning configuration.
+ */
+interface PruningConfig {
+    /** Percentage of top-scored entries to keep (1-100, default: 5) */
+    threshold: number;
+    /** Aggressiveness scale 0-100 (affects TF-IDF weighting, default: 50) */
+    aggressiveness: number;
+}
+/**
+ * Decay configuration.
+ */
+interface DecayConfig {
+    /** Default TTL in hours (default: 24) */
+    defaultTTL: number;
+    /** Decay threshold for pruning (0.0-1.0, default: 0.95) */
+    decayThreshold: number;
+}
+/**
+ * Confidence state threshold configuration.
+ */
+interface StatesConfig {
+    /** Score threshold for active state (default: 0.7) */
+    activeThreshold: number;
+    /** Score threshold for ready state (default: 0.3) */
+    readyThreshold: number;
+}
+/**
+ * UI configuration.
+ */
+interface UIConfig {
+    /** Enable colored output (default: true) */
+    colors: boolean;
+    /** Enable sound effects (default: false) */
+    sounds: boolean;
+    /** Verbose logging (default: false) */
+    verbose: boolean;
+}
+/**
+ * Complete Sparn configuration.
+ */
+interface SparnConfig {
+    pruning: PruningConfig;
+    decay: DecayConfig;
+    states: StatesConfig;
+    agent: AgentType;
+    ui: UIConfig;
+    /** Auto-consolidation interval in hours, or null for manual */
+    autoConsolidate: number | null;
+}
+/**
+ * Default configuration values.
+ */
+declare const DEFAULT_CONFIG: SparnConfig;
+
+/**
+ * Claude Code Adapter - Claude Code-specific optimization pipeline
+ *
+ * Optimized for Claude Code's conversation patterns, tool use, and context management.
+ * Implements the same AgentAdapter interface as GenericAdapter but with Claude-specific tuning.
+ */
+
+/**
+ * Create a Claude Code adapter instance
+ * @param memory - KV memory store
+ * @param config - Sparn configuration
+ * @returns AgentAdapter instance optimized for Claude Code
+ */
+declare function createClaudeCodeAdapter(memory: KVMemory, config: SparnConfig): AgentAdapter;
+
+/**
+ * Generic Adapter - Agent-agnostic optimization pipeline
+ *
+ * Orchestrates all 6 neuroscience modules to optimize context memory.
+ */
+
+/**
+ * Create a generic adapter instance
+ * @param memory - KV memory store
+ * @param config - Sparn configuration
+ * @returns AgentAdapter instance
+ */
+declare function createGenericAdapter(memory: KVMemory, config: SparnConfig): AgentAdapter;
+
+/**
+ * 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.
+ */
+
+interface BTSPEmbedder {
+    /**
+     * Detect if content contains BTSP patterns (errors, stack traces, conflicts, git diffs)
+     * @param content - Content to analyze
+     * @returns True if BTSP pattern detected
+     */
+    detectBTSP(content: string): boolean;
+    /**
+     * Create a new memory entry marked as BTSP (one-shot learned)
+     * @param content - Entry content
+     * @param tags - Optional tags
+     * @param metadata - Optional metadata
+     * @returns BTSP-marked memory entry
+     */
+    createBTSPEntry(content: string, tags?: string[], metadata?: Record<string, unknown>): MemoryEntry;
+}
+/**
+ * Create a BTSP embedder instance
+ * @returns BTSPEmbedder instance
+ */
+declare function createBTSPEmbedder(): BTSPEmbedder;
+
+/**
+ * Confidence States - Implements multi-state synapses
+ *
+ * Neuroscience: Synapses exist in three states: silent, ready (potentiated), active.
+ * Application: Classify memory entries by score into silent/ready/active states.
+ */
+
+interface ConfidenceStatesConfig {
+    /** Score threshold for active state (e.g., 0.7) */
+    activeThreshold: number;
+    /** Score threshold for ready state (e.g., 0.3) */
+    readyThreshold: number;
+}
+interface ConfidenceStates {
+    /**
+     * Calculate state based on entry score and BTSP flag
+     * @param entry - Memory entry
+     * @returns Confidence state
+     */
+    calculateState(entry: MemoryEntry): ConfidenceState;
+    /**
+     * Transition entry to correct state based on its score
+     * @param entry - Entry to transition
+     * @returns Entry with updated state
+     */
+    transition(entry: MemoryEntry): MemoryEntry;
+    /**
+     * Get distribution of states across all entries
+     * @param entries - All memory entries
+     * @returns State distribution with counts
+     */
+    getDistribution(entries: MemoryEntry[]): StateDistribution;
+}
+/**
+ * Create a confidence states manager
+ * @param config - States configuration
+ * @returns ConfidenceStates instance
+ */
+declare function createConfidenceStates(config: ConfidenceStatesConfig): ConfidenceStates;
+
+/**
+ * Engram Scorer - Implements engram theory (memory decay)
+ *
+ * Neuroscience: Memories fade over time without reinforcement.
+ * Application: Apply 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)
+ */
+
+interface EngramScorerConfig {
+    /** Default TTL in hours for new entries */
+    defaultTTL: number;
+    /** Decay threshold (0.0-1.0) above which entries are marked for pruning */
+    decayThreshold: number;
+}
+interface EngramScorer {
+    /**
+     * Calculate current score for an entry based on decay and access count
+     * @param entry - Memory entry to score
+     * @param currentTime - Current timestamp in milliseconds (for testing)
+     * @returns Updated score (0.0-1.0)
+     */
+    calculateScore(entry: MemoryEntry, currentTime?: number): number;
+    /**
+     * Refresh TTL to default value
+     * @param entry - Entry to refresh
+     * @returns Entry with refreshed TTL and timestamp
+     */
+    refreshTTL(entry: MemoryEntry): MemoryEntry;
+    /**
+     * Calculate decay factor (0.0-1.0) based on age and TTL
+     * @param ageInSeconds - Age of entry in seconds
+     * @param ttlInSeconds - TTL in seconds
+     * @returns Decay factor (0.0 = fresh, 1.0 = fully decayed)
+     */
+    calculateDecay(ageInSeconds: number, ttlInSeconds: number): number;
+}
+/**
+ * Create an engram scorer instance
+ * @param config - Scorer configuration
+ * @returns EngramScorer instance
+ */
+declare function createEngramScorer(config: EngramScorerConfig): EngramScorer;
+
+/**
+ * Sleep compressor (consolidation) types.
+ * Implements sleep replay principle from neuroscience.
+ */
+
+/**
+ * Result of a consolidation operation.
+ */
+interface ConsolidateResult {
+    /** Entries kept after consolidation */
+    kept: MemoryEntry[];
+    /** Entries removed during consolidation */
+    removed: MemoryEntry[];
+    /** Entries before consolidation */
+    entriesBefore: number;
+    /** Entries after consolidation */
+    entriesAfter: number;
+    /** Number of decayed entries removed */
+    decayedRemoved: number;
+    /** Number of duplicate entries merged */
+    duplicatesRemoved: number;
+    /** Compression ratio (0.0-1.0) */
+    compressionRatio: number;
+    /** Consolidation duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Group of duplicate entries.
+ */
+interface DuplicateGroup {
+    /** Entries in this duplicate group */
+    entries: MemoryEntry[];
+    /** Similarity score (0.0-1.0) */
+    similarity: number;
+}
+
+/**
+ * Sleep Compressor - Implements sleep replay principle
+ *
+ * Neuroscience: During sleep, the brain consolidates memories by replaying important ones
+ * and discarding irrelevant information.
+ * Application: Periodic consolidation removes decayed entries and merges duplicates.
+ */
+
+interface SleepCompressor {
+    /**
+     * Consolidate entries: remove decayed, merge duplicates
+     * @param entries - All memory entries
+     * @returns Consolidation result
+     */
+    consolidate(entries: MemoryEntry[]): ConsolidateResult;
+    /**
+     * Find duplicate entries (exact hash or near-duplicate by similarity)
+     * @param entries - Memory entries
+     * @returns Groups of duplicates
+     */
+    findDuplicates(entries: MemoryEntry[]): DuplicateGroup[];
+    /**
+     * Merge duplicate entries, keeping highest score
+     * @param groups - Duplicate groups
+     * @returns Merged entries
+     */
+    mergeDuplicates(groups: DuplicateGroup[]): MemoryEntry[];
+}
+/**
+ * Create a sleep compressor instance
+ * @returns SleepCompressor instance
+ */
+declare function createSleepCompressor(): SleepCompressor;
+
+/**
+ * Sparse pruner types.
+ * Implements sparse coding principle from neuroscience.
+ */
+
+/**
+ * Result of a pruning operation.
+ */
+interface PruneResult {
+    /** Entries kept after pruning */
+    kept: MemoryEntry[];
+    /** Entries removed during pruning */
+    removed: MemoryEntry[];
+    /** Original token count before pruning */
+    originalTokens: number;
+    /** Token count after pruning */
+    prunedTokens: number;
+}
+
+/**
+ * Sparse Pruner - Implements sparse coding principle
+ *
+ * Neuroscience: Only 2-5% of neurons fire at any given time.
+ * Application: Keep only top 5% most relevant context entries by TF-IDF score.
+ */
+
+interface SparsePrunerConfig {
+    /** Percentage threshold for pruning (e.g., 5 = keep top 5%) */
+    threshold: number;
+}
+interface SparsePruner {
+    /**
+     * Prune entries to keep only top N% by relevance score
+     * @param entries - Memory entries to prune
+     * @returns Result with kept/removed entries and token counts
+     */
+    prune(entries: MemoryEntry[]): PruneResult;
+    /**
+     * Calculate TF-IDF relevance score for a single entry
+     * @param entry - Entry to score
+     * @param allEntries - All entries for IDF calculation
+     * @returns Relevance score (0.0-1.0)
+     */
+    scoreEntry(entry: MemoryEntry, allEntries: MemoryEntry[]): number;
+}
+/**
+ * Create a sparse pruner instance
+ * @param config - Pruner configuration
+ * @returns SparsePruner instance
+ */
+declare function createSparsePruner(config: SparsePrunerConfig): SparsePruner;
+
+/**
+ * Content hashing utilities.
+ * Uses SHA-256 for deduplication.
+ */
+/**
+ * Generate SHA-256 hash of content for deduplication.
+ *
+ * @param content - Content to hash
+ * @returns 64-character hex string (SHA-256)
+ *
+ * @example
+ * ```typescript
+ * const hash = hashContent('Hello world');
+ * console.log(hash.length); // 64
+ * ```
+ */
+declare function hashContent(content: string): string;
+
+/**
+ * Logging utility.
+ * Simple console wrapper with log levels.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger interface.
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Create a logger with optional verbosity control.
+ *
+ * @param verbose - Enable debug-level logging
+ * @returns Logger instance
+ */
+declare function createLogger(verbose?: boolean): Logger;
+
+/**
+ * Token estimation utilities.
+ * Uses whitespace heuristic (~90% accuracy vs GPT tokenizer).
+ */
+/**
+ * Estimate token count for text using heuristic.
+ *
+ * Approximation: 1 token ≈ 4 chars or 0.75 words
+ * Provides ~90% accuracy compared to GPT tokenizer, sufficient for optimization heuristics.
+ *
+ * @param text - Text to count
+ * @returns Estimated token count
+ *
+ * @example
+ * ```typescript
+ * const tokens = estimateTokens('Hello world');
+ * console.log(tokens); // ~2
+ * ```
+ */
+declare function estimateTokens(text: string): number;
+
+export { type AgentAdapter, type AgentType, type BTSPEmbedder, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, DEFAULT_CONFIG, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type SleepCompressor, type SparnConfig, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createClaudeCodeAdapter, createConfidenceStates, createEngramScorer, createGenericAdapter, createKVMemory, createLogger, createSleepCompressor, createSparsePruner, estimateTokens, hashContent };