claude-mneme 2.9.1

package/scripts/session-start.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Session Start Hook
+ * Reads project-specific memory context and outputs it for injection
+ *
+ * Uses hierarchical context injection:
+ * - HIGH priority: Project context, key decisions, current state, remembered items
+ * - MEDIUM priority: Recent work, git changes, active entities
+ * - LOW priority: Recent log entries (limited to last few)
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { join } from 'path';
+import { ensureMemoryDirs, loadConfig, getProjectName, escapeAttr, formatEntry, renderSummaryToMarkdown, flushPendingLog, scoreEntriesByRelevance, getRelevantEntities, deduplicateEntries, readCachedData, withFileLock, logError, getErrorsSince } from './utils.mjs';
+import { pullIfEnabled, startHeartbeat } from './sync.mjs';
+
+async function main() {
+  const cwd = process.cwd();
+  const paths = ensureMemoryDirs(cwd);
+  const config = loadConfig();
+  const projectName = getProjectName(cwd);
+  const ciConfig = config.contextInjection || {};
+  const sections = ciConfig.sections || {};
+
+  // Flush any pending log entries from previous session
+  flushPendingLog(cwd, 0);
+
+  // Sync: pull files from server if enabled (before reading cached data)
+  const syncResult = await pullIfEnabled(cwd, config);
+  if (syncResult.lockAcquired) {
+    startHeartbeat(cwd, config);
+  }
+
+  // Prune stale tasks (>24h) instead of deleting — avoids wiping another session's tracking
+  const taskTrackingPath = join(paths.project, 'active-tasks.json');
+  const taskLockPath = taskTrackingPath + '.lock';
+  try {
+    withFileLock(taskLockPath, () => {
+      if (!existsSync(taskTrackingPath)) return;
+      const data = JSON.parse(readFileSync(taskTrackingPath, 'utf-8'));
+      const tasks = data.tasks || {};
+      const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+      let pruned = false;
+      for (const [id, task] of Object.entries(tasks)) {
+        const ts = task.createdAt ? new Date(task.createdAt).getTime() : 0;
+        if (ts < cutoff) {
+          delete tasks[id];
+          pruned = true;
+        }
+      }
+      if (pruned) {
+        data.tasks = tasks;
+        writeFileSync(taskTrackingPath, JSON.stringify(data));
+      }
+    }, 5);
+  } catch {}
+
+  // ============================================================================
+  // Read all data using cache (avoids redundant file reads/parsing)
+  // ============================================================================
+  const cachedData = readCachedData(cwd, config);
+
+  // ============================================================================
+  // HIGH PRIORITY - Always inject
+  // ============================================================================
+
+  // Render structured summary
+  let summaryParts = { high: '', medium: '', full: '' };
+
+  if (cachedData.summary) {
+    summaryParts = renderSummaryToMarkdown(cachedData.summary, projectName, ciConfig);
+  }
+
+  // Read persistent remembered items (HIGH priority)
+  let remembered = [];
+  const remConfig = sections.remembered || { enabled: true };
+  if (remConfig.enabled !== false) {
+    remembered = cachedData.remembered || [];
+  }
+
+  // ============================================================================
+  // MEDIUM PRIORITY - Inject if relevant/recent
+  // ============================================================================
+
+  // Git changes since last session
+  let gitChanges = '';
+  const gcConfig = sections.gitChanges || { enabled: true };
+  if (gcConfig.enabled !== false) {
+    try {
+      let sinceArg = null;
+      if (existsSync(paths.lastSession)) {
+        sinceArg = readFileSync(paths.lastSession, 'utf-8').trim();
+      }
+      if (sinceArg) {
+        const log = execFileSync('git', ['log', '--oneline', `--since=${sinceArg}`], {
+          encoding: 'utf8',
+          cwd,
+          stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        if (log) gitChanges = log;
+      }
+    } catch {
+      // Not a git repo or git error — skip silently
+    }
+  }
+
+  // Get relevant entities for context (MEDIUM priority)
+  let relevantEntities = null;
+  const aeConfig = sections.activeEntities || { enabled: true, maxFiles: 5, maxFunctions: 5 };
+  const eeConfig = config.entityExtraction || {};
+  if (aeConfig.enabled !== false && eeConfig.enabled !== false) {
+    try {
+      relevantEntities = getRelevantEntities(cwd);
+    } catch (e) {
+      logError(e, 'session-start:getRelevantEntities');
+    }
+  }
+
+  // ============================================================================
+  // LOW PRIORITY - Minimal injection
+  // ============================================================================
+
+  // Process log entries by relevance (LOW priority - reduced count)
+  let recentEntries = [];
+  const reConfig = sections.recentEntries || { enabled: true, maxItems: 4 };
+  if (reConfig.enabled !== false && cachedData.logEntries.length > 0) {
+    // Filter out response entries (low signal)
+    let meaningful = cachedData.logEntries.filter(e => e.type !== 'response');
+
+    // Apply semantic deduplication - group related entries and keep highest signal
+    meaningful = deduplicateEntries(meaningful, config);
+
+    // Use hierarchical limit (default 4, not 10)
+    const maxEntries = reConfig.maxItems || 4;
+    const rsConfig = config.relevanceScoring || {};
+
+    if (rsConfig.enabled !== false && meaningful.length > maxEntries) {
+      // Score and rank by relevance
+      const ranked = scoreEntriesByRelevance(meaningful, cwd, config);
+      recentEntries = ranked.slice(0, maxEntries).map(formatEntry);
+    } else {
+      // Fall back to simple recency
+      recentEntries = meaningful.slice(-maxEntries).map(formatEntry);
+    }
+  }
+
+  // Write current timestamp for next session
+  try {
+    writeFileSync(paths.lastSession, new Date().toISOString(), 'utf-8');
+  } catch (e) {
+    logError(e, 'session-start:lastSession');
+  }
+
+  // ============================================================================
+  // Output - Hierarchical injection
+  // ============================================================================
+
+  // Read handoff from previous session (if recent)
+  let handoff = null;
+  const lsConfig = sections.lastSession || { enabled: true };
+  if (lsConfig.enabled !== false && existsSync(paths.handoff)) {
+    try {
+      const data = JSON.parse(readFileSync(paths.handoff, 'utf-8'));
+      const maxAgeMs = 48 * 60 * 60 * 1000;
+      if (data.ts && (Date.now() - new Date(data.ts).getTime()) < maxAgeMs) {
+        handoff = data;
+      }
+    } catch {}
+  }
+
+  const hasContent = summaryParts.high || summaryParts.medium ||
+                     remembered.length > 0 || gitChanges ||
+                     recentEntries.length > 0 || relevantEntities || handoff;
+
+  if (hasContent) {
+    console.log(`<claude-mneme project="${escapeAttr(projectName)}">`);
+
+    // HANDOFF from previous session (highest immediate value)
+    if (handoff) {
+      console.log('\n## Last Session\n');
+      if (handoff.workingOn) console.log(`**Working on:** ${handoff.workingOn}`);
+      if (handoff.lastDone) console.log(`**Done:** ${handoff.lastDone}`);
+      if (handoff.openItems?.length > 0) {
+        console.log(`**Open:** ${handoff.openItems.join(', ')}`);
+      }
+    }
+
+    // LESSONS LEARNED - high visibility to avoid repeating mistakes
+    const lessons = remembered.filter(r => r.type === 'lesson');
+    const otherRemembered = remembered.filter(r => r.type !== 'lesson');
+
+    if (lessons.length > 0) {
+      console.log('\n## Lessons Learned\n');
+      for (const item of lessons) {
+        console.log(`- ${item.content}`);
+      }
+    }
+
+    // HIGH PRIORITY SECTION
+    if (summaryParts.high) {
+      console.log(summaryParts.high);
+    }
+
+    if (otherRemembered.length > 0) {
+      console.log('\n## Remembered\n');
+      for (const item of otherRemembered) {
+        console.log(`- [${item.type}] ${item.content}`);
+      }
+    }
+
+    // MEDIUM PRIORITY SECTION
+    if (summaryParts.medium) {
+      console.log(summaryParts.medium);
+    }
+
+    if (gitChanges) {
+      console.log('\n## Changes Since Last Session\n');
+      console.log(gitChanges);
+    }
+
+    if (relevantEntities) {
+      const maxFiles = aeConfig.maxFiles || 5;
+      const maxFunctions = aeConfig.maxFunctions || 5;
+      const hasClusters = relevantEntities.clusters?.length > 0;
+      const hasEntities = hasClusters ||
+                          (relevantEntities.files?.length > 0) ||
+                          (relevantEntities.functions?.length > 0);
+      if (hasEntities) {
+        console.log('\n## Recently Active\n');
+        const badgeMap = { commit: 'modified', task: 'worked on', prompt: 'discussed', agent: 'worked on', response: 'discussed' };
+        const formatEntity = (e) => {
+          let line = `\`${e.name}\``;
+          const badges = [...new Set((e.contextTypes || []).map(t => badgeMap[t]).filter(Boolean))];
+          if (badges.length > 0) line += ` [${badges.join(', ')}]`;
+          if (e.velocity) line += ` (${e.velocity})`;
+          if (e.recentContext) line += ` — ${e.recentContext}`;
+          return `- ${line}`;
+        };
+        if (hasClusters) {
+          for (const cluster of relevantEntities.clusters) {
+            const label = cluster.label
+              ? cluster.label.charAt(0).toUpperCase() + cluster.label.slice(1)
+              : 'Related';
+            console.log(`**${label}:**`);
+            cluster.entities.forEach(e => console.log(formatEntity(e)));
+          }
+        }
+        if (relevantEntities.files?.length > 0) {
+          console.log('**Files:**');
+          relevantEntities.files.slice(0, maxFiles).forEach(f => console.log(formatEntity(f)));
+        }
+        if (relevantEntities.functions?.length > 0) {
+          console.log('**Functions:**');
+          relevantEntities.functions.slice(0, maxFunctions).forEach(f => console.log(formatEntity(f)));
+        }
+      }
+    }
+
+    // LOW PRIORITY SECTION
+    if (recentEntries.length > 0) {
+      console.log('\n## Recent Activity\n');
+      recentEntries.forEach(entry => console.log(`- ${entry}`));
+    }
+
+    // Check for recent errors and warn user
+    const recentErrors = getErrorsSince(24);
+    if (recentErrors.length > 0) {
+      console.log(`\n⚠️ **${recentErrors.length} error(s) in the last 24 hours.** Run \`/status\` to diagnose.`);
+    }
+
+    console.log('\nTip: Use /remember to save key decisions, preferences, or project context for future sessions.');
+    console.log('</claude-mneme>');
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch(err => {
+    logError(err, 'session-start');
+    console.error(`[mneme] Error: ${err.message}`);
+    process.exit(0); // Exit 0 — memory is non-critical, don't block session startup
+  });

package/scripts/session-stop.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Session Stop Hook
+ * Flushes pending log entries, pushes to sync server, and checks for summarization
+ */
+
+import { flushPendingLog, loadConfig, logError } from './utils.mjs';
+import { pushIfEnabled, stopHeartbeat } from './sync.mjs';
+
+async function main() {
+  const cwd = process.cwd();
+  const config = loadConfig();
+
+  // Stop the heartbeat interval
+  stopHeartbeat();
+
+  // Flush all pending entries (throttle=0 forces immediate flush)
+  // This also triggers maybeSummarize after merging
+  flushPendingLog(cwd, 0);
+
+  // Sync: push files to server if enabled
+  await pushIfEnabled(cwd, config);
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch(err => {
+    logError(err, 'session-stop');
+    console.error(`[mneme] Error: ${err.message}`);
+    process.exit(0); // Exit 0 — memory is non-critical, don't block session lifecycle
+  });

package/scripts/stop-capture.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook - Response Capture
+ * Captures Claude's final response when a turn completes
+ * Supports configurable summarization: none, extractive, or llm
+ *
+ * Handles markdown formatting:
+ * - Splits on paragraph breaks (double newlines)
+ * - Treats bullet list items as separate units
+ * - Falls back to sentence boundary detection
+ *
+ * Runs before session-stop.mjs (summarization)
+ */
+
+import { readFileSync, writeFileSync, existsSync, statSync, openSync, readSync, closeSync } from 'fs';
+import { ensureMemoryDirs, loadConfig, appendLogEntry, extractiveSummarize, stripMarkdown, logError } from './utils.mjs';
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const hookData = JSON.parse(input);
+    processStop(hookData);
+  } catch (e) {
+    logError(e, 'stop-capture');
+    process.exit(0);
+  }
+});
+
+/**
+ * Read and parse transcript from transcript_path
+ * Claude Code provides transcript as a JSONL file path, not direct data
+ */
+function readTranscript(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(transcriptPath, 'utf-8').trim();
+    if (!content) return null;
+
+    // Parse JSONL - each line is a JSON object
+    const lines = content.split('\n').filter(l => l.trim());
+    const transcript = [];
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        // Transcript entries have role and message properties
+        if (entry.type === 'user' || entry.type === 'assistant') {
+          transcript.push({
+            role: entry.type,
+            content: entry.message?.content || entry.content
+          });
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return transcript.length > 0 ? transcript : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract text content from a message content field (string or content blocks)
+ */
+function extractTextContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('\n');
+  }
+  return '';
+}
+
+const CONFIRMATION_PATTERN = /^(y(es)?|no?|ok(ay)?|sure|go ahead|continue|do it|sounds good|lgtm|looks good|please|yep|yup|nope|correct|right|exactly|agreed|confirmed?)\.?$/i;
+
+function isConfirmation(text) {
+  return text.trim().length < 20 || CONFIRMATION_PATTERN.test(text.trim());
+}
+
+/**
+ * Extract open items / next steps from assistant text
+ */
+function extractOpenItems(text) {
+  if (!text) return [];
+  const items = [];
+  const patterns = [
+    /(?:next steps?|todo|remaining|still need to|should|need to|plan to)[:\s]+(.+)/gi,
+    /(?:^|\n)\s*[-*]\s*\[[ ]\]\s*(.+)/gm,  // unchecked markdown checkboxes
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const item = match[1].trim().substring(0, 150);
+      if (item.length >= 10 && items.length < 5) {
+        items.push(item);
+      }
+    }
+  }
+  return items;
+}
+
+/**
+ * Build handoff data from transcript for next session pickup
+ */
+function extractHandoff(transcript, responseSummary) {
+  // Find last meaningful user prompt (walk backward, skip confirmations)
+  let workingOn = null;
+  for (let i = transcript.length - 1; i >= 0; i--) {
+    if (transcript[i].role === 'user') {
+      const text = extractTextContent(transcript[i].content);
+      if (text && text.length >= 20 && !isConfirmation(text)) {
+        workingOn = text.substring(0, 300);
+        break;
+      }
+    }
+  }
+
+  // Get open items from last assistant response
+  let lastAssistantText = '';
+  for (let i = transcript.length - 1; i >= 0; i--) {
+    if (transcript[i].role === 'assistant') {
+      lastAssistantText = extractTextContent(transcript[i].content);
+      break;
+    }
+  }
+
+  return {
+    ts: new Date().toISOString(),
+    workingOn,
+    lastDone: responseSummary || null,
+    openItems: extractOpenItems(lastAssistantText),
+  };
+}
+
+/**
+ * Read last N lines from a file efficiently (tail of file only)
+ */
+function readLastLines(filePath, count) {
+  try {
+    const stat = statSync(filePath);
+    if (stat.size === 0) return [];
+    const readSize = Math.min(stat.size, 4096);
+    const buf = Buffer.alloc(readSize);
+    const fd = openSync(filePath, 'r');
+    readSync(fd, buf, 0, readSize, stat.size - readSize);
+    closeSync(fd);
+    const lines = buf.toString('utf-8').trim().split('\n');
+    return lines.slice(-count);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if the last response entry already has identical content.
+ * Prevents duplicate logging when Stop fires but the transcript's last
+ * assistant message hasn't changed (e.g. current turn used a subagent).
+ */
+function isDuplicateResponse(content, logPath) {
+  const pendingPath = logPath.replace('.jsonl', '.pending.jsonl');
+  const filesToCheck = [pendingPath, logPath].filter(f => existsSync(f));
+  const prefix = content.substring(0, 100).toLowerCase();
+
+  for (const filePath of filesToCheck) {
+    const lastLines = readLastLines(filePath, 5);
+    for (const line of lastLines) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === 'response') {
+          const existing = (entry.content || '').substring(0, 100).toLowerCase();
+          if (prefix === existing || prefix.startsWith(existing) || existing.startsWith(prefix)) {
+            return true;
+          }
+        }
+      } catch {}
+    }
+  }
+  return false;
+}
+
+function processStop(hookData) {
+  const { transcript_path, cwd } = hookData;
+
+  // Read transcript from file path (Claude Code passes path, not data)
+  const transcript = readTranscript(transcript_path);
+
+  if (!transcript || transcript.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Find the last assistant message in the transcript
+  let lastAssistantMessage = null;
+  for (let i = transcript.length - 1; i >= 0; i--) {
+    if (transcript[i].role === 'assistant') {
+      lastAssistantMessage = transcript[i];
+      break;
+    }
+  }
+
+  if (!lastAssistantMessage) {
+    process.exit(0);
+    return;
+  }
+
+  // Extract text content from the assistant message
+  const content = lastAssistantMessage.content;
+  let textContent = '';
+
+  if (typeof content === 'string') {
+    textContent = content;
+  } else if (Array.isArray(content)) {
+    // Content blocks - extract text blocks only
+    textContent = content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('\n');
+  }
+
+  if (!textContent || textContent.trim().length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Skip /remember command responses (already persisted in remembered.json)
+  const rememberPatterns = [
+    /what would you like me to remember/i,
+    /remembered\.json/,
+    /this will persist across all future sessions/i,
+  ];
+  if (rememberPatterns.some(p => p.test(textContent))) {
+    process.exit(0);
+    return;
+  }
+
+  const config = loadConfig();
+  let processed = stripMarkdown(textContent);
+
+  // Apply response summarization based on configured mode
+  const mode = config.responseSummarization || 'none';
+  if (mode === 'extractive') {
+    processed = extractiveSummarize(processed, config);
+  }
+  // 'llm' mode: reserved for future LLM-based summarization
+  // 'none': no summarization, just length cap below
+
+  // Apply max length truncation as final safeguard
+  if (processed.length > config.maxResponseLength) {
+    processed = processed.substring(0, config.maxResponseLength) + '...';
+  }
+
+  const workDir = cwd || process.cwd();
+  const paths = ensureMemoryDirs(workDir);
+
+  // Skip if the last response entry already has identical content
+  // (happens when Stop fires but transcript's last assistant msg is stale,
+  // e.g. current turn used a subagent whose output came via tool result)
+  if (isDuplicateResponse(processed, paths.log)) {
+    process.exit(0);
+    return;
+  }
+
+  const entry = {
+    ts: new Date().toISOString(),
+    type: 'response',
+    content: processed
+  };
+
+  appendLogEntry(entry, workDir);
+
+  // Write handoff for next session pickup
+  try {
+    const handoff = extractHandoff(transcript, processed);
+    writeFileSync(paths.handoff, JSON.stringify(handoff, null, 2));
+  } catch (e) {
+    logError(e, 'stop-capture:handoff');
+  }
+
+  process.exit(0);
+}
+
+// Timeout fallback
+setTimeout(() => process.exit(0), 10000);