@jungjaehoon/mama-server 1.7.2 → 1.7.5

package/src/mama/query-intent.js

@@ -1,237 +0,0 @@
-/**
- * MAMA (Memory-Augmented MCP Architecture) - Query Intent Analysis
- *
- * Analyzes user queries to detect decision-related intent using EXAONE 3.5
- * Tasks: 2.1-2.8 (LLM intent analysis with fallback chain)
- * AC #1: Query intent analysis within 100ms
- * AC #5: LLM fallback (EXAONE → Gemma → Qwen)
- *
- * @module query-intent
- * @version 1.0
- * @date 2025-11-14
- */
-
-const { info, error: logError } = require('./debug-logger');
-const { generate, DEFAULT_MODEL, FALLBACK_MODEL } = require('@jungjaehoon/mama-core/ollama-client');
-
-/**
- * Analyze user message for decision-related intent
- *
- * Task 2.1-2.5: LLM intent analysis
- * AC #1: Detect if query involves decisions
- * AC #5: Fallback chain implemented
- *
- * @param {string} userMessage - User's message to analyze
- * @param {Object} options - Analysis options
- * @param {number} options.timeout - Timeout in ms (default: 100ms)
- * @param {number} options.threshold - Minimum confidence (default: 0.6)
- * @returns {Promise<Object>} Intent analysis result
- */
-async function analyzeIntent(userMessage, options = {}) {
-  const {
-    timeout = 5000, // Increased: LLM needs time, user accepts longer thinking
-    threshold = 0.6,
-  } = options;
-
-  const startTime = Date.now();
-
-  try {
-    // Task 2.2: Build prompt for decision-making analysis
-    const prompt = `
-Analyze if this query involves decision-making or past choices:
-
-User Message: "${userMessage}"
-
-Decision Indicators:
-1. References to past decisions ("we chose X", "last time we did Y")
-2. Questions about previous approaches ("why did we use X?")
-3. Decision evolution queries ("should we change from X to Y?")
-4. Architecture/strategy questions
-5. Method/approach questions ("how do I...", "what's the way to...")
-6. Best practice questions ("what should I use for...", "which one should I use...")
-
-Return JSON with "topic" as a short snake_case identifier (e.g., "mesh_structure", "database_choice", "auth_strategy", "coding_style", "error_handling"):
-{
-  "involves_decision": boolean,
-  "topic": string or null (extract main technical topic in snake_case),
-  "confidence": 0.0-1.0,
-  "reasoning": "brief explanation"
-}
-
-IMPORTANT: Generate "topic" freely based on the message content. Do NOT limit to predefined values.
-
-Examples:
-- "Why did we choose COMPLEX mesh structure?" → {"involves_decision": true, "topic": "mesh_structure", "confidence": 0.9}
-- "Let's use PostgreSQL for database" → {"involves_decision": true, "topic": "database_choice", "confidence": 0.9}
-- "How should we store workflow data?" → {"involves_decision": true, "topic": "workflow_storage", "confidence": 0.85}
-- "Read the file please" → {"involves_decision": false, "topic": null, "confidence": 0.1}
-`.trim();
-
-    // Task 2.3: Call EXAONE 3.5 with Tier 1 fallback
-    const result = await generateWithFallback(prompt, {
-      format: 'json',
-      temperature: 0.3,
-      max_tokens: 200,
-      timeout,
-    });
-
-    // eslint-disable-next-line no-unused-vars
-    const latency = Date.now() - startTime;
-
-    // Task 2.4: Parse response
-    const parsed = typeof result === 'string' ? JSON.parse(result) : result;
-
-    // Task 2.5: Threshold check
-    const meetsThreshold = parsed.confidence >= threshold;
-
-    if (!meetsThreshold) {
-      info(`[MAMA] Intent confidence ${parsed.confidence} below threshold ${threshold}`);
-      return {
-        involves_decision: false,
-        topic: null,
-        confidence: parsed.confidence,
-        reasoning: 'Confidence below threshold',
-      };
-    }
-
-    return parsed;
-  } catch (error) {
-    // CLAUDE.md Rule #1: NO FALLBACK
-    // Errors must be thrown for debugging
-    logError(`[MAMA] Intent analysis FAILED: ${error.message}`);
-    throw new Error(`Intent analysis failed: ${error.message}`);
-  }
-}
-
-/**
- * Generate with tiered fallback chain
- *
- * Task 2.6-2.7: Implement fallback to Gemma 2B and Qwen 3B
- * AC #5: LLM fallback works
- *
- * @param {string} prompt - LLM prompt
- * @param {Object} options - Generation options
- * @returns {Promise<Object|string>} LLM response
- */
-async function generateWithFallback(prompt, options = {}) {
-  const models = [
-    DEFAULT_MODEL, // Tier 1: EXAONE 3.5 (2.4B)
-    FALLBACK_MODEL, // Tier 2: Gemma 2B
-    'qwen:3b', // Tier 3: Qwen 3B
-  ];
-
-  for (let i = 0; i < models.length; i++) {
-    const model = models[i];
-
-    try {
-      info(`[MAMA] Trying ${model}...`);
-
-      const result = await generate(prompt, {
-        ...options,
-        model,
-      });
-
-      info(`[MAMA] ${model} succeeded`);
-      return result;
-    } catch (error) {
-      console.warn(`[MAMA] ${model} failed: ${error.message}`);
-
-      // Continue to next tier
-      if (i === models.length - 1) {
-        // All tiers failed
-        throw new Error(`All LLM tiers failed. Last error: ${error.message}`);
-      }
-    }
-  }
-}
-
-/**
- * Extract topic keywords from user message (fallback method)
- *
- * Task 2.8: Keyword-based fallback when all LLMs fail
- * Simple regex matching for common topics
- *
- * @param {string} userMessage - User's message
- * @returns {Object} Topic detection result
- */
-function extractTopicKeywords(userMessage) {
-  const topicPatterns = {
-    workflow_storage: /workflow|save|persist/i,
-    mesh_structure: /mesh|structure/i,
-    authentication: /auth|jwt|oauth|login/i,
-    testing: /test|jest|spec/i,
-    architecture: /architecture|design/i,
-    coding_style: /style|format|coding/i,
-  };
-
-  for (const [topic, pattern] of Object.entries(topicPatterns)) {
-    if (pattern.test(userMessage)) {
-      return {
-        involves_decision: true,
-        topic,
-        confidence: 0.5, // Lower confidence for keyword matching
-        reasoning: 'Keyword-based detection (LLM fallback)',
-      };
-    }
-  }
-
-  return {
-    involves_decision: false,
-    topic: null,
-    confidence: 0.0,
-    reasoning: 'No topic keywords found',
-  };
-}
-
-// Export API
-module.exports = {
-  analyzeIntent,
-  extractTopicKeywords,
-};
-
-// CLI execution for testing
-if (require.main === module) {
-  info('🧠 MAMA Query Intent Analysis - Test\n');
-
-  // Task 2.8: Test intent detection accuracy
-  (async () => {
-    const testQueries = [
-      {
-        message: 'Why did we choose COMPLEX mesh structure?',
-        expected: { involves_decision: true, topic: 'mesh_structure' },
-      },
-      {
-        message: 'Read the file please',
-        expected: { involves_decision: false },
-      },
-      {
-        message: 'We chose JWT for authentication, remember?',
-        expected: { involves_decision: true, topic: 'authentication' },
-      },
-    ];
-
-    for (const test of testQueries) {
-      info(`📋 Testing: "${test.message}"`);
-
-      try {
-        const result = await analyzeIntent(test.message);
-        info('✅ Result:', result);
-
-        // Verify expectations
-        if (result.involves_decision === test.expected.involves_decision) {
-          info('   ✓ Decision detection matches');
-        } else {
-          info('   ✗ Decision detection MISMATCH');
-        }
-
-        info('');
-      } catch (error) {
-        logError(`❌ Error: ${error.message}\n`);
-      }
-    }
-
-    info('═══════════════════════════');
-    info('✅ Intent analysis tests complete');
-    info('═══════════════════════════');
-  })();
-}

package/src/mama/relevance-scorer.js

@@ -1,284 +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,
-    null: 0.3, // Ongoing, lowest
-  };
-
-  const importanceScore = OUTCOME_WEIGHTS[decision.outcome] || OUTCOME_WEIGHTS['null'];
-
-  // ═══════════════════════════════════════════════════════════
-  // 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/mama/time-formatter.js

@@ -1,94 +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
-    if (!timestamp) {
-      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`;
-    }
-    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,
-};