@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/lib/cross-session-patterns.js

@@ -0,0 +1,754 @@
+/**
+ * Cross-Session Pattern Detection Engine
+ *
+ * Analyzes archived sessions to discover high-confidence patterns
+ * appearing across multiple sessions. This is the core of the
+ * cross-session learning and aggregation system.
+ *
+ * Key capabilities:
+ * 1. Load and parse all archived sessions
+ * 2. Detect patterns appearing in 3+ sessions
+ * 3. Analyze patterns by technology/compliance context
+ * 4. Time-series trend analysis
+ * 5. Build skill-correction correlation matrix
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getClaudeDir,
+  ensureDir,
+  readFile,
+  writeFile,
+  getDateTimeString,
+  getDateString,
+  log,
+} = require('./utils');
+
+// Paths
+const KNOWLEDGE_DIR = path.join(getClaudeDir(), 'knowledge');
+const SESSIONS_DIR = path.join(KNOWLEDGE_DIR, 'sessions');
+const AGGREGATED_DIR = path.join(KNOWLEDGE_DIR, 'aggregated');
+
+// Thresholds
+const THRESHOLDS = {
+  MIN_SESSIONS_FOR_PATTERN: 3, // Minimum sessions to consider a pattern
+  MIN_SESSIONS_FOR_ANALYSIS: 5, // Minimum sessions before running analysis
+  HIGH_CONFIDENCE: 0.7, // Above this = high confidence pattern
+  EMERGING_THRESHOLD: 2, // Pattern appearing in recent sessions
+  DECLINING_DAYS: 30, // No occurrences in this many days = declining
+};
+
+// Category weights for confidence scoring
+const CATEGORY_WEIGHTS = {
+  approach: 1.0, // Most important - affects overall methodology
+  tool_usage: 0.8, // Important - efficiency impact
+  code_style: 0.5, // Less critical but still relevant
+  communication: 0.3, // Lowest weight
+  general: 0.6,
+};
+
+/**
+ * Load all archived sessions from knowledge/sessions/
+ * @returns {Array} Array of session objects with parsed data
+ */
+function loadArchivedSessions() {
+  ensureDir(SESSIONS_DIR);
+
+  const sessions = [];
+
+  try {
+    const files = fs.readdirSync(SESSIONS_DIR);
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+
+      const filePath = path.join(SESSIONS_DIR, file);
+      const content = readFile(filePath);
+
+      if (!content) continue;
+
+      try {
+        const session = JSON.parse(content);
+        session._filePath = filePath;
+        session._fileName = file;
+        sessions.push(session);
+      } catch (err) {
+        log(`[CrossSessionPatterns] Error parsing ${file}: ${err.message}`);
+      }
+    }
+  } catch (err) {
+    log(`[CrossSessionPatterns] Error loading sessions: ${err.message}`);
+  }
+
+  // Sort by start time (oldest first)
+  sessions.sort((a, b) => {
+    const dateA = new Date(a.startedAt?.replace(' ', 'T') || 0);
+    const dateB = new Date(b.startedAt?.replace(' ', 'T') || 0);
+    return dateA - dateB;
+  });
+
+  return sessions;
+}
+
+/**
+ * Extract all corrections from sessions
+ * @param {Array} sessions - Array of session objects
+ * @returns {Array} Flattened array of corrections with session metadata
+ */
+function extractAllCorrections(sessions) {
+  const corrections = [];
+
+  for (const session of sessions) {
+    if (!session.corrections || !Array.isArray(session.corrections)) continue;
+
+    for (const correction of session.corrections) {
+      corrections.push({
+        ...correction,
+        sessionId: session.sessionId,
+        sessionDate: session.startedAt,
+        technologies: session.context?.technologies || [],
+        complianceMode: session.context?.complianceMode || 'standard',
+      });
+    }
+  }
+
+  return corrections;
+}
+
+/**
+ * Analyze all sessions and extract comprehensive data
+ * @returns {object} { sessions, corrections, patterns, contexts, summary }
+ */
+function analyzeAllSessions() {
+  const sessions = loadArchivedSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return {
+      sessions: [],
+      corrections: [],
+      patterns: [],
+      contexts: { technologies: {}, complianceModes: {} },
+      summary: { sessionCount: sessions.length, insufficient: true },
+    };
+  }
+
+  const corrections = extractAllCorrections(sessions);
+
+  // Extract effective patterns
+  const patterns = [];
+  for (const session of sessions) {
+    if (session.effectivePatterns) {
+      for (const pattern of session.effectivePatterns) {
+        patterns.push({
+          ...pattern,
+          sessionId: session.sessionId,
+          sessionDate: session.startedAt,
+        });
+      }
+    }
+  }
+
+  // Build context summary
+  const contexts = {
+    technologies: {},
+    complianceModes: {},
+  };
+
+  for (const session of sessions) {
+    const techs = session.context?.technologies || [];
+    for (const tech of techs) {
+      contexts.technologies[tech] = (contexts.technologies[tech] || 0) + 1;
+    }
+
+    const mode = session.context?.complianceMode || 'standard';
+    contexts.complianceModes[mode] = (contexts.complianceModes[mode] || 0) + 1;
+  }
+
+  return {
+    sessions,
+    corrections,
+    patterns,
+    contexts,
+    summary: {
+      sessionCount: sessions.length,
+      correctionCount: corrections.length,
+      patternCount: patterns.length,
+      dateRange: {
+        first: sessions[0]?.startedAt,
+        last: sessions[sessions.length - 1]?.startedAt,
+      },
+    },
+  };
+}
+
+/**
+ * Detect patterns appearing across multiple sessions
+ * @param {number} threshold - Minimum sessions for a pattern (default: 3)
+ * @returns {object} { highConfidence, emerging, declining, all }
+ */
+function detectCrossSessionPatterns(threshold = THRESHOLDS.MIN_SESSIONS_FOR_PATTERN) {
+  const { sessions, corrections } = analyzeAllSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return { highConfidence: [], emerging: [], declining: [], all: [] };
+  }
+
+  // Group corrections by signature (category + original behavior)
+  const patternMap = new Map();
+
+  for (const correction of corrections) {
+    const signature = `${correction.category}::${correction.original}`;
+
+    if (!patternMap.has(signature)) {
+      patternMap.set(signature, {
+        signature,
+        category: correction.category,
+        original: correction.original,
+        corrected: correction.corrected,
+        sessions: new Set(),
+        totalCount: 0,
+        occurrences: [],
+        technologies: new Set(),
+        complianceModes: new Set(),
+        firstSeen: correction.sessionDate,
+        lastSeen: correction.sessionDate,
+      });
+    }
+
+    const pattern = patternMap.get(signature);
+    pattern.sessions.add(correction.sessionId);
+    pattern.totalCount += correction.count || 1;
+    pattern.occurrences.push({
+      sessionId: correction.sessionId,
+      date: correction.sessionDate,
+      count: correction.count || 1,
+    });
+
+    // Track contexts
+    for (const tech of correction.technologies) {
+      pattern.technologies.add(tech);
+    }
+    pattern.complianceModes.add(correction.complianceMode);
+
+    // Update date range
+    if (correction.sessionDate > pattern.lastSeen) {
+      pattern.lastSeen = correction.sessionDate;
+    }
+    if (correction.sessionDate < pattern.firstSeen) {
+      pattern.firstSeen = correction.sessionDate;
+    }
+  }
+
+  // Convert to array and filter by threshold
+  const allPatterns = Array.from(patternMap.values()).map((p) => ({
+    ...p,
+    sessionCount: p.sessions.size,
+    sessions: Array.from(p.sessions),
+    technologies: Array.from(p.technologies),
+    complianceModes: Array.from(p.complianceModes),
+    confidence: calculateConfidence(p, sessions.length),
+  }));
+
+  // Filter by session threshold
+  const significantPatterns = allPatterns.filter((p) => p.sessionCount >= threshold);
+
+  // Sort by session count (most frequent first)
+  significantPatterns.sort((a, b) => b.sessionCount - a.sessionCount);
+
+  // Categorize patterns
+  const now = new Date();
+  const thirtyDaysAgo = new Date(now - THRESHOLDS.DECLINING_DAYS * 24 * 60 * 60 * 1000);
+
+  const highConfidence = significantPatterns.filter(
+    (p) => p.confidence >= THRESHOLDS.HIGH_CONFIDENCE
+  );
+
+  const emerging = allPatterns.filter((p) => {
+    // Appeared in recent sessions but not yet at threshold
+    const lastSeenDate = new Date(p.lastSeen?.replace(' ', 'T') || 0);
+    return (
+      p.sessionCount >= THRESHOLDS.EMERGING_THRESHOLD &&
+      p.sessionCount < threshold &&
+      lastSeenDate > thirtyDaysAgo
+    );
+  });
+
+  const declining = significantPatterns.filter((p) => {
+    // Was significant but no recent occurrences
+    const lastSeenDate = new Date(p.lastSeen?.replace(' ', 'T') || 0);
+    return lastSeenDate < thirtyDaysAgo;
+  });
+
+  return {
+    highConfidence,
+    emerging,
+    declining,
+    all: significantPatterns,
+  };
+}
+
+/**
+ * Calculate confidence score for a pattern
+ * @param {object} pattern - Pattern object
+ * @param {number} totalSessions - Total number of sessions
+ * @returns {number} Confidence score between 0 and 1
+ */
+function calculateConfidence(pattern, totalSessions) {
+  // Frequency component (how many sessions contain this pattern)
+  const frequencyScore = Math.min(pattern.sessions.size / totalSessions, 1);
+
+  // Recency component (how recent was the last occurrence)
+  const now = new Date();
+  const lastSeen = new Date(pattern.lastSeen?.replace(' ', 'T') || 0);
+  const daysSinceLastSeen = (now - lastSeen) / (1000 * 60 * 60 * 24);
+  const recencyScore = Math.max(0, 1 - daysSinceLastSeen / 90); // Decay over 90 days
+
+  // Category weight
+  const categoryWeight = CATEGORY_WEIGHTS[pattern.category] || 0.5;
+
+  // Count intensity (average occurrences per session)
+  const avgCount = pattern.totalCount / pattern.sessions.size;
+  const intensityScore = Math.min(avgCount / 3, 1); // Cap at 3 per session
+
+  // Weighted combination
+  const confidence =
+    frequencyScore * 0.35 + recencyScore * 0.25 + categoryWeight * 0.25 + intensityScore * 0.15;
+
+  return Math.round(confidence * 100) / 100;
+}
+
+/**
+ * Analyze patterns grouped by technology
+ * @returns {object} { [technology]: { corrections, topIssues, rate } }
+ */
+function analyzeByTechnology() {
+  const { sessions, corrections } = analyzeAllSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return {};
+  }
+
+  const techMap = {};
+
+  for (const correction of corrections) {
+    for (const tech of correction.technologies) {
+      if (!techMap[tech]) {
+        techMap[tech] = {
+          technology: tech,
+          corrections: [],
+          sessionCount: 0,
+          sessions: new Set(),
+        };
+      }
+
+      techMap[tech].corrections.push(correction);
+      techMap[tech].sessions.add(correction.sessionId);
+    }
+  }
+
+  // Process each technology
+  const result = {};
+
+  for (const [tech, data] of Object.entries(techMap)) {
+    // Group corrections by type
+    const issueMap = {};
+    for (const c of data.corrections) {
+      const key = `${c.category}::${c.original}`;
+      if (!issueMap[key]) {
+        issueMap[key] = { category: c.category, original: c.original, count: 0 };
+      }
+      issueMap[key].count += c.count || 1;
+    }
+
+    const issues = Object.values(issueMap).sort((a, b) => b.count - a.count);
+
+    result[tech] = {
+      technology: tech,
+      sessionCount: data.sessions.size,
+      correctionCount: data.corrections.length,
+      topIssues: issues.slice(0, 5),
+      correctionRate: data.corrections.length / data.sessions.size,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Analyze patterns by compliance mode
+ * @returns {object} { [mode]: { corrections, criticalPatterns } }
+ */
+function analyzeByComplianceMode() {
+  const { sessions, corrections } = analyzeAllSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return {};
+  }
+
+  const modeMap = {};
+
+  for (const correction of corrections) {
+    const mode = correction.complianceMode || 'standard';
+
+    if (!modeMap[mode]) {
+      modeMap[mode] = {
+        mode,
+        corrections: [],
+        sessions: new Set(),
+      };
+    }
+
+    modeMap[mode].corrections.push(correction);
+    modeMap[mode].sessions.add(correction.sessionId);
+  }
+
+  // Process each mode
+  const result = {};
+
+  for (const [mode, data] of Object.entries(modeMap)) {
+    // Group corrections by type
+    const issueMap = {};
+    for (const c of data.corrections) {
+      const key = `${c.category}::${c.original}`;
+      if (!issueMap[key]) {
+        issueMap[key] = { category: c.category, original: c.original, count: 0 };
+      }
+      issueMap[key].count += c.count || 1;
+    }
+
+    const issues = Object.values(issueMap).sort((a, b) => b.count - a.count);
+
+    // Critical patterns for compliance modes
+    const criticalPatterns = issues.filter(
+      (i) => i.category === 'approach' || (mode !== 'standard' && i.count >= 3)
+    );
+
+    result[mode] = {
+      mode,
+      sessionCount: data.sessions.size,
+      correctionCount: data.corrections.length,
+      topIssues: issues.slice(0, 5),
+      criticalPatterns: criticalPatterns.slice(0, 3),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Time-series trend analysis
+ * @param {number} windowDays - Analysis window in days (default: 30)
+ * @returns {object} { improving, worsening, stable, new }
+ */
+function analyzeTrends(windowDays = 30) {
+  const { sessions, corrections } = analyzeAllSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return { improving: [], worsening: [], stable: [], new: [] };
+  }
+
+  const now = new Date();
+  const windowStart = new Date(now - windowDays * 24 * 60 * 60 * 1000);
+  const halfWindow = new Date(now - (windowDays / 2) * 24 * 60 * 60 * 1000);
+
+  // Group sessions by period (first half vs second half of window)
+  const firstHalf = { sessions: [], corrections: [] };
+  const secondHalf = { sessions: [], corrections: [] };
+
+  for (const session of sessions) {
+    const sessionDate = new Date(session.startedAt?.replace(' ', 'T') || 0);
+
+    if (sessionDate < windowStart) continue;
+
+    if (sessionDate < halfWindow) {
+      firstHalf.sessions.push(session);
+    } else {
+      secondHalf.sessions.push(session);
+    }
+  }
+
+  // Get corrections for each period
+  for (const correction of corrections) {
+    const correctionDate = new Date(correction.sessionDate?.replace(' ', 'T') || 0);
+
+    if (correctionDate < windowStart) continue;
+
+    if (correctionDate < halfWindow) {
+      firstHalf.corrections.push(correction);
+    } else {
+      secondHalf.corrections.push(correction);
+    }
+  }
+
+  // Count patterns in each period
+  function countPatterns(correctionList) {
+    const counts = {};
+    for (const c of correctionList) {
+      const key = `${c.category}::${c.original}`;
+      counts[key] = (counts[key] || 0) + (c.count || 1);
+    }
+    return counts;
+  }
+
+  const firstCounts = countPatterns(firstHalf.corrections);
+  const secondCounts = countPatterns(secondHalf.corrections);
+
+  // Analyze trends
+  const allPatterns = new Set([...Object.keys(firstCounts), ...Object.keys(secondCounts)]);
+
+  const trends = {
+    improving: [],
+    worsening: [],
+    stable: [],
+    new: [],
+  };
+
+  for (const pattern of allPatterns) {
+    const first = firstCounts[pattern] || 0;
+    const second = secondCounts[pattern] || 0;
+    const [category, original] = pattern.split('::');
+
+    const change = second - first;
+    const percentChange = first > 0 ? ((second - first) / first) * 100 : second > 0 ? 100 : 0;
+
+    const trendData = {
+      pattern,
+      category,
+      original,
+      firstPeriod: first,
+      secondPeriod: second,
+      change,
+      percentChange: Math.round(percentChange),
+    };
+
+    if (first === 0 && second > 0) {
+      trends.new.push(trendData);
+    } else if (change < -1 || percentChange < -25) {
+      trends.improving.push(trendData);
+    } else if (change > 1 || percentChange > 25) {
+      trends.worsening.push(trendData);
+    } else {
+      trends.stable.push(trendData);
+    }
+  }
+
+  // Sort each category
+  trends.improving.sort((a, b) => a.percentChange - b.percentChange);
+  trends.worsening.sort((a, b) => b.percentChange - a.percentChange);
+  trends.new.sort((a, b) => b.secondPeriod - a.secondPeriod);
+
+  return trends;
+}
+
+/**
+ * Build skill-correction correlation matrix
+ * Links which skills help prevent which corrections
+ * @returns {object} { [skill]: { prevents: [corrections], rate } }
+ */
+function buildSkillCorrectionMatrix() {
+  // Load skill effectiveness data
+  const effectivenessFile = path.join(KNOWLEDGE_DIR, 'skill-effectiveness.json');
+  let skillData = { skills: {} };
+
+  try {
+    if (fs.existsSync(effectivenessFile)) {
+      skillData = JSON.parse(fs.readFileSync(effectivenessFile, 'utf8'));
+    }
+  } catch {
+    return {};
+  }
+
+  const { sessions, corrections } = analyzeAllSessions();
+
+  if (sessions.length < THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS) {
+    return {};
+  }
+
+  // For each skill, find sessions where it was applied
+  const matrix = {};
+
+  for (const [skillName, skill] of Object.entries(skillData.skills || {})) {
+    const skillContexts = skill.contexts || [];
+    const skillSessions = new Set(
+      skillContexts.map((c) => {
+        // Extract session from context (approximation based on timestamps)
+        return c.timestamp?.split(' ')[0]; // Date portion
+      })
+    );
+
+    // Find corrections in sessions where skill was applied vs not
+    const withSkill = { corrections: 0, sessions: 0 };
+    const withoutSkill = { corrections: 0, sessions: 0 };
+
+    for (const session of sessions) {
+      const sessionDate = session.startedAt?.split(' ')[0];
+      const sessionCorrections = (session.corrections || []).length;
+
+      if (skillSessions.has(sessionDate)) {
+        withSkill.corrections += sessionCorrections;
+        withSkill.sessions++;
+      } else {
+        withoutSkill.corrections += sessionCorrections;
+        withoutSkill.sessions++;
+      }
+    }
+
+    // Calculate prevention rate
+    const rateWith = withSkill.sessions > 0 ? withSkill.corrections / withSkill.sessions : 0;
+    const rateWithout =
+      withoutSkill.sessions > 0 ? withoutSkill.corrections / withoutSkill.sessions : 0;
+
+    const preventionRate = rateWithout > 0 ? 1 - rateWith / rateWithout : 0;
+
+    if (skill.applications >= 3) {
+      matrix[skillName] = {
+        skill: skillName,
+        applications: skill.applications,
+        effectiveness: skill.effectiveness,
+        preventionRate: Math.round(preventionRate * 100) / 100,
+        withSkillRate: Math.round(rateWith * 100) / 100,
+        withoutSkillRate: Math.round(rateWithout * 100) / 100,
+      };
+    }
+  }
+
+  return matrix;
+}
+
+/**
+ * Save aggregated data to disk
+ * @param {object} data - Aggregated data to save
+ */
+function saveAggregatedData(data) {
+  ensureDir(AGGREGATED_DIR);
+
+  const files = {
+    'pattern-library.json': data.patternLibrary,
+    'context-patterns.json': data.contextPatterns,
+    'trend-analysis.json': data.trendAnalysis,
+    'skill-correction-matrix.json': data.skillCorrectionMatrix,
+    'recommendations.json': data.recommendations,
+  };
+
+  for (const [filename, content] of Object.entries(files)) {
+    if (content) {
+      const filePath = path.join(AGGREGATED_DIR, filename);
+      writeFile(
+        filePath,
+        JSON.stringify(
+          {
+            lastUpdated: getDateTimeString(),
+            ...content,
+          },
+          null,
+          2
+        )
+      );
+    }
+  }
+
+  // Save summary
+  const summaryPath = path.join(AGGREGATED_DIR, 'last-aggregation.json');
+  writeFile(
+    summaryPath,
+    JSON.stringify(
+      {
+        timestamp: getDateTimeString(),
+        patternCount: data.patternLibrary?.all?.length || 0,
+        recommendationCount: data.recommendations?.length || 0,
+      },
+      null,
+      2
+    )
+  );
+}
+
+/**
+ * Load previously aggregated data
+ * @returns {object} Previously aggregated data or null
+ */
+function loadAggregatedData() {
+  const files = [
+    'pattern-library.json',
+    'context-patterns.json',
+    'trend-analysis.json',
+    'skill-correction-matrix.json',
+    'recommendations.json',
+  ];
+
+  const data = {};
+
+  for (const filename of files) {
+    const filePath = path.join(AGGREGATED_DIR, filename);
+    const content = readFile(filePath);
+    if (content) {
+      try {
+        data[filename.replace('.json', '').replace(/-/g, '_')] = JSON.parse(content);
+      } catch {
+        // Skip invalid files
+      }
+    }
+  }
+
+  return Object.keys(data).length > 0 ? data : null;
+}
+
+/**
+ * Get aggregation summary for quick checks
+ * @returns {object} { lastRun, patternCount, recommendationCount, needsUpdate }
+ */
+function getAggregationStatus() {
+  const summaryPath = path.join(AGGREGATED_DIR, 'last-aggregation.json');
+  const content = readFile(summaryPath);
+
+  if (!content) {
+    return { lastRun: null, patternCount: 0, recommendationCount: 0, needsUpdate: true };
+  }
+
+  try {
+    const summary = JSON.parse(content);
+    const lastRun = new Date(summary.timestamp?.replace(' ', 'T') || 0);
+    const hoursSinceLastRun = (Date.now() - lastRun) / (1000 * 60 * 60);
+
+    return {
+      lastRun: summary.timestamp,
+      patternCount: summary.patternCount,
+      recommendationCount: summary.recommendationCount,
+      needsUpdate: hoursSinceLastRun > 24, // Update if older than 24 hours
+    };
+  } catch {
+    return { lastRun: null, patternCount: 0, recommendationCount: 0, needsUpdate: true };
+  }
+}
+
+module.exports = {
+  // Core analysis functions
+  loadArchivedSessions,
+  analyzeAllSessions,
+  detectCrossSessionPatterns,
+
+  // Context analysis
+  analyzeByTechnology,
+  analyzeByComplianceMode,
+
+  // Trend analysis
+  analyzeTrends,
+
+  // Skill correlation
+  buildSkillCorrectionMatrix,
+
+  // Data persistence
+  saveAggregatedData,
+  loadAggregatedData,
+  getAggregationStatus,
+
+  // Utilities
+  calculateConfidence,
+  extractAllCorrections,
+
+  // Constants
+  THRESHOLDS,
+  CATEGORY_WEIGHTS,
+  AGGREGATED_DIR,
+};