@jungjaehoon/mama-core 1.0.2 → 1.1.0

package/src/relevance-scorer.js

@@ -1,286 +0,0 @@
-/**
- * MAMA (Memory-Augmented MCP Architecture) - Relevance Scorer
- *
- * Relevance scoring formula for decision ranking and top-N selection
- * Tasks: 1.1-1.4, 2.1-2.7 (Relevance scoring and top-N selection)
- * AC #1, #4, #5: Decision relevance, failure priority boost, top-N selection
- *
- * @module relevance-scorer
- * @version 1.0
- * @date 2025-11-14
- */
-
-const { cosineSimilarity } = require('./embeddings');
-
-/**
- * Calculate relevance score for a single decision
- *
- * Task 1.2: Implement calculateRelevance(decision, queryContext) function
- * AC #1, #4: Relevance scoring with failure priority boost
- *
- * Formula:
- *   Relevance = (Recency × 0.2) + (Importance × 0.5) + (Semantic × 0.3)
- *
- * Where:
- *   - Recency: exp(-days_since / 30)  [30-day half-life]
- *   - Importance: OUTCOME_WEIGHTS[outcome]
- *     - FAILED: 1.0 (highest - failures are most valuable)
- *     - PARTIAL: 0.7
- *     - SUCCESS: 0.5
- *     - null: 0.3 (ongoing, lowest)
- *   - Semantic: cosineSimilarity(decision.embedding, query.embedding)
- *
- * @param {Object} decision - Decision object
- * @param {number} decision.created_at - Created timestamp
- * @param {string} decision.outcome - Outcome type
- * @param {Float32Array} decision.embedding - Decision embedding (384-dim)
- * @param {Object} queryContext - Query context
- * @param {Float32Array} queryContext.embedding - Query embedding (384-dim)
- * @returns {number} Relevance score (0.0-1.0)
- */
-function calculateRelevance(decision, queryContext) {
-  // ═══════════════════════════════════════════════════════════
-  // Recency Score (20%)
-  // ═══════════════════════════════════════════════════════════
-  // Exponential decay with 30-day half-life
-  const daysSince = (Date.now() - decision.created_at) / (1000 * 60 * 60 * 24);
-  const recencyScore = Math.exp(-daysSince / 30);
-
-  // Decay curve:
-  // 0 days = 1.0
-  // 30 days = 0.5
-  // 60 days = 0.25
-  // 90 days = 0.125
-
-  // ═══════════════════════════════════════════════════════════
-  // Importance Score (50%) - AC #4: Failure Priority Boost
-  // ═══════════════════════════════════════════════════════════
-  const OUTCOME_WEIGHTS = {
-    FAILED: 1.0, // Highest - failures are most valuable (AC #4)
-    PARTIAL: 0.7,
-    SUCCESS: 0.5,
-    pending: 0.3, // Ongoing/pending, lowest
-  };
-
-  // Use explicit null check to avoid confusion with object key access
-  const outcomeKey = decision.outcome ?? 'pending';
-  const importanceScore = OUTCOME_WEIGHTS[outcomeKey] ?? OUTCOME_WEIGHTS.pending;
-
-  // ═══════════════════════════════════════════════════════════
-  // Semantic Score (30%)
-  // ═══════════════════════════════════════════════════════════
-  let semanticScore = 0;
-
-  if (decision.embedding && queryContext.embedding) {
-    // Task 1.3: Use cosine similarity function
-    semanticScore = cosineSimilarity(decision.embedding, queryContext.embedding);
-  } else {
-    // Fallback: no semantic match if embeddings missing
-    semanticScore = 0;
-  }
-
-  // ═══════════════════════════════════════════════════════════
-  // Weighted Sum (Total: 100%)
-  // ═══════════════════════════════════════════════════════════
-  const relevance = recencyScore * 0.2 + importanceScore * 0.5 + semanticScore * 0.3;
-
-  return relevance;
-}
-
-/**
- * Select top N most relevant decisions
- *
- * Task 2.1: Add selectTopDecisions(decisions, queryContext, n=3) function
- * AC #1, #5: Top-N selection with threshold filtering
- *
- * @param {Array<Object>} decisions - Array of decision objects
- * @param {Object} queryContext - Query context with embedding
- * @param {number} n - Number of top decisions to return (default: 3)
- * @returns {Array<Object>} Top N decisions with relevance scores
- */
-function selectTopDecisions(decisions, queryContext, n = 3) {
-  if (!Array.isArray(decisions) || decisions.length === 0) {
-    return [];
-  }
-
-  // Task 2.3: Score all results by relevance
-  const decisionsWithScores = decisions.map((decision) => ({
-    ...decision,
-    relevanceScore: calculateRelevance(decision, queryContext),
-  }));
-
-  // Task 2.4: Sort descending (highest relevance first)
-  decisionsWithScores.sort((a, b) => b.relevanceScore - a.relevanceScore);
-
-  // Task 2.6: Filter out < 0.5 relevance (AC #1)
-  const filtered = decisionsWithScores.filter((d) => d.relevanceScore >= 0.5);
-
-  // Task 2.5: Return top 3 (or top N)
-  const topN = filtered.slice(0, n);
-
-  return topN;
-}
-
-/**
- * Cosine similarity helper (re-exported from embeddings.js)
- *
- * Task 1.3: Implement cosine similarity function
- * AC #1: Semantic similarity calculation
- *
- * Note: This is re-exported from embeddings.js for convenience
- *
- * @param {Float32Array} vec1 - First embedding vector
- * @param {Float32Array} vec2 - Second embedding vector
- * @returns {number} Cosine similarity (0.0-1.0)
- */
-// Already available from embeddings.js - no need to reimplement
-
-/**
- * Format decisions with top-N selection and summary
- *
- * Task 8.2-8.3: Format top 3 in full detail, rest as summary
- * AC #5: Top-N selection with summary
- *
- * @param {Array<Object>} decisions - All decisions (sorted by relevance)
- * @param {number} topN - Number of decisions to show in full detail (default: 3)
- * @returns {Object} Formatted context {full: Array, summary: Object}
- */
-function formatTopNContext(decisions, topN = 3) {
-  if (!Array.isArray(decisions) || decisions.length === 0) {
-    return { full: [], summary: null };
-  }
-
-  // Split into top N and rest
-  const fullDetailDecisions = decisions.slice(0, topN);
-  const summaryDecisions = decisions.slice(topN);
-
-  // Full detail for top N
-  const full = fullDetailDecisions.map((d) => ({
-    decision_id: d.id,
-    topic: d.topic,
-    decision: d.decision,
-    reasoning: d.reasoning,
-    outcome: d.outcome,
-    failure_reason: d.failure_reason,
-    user_involvement: d.user_involvement,
-    confidence: d.confidence,
-    relevanceScore: d.relevanceScore,
-    created_at: d.created_at,
-  }));
-
-  // Summary for rest (count, duration, key failures only)
-  let summary = null;
-
-  if (summaryDecisions.length > 0) {
-    // Calculate duration (oldest to newest)
-    const oldestTimestamp = Math.min(...summaryDecisions.map((d) => d.created_at));
-    const newestTimestamp = Math.max(...summaryDecisions.map((d) => d.created_at));
-    const durationDays = Math.floor((newestTimestamp - oldestTimestamp) / (1000 * 60 * 60 * 24));
-
-    // Extract key failures
-    const failures = summaryDecisions
-      .filter((d) => d.outcome === 'FAILED')
-      .map((d) => ({ decision: d.decision, reason: d.failure_reason }));
-
-    summary = {
-      count: summaryDecisions.length,
-      duration_days: durationDays,
-      failures: failures.slice(0, 3), // Show max 3 failures
-    };
-  }
-
-  return { full, summary };
-}
-
-/**
- * Test relevance scoring with sample decisions
- *
- * Task 1.4: Test relevance scoring with sample decisions
- * AC #1, #4: Verify scoring formula and failure priority
- *
- * @returns {Object} Test results
- */
-function testRelevanceScoring() {
-  const now = Date.now();
-
-  // Mock embeddings (dummy for testing)
-  const queryEmbedding = new Float32Array(384).fill(0.5);
-  const decisionEmbedding1 = new Float32Array(384).fill(0.5); // Identical (similarity = 1.0)
-  // eslint-disable-next-line no-unused-vars
-  const decisionEmbedding2 = new Float32Array(384).fill(0.3); // Different (similarity < 1.0)
-
-  const scenarios = [
-    // Scenario 1: Recent FAILED decision (should have highest relevance)
-    {
-      name: 'Recent FAILED decision',
-      decision: {
-        created_at: now - 5 * 24 * 60 * 60 * 1000, // 5 days ago
-        outcome: 'FAILED',
-        embedding: decisionEmbedding1,
-      },
-      queryContext: { embedding: queryEmbedding },
-      expected: {
-        recency: 0.85, // exp(-5/30) ≈ 0.85
-        importance: 1.0, // FAILED = 1.0 (AC #4)
-        semantic: 1.0, // Identical embeddings
-        relevance: 0.87, // (0.85×0.2) + (1.0×0.5) + (1.0×0.3)
-      },
-    },
-
-    // Scenario 2: Recent SUCCESS decision (lower importance)
-    {
-      name: 'Recent SUCCESS decision',
-      decision: {
-        created_at: now - 5 * 24 * 60 * 60 * 1000, // 5 days ago
-        outcome: 'SUCCESS',
-        embedding: decisionEmbedding1,
-      },
-      queryContext: { embedding: queryEmbedding },
-      expected: {
-        recency: 0.85,
-        importance: 0.5, // SUCCESS = 0.5
-        semantic: 1.0,
-        relevance: 0.62, // (0.85×0.2) + (0.5×0.5) + (1.0×0.3)
-      },
-    },
-
-    // Scenario 3: Old FAILED decision (recency decay)
-    {
-      name: 'Old FAILED decision',
-      decision: {
-        created_at: now - 60 * 24 * 60 * 60 * 1000, // 60 days ago
-        outcome: 'FAILED',
-        embedding: decisionEmbedding1,
-      },
-      queryContext: { embedding: queryEmbedding },
-      expected: {
-        recency: 0.25, // exp(-60/30) ≈ 0.25
-        importance: 1.0,
-        semantic: 1.0,
-        relevance: 0.85, // (0.25×0.2) + (1.0×0.5) + (1.0×0.3)
-      },
-    },
-  ];
-
-  const results = scenarios.map((scenario) => {
-    const calculated = calculateRelevance(scenario.decision, scenario.queryContext);
-    const pass = Math.abs(calculated - scenario.expected.relevance) < 0.05;
-
-    return {
-      name: scenario.name,
-      expected: scenario.expected.relevance.toFixed(2),
-      calculated: calculated.toFixed(2),
-      pass,
-    };
-  });
-
-  return results;
-}
-
-// Export API
-module.exports = {
-  calculateRelevance,
-  selectTopDecisions,
-  formatTopNContext,
-  testRelevanceScoring,
-};

package/src/tier-validator.js

@@ -1,269 +0,0 @@
-/**
- * MAMA Tier Validator
- *
- * Centralized tier validation module for MAMA.
- * Validates system requirements and determines tier status (1 or 2).
- *
- * Tier 1: Full features (Node.js 18+, SQLite, Embeddings, Database)
- * Tier 2: Degraded mode (missing one or more requirements)
- *
- * @module tier-validator
- * @version 1.0
- * @date 2026-01-30
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { info: _info, warn: _warn, error: _logError } = require('./debug-logger');
-
-/**
- * Validates Node.js version requirement
- *
- * @returns {Object} Check result { status: 'pass'|'fail', details: string }
- */
-function checkNodeVersion() {
-  try {
-    const nodeVersion = process.versions.node;
-    const majorVersion = parseInt(nodeVersion.split('.')[0], 10);
-
-    if (majorVersion >= 18) {
-      return {
-        status: 'pass',
-        details: `v${nodeVersion}`,
-      };
-    }
-
-    return {
-      status: 'fail',
-      details: `v${nodeVersion} (requires 18+)`,
-    };
-  } catch (error) {
-    return {
-      status: 'fail',
-      details: `Error checking version: ${error.message}`,
-    };
-  }
-}
-
-/**
- * Validates SQLite (better-sqlite3) availability
- *
- * Reuses logic from packages/mcp-server/scripts/postinstall.js
- *
- * @returns {Object} Check result { status: 'pass'|'fail', details: string }
- */
-function checkSQLite() {
-  try {
-    // Try to require better-sqlite3
-    const Database = require('better-sqlite3');
-
-    // Test instantiation with in-memory database
-    const testDb = new Database(':memory:');
-    testDb.close();
-
-    return {
-      status: 'pass',
-      details: 'better-sqlite3 native module ready',
-    };
-  } catch (error) {
-    return {
-      status: 'fail',
-      details: `better-sqlite3 not available: ${error.message}`,
-    };
-  }
-}
-
-/**
- * Validates embedding model availability
- *
- * Checks if embedding model has been downloaded to cache directory.
- * Reuses logic from packages/mama-core/src/embeddings.js
- *
- * @returns {Object} Check result { status: 'pass'|'fail', details: string }
- */
-function checkEmbeddings() {
-  try {
-    const { getModelName } = require('./embeddings');
-    const modelName = getModelName();
-
-    // Check if model is cached
-    const cacheDir =
-      process.env.HF_HOME ||
-      process.env.TRANSFORMERS_CACHE ||
-      path.join(os.homedir(), '.cache', 'huggingface', 'transformers');
-
-    // Model cache structure: cache_dir/models--org--model/snapshots/hash/
-    const modelPath = path.join(cacheDir, `models--${modelName.replace('/', '--')}`);
-
-    if (fs.existsSync(modelPath)) {
-      return {
-        status: 'pass',
-        details: `${modelName} (cached)`,
-      };
-    }
-
-    return {
-      status: 'fail',
-      details: `${modelName} not cached (will download on first use)`,
-    };
-  } catch (error) {
-    return {
-      status: 'fail',
-      details: `Error checking embeddings: ${error.message}`,
-    };
-  }
-}
-
-/**
- * Validates database file accessibility
- *
- * Tests write access to database location (~/.claude/mama-memory.db)
- *
- * @returns {Object} Check result { status: 'pass'|'fail', details: string }
- */
-function checkDatabase() {
-  try {
-    const dbPath = process.env.MAMA_DB_PATH || path.join(os.homedir(), '.claude', 'mama-memory.db');
-
-    const dbDir = path.dirname(dbPath);
-
-    // Check if directory exists or can be created
-    if (!fs.existsSync(dbDir)) {
-      try {
-        fs.mkdirSync(dbDir, { recursive: true });
-      } catch (mkdirErr) {
-        return {
-          status: 'fail',
-          details: `Cannot create database directory: ${mkdirErr.message}`,
-        };
-      }
-    }
-
-    // Check write access
-    try {
-      fs.accessSync(dbDir, fs.constants.W_OK);
-    } catch (accessErr) {
-      return {
-        status: 'fail',
-        details: `No write access to ${dbDir}`,
-      };
-    }
-
-    return {
-      status: 'pass',
-      details: dbPath,
-    };
-  } catch (error) {
-    return {
-      status: 'fail',
-      details: `Error checking database: ${error.message}`,
-    };
-  }
-}
-
-/**
- * Validates MAMA tier status
- *
- * Performs all system checks and determines tier:
- * - Tier 1: All checks pass (full features)
- * - Tier 2: One or more checks fail (degraded mode)
- *
- * @returns {Promise<Object>} Validation result
- * @returns {number} result.tier - 1 (full) or 2 (degraded)
- * @returns {Array} result.checks - Array of check results
- * @example
- * const { tier, checks } = await validateTier();
- * console.log(`MAMA Tier: ${tier}`);
- * checks.forEach(check => {
- *   console.log(`${check.name}: ${check.status} (${check.details})`);
- * });
- */
-async function validateTier() {
-  const checks = [
-    {
-      name: 'Node.js',
-      ...checkNodeVersion(),
-    },
-    {
-      name: 'SQLite',
-      ...checkSQLite(),
-    },
-    {
-      name: 'Embeddings',
-      ...checkEmbeddings(),
-    },
-    {
-      name: 'Database',
-      ...checkDatabase(),
-    },
-  ];
-
-  // Determine tier: all pass = tier 1, any fail = tier 2
-  const tier = checks.every((c) => c.status === 'pass') ? 1 : 2;
-
-  return {
-    tier,
-    checks,
-  };
-}
-
-/**
- * Get user-friendly tier description
- *
- * @param {number} tier - Tier number (1 or 2)
- * @returns {string} Human-readable tier description
- * @example
- * const desc = getTierDescription(1);
- * console.log(desc); // "Full Features"
- */
-function getTierDescription(tier) {
-  const descriptions = {
-    1: 'Full Features - All systems operational',
-    2: 'Degraded Mode - Some features unavailable',
-  };
-
-  return descriptions[tier] || 'Unknown Tier';
-}
-
-/**
- * Get tier status banner
- *
- * Returns formatted banner showing tier and failed checks
- *
- * @param {Object} validation - Result from validateTier()
- * @returns {string} Formatted banner text
- */
-function getTierBanner(validation) {
-  const { tier, checks } = validation;
-  const failedChecks = checks.filter((c) => c.status === 'fail');
-
-  let banner = `\n┌─────────────────────────────────────────┐\n`;
-  banner += `│ MAMA Tier ${tier}: ${getTierDescription(tier).split(' - ')[0]}\n`;
-
-  if (failedChecks.length > 0) {
-    banner += `│\n`;
-    banner += `│ ⚠️  Issues detected:\n`;
-    failedChecks.forEach((check) => {
-      banner += `│ • ${check.name}: ${check.details}\n`;
-    });
-  } else {
-    banner += `│ ✅ All systems operational\n`;
-  }
-
-  banner += `└─────────────────────────────────────────┘\n`;
-
-  return banner;
-}
-
-// Export API
-module.exports = {
-  validateTier,
-  getTierDescription,
-  getTierBanner,
-  // Internal checks (for testing)
-  checkNodeVersion,
-  checkSQLite,
-  checkEmbeddings,
-  checkDatabase,
-};

package/src/time-formatter.js

@@ -1,98 +0,0 @@
-/**
- * Time Formatter - Human-Readable Time Formatting
- *
- * Converts Unix timestamps to human-readable relative time format
- * Examples: "2d ago", "3h ago", "just now"
- *
- * Used by list_decisions and recall_decision tools
- *
- * @module time-formatter
- * @date 2025-11-20
- */
-
-const { warn } = require('./debug-logger');
-
-/**
- * Format Unix timestamp (milliseconds) to human-readable relative time
- *
- * AC #2: Format created_at as human-readable ("2d ago", "3h ago", etc.)
- *
- * @param {number|string} timestamp - Unix timestamp in milliseconds OR ISO 8601 string
- * @returns {string} Human-readable time string
- *
- * @example
- * formatTimeAgo(Date.now() - 3600000) // "1h ago"
- * formatTimeAgo(Date.now() - 172800000) // "2d ago"
- * formatTimeAgo("2025-11-20T10:30:00Z") // "2d ago" (if today is 2025-11-22)
- */
-function formatTimeAgo(timestamp) {
-  try {
-    // Handle null/undefined (but allow 0 as valid Unix epoch)
-    if (timestamp === null || timestamp === undefined) {
-      warn('[time-formatter] Timestamp is null or undefined, returning "unknown"');
-      return 'unknown';
-    }
-
-    // Parse ISO 8601 string to timestamp (if string provided)
-    let timestampMs;
-    if (typeof timestamp === 'string') {
-      timestampMs = new Date(timestamp).getTime();
-      if (isNaN(timestampMs)) {
-        warn(`[time-formatter] Invalid ISO 8601 string: ${timestamp}`);
-        return 'unknown';
-      }
-    } else {
-      timestampMs = timestamp;
-    }
-
-    const now = Date.now();
-    const diff = now - timestampMs;
-
-    // Handle future timestamps (shouldn't happen, but be defensive)
-    if (diff < 0) {
-      warn(`[time-formatter] Future timestamp detected: ${timestamp}`);
-      return 'just now';
-    }
-
-    // Calculate time units
-    const seconds = Math.floor(diff / 1000);
-    const minutes = Math.floor(seconds / 60);
-    const hours = Math.floor(minutes / 60);
-    const days = Math.floor(hours / 24);
-    const weeks = Math.floor(days / 7);
-    const months = Math.floor(days / 30);
-    const years = Math.floor(days / 365);
-
-    // Return human-readable format
-    if (seconds < 60) {
-      return 'just now';
-    }
-    if (minutes < 60) {
-      return `${minutes}m ago`;
-    }
-    if (hours < 24) {
-      return `${hours}h ago`;
-    }
-    if (days < 7) {
-      return `${days}d ago`;
-    }
-    if (weeks < 4) {
-      return `${weeks}w ago`;
-    }
-    // Guard against "0mo ago" when days are 28-29 (months = Math.floor(days/30) = 0)
-    if (months < 1) {
-      return `${weeks}w ago`;
-    }
-    if (months < 12) {
-      return `${months}mo ago`;
-    }
-    return `${years}y ago`;
-  } catch (error) {
-    warn(`[time-formatter] Error formatting timestamp ${timestamp}: ${error.message}`);
-    return 'unknown';
-  }
-}
-
-module.exports = {
-  formatTimeAgo,
-};