@ulrichc1/sparn 1.2.1 → 1.4.0

package/dist/index.cjs

@@ -31,6 +31,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   DEFAULT_CONFIG: () => DEFAULT_CONFIG,
+  calculateIDF: () => calculateIDF,
+  calculateTF: () => calculateTF,
+  calculateTFIDF: () => calculateTFIDF,
+  countTokensPrecise: () => countTokensPrecise,
   createBTSPEmbedder: () => createBTSPEmbedder,
   createBudgetPruner: () => createBudgetPruner,
   createBudgetPrunerFromConfig: () => createBudgetPrunerFromConfig,
@@ -38,6 +42,9 @@ __export(src_exports, {
   createConfidenceStates: () => createConfidenceStates,
   createContextPipeline: () => createContextPipeline,
   createDaemonCommand: () => createDaemonCommand,
+  createDebtTracker: () => createDebtTracker,
+  createDependencyGraph: () => createDependencyGraph,
+  createDocsGenerator: () => createDocsGenerator,
   createEngramScorer: () => createEngramScorer,
   createEntry: () => createEntry,
   createFileTracker: () => createFileTracker,
@@ -45,14 +52,24 @@ __export(src_exports, {
   createIncrementalOptimizer: () => createIncrementalOptimizer,
   createKVMemory: () => createKVMemory,
   createLogger: () => createLogger,
+  createMetricsCollector: () => createMetricsCollector,
+  createSearchEngine: () => createSearchEngine,
   createSessionWatcher: () => createSessionWatcher,
   createSleepCompressor: () => createSleepCompressor,
   createSparnMcpServer: () => createSparnMcpServer,
   createSparsePruner: () => createSparsePruner,
+  createTFIDFIndex: () => createTFIDFIndex,
+  createWorkflowPlanner: () => createWorkflowPlanner,
   estimateTokens: () => estimateTokens,
+  getMetrics: () => getMetrics,
   hashContent: () => hashContent,
   parseClaudeCodeContext: () => parseClaudeCodeContext,
-  parseGenericContext: () => parseGenericContext
+  parseGenericContext: () => parseGenericContext,
+  parseJSONLContext: () => parseJSONLContext,
+  parseJSONLLine: () => parseJSONLLine,
+  scoreTFIDF: () => scoreTFIDF,
+  setPreciseTokenCounting: () => setPreciseTokenCounting,
+  tokenize: () => tokenize
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -70,7 +87,7 @@ function hashContent(content) {
 }
 
 // src/core/btsp-embedder.ts
-function createBTSPEmbedder() {
+function createBTSPEmbedder(config) {
   const BTSP_PATTERNS = [
     // Error patterns
     /\b(error|exception|failure|fatal|critical|panic)\b/i,
@@ -89,6 +106,14 @@ function createBTSPEmbedder() {
     /^=======/m,
     /^>>>>>>> /m
   ];
+  if (config?.customPatterns) {
+    for (const pattern of config.customPatterns) {
+      try {
+        BTSP_PATTERNS.push(new RegExp(pattern));
+      } catch {
+      }
+    }
+  }
   function detectBTSP(content) {
     return BTSP_PATTERNS.some((pattern) => pattern.test(content));
   }
@@ -116,51 +141,96 @@ function createBTSPEmbedder() {
   };
 }
 
-// src/core/confidence-states.ts
-function createConfidenceStates(config) {
-  const { activeThreshold, readyThreshold } = config;
-  function calculateState(entry) {
-    if (entry.isBTSP) {
-      return "active";
-    }
-    if (entry.score > activeThreshold) {
-      return "active";
-    }
-    if (entry.score >= readyThreshold) {
-      return "ready";
-    }
-    return "silent";
-  }
-  function transition(entry) {
-    const newState = calculateState(entry);
-    return {
-      ...entry,
-      state: newState
-    };
-  }
-  function getDistribution(entries) {
-    const distribution = {
-      silent: 0,
-      ready: 0,
-      active: 0,
-      total: entries.length
-    };
-    for (const entry of entries) {
-      const state = calculateState(entry);
-      distribution[state]++;
+// src/utils/tfidf.ts
+function tokenize(text) {
+  return text.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
+}
+function calculateTF(term, tokens) {
+  const count = tokens.filter((t) => t === term).length;
+  return Math.sqrt(count);
+}
+function calculateIDF(term, allEntries) {
+  const totalDocs = allEntries.length;
+  const docsWithTerm = allEntries.filter((entry) => {
+    const tokens = tokenize(entry.content);
+    return tokens.includes(term);
+  }).length;
+  if (docsWithTerm === 0) return 0;
+  return Math.log(totalDocs / docsWithTerm);
+}
+function calculateTFIDF(entry, allEntries) {
+  const tokens = tokenize(entry.content);
+  if (tokens.length === 0) return 0;
+  const uniqueTerms = [...new Set(tokens)];
+  let totalScore = 0;
+  for (const term of uniqueTerms) {
+    const tf = calculateTF(term, tokens);
+    const idf = calculateIDF(term, allEntries);
+    totalScore += tf * idf;
+  }
+  return totalScore / tokens.length;
+}
+function createTFIDFIndex(entries) {
+  const documentFrequency = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const tokens = tokenize(entry.content);
+    const uniqueTerms = new Set(tokens);
+    for (const term of uniqueTerms) {
+      documentFrequency.set(term, (documentFrequency.get(term) || 0) + 1);
     }
-    return distribution;
   }
   return {
-    calculateState,
-    transition,
-    getDistribution
+    documentFrequency,
+    totalDocuments: entries.length
   };
 }
+function scoreTFIDF(entry, index) {
+  const tokens = tokenize(entry.content);
+  if (tokens.length === 0) return 0;
+  const uniqueTerms = new Set(tokens);
+  let totalScore = 0;
+  for (const term of uniqueTerms) {
+    const tf = calculateTF(term, tokens);
+    const docsWithTerm = index.documentFrequency.get(term) || 0;
+    if (docsWithTerm === 0) continue;
+    const idf = Math.log(index.totalDocuments / docsWithTerm);
+    totalScore += tf * idf;
+  }
+  return totalScore / tokens.length;
+}
+
+// src/utils/tokenizer.ts
+var import_gpt_tokenizer = require("gpt-tokenizer");
+var usePrecise = false;
+function setPreciseTokenCounting(enabled) {
+  usePrecise = enabled;
+}
+function countTokensPrecise(text) {
+  if (!text || text.length === 0) {
+    return 0;
+  }
+  return (0, import_gpt_tokenizer.encode)(text).length;
+}
+function estimateTokens(text) {
+  if (!text || text.length === 0) {
+    return 0;
+  }
+  if (usePrecise) {
+    return (0, import_gpt_tokenizer.encode)(text).length;
+  }
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  const wordCount = words.length;
+  const charCount = text.length;
+  const charEstimate = Math.ceil(charCount / 4);
+  const wordEstimate = Math.ceil(wordCount * 0.75);
+  return Math.max(wordEstimate, charEstimate);
+}
 
 // src/core/engram-scorer.ts
 function createEngramScorer(config) {
   const { defaultTTL } = config;
+  const recencyWindowMs = (config.recencyBoostMinutes ?? 30) * 60 * 1e3;
+  const recencyMultiplier = config.recencyBoostMultiplier ?? 1.3;
   function calculateDecay(ageInSeconds, ttlInSeconds) {
     if (ttlInSeconds === 0) return 1;
     if (ageInSeconds <= 0) return 0;
@@ -180,6 +250,13 @@ function createEngramScorer(config) {
     if (entry.isBTSP) {
       score = Math.max(score, 0.9);
     }
+    if (!entry.isBTSP && recencyWindowMs > 0) {
+      const ageMs = currentTime - entry.timestamp;
+      if (ageMs >= 0 && ageMs < recencyWindowMs) {
+        const boostFactor = 1 + (recencyMultiplier - 1) * (1 - ageMs / recencyWindowMs);
+        score = score * boostFactor;
+      }
+    }
     return Math.max(0, Math.min(1, score));
   }
   function refreshTTL(entry) {
@@ -197,85 +274,151 @@ function createEngramScorer(config) {
   };
 }
 
-// src/utils/tokenizer.ts
-function estimateTokens(text) {
-  if (!text || text.length === 0) {
-    return 0;
-  }
-  const words = text.split(/\s+/).filter((w) => w.length > 0);
-  const wordCount = words.length;
-  const charCount = text.length;
-  const charEstimate = Math.ceil(charCount / 4);
-  const wordEstimate = Math.ceil(wordCount * 0.75);
-  return Math.max(wordEstimate, charEstimate);
-}
-
-// src/core/sparse-pruner.ts
-function createSparsePruner(config) {
-  const { threshold } = config;
-  function tokenize(text) {
-    return text.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
-  }
-  function calculateTF(term, tokens) {
-    const count = tokens.filter((t) => t === term).length;
-    return Math.sqrt(count);
-  }
-  function calculateIDF(term, allEntries) {
-    const totalDocs = allEntries.length;
-    const docsWithTerm = allEntries.filter((entry) => {
-      const tokens = tokenize(entry.content);
-      return tokens.includes(term);
-    }).length;
-    if (docsWithTerm === 0) return 0;
-    return Math.log(totalDocs / docsWithTerm);
-  }
-  function scoreEntry(entry, allEntries) {
-    const tokens = tokenize(entry.content);
-    if (tokens.length === 0) return 0;
-    const uniqueTerms = [...new Set(tokens)];
-    let totalScore = 0;
-    for (const term of uniqueTerms) {
-      const tf = calculateTF(term, tokens);
-      const idf = calculateIDF(term, allEntries);
-      totalScore += tf * idf;
+// src/core/budget-pruner.ts
+function createBudgetPruner(config) {
+  const { tokenBudget, decay } = config;
+  const engramScorer = createEngramScorer(decay);
+  function getStateMultiplier(entry) {
+    if (entry.isBTSP) return 2;
+    switch (entry.state) {
+      case "active":
+        return 2;
+      case "ready":
+        return 1;
+      case "silent":
+        return 0.5;
+      default:
+        return 1;
     }
-    return totalScore / tokens.length;
   }
-  function prune(entries) {
+  function priorityScore(entry, allEntries, index) {
+    const tfidf = index ? scoreTFIDF(entry, index) : scoreTFIDF(entry, createTFIDFIndex(allEntries));
+    const currentScore = engramScorer.calculateScore(entry);
+    const engramDecay = 1 - currentScore;
+    const stateMultiplier = getStateMultiplier(entry);
+    return tfidf * (1 - engramDecay) * stateMultiplier;
+  }
+  function pruneToFit(entries, budget = tokenBudget) {
     if (entries.length === 0) {
       return {
         kept: [],
         removed: [],
         originalTokens: 0,
-        prunedTokens: 0
+        prunedTokens: 0,
+        budgetUtilization: 0
       };
     }
     const originalTokens = entries.reduce((sum, e) => sum + estimateTokens(e.content), 0);
-    const scored = entries.map((entry) => ({
+    const btspEntries = entries.filter((e) => e.isBTSP);
+    const regularEntries = entries.filter((e) => !e.isBTSP);
+    let includedBtsp = [];
+    let btspTokens = 0;
+    const sortedBtsp = [...btspEntries].sort((a, b) => b.timestamp - a.timestamp);
+    for (const entry of sortedBtsp) {
+      const tokens = estimateTokens(entry.content);
+      if (btspTokens + tokens <= budget * 0.8) {
+        includedBtsp.push(entry);
+        btspTokens += tokens;
+      }
+    }
+    if (includedBtsp.length === 0 && sortedBtsp.length > 0) {
+      const firstBtsp = sortedBtsp[0];
+      if (firstBtsp) {
+        includedBtsp = [firstBtsp];
+        btspTokens = estimateTokens(firstBtsp.content);
+      }
+    }
+    const excludedBtsp = btspEntries.filter((e) => !includedBtsp.includes(e));
+    const tfidfIndex = createTFIDFIndex(entries);
+    const scored = regularEntries.map((entry) => ({
       entry,
-      score: scoreEntry(entry, entries)
+      score: priorityScore(entry, entries, tfidfIndex),
+      tokens: estimateTokens(entry.content)
     }));
     scored.sort((a, b) => b.score - a.score);
-    const keepCount = Math.max(1, Math.ceil(entries.length * (threshold / 100)));
-    const kept = scored.slice(0, keepCount).map((s) => s.entry);
-    const removed = scored.slice(keepCount).map((s) => s.entry);
-    const prunedTokens = kept.reduce((sum, e) => sum + estimateTokens(e.content), 0);
+    const kept = [...includedBtsp];
+    const removed = [...excludedBtsp];
+    let currentTokens = btspTokens;
+    for (const item of scored) {
+      if (currentTokens + item.tokens <= budget) {
+        kept.push(item.entry);
+        currentTokens += item.tokens;
+      } else {
+        removed.push(item.entry);
+      }
+    }
+    const budgetUtilization = budget > 0 ? currentTokens / budget : 0;
     return {
       kept,
       removed,
       originalTokens,
-      prunedTokens
+      prunedTokens: currentTokens,
+      budgetUtilization
     };
   }
   return {
-    prune,
-    scoreEntry
+    pruneToFit,
+    priorityScore
+  };
+}
+function createBudgetPrunerFromConfig(realtimeConfig, decayConfig, statesConfig) {
+  return createBudgetPruner({
+    tokenBudget: realtimeConfig.tokenBudget,
+    decay: decayConfig,
+    states: statesConfig
+  });
+}
+
+// src/core/confidence-states.ts
+function createConfidenceStates(config) {
+  const { activeThreshold, readyThreshold } = config;
+  function calculateState(entry) {
+    if (entry.isBTSP) {
+      return "active";
+    }
+    if (entry.score >= activeThreshold) {
+      return "active";
+    }
+    if (entry.score >= readyThreshold) {
+      return "ready";
+    }
+    return "silent";
+  }
+  function transition(entry) {
+    const newState = calculateState(entry);
+    return {
+      ...entry,
+      state: newState
+    };
+  }
+  function getDistribution(entries) {
+    const distribution = {
+      silent: 0,
+      ready: 0,
+      active: 0,
+      total: entries.length
+    };
+    for (const entry of entries) {
+      const state = calculateState(entry);
+      distribution[state]++;
+    }
+    return distribution;
+  }
+  return {
+    calculateState,
+    transition,
+    getDistribution
   };
 }
 
 // src/utils/context-parser.ts
 var import_node_crypto3 = require("crypto");
 function parseClaudeCodeContext(context) {
+  const firstNonEmpty = context.split("\n").find((line) => line.trim().length > 0);
+  if (firstNonEmpty?.trim().startsWith("{")) {
+    const jsonlEntries = parseJSONLContext(context);
+    if (jsonlEntries.length > 0) return jsonlEntries;
+  }
   const entries = [];
   const now = Date.now();
   const lines = context.split("\n");
@@ -328,7 +471,7 @@ function createEntry(content, type, baseTime) {
     hash: hashContent(content),
     timestamp: baseTime,
     score: initialScore,
-    state: initialScore > 0.7 ? "active" : initialScore > 0.3 ? "ready" : "silent",
+    state: initialScore >= 0.7 ? "active" : initialScore >= 0.3 ? "ready" : "silent",
     ttl: 24 * 3600,
     // 24 hours default
     accessCount: 0,
@@ -337,6 +480,58 @@ function createEntry(content, type, baseTime) {
     isBTSP: false
   };
 }
+function parseJSONLLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+function extractContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((block) => {
+      if (block.type === "text" && block.text) return block.text;
+      if (block.type === "tool_use" && block.name) return `[tool_use: ${block.name}]`;
+      if (block.type === "tool_result") {
+        if (typeof block.content === "string") return block.content;
+        if (Array.isArray(block.content)) {
+          return block.content.filter((c) => c.type === "text" && c.text).map((c) => c.text).join("\n");
+        }
+      }
+      return "";
+    }).filter((s) => s.length > 0).join("\n");
+  }
+  return "";
+}
+function classifyJSONLMessage(msg) {
+  if (Array.isArray(msg.content)) {
+    const hasToolUse = msg.content.some((b) => b.type === "tool_use");
+    const hasToolResult = msg.content.some((b) => b.type === "tool_result");
+    if (hasToolUse) return "tool";
+    if (hasToolResult) return "result";
+  }
+  if (msg.type === "tool_use" || msg.tool_use) return "tool";
+  if (msg.type === "tool_result" || msg.tool_result) return "result";
+  if (msg.role === "user" || msg.role === "assistant") return "conversation";
+  return "other";
+}
+function parseJSONLContext(context) {
+  const entries = [];
+  const now = Date.now();
+  const lines = context.split("\n");
+  for (const line of lines) {
+    const msg = parseJSONLLine(line);
+    if (!msg) continue;
+    const content = extractContent(msg.content);
+    if (!content || content.trim().length === 0) continue;
+    const blockType = classifyJSONLMessage(msg);
+    entries.push(createEntry(content, blockType, now));
+  }
+  return entries;
+}
 function parseGenericContext(context) {
   const entries = [];
   const now = Date.now();
@@ -351,15 +546,9 @@ function parseGenericContext(context) {
 
 // src/adapters/claude-code.ts
 var CLAUDE_CODE_PROFILE = {
-  // More aggressive pruning for tool results (they can be verbose)
-  toolResultThreshold: 3,
-  // Keep top 3% of tool results
   // Preserve conversation turns more aggressively
   conversationBoost: 1.5,
   // 50% boost for User/Assistant exchanges
-  // Prioritize recent context (Claude Code sessions are typically focused)
-  recentContextWindow: 10 * 60,
-  // Last 10 minutes gets priority
   // BTSP patterns specific to Claude Code
   btspPatterns: [
     // Error patterns
@@ -380,12 +569,14 @@ var CLAUDE_CODE_PROFILE = {
   ]
 };
 function createClaudeCodeAdapter(memory, config) {
-  const pruner = createSparsePruner({
-    threshold: config.pruning.threshold
+  const pruner = createBudgetPruner({
+    tokenBudget: config.realtime.tokenBudget,
+    decay: config.decay,
+    states: config.states
   });
   const scorer = createEngramScorer(config.decay);
   const states = createConfidenceStates(config.states);
-  const btsp = createBTSPEmbedder();
+  const btsp = createBTSPEmbedder({ customPatterns: config.btspPatterns });
   async function optimize(context, options = {}) {
     const startTime = Date.now();
     const entries = parseClaudeCodeContext(context);
@@ -416,9 +607,11 @@ function createClaudeCodeAdapter(memory, config) {
     });
     const scoredEntries = boostedEntries.map((entry) => {
       const decayScore = scorer.calculateScore(entry);
+      const isConversationTurn = entry.content.trim().startsWith("User:") || entry.content.trim().startsWith("Assistant:");
+      const finalScore = isConversationTurn ? Math.min(1, decayScore * CLAUDE_CODE_PROFILE.conversationBoost) : decayScore;
       return {
         ...entry,
-        score: decayScore
+        score: finalScore
       };
     });
     const entriesWithStates = scoredEntries.map((entry) => {
@@ -428,7 +621,7 @@ function createClaudeCodeAdapter(memory, config) {
         state
       };
     });
-    const pruneResult = pruner.prune(entriesWithStates);
+    const pruneResult = pruner.pruneToFit(entriesWithStates);
     if (!options.dryRun) {
       for (const entry of pruneResult.kept) {
         await memory.put(entry);
@@ -471,29 +664,73 @@ function createClaudeCodeAdapter(memory, config) {
 
 // src/adapters/generic.ts
 var import_node_crypto4 = require("crypto");
+
+// src/core/sparse-pruner.ts
+function createSparsePruner(config) {
+  const { threshold } = config;
+  function scoreEntry(entry, allEntries) {
+    return scoreTFIDF(entry, createTFIDFIndex(allEntries));
+  }
+  function prune(entries) {
+    if (entries.length === 0) {
+      return {
+        kept: [],
+        removed: [],
+        originalTokens: 0,
+        prunedTokens: 0
+      };
+    }
+    const originalTokens = entries.reduce((sum, e) => sum + estimateTokens(e.content), 0);
+    const tfidfIndex = createTFIDFIndex(entries);
+    const scored = entries.map((entry) => ({
+      entry,
+      score: scoreTFIDF(entry, tfidfIndex)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const keepCount = Math.max(1, Math.ceil(entries.length * (threshold / 100)));
+    const kept = scored.slice(0, keepCount).map((s) => s.entry);
+    const removed = scored.slice(keepCount).map((s) => s.entry);
+    const prunedTokens = kept.reduce((sum, e) => sum + estimateTokens(e.content), 0);
+    return {
+      kept,
+      removed,
+      originalTokens,
+      prunedTokens
+    };
+  }
+  return {
+    prune,
+    scoreEntry
+  };
+}
+
+// src/adapters/generic.ts
 function createGenericAdapter(memory, config) {
   const pruner = createSparsePruner(config.pruning);
   const scorer = createEngramScorer(config.decay);
   const states = createConfidenceStates(config.states);
-  const btsp = createBTSPEmbedder();
+  const btsp = createBTSPEmbedder({ customPatterns: config.btspPatterns });
   async function optimize(context, options = {}) {
     const startTime = Date.now();
     const lines = context.split("\n").filter((line) => line.trim().length > 0);
-    const entries = lines.map((content) => ({
-      id: (0, import_node_crypto4.randomUUID)(),
-      content,
-      hash: hashContent(content),
-      timestamp: Date.now(),
-      score: btsp.detectBTSP(content) ? 1 : 0.5,
-      // BTSP gets high initial score
-      ttl: config.decay.defaultTTL * 3600,
-      // Convert hours to seconds
-      state: "ready",
-      accessCount: 0,
-      tags: [],
-      metadata: {},
-      isBTSP: btsp.detectBTSP(content)
-    }));
+    const now = Date.now();
+    const entries = lines.map((content, index) => {
+      const isBTSP = btsp.detectBTSP(content);
+      return {
+        id: (0, import_node_crypto4.randomUUID)(),
+        content,
+        hash: hashContent(content),
+        timestamp: now + index,
+        // Unique timestamps preserve ordering
+        score: isBTSP ? 1 : 0.5,
+        ttl: config.decay.defaultTTL * 3600,
+        state: "ready",
+        accessCount: 0,
+        tags: [],
+        metadata: {},
+        isBTSP
+      };
+    });
     const tokensBefore = entries.reduce((sum, e) => sum + estimateTokens(e.content), 0);
     const scoredEntries = entries.map((entry) => ({
       ...entry,
@@ -545,111 +782,6 @@ function createGenericAdapter(memory, config) {
   };
 }
 
-// src/core/budget-pruner.ts
-function createBudgetPruner(config) {
-  const { tokenBudget, decay } = config;
-  const engramScorer = createEngramScorer(decay);
-  function tokenize(text) {
-    return text.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
-  }
-  function calculateTF(term, tokens) {
-    const count = tokens.filter((t) => t === term).length;
-    return Math.sqrt(count);
-  }
-  function calculateIDF(term, allEntries) {
-    const totalDocs = allEntries.length;
-    const docsWithTerm = allEntries.filter((entry) => {
-      const tokens = tokenize(entry.content);
-      return tokens.includes(term);
-    }).length;
-    if (docsWithTerm === 0) return 0;
-    return Math.log(totalDocs / docsWithTerm);
-  }
-  function calculateTFIDF(entry, allEntries) {
-    const tokens = tokenize(entry.content);
-    if (tokens.length === 0) return 0;
-    const uniqueTerms = [...new Set(tokens)];
-    let totalScore = 0;
-    for (const term of uniqueTerms) {
-      const tf = calculateTF(term, tokens);
-      const idf = calculateIDF(term, allEntries);
-      totalScore += tf * idf;
-    }
-    return totalScore / tokens.length;
-  }
-  function getStateMultiplier(entry) {
-    if (entry.isBTSP) return 2;
-    switch (entry.state) {
-      case "active":
-        return 2;
-      case "ready":
-        return 1;
-      case "silent":
-        return 0.5;
-      default:
-        return 1;
-    }
-  }
-  function priorityScore(entry, allEntries) {
-    const tfidf = calculateTFIDF(entry, allEntries);
-    const currentScore = engramScorer.calculateScore(entry);
-    const engramDecay = 1 - currentScore;
-    const stateMultiplier = getStateMultiplier(entry);
-    return tfidf * (1 - engramDecay) * stateMultiplier;
-  }
-  function pruneToFit(entries, budget = tokenBudget) {
-    if (entries.length === 0) {
-      return {
-        kept: [],
-        removed: [],
-        originalTokens: 0,
-        prunedTokens: 0,
-        budgetUtilization: 0
-      };
-    }
-    const originalTokens = entries.reduce((sum, e) => sum + estimateTokens(e.content), 0);
-    const btspEntries = entries.filter((e) => e.isBTSP);
-    const regularEntries = entries.filter((e) => !e.isBTSP);
-    const btspTokens = btspEntries.reduce((sum, e) => sum + estimateTokens(e.content), 0);
-    const scored = regularEntries.map((entry) => ({
-      entry,
-      score: priorityScore(entry, entries),
-      tokens: estimateTokens(entry.content)
-    }));
-    scored.sort((a, b) => b.score - a.score);
-    const kept = [...btspEntries];
-    const removed = [];
-    let currentTokens = btspTokens;
-    for (const item of scored) {
-      if (currentTokens + item.tokens <= budget) {
-        kept.push(item.entry);
-        currentTokens += item.tokens;
-      } else {
-        removed.push(item.entry);
-      }
-    }
-    const budgetUtilization = budget > 0 ? currentTokens / budget : 0;
-    return {
-      kept,
-      removed,
-      originalTokens,
-      prunedTokens: currentTokens,
-      budgetUtilization
-    };
-  }
-  return {
-    pruneToFit,
-    priorityScore
-  };
-}
-function createBudgetPrunerFromConfig(realtimeConfig, decayConfig, statesConfig) {
-  return createBudgetPruner({
-    tokenBudget: realtimeConfig.tokenBudget,
-    decay: decayConfig,
-    states: statesConfig
-  });
-}
-
 // src/core/metrics.ts
 function createMetricsCollector() {
   const optimizations = [];
@@ -683,11 +815,10 @@ function createMetricsCollector() {
       ...metric
     };
   }
-  function calculatePercentile(values, percentile) {
-    if (values.length === 0) return 0;
-    const sorted = [...values].sort((a, b) => a - b);
-    const index = Math.ceil(percentile / 100 * sorted.length) - 1;
-    return sorted[index] || 0;
+  function calculatePercentile(sortedValues, percentile) {
+    if (sortedValues.length === 0) return 0;
+    const index = Math.ceil(percentile / 100 * sortedValues.length) - 1;
+    return sortedValues[index] || 0;
   }
   function getSnapshot() {
     const totalRuns = optimizations.length;
@@ -698,7 +829,7 @@ function createMetricsCollector() {
     );
     const totalTokensBefore = optimizations.reduce((sum, m) => sum + m.tokensBefore, 0);
     const averageReduction = totalTokensBefore > 0 ? totalTokensSaved / totalTokensBefore : 0;
-    const durations = optimizations.map((m) => m.duration);
+    const sortedDurations = optimizations.map((m) => m.duration).sort((a, b) => a - b);
     const totalCacheQueries = cacheHits + cacheMisses;
     const hitRate = totalCacheQueries > 0 ? cacheHits / totalCacheQueries : 0;
     return {
@@ -708,9 +839,9 @@ function createMetricsCollector() {
         totalDuration,
         totalTokensSaved,
         averageReduction,
-        p50Latency: calculatePercentile(durations, 50),
-        p95Latency: calculatePercentile(durations, 95),
-        p99Latency: calculatePercentile(durations, 99)
+        p50Latency: calculatePercentile(sortedDurations, 50),
+        p95Latency: calculatePercentile(sortedDurations, 95),
+        p99Latency: calculatePercentile(sortedDurations, 99)
       },
       cache: {
         hitRate,
@@ -768,9 +899,6 @@ function createIncrementalOptimizer(config) {
     updateCount: 0,
     lastFullOptimization: Date.now()
   };
-  function tokenize(text) {
-    return text.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
-  }
   function updateDocumentFrequency(entries, remove = false) {
     for (const entry of entries) {
       const tokens = tokenize(entry.content);
@@ -793,7 +921,19 @@ function createIncrementalOptimizer(config) {
     if (!cached) return null;
     return cached.entry;
   }
+  const MAX_CACHE_SIZE = 1e4;
   function cacheEntry(entry, score) {
+    if (state.entryCache.size >= MAX_CACHE_SIZE) {
+      const entries = Array.from(state.entryCache.entries());
+      entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+      const toRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
+      for (let i = 0; i < toRemove && i < entries.length; i++) {
+        const entry2 = entries[i];
+        if (entry2) {
+          state.entryCache.delete(entry2[0]);
+        }
+      }
+    }
     state.entryCache.set(entry.hash, {
       entry,
       score,
@@ -920,13 +1060,40 @@ function createIncrementalOptimizer(config) {
       lastFullOptimization: state.lastFullOptimization
     };
   }
+  function serializeState() {
+    const s = getState();
+    return JSON.stringify({
+      entryCache: Array.from(s.entryCache.entries()),
+      documentFrequency: Array.from(s.documentFrequency.entries()),
+      totalDocuments: s.totalDocuments,
+      updateCount: s.updateCount,
+      lastFullOptimization: s.lastFullOptimization
+    });
+  }
+  function deserializeState(json) {
+    try {
+      const parsed = JSON.parse(json);
+      restoreState({
+        entryCache: new Map(parsed.entryCache),
+        documentFrequency: new Map(parsed.documentFrequency),
+        totalDocuments: parsed.totalDocuments,
+        updateCount: parsed.updateCount,
+        lastFullOptimization: parsed.lastFullOptimization
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
   return {
     optimizeIncremental,
     optimizeFull,
     getState,
     restoreState,
     reset,
-    getStats
+    getStats,
+    serializeState,
+    deserializeState
   };
 }
 
@@ -951,9 +1118,22 @@ function createContextPipeline(config) {
     currentEntries = result.kept;
     budgetUtilization = result.budgetUtilization;
     if (currentEntries.length > windowSize) {
-      const sorted = [...currentEntries].sort((a, b) => b.timestamp - a.timestamp);
-      const toKeep = sorted.slice(0, windowSize);
-      const toRemove = sorted.slice(windowSize);
+      const timestamps = currentEntries.map((e) => e.timestamp);
+      const minTs = Math.min(...timestamps);
+      const maxTs = Math.max(...timestamps);
+      const tsRange = maxTs - minTs || 1;
+      const scored = currentEntries.map((entry) => {
+        if (entry.isBTSP) return { entry, hybridScore: 2 };
+        const ageNormalized = (entry.timestamp - minTs) / tsRange;
+        const hybridScore = ageNormalized * 0.4 + entry.score * 0.6;
+        return { entry, hybridScore };
+      });
+      scored.sort((a, b) => {
+        if (b.hybridScore !== a.hybridScore) return b.hybridScore - a.hybridScore;
+        return b.entry.timestamp - a.entry.timestamp;
+      });
+      const toKeep = scored.slice(0, windowSize).map((s) => s.entry);
+      const toRemove = scored.slice(windowSize);
       currentEntries = toKeep;
       evictedEntries += toRemove.length;
     }
@@ -980,32 +1160,638 @@ function createContextPipeline(config) {
         uniqueTerms: optimizerStats.uniqueTerms,
         updateCount: optimizerStats.updateCount
       }
-    };
+    };
+  }
+  function clear() {
+    totalIngested = 0;
+    evictedEntries = 0;
+    currentEntries = [];
+    budgetUtilization = 0;
+    optimizer.reset();
+  }
+  function serializeOptimizerState() {
+    return optimizer.serializeState();
+  }
+  function deserializeOptimizerState(json) {
+    return optimizer.deserializeState(json);
+  }
+  return {
+    serializeOptimizerState,
+    deserializeOptimizerState,
+    ingest,
+    getContext,
+    getEntries,
+    getStats,
+    clear
+  };
+}
+
+// src/core/debt-tracker.ts
+var import_node_crypto5 = require("crypto");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+function createDebtTracker(dbPath) {
+  const db = new import_better_sqlite3.default(dbPath);
+  db.pragma("journal_mode = WAL");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS tech_debt (
+      id TEXT PRIMARY KEY NOT NULL,
+      description TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      repayment_date INTEGER NOT NULL,
+      severity TEXT NOT NULL CHECK(severity IN ('P0', 'P1', 'P2')),
+      token_cost INTEGER NOT NULL DEFAULT 0,
+      files_affected TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open', 'in_progress', 'resolved')),
+      resolution_tokens INTEGER,
+      resolved_at INTEGER
+    );
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_debt_status ON tech_debt(status);
+    CREATE INDEX IF NOT EXISTS idx_debt_severity ON tech_debt(severity);
+    CREATE INDEX IF NOT EXISTS idx_debt_repayment ON tech_debt(repayment_date);
+  `);
+  const insertStmt = db.prepare(`
+    INSERT INTO tech_debt (id, description, created_at, repayment_date, severity, token_cost, files_affected, status)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'open')
+  `);
+  const getStmt = db.prepare("SELECT * FROM tech_debt WHERE id = ?");
+  function rowToDebt(row) {
+    return {
+      id: row["id"],
+      description: row["description"],
+      created_at: row["created_at"],
+      repayment_date: row["repayment_date"],
+      severity: row["severity"],
+      token_cost: row["token_cost"],
+      files_affected: JSON.parse(row["files_affected"] || "[]"),
+      status: row["status"],
+      resolution_tokens: row["resolution_tokens"],
+      resolved_at: row["resolved_at"]
+    };
+  }
+  async function add(debt) {
+    const id = (0, import_node_crypto5.randomUUID)().split("-")[0] || "debt";
+    const created_at = Date.now();
+    insertStmt.run(
+      id,
+      debt.description,
+      created_at,
+      debt.repayment_date,
+      debt.severity,
+      debt.token_cost,
+      JSON.stringify(debt.files_affected)
+    );
+    return {
+      id,
+      created_at,
+      status: "open",
+      description: debt.description,
+      repayment_date: debt.repayment_date,
+      severity: debt.severity,
+      token_cost: debt.token_cost,
+      files_affected: debt.files_affected
+    };
+  }
+  async function list(filter = {}) {
+    let sql = "SELECT * FROM tech_debt WHERE 1=1";
+    const params = [];
+    if (filter.status) {
+      sql += " AND status = ?";
+      params.push(filter.status);
+    }
+    if (filter.severity) {
+      sql += " AND severity = ?";
+      params.push(filter.severity);
+    }
+    if (filter.overdue) {
+      sql += " AND repayment_date < ? AND status != ?";
+      params.push(Date.now());
+      params.push("resolved");
+    }
+    sql += " ORDER BY severity ASC, repayment_date ASC";
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToDebt);
+  }
+  async function get(id) {
+    const row = getStmt.get(id);
+    if (!row) return null;
+    return rowToDebt(row);
+  }
+  async function resolve2(id, resolutionTokens) {
+    const result = db.prepare(
+      "UPDATE tech_debt SET status = ?, resolution_tokens = ?, resolved_at = ? WHERE id = ?"
+    ).run("resolved", resolutionTokens ?? null, Date.now(), id);
+    if (result.changes === 0) {
+      throw new Error(`Debt not found: ${id}`);
+    }
+  }
+  async function start(id) {
+    const result = db.prepare("UPDATE tech_debt SET status = ? WHERE id = ?").run("in_progress", id);
+    if (result.changes === 0) {
+      throw new Error(`Debt not found: ${id}`);
+    }
+  }
+  async function remove(id) {
+    db.prepare("DELETE FROM tech_debt WHERE id = ?").run(id);
+  }
+  async function stats() {
+    const all = db.prepare("SELECT * FROM tech_debt").all();
+    const debts = all.map(rowToDebt);
+    const now = Date.now();
+    const open = debts.filter((d) => d.status === "open");
+    const inProgress = debts.filter((d) => d.status === "in_progress");
+    const resolved = debts.filter((d) => d.status === "resolved");
+    const overdue = debts.filter((d) => d.status !== "resolved" && d.repayment_date < now);
+    const totalTokenCost = debts.reduce((sum, d) => sum + d.token_cost, 0);
+    const resolvedTokenCost = resolved.reduce(
+      (sum, d) => sum + (d.resolution_tokens || d.token_cost),
+      0
+    );
+    const resolvedOnTime = resolved.filter(
+      (d) => d.resolved_at && d.resolved_at <= d.repayment_date
+    ).length;
+    const repaymentRate = resolved.length > 0 ? resolvedOnTime / resolved.length : 0;
+    return {
+      total: debts.length,
+      open: open.length,
+      in_progress: inProgress.length,
+      resolved: resolved.length,
+      overdue: overdue.length,
+      totalTokenCost,
+      resolvedTokenCost,
+      repaymentRate
+    };
+  }
+  async function getCritical() {
+    const rows = db.prepare(
+      "SELECT * FROM tech_debt WHERE severity = 'P0' AND status != 'resolved' ORDER BY repayment_date ASC"
+    ).all();
+    return rows.map(rowToDebt);
+  }
+  async function close() {
+    db.close();
+  }
+  return {
+    add,
+    list,
+    get,
+    resolve: resolve2,
+    start,
+    remove,
+    stats,
+    getCritical,
+    close
+  };
+}
+
+// src/core/dependency-graph.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var IMPORT_PATTERNS = [
+  // import { Foo, Bar } from './module'
+  /import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g,
+  // import Foo from './module'
+  /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g,
+  // import * as Foo from './module'
+  /import\s+\*\s+as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g,
+  // import './module' (side-effect)
+  /import\s+['"]([^'"]+)['"]/g,
+  // require('./module')
+  /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+];
+var EXPORT_PATTERNS = [
+  // export { Foo, Bar }
+  /export\s+\{([^}]+)\}/g,
+  // export function/class/const/let/var/type/interface
+  /export\s+(?:default\s+)?(?:function|class|const|let|var|type|interface|enum)\s+(\w+)/g,
+  // export default
+  /export\s+default\s+/g
+];
+function parseImports(content, filePath) {
+  const edges = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const pattern of IMPORT_PATTERNS) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    const matches = [...content.matchAll(regex)];
+    for (const match of matches) {
+      if (pattern.source.includes("from")) {
+        const symbolsRaw = match[1] || "";
+        const target = match[2] || "";
+        if (!target || target.startsWith(".") === false && !target.startsWith("/")) {
+          continue;
+        }
+        const symbols = symbolsRaw.split(",").map(
+          (s) => s.trim().split(/\s+as\s+/)[0]?.trim() || ""
+        ).filter(Boolean);
+        const key = `${filePath}->${target}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          edges.push({ source: filePath, target, symbols });
+        }
+      } else if (pattern.source.includes("require")) {
+        const target = match[1] || "";
+        if (!target || !target.startsWith(".") && !target.startsWith("/")) {
+          continue;
+        }
+        const key = `${filePath}->${target}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          edges.push({ source: filePath, target, symbols: [] });
+        }
+      } else {
+        const target = match[1] || "";
+        if (!target || !target.startsWith(".") && !target.startsWith("/")) {
+          continue;
+        }
+        const key = `${filePath}->${target}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          edges.push({ source: filePath, target, symbols: [] });
+        }
+      }
+    }
+  }
+  return edges;
+}
+function parseExports(content) {
+  const exportsList = [];
+  for (const pattern of EXPORT_PATTERNS) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    const matches = [...content.matchAll(regex)];
+    for (const match of matches) {
+      if (match[1]) {
+        const symbols = match[1].split(",").map(
+          (s) => s.trim().split(/\s+as\s+/)[0]?.trim() || ""
+        ).filter(Boolean);
+        exportsList.push(...symbols);
+      } else {
+        exportsList.push("default");
+      }
+    }
+  }
+  return [...new Set(exportsList)];
+}
+function resolveImportPath(importPath, fromFile, projectRoot, extensions) {
+  const cleanImport = importPath.replace(/\.(js|ts|tsx|jsx)$/, "");
+  const baseDir = (0, import_node_path.join)(projectRoot, fromFile, "..");
+  const candidates = [
+    ...extensions.map((ext) => (0, import_node_path.resolve)(baseDir, `${cleanImport}${ext}`)),
+    ...extensions.map((ext) => (0, import_node_path.resolve)(baseDir, cleanImport, `index${ext}`))
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs.existsSync)(candidate)) {
+      return (0, import_node_path.relative)(projectRoot, candidate).replace(/\\/g, "/");
+    }
+  }
+  return null;
+}
+function collectFiles(dir, projectRoot, extensions, ignoreDirs) {
+  const files = [];
+  try {
+    const entries = (0, import_node_fs.readdirSync)(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = (0, import_node_path.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!ignoreDirs.includes(entry.name)) {
+          files.push(...collectFiles(fullPath, projectRoot, extensions, ignoreDirs));
+        }
+      } else if (entry.isFile() && extensions.includes((0, import_node_path.extname)(entry.name))) {
+        files.push((0, import_node_path.relative)(projectRoot, fullPath).replace(/\\/g, "/"));
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+function createDependencyGraph(config) {
+  const {
+    projectRoot,
+    maxDepth = 50,
+    extensions = [".ts", ".tsx", ".js", ".jsx"],
+    ignoreDirs = ["node_modules", "dist", ".git", ".sparn", "coverage"]
+  } = config;
+  const nodes = /* @__PURE__ */ new Map();
+  let built = false;
+  async function build() {
+    nodes.clear();
+    const files = collectFiles(projectRoot, projectRoot, extensions, ignoreDirs);
+    for (const filePath of files) {
+      const fullPath = (0, import_node_path.join)(projectRoot, filePath);
+      try {
+        const content = (0, import_node_fs.readFileSync)(fullPath, "utf-8");
+        const stat = (0, import_node_fs.statSync)(fullPath);
+        const exports2 = parseExports(content);
+        const imports = parseImports(content, filePath);
+        const resolvedImports = [];
+        for (const imp of imports) {
+          const resolved = resolveImportPath(imp.target, filePath, projectRoot, extensions);
+          if (resolved) {
+            resolvedImports.push({ ...imp, target: resolved });
+          }
+        }
+        nodes.set(filePath, {
+          filePath,
+          exports: exports2,
+          imports: resolvedImports,
+          callers: [],
+          // Populated in second pass
+          engram_score: 0,
+          lastModified: stat.mtimeMs,
+          tokenEstimate: estimateTokens(content)
+        });
+      } catch {
+      }
+    }
+    for (const [filePath, node] of nodes) {
+      for (const imp of node.imports) {
+        const targetNode = nodes.get(imp.target);
+        if (targetNode && !targetNode.callers.includes(filePath)) {
+          targetNode.callers.push(filePath);
+        }
+      }
+    }
+    built = true;
+    return nodes;
+  }
+  async function analyze() {
+    if (!built) await build();
+    const entryPoints = [];
+    const orphans = [];
+    const callerCounts = /* @__PURE__ */ new Map();
+    for (const [filePath, node] of nodes) {
+      if (node.callers.length === 0 && node.imports.length > 0) {
+        entryPoints.push(filePath);
+      }
+      if (node.callers.length === 0 && node.imports.length === 0) {
+        orphans.push(filePath);
+      }
+      callerCounts.set(filePath, node.callers.length);
+    }
+    const sortedByCallers = [...callerCounts.entries()].sort((a, b) => b[1] - a[1]).filter(([, count]) => count > 0);
+    const hotPaths = sortedByCallers.slice(0, 10).map(([path]) => path);
+    const totalTokens = [...nodes.values()].reduce((sum, n) => sum + n.tokenEstimate, 0);
+    const hotPathTokens = hotPaths.reduce(
+      (sum, path) => sum + (nodes.get(path)?.tokenEstimate || 0),
+      0
+    );
+    return {
+      entryPoints,
+      hotPaths,
+      orphans,
+      totalTokens,
+      optimizedTokens: hotPathTokens
+    };
+  }
+  async function focus(pattern) {
+    if (!built) await build();
+    const matching = /* @__PURE__ */ new Map();
+    const lowerPattern = pattern.toLowerCase();
+    for (const [filePath, node] of nodes) {
+      if (filePath.toLowerCase().includes(lowerPattern)) {
+        matching.set(filePath, node);
+        for (const imp of node.imports) {
+          const depNode = nodes.get(imp.target);
+          if (depNode) {
+            matching.set(imp.target, depNode);
+          }
+        }
+        for (const caller of node.callers) {
+          const callerNode = nodes.get(caller);
+          if (callerNode) {
+            matching.set(caller, callerNode);
+          }
+        }
+      }
+    }
+    return matching;
+  }
+  async function getFilesFromEntry(entryPoint, depth = maxDepth) {
+    if (!built) await build();
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [{ path: entryPoint, depth: 0 }];
+    while (queue.length > 0) {
+      const item = queue.shift();
+      if (!item) break;
+      if (visited.has(item.path) || item.depth > depth) continue;
+      visited.add(item.path);
+      const node = nodes.get(item.path);
+      if (node) {
+        for (const imp of node.imports) {
+          if (!visited.has(imp.target)) {
+            queue.push({ path: imp.target, depth: item.depth + 1 });
+          }
+        }
+      }
+    }
+    return [...visited];
+  }
+  function getNodes() {
+    return nodes;
+  }
+  return {
+    build,
+    analyze,
+    focus,
+    getFilesFromEntry,
+    getNodes
+  };
+}
+
+// src/core/docs-generator.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+function detectEntryPoints(projectRoot) {
+  const entries = [];
+  const candidates = [
+    { path: "src/index.ts", desc: "Library API" },
+    { path: "src/cli/index.ts", desc: "CLI entry point" },
+    { path: "src/daemon/index.ts", desc: "Daemon process" },
+    { path: "src/mcp/index.ts", desc: "MCP server" },
+    { path: "src/main.ts", desc: "Main entry" },
+    { path: "src/app.ts", desc: "App entry" },
+    { path: "src/server.ts", desc: "Server entry" },
+    { path: "index.ts", desc: "Root entry" },
+    { path: "index.js", desc: "Root entry" }
+  ];
+  for (const c of candidates) {
+    if ((0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, c.path))) {
+      entries.push({ path: c.path, description: c.desc });
+    }
+  }
+  return entries;
+}
+function scanModules(dir, projectRoot, ignoreDirs = ["node_modules", "dist", ".git", ".sparn", "coverage"]) {
+  const modules = [];
+  try {
+    const entries = (0, import_node_fs2.readdirSync)(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = (0, import_node_path2.join)(dir, entry.name);
+      if (entry.isDirectory() && !ignoreDirs.includes(entry.name)) {
+        modules.push(...scanModules(fullPath, projectRoot, ignoreDirs));
+      } else if (entry.isFile() && [".ts", ".tsx", ".js", ".jsx"].includes((0, import_node_path2.extname)(entry.name))) {
+        try {
+          const content = (0, import_node_fs2.readFileSync)(fullPath, "utf-8");
+          modules.push({
+            path: (0, import_node_path2.relative)(projectRoot, fullPath).replace(/\\/g, "/"),
+            lines: content.split("\n").length
+          });
+        } catch {
+        }
+      }
+    }
+  } catch {
   }
-  function clear() {
-    totalIngested = 0;
-    evictedEntries = 0;
-    currentEntries = [];
-    budgetUtilization = 0;
-    optimizer.reset();
+  return modules;
+}
+function readPackageJson(projectRoot) {
+  const pkgPath = (0, import_node_path2.join)(projectRoot, "package.json");
+  if (!(0, import_node_fs2.existsSync)(pkgPath)) return null;
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(pkgPath, "utf-8"));
+  } catch {
+    return null;
   }
-  return {
-    ingest,
-    getContext,
-    getEntries,
-    getStats,
-    clear
+}
+function detectStack(projectRoot) {
+  const stack = [];
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg) return stack;
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
   };
+  if (allDeps["typescript"]) stack.push("TypeScript");
+  if (allDeps["vitest"]) stack.push("Vitest");
+  if (allDeps["@biomejs/biome"]) stack.push("Biome");
+  if (allDeps["eslint"]) stack.push("ESLint");
+  if (allDeps["prettier"]) stack.push("Prettier");
+  if (allDeps["react"]) stack.push("React");
+  if (allDeps["next"]) stack.push("Next.js");
+  if (allDeps["express"]) stack.push("Express");
+  if (allDeps["commander"]) stack.push("Commander.js CLI");
+  if (allDeps["better-sqlite3"]) stack.push("SQLite (better-sqlite3)");
+  if (allDeps["zod"]) stack.push("Zod validation");
+  return stack;
+}
+function createDocsGenerator(config) {
+  const { projectRoot, includeGraph = true } = config;
+  async function generate(graph) {
+    const lines = [];
+    const pkg = readPackageJson(projectRoot);
+    const projectName = pkg?.name || "Project";
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    lines.push(`# ${projectName} \u2014 Developer Guide`);
+    lines.push(`<!-- Auto-generated by Sparn v1.3.0 \u2014 ${now} -->`);
+    lines.push("");
+    const stack = detectStack(projectRoot);
+    if (stack.length > 0) {
+      lines.push(`**Stack**: ${stack.join(", ")}`);
+      lines.push("");
+    }
+    if (pkg?.scripts) {
+      lines.push("## Commands");
+      lines.push("");
+      const important = ["build", "dev", "test", "lint", "typecheck", "start"];
+      for (const cmd of important) {
+        if (pkg.scripts[cmd]) {
+          lines.push(`- \`npm run ${cmd}\` \u2014 \`${pkg.scripts[cmd]}\``);
+        }
+      }
+      lines.push("");
+    }
+    const entryPoints = detectEntryPoints(projectRoot);
+    if (entryPoints.length > 0) {
+      lines.push("## Entry Points");
+      lines.push("");
+      for (const ep of entryPoints) {
+        lines.push(`- \`${ep.path}\` \u2014 ${ep.description}`);
+      }
+      lines.push("");
+    }
+    const srcDir = (0, import_node_path2.join)(projectRoot, "src");
+    if ((0, import_node_fs2.existsSync)(srcDir)) {
+      const modules = scanModules(srcDir, projectRoot);
+      const dirGroups = /* @__PURE__ */ new Map();
+      for (const mod of modules) {
+        const parts = mod.path.split("/");
+        const dir = parts.length > 2 ? parts.slice(0, 2).join("/") : parts[0] || "";
+        if (!dirGroups.has(dir)) {
+          dirGroups.set(dir, []);
+        }
+        dirGroups.get(dir)?.push({
+          file: parts[parts.length - 1] || mod.path,
+          lines: mod.lines
+        });
+      }
+      lines.push("## Structure");
+      lines.push("");
+      for (const [dir, files] of dirGroups) {
+        lines.push(`### ${dir}/ (${files.length} files)`);
+        const shown = files.slice(0, 8);
+        for (const f of shown) {
+          lines.push(`- \`${f.file}\` (${f.lines}L)`);
+        }
+        if (files.length > 8) {
+          lines.push(`- ... and ${files.length - 8} more`);
+        }
+        lines.push("");
+      }
+    }
+    if (includeGraph && graph) {
+      try {
+        const analysis = await graph.analyze();
+        lines.push("## Hot Dependencies (most imported)");
+        lines.push("");
+        for (const path of analysis.hotPaths.slice(0, 5)) {
+          const node = graph.getNodes().get(path);
+          const callerCount = node?.callers.length || 0;
+          lines.push(`- \`${path}\` (imported by ${callerCount} modules)`);
+        }
+        lines.push("");
+        if (analysis.orphans.length > 0) {
+          lines.push(
+            `**Orphaned files** (${analysis.orphans.length}): ${analysis.orphans.slice(0, 3).join(", ")}${analysis.orphans.length > 3 ? "..." : ""}`
+          );
+          lines.push("");
+        }
+        lines.push(
+          `**Total tokens**: ${analysis.totalTokens.toLocaleString()} | **Hot path tokens**: ${analysis.optimizedTokens.toLocaleString()}`
+        );
+        lines.push("");
+      } catch {
+      }
+    }
+    const sparnConfigPath = (0, import_node_path2.join)(projectRoot, ".sparn", "config.yaml");
+    if ((0, import_node_fs2.existsSync)(sparnConfigPath)) {
+      lines.push("## Sparn Optimization");
+      lines.push("");
+      lines.push("Sparn is active in this project. Key features:");
+      lines.push("- Context optimization (60-70% token reduction)");
+      lines.push("- Use `sparn search` before reading files");
+      lines.push("- Use `sparn graph` to understand dependencies");
+      lines.push("- Use `sparn plan` for planning, `sparn exec` for execution");
+      lines.push("");
+    }
+    if (config.customSections) {
+      for (const section of config.customSections) {
+        lines.push(section);
+        lines.push("");
+      }
+    }
+    return lines.join("\n");
+  }
+  return { generate };
 }
 
 // src/core/kv-memory.ts
-var import_node_fs = require("fs");
-var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var import_node_fs3 = require("fs");
+var import_better_sqlite32 = __toESM(require("better-sqlite3"), 1);
 function createBackup(dbPath) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backupPath = `${dbPath}.backup-${timestamp}`;
   try {
-    (0, import_node_fs.copyFileSync)(dbPath, backupPath);
+    (0, import_node_fs3.copyFileSync)(dbPath, backupPath);
     console.log(`\u2713 Database backed up to: ${backupPath}`);
     return backupPath;
   } catch (error) {
@@ -1016,29 +1802,30 @@ function createBackup(dbPath) {
 async function createKVMemory(dbPath) {
   let db;
   try {
-    db = new import_better_sqlite3.default(dbPath);
+    db = new import_better_sqlite32.default(dbPath);
     const integrityCheck = db.pragma("quick_check", { simple: true });
     if (integrityCheck !== "ok") {
       console.error("\u26A0 Database corruption detected!");
-      if ((0, import_node_fs.existsSync)(dbPath)) {
+      db.close();
+      if ((0, import_node_fs3.existsSync)(dbPath)) {
         const backupPath = createBackup(dbPath);
         if (backupPath) {
           console.log(`Backup created at: ${backupPath}`);
         }
       }
       console.log("Attempting database recovery...");
-      db.close();
-      db = new import_better_sqlite3.default(dbPath);
+      db = new import_better_sqlite32.default(dbPath);
     }
   } catch (error) {
     console.error("\u26A0 Database error detected:", error);
-    if ((0, import_node_fs.existsSync)(dbPath)) {
+    if ((0, import_node_fs3.existsSync)(dbPath)) {
       createBackup(dbPath);
       console.log("Creating new database...");
     }
-    db = new import_better_sqlite3.default(dbPath);
+    db = new import_better_sqlite32.default(dbPath);
   }
   db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
   db.exec(`
     CREATE TABLE IF NOT EXISTS entries_index (
       id TEXT PRIMARY KEY NOT NULL,
@@ -1078,6 +1865,36 @@ async function createKVMemory(dbPath) {
     CREATE INDEX IF NOT EXISTS idx_entries_timestamp ON entries_index(timestamp DESC);
     CREATE INDEX IF NOT EXISTS idx_stats_timestamp ON optimization_stats(timestamp DESC);
   `);
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(id, content, tokenize='porter');
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_fts_insert
+    AFTER INSERT ON entries_value
+    BEGIN
+      INSERT OR REPLACE INTO entries_fts(id, content) VALUES (NEW.id, NEW.content);
+    END;
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_fts_delete
+    AFTER DELETE ON entries_value
+    BEGIN
+      DELETE FROM entries_fts WHERE id = OLD.id;
+    END;
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_fts_update
+    AFTER UPDATE ON entries_value
+    BEGIN
+      DELETE FROM entries_fts WHERE id = OLD.id;
+      INSERT INTO entries_fts(id, content) VALUES (NEW.id, NEW.content);
+    END;
+  `);
+  db.exec(`
+    INSERT OR IGNORE INTO entries_fts(id, content)
+    SELECT id, content FROM entries_value
+    WHERE id NOT IN (SELECT id FROM entries_fts);
+  `);
   const putIndexStmt = db.prepare(`
     INSERT OR REPLACE INTO entries_index
     (id, hash, timestamp, score, ttl, state, accessCount, isBTSP)
@@ -1166,14 +1983,20 @@ async function createKVMemory(dbPath) {
         sql += " AND i.isBTSP = ?";
         params.push(filters.isBTSP ? 1 : 0);
       }
+      if (filters.tags && filters.tags.length > 0) {
+        for (const tag of filters.tags) {
+          sql += " AND v.tags LIKE ?";
+          params.push(`%"${tag}"%`);
+        }
+      }
       sql += " ORDER BY i.score DESC";
       if (filters.limit) {
         sql += " LIMIT ?";
         params.push(filters.limit);
-      }
-      if (filters.offset) {
-        sql += " OFFSET ?";
-        params.push(filters.offset);
+        if (filters.offset) {
+          sql += " OFFSET ?";
+          params.push(filters.offset);
+        }
       }
       const stmt = db.prepare(sql);
       const rows = stmt.all(...params);
@@ -1208,7 +2031,22 @@ async function createKVMemory(dbPath) {
     },
     async compact() {
       const before = db.prepare("SELECT COUNT(*) as count FROM entries_index").get();
-      db.exec("DELETE FROM entries_index WHERE ttl <= 0");
+      const now = Date.now();
+      db.prepare("DELETE FROM entries_index WHERE isBTSP = 0 AND (timestamp + ttl * 1000) < ?").run(
+        now
+      );
+      db.exec("DELETE FROM entries_index WHERE isBTSP = 0 AND ttl <= 0");
+      const candidates = db.prepare("SELECT id, timestamp, ttl FROM entries_index WHERE isBTSP = 0").all();
+      for (const row of candidates) {
+        const ageSeconds = Math.max(0, (now - row.timestamp) / 1e3);
+        const ttlSeconds = row.ttl;
+        if (ttlSeconds <= 0) continue;
+        const decay = 1 - Math.exp(-ageSeconds / ttlSeconds);
+        if (decay >= 0.95) {
+          db.prepare("DELETE FROM entries_index WHERE id = ?").run(row.id);
+        }
+      }
+      db.exec("DELETE FROM entries_value WHERE id NOT IN (SELECT id FROM entries_index)");
       db.exec("VACUUM");
       const after = db.prepare("SELECT COUNT(*) as count FROM entries_index").get();
       return before.count - after.count;
@@ -1228,6 +2066,9 @@ async function createKVMemory(dbPath) {
         stats.entries_pruned,
         stats.duration_ms
       );
+      db.prepare(
+        "DELETE FROM optimization_stats WHERE id NOT IN (SELECT id FROM optimization_stats ORDER BY timestamp DESC LIMIT 1000)"
+      ).run();
     },
     async getOptimizationStats() {
       const stmt = db.prepare(`
@@ -1240,7 +2081,286 @@ async function createKVMemory(dbPath) {
     },
     async clearOptimizationStats() {
       db.exec("DELETE FROM optimization_stats");
+    },
+    async searchFTS(query, limit = 10) {
+      if (!query || query.trim().length === 0) return [];
+      const sanitized = query.replace(/[{}()[\]"':*^~]/g, " ").trim();
+      if (sanitized.length === 0) return [];
+      const stmt = db.prepare(`
+        SELECT
+          f.id, f.content, rank,
+          i.hash, i.timestamp, i.score, i.ttl, i.state, i.accessCount, i.isBTSP,
+          v.tags, v.metadata
+        FROM entries_fts f
+        JOIN entries_index i ON f.id = i.id
+        JOIN entries_value v ON f.id = v.id
+        WHERE entries_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      `);
+      try {
+        const rows = stmt.all(sanitized, limit);
+        return rows.map((r) => ({
+          entry: {
+            id: r.id,
+            content: r.content,
+            hash: r.hash,
+            timestamp: r.timestamp,
+            score: r.score,
+            ttl: r.ttl,
+            state: r.state,
+            accessCount: r.accessCount,
+            tags: r.tags ? JSON.parse(r.tags) : [],
+            metadata: r.metadata ? JSON.parse(r.metadata) : {},
+            isBTSP: r.isBTSP === 1
+          },
+          rank: r.rank
+        }));
+      } catch {
+        return [];
+      }
+    }
+  };
+}
+
+// src/core/search-engine.ts
+var import_node_child_process = require("child_process");
+var import_node_fs4 = require("fs");
+var import_node_path3 = require("path");
+var import_better_sqlite33 = __toESM(require("better-sqlite3"), 1);
+function hasRipgrep() {
+  try {
+    (0, import_node_child_process.execSync)("rg --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ripgrepSearch(query, projectRoot, opts = {}) {
+  try {
+    const args = ["--line-number", "--no-heading", "--color=never"];
+    if (opts.fileGlob) {
+      args.push("--glob", opts.fileGlob);
+    }
+    args.push(
+      "--glob",
+      "!node_modules",
+      "--glob",
+      "!dist",
+      "--glob",
+      "!.git",
+      "--glob",
+      "!.sparn",
+      "--glob",
+      "!coverage"
+    );
+    const maxResults = opts.maxResults || 20;
+    args.push("--max-count", String(maxResults));
+    if (opts.includeContext) {
+      args.push("-C", "2");
+    }
+    args.push("--", query, projectRoot);
+    const output = (0, import_node_child_process.execFileSync)("rg", args, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 });
+    const results = [];
+    const lines = output.split("\n").filter(Boolean);
+    for (const line of lines) {
+      const match = line.match(/^(.+?):(\d+):(.*)/);
+      if (match) {
+        const filePath = (0, import_node_path3.relative)(projectRoot, match[1] || "").replace(/\\/g, "/");
+        const lineNumber = Number.parseInt(match[2] || "0", 10);
+        const content = (match[3] || "").trim();
+        results.push({
+          filePath,
+          lineNumber,
+          content,
+          score: 0.8,
+          // Exact match gets high base score
+          context: [],
+          engram_score: 0
+        });
+      }
+    }
+    return results.slice(0, maxResults);
+  } catch {
+    return [];
+  }
+}
+function collectIndexableFiles(dir, projectRoot, ignoreDirs = ["node_modules", "dist", ".git", ".sparn", "coverage"], exts = [".ts", ".tsx", ".js", ".jsx", ".json", ".md", ".yaml", ".yml"]) {
+  const files = [];
+  try {
+    const entries = (0, import_node_fs4.readdirSync)(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = (0, import_node_path3.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!ignoreDirs.includes(entry.name)) {
+          files.push(...collectIndexableFiles(fullPath, projectRoot, ignoreDirs, exts));
+        }
+      } else if (entry.isFile() && exts.includes((0, import_node_path3.extname)(entry.name))) {
+        try {
+          const stat = (0, import_node_fs4.statSync)(fullPath);
+          if (stat.size < 100 * 1024) {
+            files.push((0, import_node_path3.relative)(projectRoot, fullPath).replace(/\\/g, "/"));
+          }
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+function createSearchEngine(dbPath) {
+  let db = null;
+  let projectRoot = "";
+  const rgAvailable = hasRipgrep();
+  async function init(root) {
+    if (db) {
+      try {
+        db.close();
+      } catch {
+      }
+    }
+    projectRoot = root;
+    db = new import_better_sqlite33.default(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+        filepath, line_number, content, tokenize='porter'
+      );
+    `);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS search_meta (
+        filepath TEXT PRIMARY KEY,
+        mtime INTEGER NOT NULL,
+        indexed_at INTEGER NOT NULL
+      );
+    `);
+  }
+  async function index(paths) {
+    if (!db) throw new Error("Search engine not initialized. Call init() first.");
+    const startTime = Date.now();
+    const filesToIndex = paths || collectIndexableFiles(projectRoot, projectRoot);
+    let filesIndexed = 0;
+    let totalLines = 0;
+    const insertStmt = db.prepare(
+      "INSERT INTO search_index(filepath, line_number, content) VALUES (?, ?, ?)"
+    );
+    const metaStmt = db.prepare(
+      "INSERT OR REPLACE INTO search_meta(filepath, mtime, indexed_at) VALUES (?, ?, ?)"
+    );
+    const checkMeta = db.prepare("SELECT mtime FROM search_meta WHERE filepath = ?");
+    const deleteFile = db.prepare("DELETE FROM search_index WHERE filepath = ?");
+    const transaction = db.transaction(() => {
+      for (const filePath of filesToIndex) {
+        const fullPath = (0, import_node_path3.join)(projectRoot, filePath);
+        if (!(0, import_node_fs4.existsSync)(fullPath)) continue;
+        try {
+          const stat = (0, import_node_fs4.statSync)(fullPath);
+          const existing = checkMeta.get(filePath);
+          if (existing && existing.mtime >= stat.mtimeMs) {
+            continue;
+          }
+          deleteFile.run(filePath);
+          const content = (0, import_node_fs4.readFileSync)(fullPath, "utf-8");
+          const lines = content.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line && line.trim().length > 0) {
+              insertStmt.run(filePath, i + 1, line);
+              totalLines++;
+            }
+          }
+          metaStmt.run(filePath, stat.mtimeMs, Date.now());
+          filesIndexed++;
+        } catch {
+        }
+      }
+    });
+    transaction();
+    return {
+      filesIndexed,
+      totalLines,
+      duration: Date.now() - startTime
+    };
+  }
+  async function search(query, opts = {}) {
+    if (!db) throw new Error("Search engine not initialized. Call init() first.");
+    const maxResults = opts.maxResults || 10;
+    const results = [];
+    const seen = /* @__PURE__ */ new Set();
+    try {
+      const ftsQuery = query.replace(/['"*(){}[\]^~\\:]/g, " ").trim().split(/\s+/).filter((w) => w.length > 0).map((w) => `content:${w}`).join(" ");
+      if (ftsQuery.length > 0) {
+        let sql = `
+          SELECT filepath, line_number, content, rank
+          FROM search_index
+          WHERE search_index MATCH ?
+        `;
+        const params = [ftsQuery];
+        if (opts.fileGlob) {
+          const likePattern = opts.fileGlob.replace(/\*/g, "%").replace(/\?/g, "_");
+          sql += " AND filepath LIKE ?";
+          params.push(likePattern);
+        }
+        sql += " ORDER BY rank LIMIT ?";
+        params.push(maxResults * 2);
+        const rows = db.prepare(sql).all(...params);
+        for (const row of rows) {
+          const key = `${row.filepath}:${row.line_number}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            const score = Math.min(1, Math.max(0, 1 + row.rank / 10));
+            const context = [];
+            if (opts.includeContext) {
+              const contextRows = db.prepare(
+                `SELECT content FROM search_index WHERE filepath = ? AND CAST(line_number AS INTEGER) BETWEEN ? AND ? ORDER BY CAST(line_number AS INTEGER)`
+              ).all(row.filepath, row.line_number - 2, row.line_number + 2);
+              context.push(...contextRows.map((r) => r.content));
+            }
+            results.push({
+              filePath: row.filepath,
+              lineNumber: row.line_number,
+              content: row.content,
+              score,
+              context,
+              engram_score: 0
+            });
+          }
+        }
+      }
+    } catch {
     }
+    if (rgAvailable && opts.useRipgrep !== false) {
+      const rgResults = ripgrepSearch(query, projectRoot, opts);
+      for (const result of rgResults) {
+        const key = `${result.filePath}:${result.lineNumber}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          results.push(result);
+        }
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+  }
+  async function refresh() {
+    if (!db) throw new Error("Search engine not initialized. Call init() first.");
+    db.exec("DELETE FROM search_index");
+    db.exec("DELETE FROM search_meta");
+    return index();
+  }
+  async function close() {
+    if (db) {
+      db.close();
+      db = null;
+    }
+  }
+  return {
+    init,
+    index,
+    search,
+    refresh,
+    close
   };
 }
 
@@ -1335,13 +2455,15 @@ function createSleepCompressor() {
   function cosineSimilarity(text1, text2) {
     const words1 = tokenize(text1);
     const words2 = tokenize(text2);
-    const vocab = /* @__PURE__ */ new Set([...words1, ...words2]);
     const vec1 = {};
     const vec2 = {};
-    for (const word of vocab) {
-      vec1[word] = words1.filter((w) => w === word).length;
-      vec2[word] = words2.filter((w) => w === word).length;
+    for (const word of words1) {
+      vec1[word] = (vec1[word] ?? 0) + 1;
+    }
+    for (const word of words2) {
+      vec2[word] = (vec2[word] ?? 0) + 1;
     }
+    const vocab = /* @__PURE__ */ new Set([...words1, ...words2]);
     let dotProduct = 0;
     let mag1 = 0;
     let mag2 = 0;
@@ -1357,9 +2479,6 @@ function createSleepCompressor() {
     if (mag1 === 0 || mag2 === 0) return 0;
     return dotProduct / (mag1 * mag2);
   }
-  function tokenize(text) {
-    return text.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
-  }
   return {
     consolidate,
     findDuplicates,
@@ -1367,18 +2486,164 @@ function createSleepCompressor() {
   };
 }
 
+// src/core/workflow-planner.ts
+var import_node_crypto6 = require("crypto");
+var import_node_fs5 = require("fs");
+var import_node_path4 = require("path");
+function createWorkflowPlanner(projectRoot) {
+  const plansDir = (0, import_node_path4.join)(projectRoot, ".sparn", "plans");
+  if (!(0, import_node_fs5.existsSync)(plansDir)) {
+    (0, import_node_fs5.mkdirSync)(plansDir, { recursive: true });
+  }
+  function sanitizeId(id) {
+    return id.replace(/[/\\:.]/g, "").replace(/\.\./g, "");
+  }
+  function planPath(planId) {
+    const safeId = sanitizeId(planId);
+    if (!safeId) throw new Error("Invalid plan ID");
+    return (0, import_node_path4.join)(plansDir, `plan-${safeId}.json`);
+  }
+  async function createPlan(taskDescription, filesNeeded, searchQueries, steps, tokenBudget = { planning: 0, estimated_execution: 0, max_file_reads: 5 }) {
+    const id = (0, import_node_crypto6.randomUUID)().split("-")[0] || "plan";
+    const plan = {
+      id,
+      created_at: Date.now(),
+      task_description: taskDescription,
+      steps: steps.map((s) => ({ ...s, status: "pending" })),
+      token_budget: tokenBudget,
+      files_needed: filesNeeded,
+      search_queries: searchQueries,
+      status: "draft"
+    };
+    (0, import_node_fs5.writeFileSync)(planPath(id), JSON.stringify(plan, null, 2), "utf-8");
+    return plan;
+  }
+  async function loadPlan(planId) {
+    const path = planPath(planId);
+    if (!(0, import_node_fs5.existsSync)(path)) return null;
+    try {
+      return JSON.parse((0, import_node_fs5.readFileSync)(path, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+  async function listPlans() {
+    if (!(0, import_node_fs5.existsSync)(plansDir)) return [];
+    const files = (0, import_node_fs5.readdirSync)(plansDir).filter((f) => f.startsWith("plan-") && f.endsWith(".json"));
+    const plans = [];
+    for (const file of files) {
+      try {
+        const plan = JSON.parse((0, import_node_fs5.readFileSync)((0, import_node_path4.join)(plansDir, file), "utf-8"));
+        plans.push({
+          id: plan.id,
+          task: plan.task_description,
+          status: plan.status,
+          created: plan.created_at
+        });
+      } catch {
+      }
+    }
+    return plans.sort((a, b) => b.created - a.created);
+  }
+  async function updateStep(planId, stepOrder, status, result) {
+    const plan = await loadPlan(planId);
+    if (!plan) throw new Error(`Plan ${planId} not found`);
+    const step = plan.steps.find((s) => s.order === stepOrder);
+    if (!step) throw new Error(`Step ${stepOrder} not found in plan ${planId}`);
+    step.status = status;
+    if (result !== void 0) {
+      step.result = result;
+    }
+    (0, import_node_fs5.writeFileSync)(planPath(planId), JSON.stringify(plan, null, 2), "utf-8");
+  }
+  async function startExec(planId) {
+    const plan = await loadPlan(planId);
+    if (!plan) throw new Error(`Plan ${planId} not found`);
+    plan.status = "executing";
+    (0, import_node_fs5.writeFileSync)(planPath(planId), JSON.stringify(plan, null, 2), "utf-8");
+    return {
+      maxFileReads: plan.token_budget.max_file_reads,
+      tokenBudget: plan.token_budget.estimated_execution,
+      allowReplan: false
+    };
+  }
+  async function verify(planId) {
+    const plan = await loadPlan(planId);
+    if (!plan) throw new Error(`Plan ${planId} not found`);
+    let stepsCompleted = 0;
+    let stepsFailed = 0;
+    let stepsSkipped = 0;
+    let tokensUsed = 0;
+    const details = [];
+    for (const step of plan.steps) {
+      switch (step.status) {
+        case "completed":
+          stepsCompleted++;
+          tokensUsed += step.estimated_tokens;
+          break;
+        case "failed":
+          stepsFailed++;
+          break;
+        case "skipped":
+          stepsSkipped++;
+          break;
+        default:
+          break;
+      }
+      details.push({
+        step: step.order,
+        action: step.action,
+        target: step.target,
+        status: step.status
+      });
+    }
+    const totalSteps = plan.steps.length;
+    const success = stepsFailed === 0 && stepsCompleted === totalSteps;
+    const hasInProgress = plan.steps.some(
+      (s) => s.status === "pending" || s.status === "in_progress"
+    );
+    if (!hasInProgress) {
+      plan.status = success ? "completed" : "failed";
+      (0, import_node_fs5.writeFileSync)(planPath(planId), JSON.stringify(plan, null, 2), "utf-8");
+    }
+    return {
+      planId,
+      stepsCompleted,
+      stepsFailed,
+      stepsSkipped,
+      totalSteps,
+      tokensBudgeted: plan.token_budget.estimated_execution,
+      tokensUsed,
+      success,
+      details
+    };
+  }
+  function getPlansDir() {
+    return plansDir;
+  }
+  return {
+    createPlan,
+    loadPlan,
+    listPlans,
+    updateStep,
+    startExec,
+    verify,
+    getPlansDir
+  };
+}
+
 // src/daemon/daemon-process.ts
-var import_node_child_process = require("child_process");
-var import_node_fs2 = require("fs");
-var import_node_path = require("path");
+var import_node_child_process2 = require("child_process");
+var import_node_fs6 = require("fs");
+var import_node_path5 = require("path");
 var import_node_url = require("url");
 function createDaemonCommand() {
   function isDaemonRunning(pidFile) {
-    if (!(0, import_node_fs2.existsSync)(pidFile)) {
+    if (!(0, import_node_fs6.existsSync)(pidFile)) {
       return { running: false };
     }
     try {
-      const pidStr = (0, import_node_fs2.readFileSync)(pidFile, "utf-8").trim();
+      const pidStr = (0, import_node_fs6.readFileSync)(pidFile, "utf-8").trim();
       const pid = Number.parseInt(pidStr, 10);
       if (Number.isNaN(pid)) {
         return { running: false };
@@ -1387,7 +2652,7 @@ function createDaemonCommand() {
         process.kill(pid, 0);
         return { running: true, pid };
       } catch {
-        (0, import_node_fs2.unlinkSync)(pidFile);
+        (0, import_node_fs6.unlinkSync)(pidFile);
         return { running: false };
       }
     } catch {
@@ -1395,15 +2660,15 @@ function createDaemonCommand() {
     }
   }
   function writePidFile(pidFile, pid) {
-    const dir = (0, import_node_path.dirname)(pidFile);
-    if (!(0, import_node_fs2.existsSync)(dir)) {
-      (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+    const dir = (0, import_node_path5.dirname)(pidFile);
+    if (!(0, import_node_fs6.existsSync)(dir)) {
+      (0, import_node_fs6.mkdirSync)(dir, { recursive: true });
     }
-    (0, import_node_fs2.writeFileSync)(pidFile, String(pid), "utf-8");
+    (0, import_node_fs6.writeFileSync)(pidFile, String(pid), "utf-8");
   }
   function removePidFile(pidFile) {
-    if ((0, import_node_fs2.existsSync)(pidFile)) {
-      (0, import_node_fs2.unlinkSync)(pidFile);
+    if ((0, import_node_fs6.existsSync)(pidFile)) {
+      (0, import_node_fs6.unlinkSync)(pidFile);
     }
   }
   async function start(config) {
@@ -1419,17 +2684,61 @@ function createDaemonCommand() {
     }
     try {
       const __filename2 = (0, import_node_url.fileURLToPath)(importMetaUrl);
-      const __dirname = (0, import_node_path.dirname)(__filename2);
-      const daemonPath = (0, import_node_path.join)(__dirname, "index.js");
-      const child = (0, import_node_child_process.fork)(daemonPath, [], {
+      const __dirname = (0, import_node_path5.dirname)(__filename2);
+      const daemonPath = (0, import_node_path5.join)(__dirname, "..", "daemon", "index.js");
+      const isWindows = process.platform === "win32";
+      const childEnv = {
+        ...process.env,
+        SPARN_CONFIG: JSON.stringify(config),
+        SPARN_PID_FILE: pidFile,
+        SPARN_LOG_FILE: logFile
+      };
+      if (isWindows) {
+        const configFile = (0, import_node_path5.join)((0, import_node_path5.dirname)(pidFile), "daemon-config.json");
+        (0, import_node_fs6.writeFileSync)(configFile, JSON.stringify({ config, pidFile, logFile }), "utf-8");
+        const launcherFile = (0, import_node_path5.join)((0, import_node_path5.dirname)(pidFile), "daemon-launcher.mjs");
+        const launcherCode = [
+          `import { readFileSync } from 'node:fs';`,
+          `const cfg = JSON.parse(readFileSync(${JSON.stringify(configFile)}, 'utf-8'));`,
+          `process.env.SPARN_CONFIG = JSON.stringify(cfg.config);`,
+          `process.env.SPARN_PID_FILE = cfg.pidFile;`,
+          `process.env.SPARN_LOG_FILE = cfg.logFile;`,
+          `await import(${JSON.stringify(`file:///${daemonPath.replace(/\\/g, "/")}`)});`
+        ].join("\n");
+        (0, import_node_fs6.writeFileSync)(launcherFile, launcherCode, "utf-8");
+        const ps = (0, import_node_child_process2.spawn)(
+          "powershell.exe",
+          [
+            "-NoProfile",
+            "-WindowStyle",
+            "Hidden",
+            "-Command",
+            `Start-Process -FilePath '${process.execPath}' -ArgumentList '${launcherFile}' -WindowStyle Hidden`
+          ],
+          { stdio: "ignore", windowsHide: true }
+        );
+        ps.unref();
+        await new Promise((resolve2) => setTimeout(resolve2, 2e3));
+        if ((0, import_node_fs6.existsSync)(pidFile)) {
+          const pid = Number.parseInt((0, import_node_fs6.readFileSync)(pidFile, "utf-8").trim(), 10);
+          if (!Number.isNaN(pid)) {
+            return {
+              success: true,
+              pid,
+              message: `Daemon started (PID ${pid})`
+            };
+          }
+        }
+        return {
+          success: false,
+          message: "Daemon failed to start (no PID file written)",
+          error: "Timeout waiting for daemon PID"
+        };
+      }
+      const child = (0, import_node_child_process2.spawn)(process.execPath, [daemonPath], {
         detached: true,
         stdio: "ignore",
-        env: {
-          ...process.env,
-          SPARN_CONFIG: JSON.stringify(config),
-          SPARN_PID_FILE: pidFile,
-          SPARN_LOG_FILE: logFile
-        }
+        env: childEnv
       });
       child.unref();
       if (child.pid) {
@@ -1463,14 +2772,19 @@ function createDaemonCommand() {
       };
     }
     try {
-      process.kill(status2.pid, "SIGTERM");
+      const isWindows = process.platform === "win32";
+      if (isWindows) {
+        process.kill(status2.pid);
+      } else {
+        process.kill(status2.pid, "SIGTERM");
+      }
       const maxWait = 5e3;
       const interval = 100;
       let waited = 0;
       while (waited < maxWait) {
         try {
           process.kill(status2.pid, 0);
-          await new Promise((resolve) => setTimeout(resolve, interval));
+          await new Promise((resolve2) => setTimeout(resolve2, interval));
           waited += interval;
         } catch {
           removePidFile(pidFile);
@@ -1481,7 +2795,9 @@ function createDaemonCommand() {
         }
       }
       try {
-        process.kill(status2.pid, "SIGKILL");
+        if (!isWindows) {
+          process.kill(status2.pid, "SIGKILL");
+        }
         removePidFile(pidFile);
         return {
           success: true,
@@ -1511,13 +2827,9 @@ function createDaemonCommand() {
         message: "Daemon not running"
       };
     }
-    const metrics = getMetrics().getSnapshot();
     return {
       running: true,
       pid: daemonStatus.pid,
-      uptime: metrics.daemon.uptime,
-      sessionsWatched: metrics.daemon.sessionsWatched,
-      tokensSaved: metrics.optimization.totalTokensSaved,
       message: `Daemon running (PID ${daemonStatus.pid})`
     };
   }
@@ -1529,12 +2841,12 @@ function createDaemonCommand() {
 }
 
 // src/daemon/file-tracker.ts
-var import_node_fs3 = require("fs");
+var import_node_fs7 = require("fs");
 function createFileTracker() {
   const positions = /* @__PURE__ */ new Map();
   function readNewLines(filePath) {
     try {
-      const stats = (0, import_node_fs3.statSync)(filePath);
+      const stats = (0, import_node_fs7.statSync)(filePath);
       const currentSize = stats.size;
       const currentModified = stats.mtimeMs;
       let pos = positions.get(filePath);
@@ -1555,9 +2867,14 @@ function createFileTracker() {
         }
         return [];
       }
-      const buffer = Buffer.alloc(currentSize - pos.position);
-      const fd = (0, import_node_fs3.readFileSync)(filePath);
-      fd.copy(buffer, 0, pos.position, currentSize);
+      const bytesToRead = currentSize - pos.position;
+      const buffer = Buffer.alloc(bytesToRead);
+      const fd = (0, import_node_fs7.openSync)(filePath, "r");
+      try {
+        (0, import_node_fs7.readSync)(fd, buffer, 0, bytesToRead, pos.position);
+      } finally {
+        (0, import_node_fs7.closeSync)(fd);
+      }
       const newContent = (pos.partialLine + buffer.toString("utf-8")).split("\n");
       const partialLine = newContent.pop() || "";
       pos.position = currentSize;
@@ -1591,9 +2908,9 @@ function createFileTracker() {
 }
 
 // src/daemon/session-watcher.ts
-var import_node_fs4 = require("fs");
+var import_node_fs8 = require("fs");
 var import_node_os = require("os");
-var import_node_path2 = require("path");
+var import_node_path6 = require("path");
 function createSessionWatcher(config) {
   const { config: sparnConfig, onOptimize, onError } = config;
   const { realtime, decay, states } = sparnConfig;
@@ -1602,7 +2919,7 @@ function createSessionWatcher(config) {
   const watchers = [];
   const debounceTimers = /* @__PURE__ */ new Map();
   function getProjectsDir() {
-    return (0, import_node_path2.join)((0, import_node_os.homedir)(), ".claude", "projects");
+    return (0, import_node_path6.join)((0, import_node_os.homedir)(), ".claude", "projects");
   }
   function getSessionId(filePath) {
     const filename = filePath.split(/[/\\]/).pop() || "";
@@ -1619,6 +2936,7 @@ function createSessionWatcher(config) {
         fullOptimizationInterval: 50
         // Full re-optimization every 50 incremental updates
       });
+      loadState(sessionId, pipeline);
       pipelines.set(sessionId, pipeline);
     }
     return pipeline;
@@ -1660,16 +2978,16 @@ function createSessionWatcher(config) {
   function findJsonlFiles(dir) {
     const files = [];
     try {
-      const entries = (0, import_node_fs4.readdirSync)(dir);
+      const entries = (0, import_node_fs8.readdirSync)(dir);
       for (const entry of entries) {
-        const fullPath = (0, import_node_path2.join)(dir, entry);
-        const stat = (0, import_node_fs4.statSync)(fullPath);
+        const fullPath = (0, import_node_path6.join)(dir, entry);
+        const stat = (0, import_node_fs8.statSync)(fullPath);
         if (stat.isDirectory()) {
           files.push(...findJsonlFiles(fullPath));
         } else if (entry.endsWith(".jsonl")) {
           const matches = realtime.watchPatterns.some((pattern) => {
             const regex = new RegExp(
-              pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/\\\\]*").replace(/\./g, "\\.")
+              pattern.replace(/\./g, "\\.").replace(/\*\*/g, ".*").replace(/(?<!\.)(\*)/g, "[^/\\\\]*")
             );
             return regex.test(fullPath);
           });
@@ -1698,34 +3016,69 @@ function createSessionWatcher(config) {
   async function start() {
     const projectsDir = getProjectsDir();
     const jsonlFiles = findJsonlFiles(projectsDir);
-    const watchedDirs = /* @__PURE__ */ new Set();
-    for (const file of jsonlFiles) {
-      const dir = (0, import_node_path2.dirname)(file);
-      if (!watchedDirs.has(dir)) {
-        const watcher = (0, import_node_fs4.watch)(dir, { recursive: false }, (_eventType, filename) => {
-          if (filename?.endsWith(".jsonl")) {
-            const fullPath = (0, import_node_path2.join)(dir, filename);
-            handleFileChange(fullPath);
-          }
-        });
-        watchers.push(watcher);
-        watchedDirs.add(dir);
+    try {
+      const projectsWatcher = (0, import_node_fs8.watch)(projectsDir, { recursive: true }, (_eventType, filename) => {
+        if (filename?.endsWith(".jsonl")) {
+          const fullPath = (0, import_node_path6.join)(projectsDir, filename);
+          handleFileChange(fullPath);
+        }
+      });
+      watchers.push(projectsWatcher);
+    } catch {
+      const watchedDirs = /* @__PURE__ */ new Set();
+      for (const file of jsonlFiles) {
+        const dir = (0, import_node_path6.dirname)(file);
+        if (!watchedDirs.has(dir)) {
+          const watcher = (0, import_node_fs8.watch)(dir, { recursive: false }, (_eventType, filename) => {
+            if (filename?.endsWith(".jsonl")) {
+              const fullPath = (0, import_node_path6.join)(dir, filename);
+              handleFileChange(fullPath);
+            }
+          });
+          watchers.push(watcher);
+          watchedDirs.add(dir);
+        }
       }
     }
-    const projectsWatcher = (0, import_node_fs4.watch)(projectsDir, { recursive: true }, (_eventType, filename) => {
-      if (filename?.endsWith(".jsonl")) {
-        const fullPath = (0, import_node_path2.join)(projectsDir, filename);
-        handleFileChange(fullPath);
-      }
-    });
-    watchers.push(projectsWatcher);
     getMetrics().updateDaemon({
       startTime: Date.now(),
       sessionsWatched: jsonlFiles.length,
       memoryUsage: process.memoryUsage().heapUsed
     });
   }
+  function getStatePath() {
+    return (0, import_node_path6.join)((0, import_node_os.homedir)(), ".sparn", "optimizer-state.json");
+  }
+  function saveState() {
+    try {
+      const stateMap = {};
+      for (const [sessionId, pipeline] of pipelines.entries()) {
+        stateMap[sessionId] = pipeline.serializeOptimizerState();
+      }
+      const statePath = getStatePath();
+      const dir = (0, import_node_path6.dirname)(statePath);
+      if (!(0, import_node_fs8.existsSync)(dir)) {
+        (0, import_node_fs8.mkdirSync)(dir, { recursive: true });
+      }
+      (0, import_node_fs8.writeFileSync)(statePath, JSON.stringify(stateMap), "utf-8");
+    } catch {
+    }
+  }
+  function loadState(sessionId, pipeline) {
+    try {
+      const statePath = getStatePath();
+      if (!(0, import_node_fs8.existsSync)(statePath)) return;
+      const raw = (0, import_node_fs8.readFileSync)(statePath, "utf-8");
+      const stateMap = JSON.parse(raw);
+      const sessionState = stateMap[sessionId];
+      if (sessionState) {
+        pipeline.deserializeOptimizerState(sessionState);
+      }
+    } catch {
+    }
+  }
   function stop() {
+    saveState();
     for (const watcher of watchers) {
       watcher.close();
     }
@@ -1795,8 +3148,8 @@ var DEFAULT_CONFIG = {
   },
   autoConsolidate: null,
   realtime: {
-    tokenBudget: 5e4,
-    autoOptimizeThreshold: 8e4,
+    tokenBudget: 4e4,
+    autoOptimizeThreshold: 6e4,
     watchPatterns: ["**/*.jsonl"],
     pidFile: ".sparn/daemon.pid",
     logFile: ".sparn/daemon.log",
@@ -1812,11 +3165,12 @@ function createSparnMcpServer(options) {
   const { memory, config = DEFAULT_CONFIG } = options;
   const server = new import_mcp.McpServer({
     name: "sparn",
-    version: "1.1.1"
+    version: "1.4.0"
   });
   registerOptimizeTool(server, memory, config);
   registerStatsTool(server, memory);
   registerConsolidateTool(server, memory);
+  registerSearchTool(server, memory);
   return server;
 }
 function registerOptimizeTool(server, memory, config) {
@@ -1824,7 +3178,7 @@ function registerOptimizeTool(server, memory, config) {
     "sparn_optimize",
     {
       title: "Sparn Optimize",
-      description: "Optimize context using neuroscience-inspired pruning. Applies BTSP detection, engram scoring, confidence states, and sparse pruning to reduce token usage while preserving important information.",
+      description: "Optimize context using multi-stage pruning. Applies critical event detection, relevance scoring, entry classification, and sparse pruning to reduce token usage while preserving important information.",
       inputSchema: {
         context: import_zod.z.string().describe("The context text to optimize"),
         dryRun: import_zod.z.boolean().optional().default(false).describe("If true, do not persist changes to the memory store"),
@@ -1954,12 +3308,58 @@ function registerStatsTool(server, memory) {
     }
   );
 }
+function registerSearchTool(server, memory) {
+  server.registerTool(
+    "sparn_search",
+    {
+      title: "Sparn Search",
+      description: "Search memory entries using full-text search. Returns matching entries with relevance ranking, score, and state information.",
+      inputSchema: {
+        query: import_zod.z.string().describe("Search query text"),
+        limit: import_zod.z.number().int().min(1).max(100).optional().default(10).describe("Maximum number of results (1-100, default 10)")
+      }
+    },
+    async ({ query, limit }) => {
+      try {
+        const results = await memory.searchFTS(query, limit);
+        const response = results.map((r) => ({
+          id: r.entry.id,
+          content: r.entry.content.length > 500 ? `${r.entry.content.slice(0, 500)}...` : r.entry.content,
+          score: r.entry.score,
+          state: r.entry.state,
+          rank: r.rank,
+          tags: r.entry.tags,
+          isBTSP: r.entry.isBTSP
+        }));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ results: response, total: response.length }, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: message })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
 function registerConsolidateTool(server, memory) {
   server.registerTool(
     "sparn_consolidate",
     {
       title: "Sparn Consolidate",
-      description: "Run memory consolidation (sleep replay). Removes decayed entries and merges duplicates to reclaim space. Inspired by the neuroscience principle of sleep-based memory consolidation."
+      description: "Run memory consolidation. Removes decayed entries and merges duplicates to reclaim space."
     },
     async () => {
       try {
@@ -2035,6 +3435,10 @@ function createLogger(verbose = false) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CONFIG,
+  calculateIDF,
+  calculateTF,
+  calculateTFIDF,
+  countTokensPrecise,
   createBTSPEmbedder,
   createBudgetPruner,
   createBudgetPrunerFromConfig,
@@ -2042,6 +3446,9 @@ function createLogger(verbose = false) {
   createConfidenceStates,
   createContextPipeline,
   createDaemonCommand,
+  createDebtTracker,
+  createDependencyGraph,
+  createDocsGenerator,
   createEngramScorer,
   createEntry,
   createFileTracker,
@@ -2049,13 +3456,23 @@ function createLogger(verbose = false) {
   createIncrementalOptimizer,
   createKVMemory,
   createLogger,
+  createMetricsCollector,
+  createSearchEngine,
   createSessionWatcher,
   createSleepCompressor,
   createSparnMcpServer,
   createSparsePruner,
+  createTFIDFIndex,
+  createWorkflowPlanner,
   estimateTokens,
+  getMetrics,
   hashContent,
   parseClaudeCodeContext,
-  parseGenericContext
+  parseGenericContext,
+  parseJSONLContext,
+  parseJSONLLine,
+  scoreTFIDF,
+  setPreciseTokenCounting,
+  tokenize
 });
 //# sourceMappingURL=index.cjs.map