Release v3.6.3

Published from npm package build Source: https://github.com/thedotmack/claude-mem-source
2025-09-11 17:15:50 -04:00
parent c4eb2e2dc9
commit 97807494fd
43 changed files with 10632 additions and 286 deletions
@@ -0,0 +1,644 @@
+/**
+ * Context Templates for Human-Readable Formatting
+ *
+ * Essential templates for user-facing messages in the memory system.
+ * Focused on session start messages, error handling, and operation feedback.
+ * Previously included Handlebars templates for session start formatting; current
+ * version renders directly via console for clarity and performance.
+ */
+ 
+import { formatRelativeTime, parseTimestamp } from '../../../lib/time-utils.js';
+
+// =============================================================================
+// TERMINAL WIDTH & WORD WRAPPING
+// =============================================================================
+
+/**
+ * Determines target wrap width based on:
+ * 1) CLAUDE_MEM_WRAP_WIDTH env override
+ * 2) TTY columns (capped at 120)
+ * 3) Fallback default of 80
+ */
+function getWrapWidth(): number {
+  const env = process.env.CLAUDE_MEM_WRAP_WIDTH;
+  if (env) {
+    const n = parseInt(env, 10);
+    if (!Number.isNaN(n) && n > 40 && n <= 200) return n;
+  }
+  // Default to classic 80 columns unless overridden
+  return 80;
+}
+
+/**
+ * Wrap a single logical line to the given width, preserving leading indentation.
+ * Also avoids wrapping pure separator lines (====, ----, etc.).
+ */
+function wrapSingleLine(line: string, width: number): string {
+  if (!line) return '';
+  // Don't wrap long separator lines
+  if (/^[\-=\u2014_\u2500\u2550]{5,}$/.test(line.trim())) return line;
+
+  // If already short enough, return as-is
+  if (line.length <= width) return line;
+
+  const indentMatch = line.match(/^\s*/);
+  const indent = indentMatch ? indentMatch[0] : '';
+  const content = line.slice(indent.length);
+  const avail = Math.max(10, width - indent.length); // keep some minimum
+
+  const words = content.split(/(\s+)/); // keep whitespace tokens
+  const out: string[] = [];
+  let current = '';
+
+  const pushLine = () => {
+    out.push(indent + current.trimEnd());
+    current = '';
+  };
+
+  for (const token of words) {
+    if (token === '') continue;
+    // If token itself is longer than available width, hard-break it
+    if (!/\s/.test(token) && token.length > avail) {
+      if (current.trim().length > 0) pushLine();
+      let start = 0;
+      while (start < token.length) {
+        const chunk = token.slice(start, start + avail);
+        out.push(indent + chunk);
+        start += avail;
+      }
+      current = '';
+      continue;
+    }
+
+    if (indent.length + current.length + token.length > width) {
+      pushLine();
+    }
+    current += token;
+  }
+
+  if (current.trim().length > 0 || out.length === 0) pushLine();
+  return out.join('\n');
+}
+
+/**
+ * Wrap a block of text (possibly multi-line) to the given width.
+ * Preserves blank lines and wraps each line independently.
+ */
+function wrapText(text: string, width: number): string {
+  if (!text) return '';
+  return text
+    .split('\n')
+    .map((line) => wrapSingleLine(line, width))
+    .join('\n');
+}
+
+/** Create a full-width horizontal line with the given character */
+function makeLine(char: string = '─', width: number = getWrapWidth()): string {
+  if (!char || char.length === 0) char = '-';
+  // Repeat and slice to exact width to avoid multi-column surprises
+  return char.repeat(width).slice(0, width);
+}
+
+// =============================================================================
+// SESSION START MESSAGES
+// =============================================================================
+
+/**
+ * Creates a welcoming session start message explaining what memories were loaded
+ */
+export function createSessionStartMessage(
+  projectName: string,
+  memoryCount: number,
+  lastSessionTime?: string
+): string {
+  const width = getWrapWidth();
+  const timeInfo = lastSessionTime ? ` (last worked: ${lastSessionTime})` : '';
+
+  if (memoryCount === 0) {
+    return wrapText(
+      `🧠 Loading memories from previous sessions for ${projectName}${timeInfo}
+
+No relevant memories found - this appears to be your first session or a new project area.
+
+💡 Getting Started:
+• Start working and memories will be automatically created
+• At the end of your session, ask to compress and store the conversation
+• Next time you return, relevant context will be loaded automatically`,
+      width
+    );
+  }
+
+  const memoryText =
+    memoryCount === 1 ? 'relevant memory' : 'relevant memories';
+  return wrapText(
+    `🧠 Loading memories from previous sessions for ${projectName}${timeInfo}
+
+Found ${memoryCount} ${memoryText} to help continue your work.`,
+    width
+  );
+}
+
+// =============================================================================
+// OPERATION MESSAGES
+// =============================================================================
+
+/**
+ * Creates a loading message during context retrieval
+ */
+export function createLoadingMessage(operation: string): string {
+  const operations: Record<string, string> = {
+    searching: '🔍 Searching previous memories...',
+    loading: '📚 Loading relevant context...',
+    formatting: '✨ Organizing memories for display...',
+    compressing: '🗜️ Compressing session transcript...',
+    archiving: '📦 Archiving conversation...',
+  };
+
+  const width = getWrapWidth();
+  return wrapText(operations[operation] || `⏳ ${operation}...`, width);
+}
+
+/**
+ * Creates a completion message after context operations
+ */
+export function createCompletionMessage(
+  operation: string,
+  count?: number,
+  details?: string
+): string {
+  const countInfo = count !== undefined ? ` (${count} items)` : '';
+  const detailInfo = details ? `\n${details}` : '';
+  const width = getWrapWidth();
+  return wrapText(
+    `✅ ${operation} completed successfully${countInfo}${detailInfo}`,
+    width
+  );
+}
+
+// =============================================================================
+// ERROR MESSAGES (USER-FRIENDLY)
+// =============================================================================
+
+/**
+ * Creates user-friendly error messages with helpful suggestions
+ */
+export function createUserFriendlyError(
+  operation: string,
+  error: string,
+  suggestion?: string
+): string {
+  const suggestionText = suggestion ? `\n\n💡 ${suggestion}` : '';
+  const width = getWrapWidth();
+  return wrapText(
+    `❌ ${operation} encountered an issue: ${error}${suggestionText}`,
+    width
+  );
+}
+
+/**
+ * Common error scenarios with built-in suggestions
+ */
+export const ERROR_SCENARIOS = {
+  NO_MEMORIES: (projectName: string) => ({
+    message: `No previous memories found for ${projectName}`,
+    suggestion:
+      'This appears to be your first session. Memories will be created as you work.',
+  }),
+
+  CONNECTION_FAILED: () => ({
+    message: 'Could not connect to memory system',
+    suggestion:
+      'Try restarting Claude Code or check if the MCP server is properly configured.',
+  }),
+
+  SEARCH_FAILED: (query: string) => ({
+    message: `Search for "${query}" didn't return any results`,
+    suggestion:
+      'Try using different keywords or check if memories exist for this project.',
+  }),
+
+  LOAD_TIMEOUT: () => ({
+    message: 'Memory loading timed out',
+    suggestion:
+      'The operation is taking longer than expected. You can continue without loaded context.',
+  }),
+};
+
+/**
+ * Creates contextual error messages based on common scenarios
+ */
+export function createContextualError(
+  scenario: keyof typeof ERROR_SCENARIOS,
+  ...args: string[]
+): string {
+  const errorInfo = (ERROR_SCENARIOS[scenario] as any)(...args);
+  return createUserFriendlyError(
+    'Memory system',
+    errorInfo.message,
+    errorInfo.suggestion
+  );
+}
+
+// =============================================================================
+// TIME AND DATE FORMATTING
+// =============================================================================
+
+/**
+ * Formats timestamps into human-readable "time ago" format
+ */
+export function formatTimeAgo(timestamp: string | Date): string {
+  const date = typeof timestamp === 'string' ? new Date(timestamp) : timestamp;
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
+  if (hours < 24) return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+  if (days < 7) return `${days} day${days > 1 ? 's' : ''} ago`;
+
+  return date.toLocaleDateString();
+}
+
+/**
+ * Creates summary text for memory operations
+ */
+export function createOperationSummary(
+  operation: 'compress' | 'load' | 'search' | 'archive',
+  results: { count: number; duration?: number; details?: string }
+): string {
+  const { count, duration, details } = results;
+  const durationText = duration ? ` in ${duration}ms` : '';
+  const detailsText = details ? ` - ${details}` : '';
+
+  const templates = {
+    compress: `Compressed ${count} conversation turns${durationText}${detailsText}`,
+    load: `Loaded ${count} relevant memories${durationText}${detailsText}`,
+    search: `Found ${count} matching memories${durationText}${detailsText}`,
+    archive: `Archived ${count} conversation segments${durationText}${detailsText}`,
+  };
+
+  const width = getWrapWidth();
+  return wrapText(`📊 ${templates[operation]}`, width);
+}
+
+// =============================================================================
+// SESSION START TEMPLATE SYSTEM (data processing only)
+// =============================================================================
+
+/**
+ * Interface for memory entry data structure
+ */
+interface MemoryEntry {
+  summary: string;
+  keywords?: string;
+  location?: string;
+  sessionId?: string;
+  number?: number;
+}
+
+/**
+ * Interface for grouped session memories
+ */
+interface SessionGroup {
+  sessionId: string;
+  memories: MemoryEntry[];
+}
+
+/**
+ * Formats current date and time for session start
+ */
+export function formatCurrentDateTime(): string {
+  const now = new Date();
+  const currentDateTime = now.toLocaleString('en-US', {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    timeZoneName: 'short',
+  });
+
+  return `Current Date / Time: ${currentDateTime}\n`;
+}
+
+/**
+ * Extracts overview section from JSON objects
+ * Looks for objects with type "overview" and matching project
+ */
+export function extractOverview(
+  recentObjects: any[],
+  projectName?: string
+): string | null {
+  // Find overview objects
+  const overviewObjects = recentObjects.filter(
+    (obj) => obj.type === 'overview'
+  );
+
+  if (overviewObjects.length === 0) {
+    return null;
+  }
+
+  // If project is specified, find overview for that project
+  if (projectName) {
+    const projectOverview = overviewObjects.find(
+      (obj) => obj.project === projectName
+    );
+    if (projectOverview) {
+      return projectOverview.content;
+    }
+  }
+
+  // Return the most recent overview if no project match
+  return overviewObjects[overviewObjects.length - 1]?.content || null;
+}
+
+/**
+ * Interface for overview with timestamp
+ */
+interface OverviewEntry {
+  content: string;
+  timestamp?: Date;
+  timeAgo?: string;
+  sessionId?: string;
+}
+
+/**
+ * Interface for session-grouped overviews
+ */
+interface SessionOverviewGroup {
+  sessionId: string;
+  overviews: OverviewEntry[];
+  earliestTimestamp?: Date;
+  timeAgo?: string;
+}
+
+/**
+ * Extracts multiple overviews with timestamps
+ * Returns up to 'count' most recent overviews
+ */
+export function extractOverviews(
+  recentObjects: any[],
+  count: number = 3,
+  projectName?: string
+): OverviewEntry[] {
+  // Find overview objects
+  const overviewObjects = recentObjects.filter(
+    (obj) => obj.type === 'overview'
+  );
+
+  if (overviewObjects.length === 0) {
+    return [];
+  }
+
+  // Filter by project if specified
+  let filteredOverviews = overviewObjects;
+  if (projectName) {
+    filteredOverviews = overviewObjects.filter(
+      (obj) => obj.project === projectName
+    );
+
+    // Fall back to all overviews if no project match
+    if (filteredOverviews.length === 0) {
+      filteredOverviews = overviewObjects;
+    }
+  }
+
+  // Take the last 'count' overviews
+  const recentOverviews = filteredOverviews.slice(-count);
+
+  // Process each overview with timestamp and session ID
+  return recentOverviews.map((obj) => {
+    const entry: OverviewEntry = {
+      content: obj.content || '',
+      sessionId: obj.sessionId || obj.session_id || 'unknown',
+    };
+
+    // Try to parse timestamp
+    const timestamp = parseTimestamp(obj);
+    if (timestamp) {
+      entry.timestamp = timestamp;
+      entry.timeAgo = formatRelativeTime(timestamp);
+    } else {
+      // Fallback if no timestamp
+      entry.timeAgo = 'Recently';
+    }
+
+    return entry;
+  }); // Show in original order (oldest to newest)
+}
+
+/**
+ * Pure data processing function - converts JSON objects into structured memory entries
+ * No formatting is done here, only data parsing and cleaning
+ */
+export function processMemoryEntries(recentObjects: any[]): MemoryEntry[] {
+  if (recentObjects.length === 0) {
+    return [];
+  }
+
+  // Filter only memory type objects and convert to MemoryEntry format
+  return recentObjects
+    .filter((obj) => obj.type === 'memory')
+    .map((obj) => {
+      const entry: MemoryEntry = {
+        summary: obj.text || '',
+        sessionId: obj.session_id || '',
+      };
+
+      // Add optional fields if present
+      if (obj.keywords) {
+        entry.keywords = obj.keywords;
+      }
+      if (obj.document_id && !obj.document_id.includes('Session:')) {
+        entry.location = obj.document_id;
+      }
+
+      return entry;
+    })
+    .filter((entry) => entry.summary.length > 0);
+}
+
+/**
+ * Groups memories by session ID and adds numbering
+ */
+function groupMemoriesBySession(memories: MemoryEntry[]): SessionGroup[] {
+  const sessionMap = new Map<string, MemoryEntry[]>();
+
+  // Group memories by session ID
+  memories.forEach((memory) => {
+    const sessionId = memory.sessionId;
+    if (sessionId) {
+      if (!sessionMap.has(sessionId)) {
+        sessionMap.set(sessionId, []);
+      }
+      sessionMap.get(sessionId)!.push(memory);
+    }
+  });
+
+  // Convert to session groups with numbering
+  return Array.from(sessionMap.entries()).map(
+    ([sessionId, sessionMemories]) => {
+      const numberedMemories = sessionMemories.map((memory, index) => ({
+        ...memory,
+        number: index + 1,
+      }));
+
+      return {
+        sessionId,
+        memories: numberedMemories,
+      };
+    }
+  );
+}
+
+/**
+ * Groups overviews by session ID and calculates session timestamps
+ */
+function groupOverviewsBySession(
+  overviews: OverviewEntry[]
+): SessionOverviewGroup[] {
+  const sessionMap = new Map<string, OverviewEntry[]>();
+
+  // Group overviews by session ID
+  overviews.forEach((overview) => {
+    const sessionId = overview.sessionId || 'unknown';
+    if (!sessionMap.has(sessionId)) {
+      sessionMap.set(sessionId, []);
+    }
+    sessionMap.get(sessionId)!.push(overview);
+  });
+
+  // Convert to session groups with timestamps
+  return Array.from(sessionMap.entries()).map(
+    ([sessionId, sessionOverviews]) => {
+      // Find the earliest timestamp in this session's overviews
+      const timestamps = sessionOverviews
+        .map((o) => o.timestamp)
+        .filter((t): t is Date => t !== undefined)
+        .sort((a, b) => a.getTime() - b.getTime());
+
+      const group: SessionOverviewGroup = {
+        sessionId,
+        overviews: sessionOverviews,
+      };
+
+      // Add session-level timestamp if available
+      if (timestamps.length > 0) {
+        group.earliestTimestamp = timestamps[0];
+        group.timeAgo = formatRelativeTime(timestamps[0]);
+      }
+
+      return group;
+    }
+  );
+}
+
+/**
+ * Renders the complete session start template with provided data using Handlebars
+ * Data processing is separated from presentation - template controls the format
+ */
+// Intentionally removed Handlebars-based renderer; console output is handled by
+// outputSessionStartContent() below.
+
+/**
+ * Outputs session start content using dual streams:
+ * - stdout (console.log) -> Claude's context only (granular memories)
+ * - stderr (console.error) -> User visible (clean overviews)
+ */
+export function outputSessionStartContent(params: {
+  projectName: string;
+  memoryCount: number;
+  lastSessionTime?: string;
+  recentObjects: any[];
+}): void {
+  const { projectName, memoryCount, lastSessionTime, recentObjects } = params;
+  const width = getWrapWidth();
+
+  // Extract overviews for user display - get more to show session grouping
+  const overviews = extractOverviews(recentObjects, 10, projectName);
+
+  // Process memory entries for Claude context
+  const memories = processMemoryEntries(recentObjects);
+  // Helper to split and normalize keywords into a map (lowercased -> original)
+  const splitKeywordsInto = (kw: string, dest: Map<string, string>) => {
+    const tokens =
+      kw.includes(',') || kw.includes('\n') ? kw.split(/[\n,]+/) : [kw];
+    for (const t of tokens) {
+      const trimmed = t.trim();
+      if (!trimmed) continue;
+      const key = trimmed.toLowerCase();
+      if (!dest.has(key)) dest.set(key, trimmed);
+    }
+  };
+
+  // Output memories first, then overviews at bottom, all sorted oldest to newest
+  if (memories.length > 0) {
+    const sessionGroups = groupMemoriesBySession(memories);
+    console.log('');
+    console.log('');
+
+    console.log(wrapText('📚 Memories', width));
+    sessionGroups.forEach((group) => {
+      console.log(makeLine('─', width));
+
+      console.log('');
+
+      console.log(wrapText(`🔍 ${group.sessionId}`, width));
+
+      // Collect keywords for this session as we iterate its memories
+      const groupKeywordMap = new Map<string, string>();
+
+      group.memories.forEach((memory) => {
+        console.log('');
+        console.log(wrapText(`${memory.number}. ${memory.summary}`, width));
+        if (memory.keywords)
+          splitKeywordsInto(memory.keywords, groupKeywordMap);
+      });
+
+      // Print this session's aggregated keywords under the session block
+      const groupKeywords = Array.from(groupKeywordMap.values());
+      if (groupKeywords.length > 0) {
+        console.log('');
+        console.log(wrapText(`🏷️  ${groupKeywords.join(', ')}`, width));
+      }
+      console.log('');
+    });
+  }
+
+  // Overview section at bottom with session grouping
+  if (overviews.length > 0) {
+    const sessionGroups = groupOverviewsBySession(overviews);
+    console.log('');
+
+    console.log(wrapText('🧠 Overviews', width));
+    console.log(makeLine('─', width));
+
+    // Match the memories section layout: session header, numbered items, per-session separator
+    sessionGroups.forEach((group) => {
+      console.log('');
+      console.log(wrapText(`🔍 ${group.sessionId}`, width));
+
+      group.overviews.forEach((overview, index) => {
+        console.log('');
+        console.log(wrapText(`${index + 1}. ${overview.content}`, width));
+        console.log('');
+
+        if (overview.timeAgo) {
+          console.log(wrapText(`📅 ${overview.timeAgo}`, width));
+        }
+      });
+
+      console.log('');
+      console.log(makeLine('─', width));
+    });
+  } else if (memories.length === 0) {
+    console.log(
+      wrapText(`🧠 No recent context found for ${projectName}`, width)
+    );
+  }
+}