memorylink 1.0.0

package/src/utils/commit-patterns.ts

@@ -0,0 +1,87 @@
+/**
+ * MemoryLink - Commit Pattern Detection
+ * Detect commit message patterns and suggest logging
+ * 
+ * v1.3: Week 6 - Enhanced Auto-Capture
+ */
+
+/**
+ * Commit message patterns that suggest learning/decision logging
+ */
+export interface CommitPattern {
+  pattern: RegExp;
+  type: 'learning' | 'memory';
+  suggestion: string;
+  tags?: string[];
+}
+
+const COMMIT_PATTERNS: CommitPattern[] = [
+  {
+    pattern: /^(fix|bugfix|fixes?|fixed|resolve|resolves?|resolved)/i,
+    type: 'learning',
+    suggestion: 'This looks like a bug fix. Consider logging as a learning: memorylink learn "Problem" "Solution" --status SUCCESS',
+    tags: ['bugfix', 'fix'],
+  },
+  {
+    pattern: /^(feat|feature|add|added|implement|implements?|implemented)/i,
+    type: 'memory',
+    suggestion: 'This looks like a new feature. Consider logging as a decision: memorylink memory "Feature description" --type decision',
+    tags: ['feature', 'decision'],
+  },
+  {
+    pattern: /^(refactor|refactoring|refactored|cleanup|clean)/i,
+    type: 'learning',
+    suggestion: 'This looks like a refactoring. Consider logging as a learning: memorylink learn "What needed refactoring" "How you refactored it" --status SUCCESS',
+    tags: ['refactor', 'code-quality'],
+  },
+  {
+    pattern: /^(test|tests?|testing|spec|specs?)/i,
+    type: 'memory',
+    suggestion: 'This looks like test-related changes. Consider logging: memorylink memory "Test description" --tags test',
+    tags: ['test', 'testing'],
+  },
+  {
+    pattern: /^(docs?|documentation|readme)/i,
+    type: 'memory',
+    suggestion: 'This looks like documentation changes. Consider logging: memorylink memory "Documentation update" --type doc_ref',
+    tags: ['docs', 'documentation'],
+  },
+  {
+    pattern: /^(perf|performance|optimize|optimization|optimized)/i,
+    type: 'learning',
+    suggestion: 'This looks like a performance improvement. Consider logging as a learning: memorylink learn "Performance issue" "Optimization solution" --status SUCCESS',
+    tags: ['performance', 'optimization'],
+  },
+  {
+    pattern: /^(chore|maintenance|update|updated|upgrade|upgraded)/i,
+    type: 'memory',
+    suggestion: 'This looks like maintenance. Consider logging: memorylink memory "Maintenance description" --tags maintenance',
+    tags: ['maintenance', 'chore'],
+  },
+];
+
+/**
+ * Detect commit message pattern and suggest logging
+ */
+export function detectCommitPattern(commitMessage: string): CommitPattern | null {
+  for (const pattern of COMMIT_PATTERNS) {
+    if (pattern.pattern.test(commitMessage)) {
+      return pattern;
+    }
+  }
+  return null;
+}
+
+/**
+ * Format suggestion for display
+ */
+export function formatSuggestion(pattern: CommitPattern, commitHash: string, commitMessage: string): string {
+  let output = `💡 Commit pattern detected: ${pattern.type}\n`;
+  output += `   Commit: ${commitHash.substring(0, 8)} - ${commitMessage.substring(0, 60)}...\n`;
+  output += `   ${pattern.suggestion}\n`;
+  if (pattern.tags && pattern.tags.length > 0) {
+    output += `   Suggested tags: ${pattern.tags.join(', ')}\n`;
+  }
+  return output;
+}
+

package/src/utils/observability.ts

@@ -0,0 +1,149 @@
+/**
+ * MemoryLink - Observability Logging
+ * v1.4: Log Buddy-Check runs for analytics and debugging
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { findRoot, getFilePath } from '../utils.js';
+import { MEMORYLINK_DIR } from '../types.js';
+import type { BuddyReport, BuddyStatus } from '../types.js';
+
+/**
+ * Observability log entry
+ */
+export interface ObservabilityEntry {
+  timestamp: string;           // ISO 8601 UTC
+  runType: 'preflight' | 'postflight';
+  status: BuddyStatus;
+  agentId?: string;
+  branch?: string;
+  prNumber?: string;
+  recordsUsed?: number;
+  highTrust?: number;
+  mediumTrust?: number;
+  lowTrust?: number;
+  staleCount?: number;
+  issues?: string[];          // Unique issue types found
+  durationMs?: number;
+  override?: boolean;          // Was this run overridden?
+  overrideBy?: string;         // Who overrode it?
+}
+
+/**
+ * Get observability log file path
+ */
+function getObservabilityLogPath(root?: string): string {
+  const projectRoot = root || findRoot() || process.cwd();
+  return path.join(projectRoot, MEMORYLINK_DIR, 'observability.log');
+}
+
+/**
+ * Log a Buddy-Check run to observability log
+ */
+export function logBuddyCheckRun(report: BuddyReport, root?: string): void {
+  try {
+    const logPath = getObservabilityLogPath(root);
+    const projectRoot = root || findRoot() || process.cwd();
+    
+    // Extract unique issue types
+    const issueTypes = [...new Set(report.issues.map(i => i.type))];
+    
+    // Create log entry
+    const entry: ObservabilityEntry = {
+      timestamp: report.timestamp || new Date().toISOString(),
+      runType: report.runType || 'preflight',
+      status: report.status,
+      agentId: report.agentId,
+      branch: report.branch,
+      recordsUsed: report.recordsUsed,
+      highTrust: report.highTrust,
+      mediumTrust: report.mediumTrust,
+      lowTrust: report.lowTrust,
+      staleCount: report.staleCount,
+      issues: issueTypes.length > 0 ? issueTypes : undefined,
+      durationMs: report.durationMs,
+      override: report.override !== undefined,
+      overrideBy: report.override?.approvedBy,
+    };
+    
+    // Append to JSONL file
+    const jsonlLine = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(logPath, jsonlLine, 'utf-8');
+  } catch (err) {
+    // Silently fail - observability logging should not break the main flow
+    // Could add a debug flag to log errors if needed
+  }
+}
+
+/**
+ * Read observability log entries
+ */
+export function readObservabilityLog(limit?: number, root?: string): ObservabilityEntry[] {
+  const logPath = getObservabilityLogPath(root);
+  
+  if (!fs.existsSync(logPath)) {
+    return [];
+  }
+  
+  const content = fs.readFileSync(logPath, 'utf-8');
+  const lines = content.split('\n').filter(line => line.trim() !== '');
+  const entries: ObservabilityEntry[] = [];
+  
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line) as ObservabilityEntry;
+      entries.push(entry);
+    } catch {
+      // Skip invalid JSON lines
+      continue;
+    }
+  }
+  
+  // Sort by timestamp (newest first)
+  entries.sort((a, b) => 
+    new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  );
+  
+  return limit ? entries.slice(0, limit) : entries;
+}
+
+/**
+ * Get observability statistics
+ */
+export function getObservabilityStats(root?: string): {
+  totalRuns: number;
+  preflightRuns: number;
+  postflightRuns: number;
+  greenCount: number;
+  yellowCount: number;
+  redCount: number;
+  overrideCount: number;
+  avgDuration: number;
+} {
+  const entries = readObservabilityLog(undefined, root);
+  
+  const stats = {
+    totalRuns: entries.length,
+    preflightRuns: entries.filter(e => e.runType === 'preflight').length,
+    postflightRuns: entries.filter(e => e.runType === 'postflight').length,
+    greenCount: entries.filter(e => e.status === 'GREEN').length,
+    yellowCount: entries.filter(e => e.status === 'YELLOW').length,
+    redCount: entries.filter(e => e.status === 'RED').length,
+    overrideCount: entries.filter(e => e.override === true).length,
+    avgDuration: 0,
+  };
+  
+  const durations = entries
+    .filter(e => e.durationMs !== undefined)
+    .map(e => e.durationMs!);
+  
+  if (durations.length > 0) {
+    stats.avgDuration = Math.round(
+      durations.reduce((a, b) => a + b, 0) / durations.length
+    );
+  }
+  
+  return stats;
+}
+

package/src/utils/quality.ts

@@ -0,0 +1,230 @@
+/**
+ * MemoryLink - Quality Validation
+ * Prevent log rot with quality checks
+ * 
+ * v1.3: Week 5 - Memory Quality Validation
+ */
+
+import type { MemoryEntry, LearningEntry, BaseEntry } from '../types.js';
+
+/**
+ * Quality score result
+ */
+export interface QualityScore {
+  score: number; // 0-100
+  issues: string[]; // List of issues found
+  suggestions: string[]; // Suggestions for improvement
+}
+
+/**
+ * Vague words that indicate low quality
+ */
+const VAGUE_WORDS = [
+  'thing', 'stuff', 'something', 'anything', 'everything',
+  'fixed', 'done', 'updated', 'changed', 'modified',
+  'issue', 'problem', 'bug', 'error', 'broken',
+  'work', 'works', 'working', 'not working',
+];
+
+/**
+ * Score a memory entry
+ */
+export function scoreMemoryEntry(entry: MemoryEntry): QualityScore {
+  const issues: string[] = [];
+  const suggestions: string[] = [];
+  let score = 100;
+
+  // Check length
+  const details = entry.details || '';
+  if (details.length < 10) {
+    score -= 30;
+    issues.push('Too short (less than 10 characters)');
+    suggestions.push('Add more details about the memory');
+  } else if (details.length < 30) {
+    score -= 15;
+    issues.push('Short (less than 30 characters)');
+    suggestions.push('Consider adding more context');
+  }
+
+  // Check for vague words
+  const detailsLower = details.toLowerCase();
+  const vagueCount = VAGUE_WORDS.filter(word => detailsLower.includes(word)).length;
+  if (vagueCount > 2) {
+    score -= 20;
+    issues.push(`Contains ${vagueCount} vague words`);
+    suggestions.push('Be more specific (avoid words like "thing", "stuff", "fixed")');
+  } else if (vagueCount > 0) {
+    score -= 10;
+    issues.push(`Contains ${vagueCount} vague word(s)`);
+    suggestions.push('Consider being more specific');
+  }
+
+  // Check for tags
+  if (!entry.tags || entry.tags.length === 0) {
+    score -= 15;
+    issues.push('No tags');
+    suggestions.push('Add tags to improve searchability');
+  } else if (entry.tags.length === 1) {
+    score -= 5;
+    issues.push('Only one tag');
+    suggestions.push('Consider adding more tags');
+  }
+
+  // Check for file context
+  if (!entry.path && entry.type !== 'rule' && entry.type !== 'preference') {
+    score -= 10;
+    issues.push('No file context');
+    suggestions.push('Link to a file if this memory is file-specific');
+  }
+
+  // Bonus for good status
+  if (entry.status === 'ACTIVE') {
+    score += 5;
+  }
+
+  // Bonus for recent entries (within 7 days)
+  const entryDate = new Date(entry.ts);
+  const daysSince = (Date.now() - entryDate.getTime()) / (1000 * 60 * 60 * 24);
+  if (daysSince < 7) {
+    score += 5;
+  }
+
+  // Bonus for code snippets with context
+  if (entry.type === 'code_snippet' && entry.code && entry.context) {
+    score += 10;
+  }
+
+  // Ensure score is within bounds
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    score: Math.round(score),
+    issues,
+    suggestions,
+  };
+}
+
+/**
+ * Score a learning entry
+ */
+export function scoreLearningEntry(entry: LearningEntry): QualityScore {
+  const issues: string[] = [];
+  const suggestions: string[] = [];
+  let score = 100;
+
+  // Check problem clarity
+  const problem = entry.problem || '';
+  if (problem.length < 10) {
+    score -= 25;
+    issues.push('Problem description too short');
+    suggestions.push('Describe the problem in detail');
+  } else if (problem.length < 30) {
+    score -= 15;
+    issues.push('Problem description short');
+    suggestions.push('Add more details about the problem');
+  }
+
+  // Check solution clarity
+  const solution = entry.solution || '';
+  if (solution.length < 10) {
+    score -= 25;
+    issues.push('Solution description too short');
+    suggestions.push('Describe the solution in detail');
+  } else if (solution.length < 30) {
+    score -= 15;
+    issues.push('Solution description short');
+    suggestions.push('Add more details about the solution');
+  }
+
+  // Check for vague words in problem
+  const problemLower = problem.toLowerCase();
+  const vagueCount = VAGUE_WORDS.filter(word => problemLower.includes(word)).length;
+  if (vagueCount > 1) {
+    score -= 15;
+    issues.push(`Problem contains ${vagueCount} vague words`);
+    suggestions.push('Be more specific about the problem');
+  }
+
+  // Check for vague words in solution
+  const solutionLower = solution.toLowerCase();
+  const vagueCountSolution = VAGUE_WORDS.filter(word => solutionLower.includes(word)).length;
+  if (vagueCountSolution > 1) {
+    score -= 15;
+    issues.push(`Solution contains ${vagueCountSolution} vague words`);
+    suggestions.push('Be more specific about the solution');
+  }
+
+  // Check outcome
+  if (!entry.outcome || (entry.outcome !== 'SUCCESS' && entry.outcome !== 'FAILED')) {
+    score -= 20;
+    issues.push('No outcome specified');
+    suggestions.push('Specify outcome: SUCCESS or FAILED');
+  } else if (entry.outcome === 'SUCCESS') {
+    score += 10; // Bonus for successful learnings
+  }
+
+  // Check for tags
+  if (!entry.tags || entry.tags.length === 0) {
+    score -= 10;
+    issues.push('No tags');
+    suggestions.push('Add tags to improve searchability');
+  }
+
+  // Bonus for recent entries
+  const entryDate = new Date(entry.ts);
+  const daysSince = (Date.now() - entryDate.getTime()) / (1000 * 60 * 60 * 24);
+  if (daysSince < 7) {
+    score += 5;
+  }
+
+  // Ensure score is within bounds
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    score: Math.round(score),
+    issues,
+    suggestions,
+  };
+}
+
+/**
+ * Get quality level from score
+ */
+export function getQualityLevel(score: number): 'excellent' | 'good' | 'acceptable' | 'poor' {
+  if (score >= 80) return 'excellent';
+  if (score >= 60) return 'good';
+  if (score >= 40) return 'acceptable';
+  return 'poor';
+}
+
+/**
+ * Format quality score for display
+ */
+export function formatQualityScore(score: QualityScore): string {
+  const level = getQualityLevel(score.score);
+  const levelEmoji = {
+    excellent: '🌟',
+    good: '✅',
+    acceptable: '⚠️',
+    poor: '❌',
+  }[level];
+
+  let output = `${levelEmoji} Quality Score: ${score.score}/100 (${level})\n`;
+
+  if (score.issues.length > 0) {
+    output += '\nIssues:\n';
+    score.issues.forEach(issue => {
+      output += `  • ${issue}\n`;
+    });
+  }
+
+  if (score.suggestions.length > 0) {
+    output += '\nSuggestions:\n';
+    score.suggestions.forEach(suggestion => {
+      output += `  💡 ${suggestion}\n`;
+    });
+  }
+
+  return output;
+}
+

package/src/utils/semantic-search.ts

@@ -0,0 +1,222 @@
+/**
+ * MemoryLink - Semantic Search Utilities
+ * Lightweight TF-IDF and word similarity for semantic search
+ * 
+ * v1.0: TF-IDF + word similarity (no ML dependencies)
+ * v1.5: Can upgrade to embeddings (transformers.js, etc.)
+ */
+
+import type { BaseEntry, MemoryEntry, LearningEntry, ChangeEntry } from '../types.js';
+
+/**
+ * Tokenize text into words (lowercase, remove punctuation)
+ */
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(word => word.length > 2); // Filter out very short words
+}
+
+/**
+ * Calculate Term Frequency (TF) for a term in a document
+ */
+function termFrequency(term: string, tokens: string[]): number {
+  const count = tokens.filter(t => t === term).length;
+  return count / tokens.length;
+}
+
+/**
+ * Calculate Inverse Document Frequency (IDF) for a term across all documents
+ */
+function inverseDocumentFrequency(
+  term: string,
+  allDocuments: string[][]
+): number {
+  const documentsContainingTerm = allDocuments.filter(doc =>
+    doc.includes(term)
+  ).length;
+
+  if (documentsContainingTerm === 0) {
+    return 0;
+  }
+
+  return Math.log(allDocuments.length / documentsContainingTerm);
+}
+
+/**
+ * Calculate TF-IDF score for a term in a document
+ */
+function tfidf(
+  term: string,
+  documentTokens: string[],
+  allDocuments: string[][]
+): number {
+  const tf = termFrequency(term, documentTokens);
+  const idf = inverseDocumentFrequency(term, allDocuments);
+  return tf * idf;
+}
+
+/**
+ * Calculate Jaccard similarity between two sets
+ */
+function jaccardSimilarity(set1: Set<string>, set2: Set<string>): number {
+  const intersection = new Set([...set1].filter(x => set2.has(x)));
+  const union = new Set([...set1, ...set2]);
+  return union.size === 0 ? 0 : intersection.size / union.size;
+}
+
+/**
+ * Calculate cosine similarity between two vectors (word counts)
+ */
+function cosineSimilarity(
+  vec1: Map<string, number>,
+  vec2: Map<string, number>
+): number {
+  const allTerms = new Set([...vec1.keys(), ...vec2.keys()]);
+  
+  let dotProduct = 0;
+  let norm1 = 0;
+  let norm2 = 0;
+
+  for (const term of allTerms) {
+    const v1 = vec1.get(term) || 0;
+    const v2 = vec2.get(term) || 0;
+    dotProduct += v1 * v2;
+    norm1 += v1 * v1;
+    norm2 += v2 * v2;
+  }
+
+  if (norm1 === 0 || norm2 === 0) {
+    return 0;
+  }
+
+  return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
+}
+
+/**
+ * Extract searchable text from an entry
+ */
+function extractSearchableText(entry: BaseEntry): string {
+  let text = '';
+
+  // Memory entry
+  if ('details' in entry) {
+    const memEntry = entry as MemoryEntry;
+    text += memEntry.details || '';
+    if (memEntry.code) {
+      text += ' ' + memEntry.code;
+    }
+    if (memEntry.context) {
+      text += ' ' + memEntry.context;
+    }
+  }
+
+  // Learning entry
+  if ('problem' in entry) {
+    const learnEntry = entry as LearningEntry;
+    text += (learnEntry.problem || '') + ' ' + (learnEntry.solution || '');
+  }
+
+  // Change entry
+  if ('file' in entry) {
+    const changeEntry = entry as ChangeEntry;
+    text += (changeEntry.file || '') + ' ' + (changeEntry.reason || '');
+  }
+
+  // Tags
+  if (entry.tags && entry.tags.length > 0) {
+    text += ' ' + entry.tags.join(' ');
+  }
+
+  return text;
+}
+
+/**
+ * Calculate semantic similarity score between query and entry
+ * Returns a score between 0 and 1
+ */
+export function calculateSemanticScore(
+  query: string,
+  entry: BaseEntry,
+  allEntries: BaseEntry[]
+): number {
+  const queryTokens = tokenize(query);
+  const entryText = extractSearchableText(entry);
+  const entryTokens = tokenize(entryText);
+
+  if (entryTokens.length === 0) {
+    return 0;
+  }
+
+  // 1. TF-IDF score (relevance)
+  const allDocuments = allEntries.map(e => tokenize(extractSearchableText(e)));
+  let tfidfScore = 0;
+  for (const term of queryTokens) {
+    tfidfScore += tfidf(term, entryTokens, allDocuments);
+  }
+  // Normalize TF-IDF score (0-1 range)
+  const normalizedTfidf = Math.min(1, tfidfScore / queryTokens.length);
+
+  // 2. Jaccard similarity (word overlap)
+  const querySet = new Set(queryTokens);
+  const entrySet = new Set(entryTokens);
+  const jaccardScore = jaccardSimilarity(querySet, entrySet);
+
+  // 3. Cosine similarity (word frequency)
+  const queryVec = new Map<string, number>();
+  queryTokens.forEach(t => queryVec.set(t, (queryVec.get(t) || 0) + 1));
+  
+  const entryVec = new Map<string, number>();
+  entryTokens.forEach(t => entryVec.set(t, (entryVec.get(t) || 0) + 1));
+  
+  const cosineScore = cosineSimilarity(queryVec, entryVec);
+
+  // 4. Exact keyword match bonus
+  const exactMatchBonus = queryTokens.some(term =>
+    entryTokens.includes(term)
+  ) ? 0.2 : 0;
+
+  // Combine scores (weighted average)
+  const combinedScore =
+    normalizedTfidf * 0.4 +
+    jaccardScore * 0.3 +
+    cosineScore * 0.2 +
+    exactMatchBonus * 0.1;
+
+  return Math.min(1, combinedScore);
+}
+
+/**
+ * Rank entries by semantic similarity to query
+ */
+export function rankBySemanticSimilarity<T extends BaseEntry>(
+  query: string,
+  entries: T[],
+  threshold: number = 0.1
+): Array<{ entry: T; score: number }> {
+  const scored = entries.map(entry => ({
+    entry,
+    score: calculateSemanticScore(query, entry, entries),
+  }));
+
+  // Filter by threshold and sort by score (descending)
+  return scored
+    .filter(item => item.score >= threshold)
+    .sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Find semantically similar entries
+ */
+export function findSemanticMatches<T extends BaseEntry>(
+  query: string,
+  entries: T[],
+  limit: number = 10,
+  threshold: number = 0.1
+): T[] {
+  const ranked = rankBySemanticSimilarity(query, entries, threshold);
+  return ranked.slice(0, limit).map(item => item.entry);
+}
+