@pcircle/memesh 2.8.11 → 2.9.1

package/scripts/hooks/session-start.js

@@ -0,0 +1,544 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook - Claude Code Event-Driven Hooks
+ *
+ * Triggered at the start of each Claude Code session.
+ *
+ * Features:
+ * - Checks MeMesh MCP server availability
+ * - Auto-recalls last session key points from MeMesh
+ * - Reads recommendations from last session
+ * - Displays suggested skills to load
+ * - Shows warnings (quota, slow tools, etc.)
+ * - Initializes current session state
+ */
+
+import {
+  HOME_DIR,
+  STATE_DIR,
+  MEMESH_DB_PATH,
+  THRESHOLDS,
+  readJSONFile,
+  writeJSONFile,
+  sqliteQueryJSON,
+  getTimeAgo,
+  logError,
+  queryActivePlans,
+  renderTimelineCompact,
+} from './hook-utils.js';
+import fs from 'fs';
+import path from 'path';
+
+// ============================================================================
+// File Paths
+// ============================================================================
+
+const CCB_HEARTBEAT_FILE = path.join(STATE_DIR, 'ccb-heartbeat.json');
+const MCP_SETTINGS_FILE = path.join(HOME_DIR, '.claude', 'mcp_settings.json');
+const RECOMMENDATIONS_FILE = path.join(STATE_DIR, 'recommendations.json');
+const SESSION_CONTEXT_FILE = path.join(STATE_DIR, 'session-context.json');
+const CURRENT_SESSION_FILE = path.join(STATE_DIR, 'current-session.json');
+const LAST_SESSION_CACHE_FILE = path.join(STATE_DIR, 'last-session-summary.json');
+
+/** Maximum cache age: 7 days */
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+// ============================================================================
+// MeMesh Status Check
+// ============================================================================
+
+/**
+ * Check MeMesh MCP Server availability
+ * @returns {{ configured: boolean, running: boolean, lastHeartbeat: string|null, serverPath: string|null }}
+ */
+function checkCCBAvailability() {
+  const result = {
+    configured: false,
+    running: false,
+    lastHeartbeat: null,
+    serverPath: null,
+  };
+
+  // Check if MeMesh is configured in MCP settings
+  try {
+    if (fs.existsSync(MCP_SETTINGS_FILE)) {
+      const mcpSettings = JSON.parse(fs.readFileSync(MCP_SETTINGS_FILE, 'utf-8'));
+
+      // Check for MeMesh and legacy names (backward compatibility)
+      const ccbNames = [
+        'memesh',
+        '@pcircle/memesh',
+        '@pcircle/claude-code-buddy-mcp',
+        'claude-code-buddy',
+        'ccb',
+      ];
+
+      for (const name of ccbNames) {
+        if (mcpSettings.mcpServers && mcpSettings.mcpServers[name]) {
+          result.configured = true;
+          result.serverPath = mcpSettings.mcpServers[name].args?.[0] || 'configured';
+          break;
+        }
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  // Check heartbeat file (MeMesh writes this when running)
+  try {
+    if (fs.existsSync(CCB_HEARTBEAT_FILE)) {
+      const heartbeat = JSON.parse(fs.readFileSync(CCB_HEARTBEAT_FILE, 'utf-8'));
+      result.lastHeartbeat = heartbeat.timestamp;
+
+      const heartbeatTime = new Date(heartbeat.timestamp).getTime();
+      const now = Date.now();
+
+      if (now - heartbeatTime < THRESHOLDS.HEARTBEAT_VALIDITY) {
+        result.running = true;
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return result;
+}
+
+/**
+ * Display MeMesh status and reminder
+ */
+function displayCCBStatus(ccbStatus) {
+  console.log('═'.repeat(60));
+  console.log('  🤖 MeMesh Status');
+  console.log('═'.repeat(60));
+
+  if (!ccbStatus.configured) {
+    console.log('');
+    console.log('  ⚠️  MeMesh MCP Server is NOT configured!');
+    console.log('');
+    console.log('  MeMesh provides memory management and knowledge graph tools.');
+    console.log('  To configure MeMesh, add it to ~/.claude/mcp_settings.json');
+    console.log('');
+    console.log('  Available MeMesh tools when connected:');
+    console.log('    • buddy-remember: Query past knowledge');
+    console.log('    • buddy-do: Execute common operations');
+    console.log('    • memesh-create-entities: Store new knowledge to graph');
+    console.log('');
+  } else if (!ccbStatus.running) {
+    console.log('');
+    console.log('  ℹ️  MeMesh is configured but status unknown');
+    console.log(`  Path: ${ccbStatus.serverPath}`);
+    console.log('');
+    console.log('  📝 REMINDER: Use MeMesh tools for memory management:');
+    console.log('');
+    console.log('  Before starting work:');
+    console.log('    buddy-remember "relevant topic" - Query past experiences');
+    console.log('');
+    console.log('  After completing work:');
+    console.log('    memesh-create-entities - Store new learnings');
+    console.log('    memesh-record-mistake - Record errors for future reference');
+    console.log('');
+    console.log('  💡 If MeMesh tools fail, check MCP server status.');
+    console.log('');
+  } else {
+    console.log('');
+    console.log('  ✅ MeMesh MCP Server is running');
+    console.log(`  Last heartbeat: ${ccbStatus.lastHeartbeat}`);
+    console.log('');
+    console.log('  📋 Session Start Checklist:');
+    console.log('    ☐ buddy-remember - Query relevant past knowledge');
+    console.log('');
+    console.log('  📋 Session End Checklist:');
+    console.log('    ☐ memesh-create-entities - Store new learnings');
+    console.log('    ☐ memesh-record-mistake - Record any errors');
+    console.log('');
+  }
+
+  console.log('═'.repeat(60));
+  console.log('');
+}
+
+// ============================================================================
+// Memory Recall
+// ============================================================================
+
+/**
+ * Try to read session summary from cache file (fast path).
+ * Cache is written by stop.js on session end.
+ * @returns {{ entityName: string, createdAt: string, metadata: object, keyPoints: string[] } | null}
+ */
+function recallFromCache() {
+  try {
+    if (!fs.existsSync(LAST_SESSION_CACHE_FILE)) {
+      return null;
+    }
+
+    const cache = readJSONFile(LAST_SESSION_CACHE_FILE, null);
+    if (!cache || !cache.savedAt || !cache.keyPoints) {
+      return null;
+    }
+
+    // Check staleness
+    const cacheAge = Date.now() - new Date(cache.savedAt).getTime();
+    if (cacheAge > CACHE_MAX_AGE_MS) {
+      // Stale cache — delete it
+      try { fs.unlinkSync(LAST_SESSION_CACHE_FILE); } catch { /* ignore */ }
+      return null;
+    }
+
+    return {
+      entityName: 'session_cache',
+      createdAt: cache.savedAt,
+      metadata: {
+        duration: cache.duration,
+        toolCount: cache.toolCount,
+      },
+      keyPoints: cache.keyPoints,
+    };
+  } catch (error) {
+    logError('recallFromCache', error);
+    return null;
+  }
+}
+
+/**
+ * Recall recent session key points from MeMesh (slow path — SQLite query).
+ * Used as fallback when cache is not available.
+ * @returns {{ entityName: string, createdAt: string, metadata: object, keyPoints: string[] } | null}
+ */
+function recallFromSQLite() {
+  try {
+    if (!fs.existsSync(MEMESH_DB_PATH)) {
+      return null;
+    }
+
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - THRESHOLDS.RECALL_DAYS);
+    const cutoffISO = cutoffDate.toISOString();
+
+    const query = `
+      SELECT id, name, metadata, created_at
+      FROM entities
+      WHERE type = ? AND created_at > ?
+      ORDER BY created_at DESC
+      LIMIT 1
+    `.replace(/\n/g, ' ');
+
+    // Use JSON mode to avoid pipe-split issues with | in metadata
+    const entityRows = sqliteQueryJSON(
+      MEMESH_DB_PATH,
+      query,
+      ['session_keypoint', cutoffISO]
+    );
+
+    if (!entityRows || entityRows.length === 0) {
+      return null;
+    }
+
+    const row = entityRows[0];
+    const entityId = row.id;
+    const entityName = row.name;
+    const createdAt = row.created_at;
+
+    // Observations also use JSON mode for safety
+    const obsRows = sqliteQueryJSON(
+      MEMESH_DB_PATH,
+      'SELECT content FROM observations WHERE entity_id = ? ORDER BY created_at ASC',
+      [entityId]
+    );
+
+    const keyPoints = (obsRows || []).map(r => r.content).filter(Boolean);
+
+    let parsedMetadata = {};
+    try {
+      parsedMetadata = JSON.parse(row.metadata || '{}');
+    } catch {
+      // Ignore parse errors
+    }
+
+    return {
+      entityName,
+      createdAt,
+      metadata: parsedMetadata,
+      keyPoints,
+    };
+  } catch (error) {
+    logError('recallFromSQLite', error);
+    return null;
+  }
+}
+
+/**
+ * Recall recent session key points — cache-first, SQLite fallback.
+ * @returns {{ entityName: string, createdAt: string, metadata: object, keyPoints: string[] } | null}
+ */
+function recallRecentKeyPoints() {
+  // Fast path: read from cache file (no sqlite3 spawn)
+  const cached = recallFromCache();
+  if (cached) {
+    return cached;
+  }
+
+  // Slow path: query SQLite
+  return recallFromSQLite();
+}
+
+/**
+ * Display recalled key points from last session
+ */
+function displayRecalledMemory(recalledData) {
+  console.log('═'.repeat(60));
+  console.log('  🧠 MeMesh Memory Recall');
+  console.log('═'.repeat(60));
+
+  if (!recalledData || !recalledData.keyPoints || recalledData.keyPoints.length === 0) {
+    console.log('');
+    console.log('  ℹ️  No recent memories found (last 30 days)');
+    console.log('  💡 Memories will be auto-saved when this session ends');
+    console.log('');
+    console.log('═'.repeat(60));
+    console.log('');
+    return;
+  }
+
+  console.log('');
+
+  // Display timestamp
+  const savedTime = new Date(recalledData.createdAt);
+  const timeAgo = getTimeAgo(savedTime);
+  console.log(`  🕐 Saved: ${timeAgo}`);
+
+  // Display metadata if available
+  if (recalledData.metadata) {
+    const meta = recalledData.metadata;
+    if (meta.duration) {
+      console.log(`  ⏱️  Last session duration: ${meta.duration}`);
+    }
+    if (meta.toolCount) {
+      console.log(`  🛠️  Tools used: ${meta.toolCount}`);
+    }
+  }
+
+  console.log('');
+  console.log('  📋 Key Points:');
+
+  // Display key points with formatting
+  recalledData.keyPoints.forEach(point => {
+    if (point.startsWith('[SESSION]')) {
+      console.log(`    📊 ${point.replace('[SESSION] ', '')}`);
+    } else if (point.startsWith('[WORK]')) {
+      console.log(`    📁 ${point.replace('[WORK] ', '')}`);
+    } else if (point.startsWith('[COMMIT]')) {
+      console.log(`    ✅ ${point.replace('[COMMIT] ', '')}`);
+    } else if (point.startsWith('[ISSUE]') || point.startsWith('[PROBLEM]')) {
+      console.log(`    ⚠️  ${point.replace(/\[(ISSUE|PROBLEM)\] /, '')}`);
+    } else if (point.startsWith('[LEARN]')) {
+      console.log(`    💡 ${point.replace('[LEARN] ', '')}`);
+    } else if (point.startsWith('[TASK]')) {
+      console.log(`    📝 ${point.replace('[TASK] ', '')}`);
+    } else if (point.startsWith('[DECISION]')) {
+      console.log(`    🎯 ${point.replace('[DECISION] ', '')}`);
+    } else if (point.startsWith('[PATTERN]')) {
+      console.log(`    🔄 ${point.replace('[PATTERN] ', '')}`);
+    } else if (point.startsWith('[SCOPE]') || point.startsWith('[FOCUS]')) {
+      console.log(`    🎯 ${point.replace(/\[(SCOPE|FOCUS)\] /, '')}`);
+    } else if (point.startsWith('[NOTE]')) {
+      console.log(`    📌 ${point.replace('[NOTE] ', '')}`);
+    } else {
+      console.log(`    • ${point}`);
+    }
+  });
+
+  console.log('');
+  console.log('═'.repeat(60));
+  console.log('');
+}
+
+// ============================================================================
+// CLAUDE.md Reload
+// ============================================================================
+
+/**
+ * Find and display project CLAUDE.md content on session start.
+ * This ensures instructions are fresh in context even after compaction.
+ * Searches: CWD/.claude/CLAUDE.md, CWD/CLAUDE.md
+ */
+function reloadClaudeMd() {
+  const cwd = process.cwd();
+  const candidates = [
+    path.join(cwd, '.claude', 'CLAUDE.md'),
+    path.join(cwd, 'CLAUDE.md'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        const content = fs.readFileSync(candidate, 'utf-8');
+        const lineCount = content.split('\n').length;
+        const relativePath = path.relative(cwd, candidate);
+
+        console.log('═'.repeat(60));
+        console.log('  📋 CLAUDE.md Reloaded');
+        console.log('═'.repeat(60));
+        console.log('');
+        console.log(`  Source: ${relativePath} (${lineCount} lines)`);
+        console.log('');
+        console.log(content);
+        console.log('');
+        console.log('═'.repeat(60));
+        console.log('');
+        return;
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+}
+
+// ============================================================================
+// Main Session Start Logic
+// ============================================================================
+
+// ============================================================================
+// Active Plans Display (Beta)
+// ============================================================================
+
+/**
+ * Display active plans with compact timeline.
+ * Also warns about stale plans (no progress for 7+ days).
+ */
+function displayActivePlans() {
+  try {
+    if (!fs.existsSync(MEMESH_DB_PATH)) return;
+
+    const activePlans = queryActivePlans(MEMESH_DB_PATH);
+    if (activePlans.length === 0) return;
+
+    console.log('═'.repeat(60));
+    console.log('  📋 Active Plans');
+    console.log('═'.repeat(60));
+    console.log('');
+
+    for (const plan of activePlans) {
+      console.log(renderTimelineCompact(plan));
+
+      // Stale plan warning (7+ days since last progress)
+      const lastStep = plan.metadata.stepsDetail
+        ?.filter(s => s.completed && s.date)
+        .sort((a, b) => b.date.localeCompare(a.date))[0];
+      if (lastStep && lastStep.date) {
+        const daysSince = Math.floor((Date.now() - new Date(lastStep.date).getTime()) / (1000 * 60 * 60 * 24));
+        if (daysSince >= 7) {
+          console.log(`  ⚠️  No progress for ${daysSince} days`);
+        }
+      }
+      console.log('');
+    }
+
+    console.log('═'.repeat(60));
+    console.log('');
+  } catch (error) {
+    logError('displayActivePlans', error);
+  }
+}
+
+function sessionStart() {
+  console.log('\n🚀 Smart-Agents Session Started\n');
+
+  // Reload project CLAUDE.md into context
+  reloadClaudeMd();
+
+  // Check MeMesh availability
+  const ccbStatus = checkCCBAvailability();
+  displayCCBStatus(ccbStatus);
+
+  // Auto-recall last session's key points from MeMesh
+  const recalledMemory = recallRecentKeyPoints();
+  displayRecalledMemory(recalledMemory);
+
+  // Display active plans (beta)
+  displayActivePlans();
+
+  // Read recommendations from last session
+  const recommendations = readJSONFile(RECOMMENDATIONS_FILE, {
+    recommendedSkills: [],
+    detectedPatterns: [],
+    warnings: [],
+    lastUpdated: null,
+  });
+
+  // Read session context
+  const sessionContext = readJSONFile(SESSION_CONTEXT_FILE, {
+    tokenQuota: { used: 0, limit: 200000 },
+    learnedPatterns: [],
+    lastSessionDate: null,
+  });
+
+  // Display recommendations
+  if (recommendations.recommendedSkills?.length > 0) {
+    console.log('📚 Recommended skills based on last session:');
+    recommendations.recommendedSkills.forEach(skill => {
+      const priority = skill.priority === 'high' ? '🔴' : skill.priority === 'medium' ? '🟡' : '🟢';
+      console.log(`  ${priority} ${skill.name} - ${skill.reason}`);
+    });
+    console.log('');
+  }
+
+  // Display detected patterns
+  if (recommendations.detectedPatterns?.length > 0) {
+    console.log('✨ Detected patterns:');
+    recommendations.detectedPatterns.slice(0, 3).forEach(pattern => {
+      console.log(`  • ${pattern.description}`);
+      if (pattern.suggestion) {
+        console.log(`    💡 ${pattern.suggestion}`);
+      }
+    });
+    console.log('');
+  }
+
+  // Display warnings
+  if (recommendations.warnings?.length > 0) {
+    console.log('⚠️  Warnings:');
+    recommendations.warnings.forEach(warning => {
+      console.log(`  • ${warning}`);
+    });
+    console.log('');
+  }
+
+  // Display quota info (guard against division by zero)
+  const quotaLimit = sessionContext.tokenQuota?.limit || 1;
+  const quotaUsed = sessionContext.tokenQuota?.used || 0;
+  const quotaPercentNum = (quotaUsed / quotaLimit) * 100;
+  if (quotaPercentNum > 80) {
+    console.log(`🔴 Quota usage: ${quotaPercentNum.toFixed(1)}% (please monitor usage)\n`);
+  } else if (quotaPercentNum > 50) {
+    console.log(`🟡 Quota usage: ${quotaPercentNum.toFixed(1)}%\n`);
+  }
+
+  // Initialize current session
+  const currentSession = {
+    startTime: new Date().toISOString(),
+    toolCalls: [],
+    patterns: [],
+    ccbStatus: ccbStatus,
+  };
+
+  if (writeJSONFile(CURRENT_SESSION_FILE, currentSession)) {
+    console.log('✅ Session initialized, ready to work!\n');
+  } else {
+    console.log('⚠️ Session initialization failed, but you can continue working\n');
+  }
+}
+
+// ============================================================================
+// Execute
+// ============================================================================
+
+try {
+  sessionStart();
+} catch (error) {
+  console.error('❌ SessionStart hook error:', error.message);
+  process.exit(0); // Never block Claude Code on hook errors
+}