@jungjaehoon/mama-core 1.0.2 → 1.1.0

package/src/embeddings.js

@@ -1,305 +0,0 @@
-/**
- * MAMA (Memory-Augmented MCP Architecture) - Embedding Generation
- *
- * Story M1.4: Configurable embedding model selection
- * Generates embeddings using configurable model (default: multilingual-e5-small)
- * Supports: Korean-English cross-lingual similarity, enhanced metadata
- *
- * @module embeddings
- * @version 1.1
- * @date 2025-11-20
- */
-
-// eslint-disable-next-line no-unused-vars
-const { info, error: logError } = require('./debug-logger');
-const { logProgress: _logProgress, logComplete, logLoading } = require('./progress-indicator');
-const os = require('os');
-const path = require('path');
-// Lazy-load @huggingface/transformers to avoid loading sharp at module load time (Story 014.12.7)
-// const { pipeline } = require('@huggingface/transformers');
-const { embeddingCache } = require('./embedding-cache');
-const { loadConfig, getModelName, getEmbeddingDim } = require('./config-loader');
-
-// Shared cache directory (not in node_modules)
-const DEFAULT_CACHE_DIR = path.join(os.homedir(), '.cache', 'huggingface', 'transformers');
-
-// Singleton pattern for model loading
-let embeddingPipeline = null;
-let currentModelName = null;
-
-/**
- * Load embedding model (configurable)
- *
- * Story M1.4 AC #2: Transformers.js singleton initialization
- * Story M1.4 AC #3: Changing model via config triggers informative log + resets caches
- *
- * @returns {Promise<Function>} Embedding pipeline
- */
-async function loadModel() {
-  const modelName = getModelName();
-
-  // Check if model has changed (Story M1.4 AC #3)
-  if (embeddingPipeline && currentModelName && currentModelName !== modelName) {
-    info('[MAMA] ⚠️  Embedding model changed - resetting pipeline');
-    info(`[MAMA] Old model: ${currentModelName}`);
-    info(`[MAMA] New model: ${modelName}`);
-
-    // Reset pipeline and cache
-    embeddingPipeline = null;
-    currentModelName = null;
-    embeddingCache.clear();
-
-    info('[MAMA] ⚡ Model cache cleared');
-  }
-
-  // Load model if not already loaded
-  if (!embeddingPipeline) {
-    logLoading(`Loading embedding model: ${modelName}...`);
-    const startTime = Date.now();
-
-    // Dynamic import for ES Module compatibility (Railway deployment)
-    const transformers = await import('@huggingface/transformers');
-    const { pipeline, env } = transformers;
-
-    // Set shared cache directory (not in node_modules)
-    // This prevents re-downloading models on every npm install
-    const cacheDir = process.env.HF_HOME || process.env.TRANSFORMERS_CACHE || DEFAULT_CACHE_DIR;
-    env.cacheDir = cacheDir;
-    info(`[MAMA] Model cache directory: ${cacheDir}`);
-
-    embeddingPipeline = await pipeline('feature-extraction', modelName);
-    currentModelName = modelName;
-
-    const loadTime = Date.now() - startTime;
-    const config = loadConfig();
-    logComplete(`Embedding model ready (${loadTime}ms, ${config.embeddingDim}-dim)`);
-  }
-
-  return embeddingPipeline;
-}
-
-/**
- * Generate embedding vector from text
- *
- * Story M1.4 AC #1: Uses configurable embeddingDim from config
- * Target: < 30ms latency
- *
- * @param {string} text - Input text to embed
- * @returns {Promise<Float32Array>} Embedding vector (dimension from config)
- * @throws {Error} If text is empty or embedding fails
- */
-async function generateEmbedding(text) {
-  if (!text || text.trim().length === 0) {
-    throw new Error('Text cannot be empty');
-  }
-
-  // Task 2: Check cache first (AC #3)
-  const cached = embeddingCache.get(text);
-  if (cached) {
-    return cached;
-  }
-
-  const startTime = Date.now();
-
-  try {
-    const model = await loadModel();
-    const expectedDim = getEmbeddingDim();
-
-    // Generate embedding
-    const output = await model(text, {
-      pooling: 'mean', // Mean pooling over tokens
-      normalize: true, // L2 normalization
-    });
-
-    // Extract Float32Array
-    const embedding = output.data;
-
-    // Verify dimensions match config
-    if (embedding.length !== expectedDim) {
-      throw new Error(`Expected ${expectedDim}-dim, got ${embedding.length}-dim`);
-    }
-
-    // eslint-disable-next-line no-unused-vars
-    const latency = Date.now() - startTime;
-
-    // Task 2: Store in cache (AC #3)
-    embeddingCache.set(text, embedding);
-
-    return embedding;
-  } catch (error) {
-    throw new Error(`Failed to generate embedding: ${error.message}`);
-  }
-}
-
-/**
- * Generate enhanced embedding with content + metadata
- *
- * Task 3.4: Implement enhanced embedding format
- * Inspired by A-mem: Content + Metadata for richer semantic representation
- *
- * @param {Object} decision - Decision object
- * @param {string} decision.topic - Decision topic
- * @param {string} decision.decision - Decision value
- * @param {string} decision.reasoning - Decision reasoning
- * @param {string} decision.outcome - Decision outcome (optional)
- * @param {number} decision.confidence - Confidence score (optional)
- * @param {string} decision.user_involvement - User involvement (optional)
- * @returns {Promise<Float32Array>} 384-dim enhanced embedding
- */
-async function generateEnhancedEmbedding(decision) {
-  // Construct enriched text representation with narrative fields (Story 2.2)
-  const parts = [
-    `Topic: ${decision.topic}`,
-    `Decision: ${decision.decision}`,
-    `Reasoning: ${decision.reasoning || 'N/A'}`,
-    `Outcome: ${decision.outcome || 'ONGOING'}`,
-    `Confidence: ${decision.confidence !== undefined ? decision.confidence : 0.5}`,
-    `User Involvement: ${decision.user_involvement || 'N/A'}`,
-  ];
-
-  // Add narrative fields if present (Story 2.2: Narrative-Based Search)
-  if (decision.evidence) {
-    const evidenceText = Array.isArray(decision.evidence)
-      ? decision.evidence.join('; ')
-      : typeof decision.evidence === 'string'
-        ? decision.evidence
-        : JSON.stringify(decision.evidence);
-    parts.push(`Evidence: ${evidenceText}`);
-  }
-
-  if (decision.alternatives) {
-    const alternativesText = Array.isArray(decision.alternatives)
-      ? decision.alternatives.join('; ')
-      : typeof decision.alternatives === 'string'
-        ? decision.alternatives
-        : JSON.stringify(decision.alternatives);
-    parts.push(`Alternatives: ${alternativesText}`);
-  }
-
-  if (decision.risks) {
-    parts.push(`Risks: ${decision.risks}`);
-  }
-
-  const enrichedText = parts.join('\n').trim();
-
-  return generateEmbedding(enrichedText);
-}
-
-/**
- * Batch generate embeddings (optimized)
- *
- * Task 1: Implement Batch Embedding Generation
- * AC #3: Target - 30ms for 10 embeddings (vs 300ms sequential)
- *
- * Strategy: Use native transformer batch processing for parallel inference
- *
- * @param {string[]} texts - Array of texts to embed (max 10 per batch)
- * @returns {Promise<Float32Array[]>} Array of embeddings
- */
-async function generateBatchEmbeddings(texts) {
-  if (!Array.isArray(texts) || texts.length === 0) {
-    throw new Error('Texts must be a non-empty array');
-  }
-
-  // Validate all texts
-  for (const text of texts) {
-    if (!text || text.trim().length === 0) {
-      throw new Error('All texts must be non-empty');
-    }
-  }
-
-  const startTime = Date.now();
-
-  try {
-    const model = await loadModel();
-    const expectedDim = getEmbeddingDim();
-
-    // Native batch processing - single model forward pass
-    // This is significantly faster than sequential calls
-    const outputs = await model(texts, {
-      pooling: 'mean',
-      normalize: true,
-    });
-
-    // Extract embeddings from batch output
-    const embeddings = [];
-    const batchSize = texts.length;
-
-    for (let i = 0; i < batchSize; i++) {
-      // Each embedding is expectedDim consecutive elements
-      const start = i * expectedDim;
-      const end = start + expectedDim;
-      const embedding = outputs.data.slice(start, end);
-
-      // Verify dimensions
-      if (embedding.length !== expectedDim) {
-        throw new Error(`Expected ${expectedDim}-dim, got ${embedding.length}-dim at index ${i}`);
-      }
-
-      embeddings.push(embedding);
-    }
-
-    const latency = Date.now() - startTime;
-    const avgLatency = latency / batchSize;
-
-    // Log for performance tracking
-    if (process.env.MAMA_DEBUG) {
-      info(
-        `[MAMA] Batch(${batchSize}) embeddings: ${latency}ms total (${avgLatency.toFixed(1)}ms avg)`
-      );
-    }
-
-    return embeddings;
-  } catch (error) {
-    throw new Error(`Failed to generate batch embeddings: ${error.message}`);
-  }
-}
-
-/**
- * Calculate cosine similarity between two embeddings
- *
- * Utility for testing and validation
- *
- * @param {Float32Array} embA - First embedding
- * @param {Float32Array} embB - Second embedding
- * @returns {number} Cosine similarity (0-1)
- */
-function cosineSimilarity(embA, embB) {
-  if (embA.length !== embB.length) {
-    throw new Error('Embeddings must have same dimension');
-  }
-
-  let dotProduct = 0;
-  let normA = 0;
-  let normB = 0;
-
-  for (let i = 0; i < embA.length; i++) {
-    dotProduct += embA[i] * embB[i];
-    normA += embA[i] * embA[i];
-    normB += embB[i] * embB[i];
-  }
-
-  const similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
-
-  return similarity;
-}
-
-// Export API
-module.exports = {
-  generateEmbedding,
-  generateEnhancedEmbedding,
-  generateBatchEmbeddings,
-  cosineSimilarity,
-  embeddingCache,
-  // Dynamic getters for config values (Story M1.4)
-  get EMBEDDING_DIM() {
-    return getEmbeddingDim();
-  },
-  get MODEL_NAME() {
-    return getModelName();
-  },
-  // Expose config functions for external use
-  loadConfig,
-  getModelName,
-  getEmbeddingDim,
-};

package/src/errors.js

@@ -1,326 +0,0 @@
-/**
- * MAMA Error Classes - Typed Error Handling
- *
- * Story 8.3: Typed Error Classes
- * Provides consistent error handling across MCP tools and core modules
- *
- * Error codes follow MCP standard response format:
- * {error: {code: 'ERROR_CODE', message: '...', details: {}}}
- *
- * @module errors
- * @version 1.0
- * @date 2025-11-25
- */
-
-/**
- * Base error class for all MAMA errors
- *
- * @class MAMAError
- * @extends Error
- */
-class MAMAError extends Error {
-  /**
-   * @param {string} message - Error message
-   * @param {string} code - Error code (e.g., 'DECISION_NOT_FOUND')
-   * @param {Object} details - Additional error details
-   */
-  constructor(message, code = 'MAMA_ERROR', details = {}) {
-    super(message);
-    this.name = 'MAMAError';
-    this.code = code;
-    this.details = details;
-    this.timestamp = new Date().toISOString();
-
-    // Capture stack trace
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-
-  /**
-   * Convert to MCP-compatible error response format
-   *
-   * @returns {Object} {error: {code, message, details}}
-   */
-  toResponse() {
-    return {
-      error: {
-        code: this.code,
-        message: this.message,
-        details: this.details,
-      },
-    };
-  }
-
-  /**
-   * Convert to JSON for logging
-   *
-   * @returns {Object} JSON representation
-   */
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      details: this.details,
-      timestamp: this.timestamp,
-      stack: this.stack,
-    };
-  }
-}
-
-/**
- * Error thrown when a decision is not found
- *
- * @class NotFoundError
- * @extends MAMAError
- */
-class NotFoundError extends MAMAError {
-  /**
-   * @param {string} resourceType - Type of resource (e.g., 'decision', 'checkpoint')
-   * @param {string} identifier - Resource identifier
-   * @param {Object} details - Additional details
-   */
-  constructor(resourceType, identifier, details = {}) {
-    super(`${resourceType} not found: ${identifier}`, `${resourceType.toUpperCase()}_NOT_FOUND`, {
-      resourceType,
-      identifier,
-      ...details,
-    });
-    this.name = 'NotFoundError';
-  }
-}
-
-/**
- * Error thrown when input validation fails
- *
- * @class ValidationError
- * @extends MAMAError
- */
-class ValidationError extends MAMAError {
-  /**
-   * @param {string} field - Field that failed validation
-   * @param {string} message - Validation error message
-   * @param {*} received - Received value
-   * @param {Object} details - Additional details
-   */
-  constructor(field, message, received = undefined, details = {}) {
-    super(`Validation failed for '${field}': ${message}`, 'INVALID_INPUT', {
-      field,
-      received: received !== undefined ? String(received).substring(0, 100) : undefined,
-      ...details,
-    });
-    this.name = 'ValidationError';
-    this.field = field;
-  }
-}
-
-/**
- * Error thrown when database operations fail
- *
- * @class DatabaseError
- * @extends MAMAError
- */
-class DatabaseError extends MAMAError {
-  /**
-   * @param {string} operation - Database operation (e.g., 'insert', 'query', 'update')
-   * @param {string} message - Error message
-   * @param {Object} details - Additional details
-   */
-  constructor(operation, message, details = {}) {
-    super(`Database ${operation} failed: ${message}`, 'DATABASE_ERROR', {
-      operation,
-      ...details,
-    });
-    this.name = 'DatabaseError';
-    this.operation = operation;
-  }
-}
-
-/**
- * Error thrown when embedding generation fails
- *
- * @class EmbeddingError
- * @extends MAMAError
- */
-class EmbeddingError extends MAMAError {
-  /**
-   * @param {string} message - Error message
-   * @param {Object} details - Additional details (model, input length, etc.)
-   */
-  constructor(message, details = {}) {
-    super(`Embedding generation failed: ${message}`, 'EMBEDDING_ERROR', details);
-    this.name = 'EmbeddingError';
-  }
-}
-
-/**
- * Error thrown when configuration is invalid
- *
- * @class ConfigurationError
- * @extends MAMAError
- */
-class ConfigurationError extends MAMAError {
-  /**
-   * @param {string} configKey - Configuration key
-   * @param {string} message - Error message
-   * @param {Object} details - Additional details
-   */
-  constructor(configKey, message, details = {}) {
-    super(`Configuration error for '${configKey}': ${message}`, 'CONFIG_ERROR', {
-      configKey,
-      ...details,
-    });
-    this.name = 'ConfigurationError';
-    this.configKey = configKey;
-  }
-}
-
-/**
- * Error thrown when a link operation fails
- *
- * @class LinkError
- * @extends MAMAError
- */
-class LinkError extends MAMAError {
-  /**
-   * @param {string} operation - Link operation (e.g., 'propose', 'approve', 'reject')
-   * @param {string} message - Error message
-   * @param {Object} details - Additional details (from_id, to_id, etc.)
-   */
-  constructor(operation, message, details = {}) {
-    super(`Link ${operation} failed: ${message}`, 'LINK_ERROR', {
-      operation,
-      ...details,
-    });
-    this.name = 'LinkError';
-    this.operation = operation;
-  }
-}
-
-/**
- * Error thrown when rate limit is exceeded
- *
- * @class RateLimitError
- * @extends MAMAError
- */
-class RateLimitError extends MAMAError {
-  /**
-   * @param {string} operation - Operation that was rate limited
-   * @param {number} retryAfterMs - Time to wait before retry (ms)
-   * @param {Object} details - Additional details
-   */
-  constructor(operation, retryAfterMs, details = {}) {
-    super(`Rate limit exceeded for ${operation}. Retry after ${retryAfterMs}ms`, 'RATE_LIMITED', {
-      operation,
-      retryAfterMs,
-      ...details,
-    });
-    this.name = 'RateLimitError';
-    this.retryAfterMs = retryAfterMs;
-  }
-}
-
-/**
- * Error thrown when operation times out
- *
- * @class TimeoutError
- * @extends MAMAError
- */
-class TimeoutError extends MAMAError {
-  /**
-   * @param {string} operation - Operation that timed out
-   * @param {number} timeoutMs - Timeout duration (ms)
-   * @param {Object} details - Additional details
-   */
-  constructor(operation, timeoutMs, details = {}) {
-    super(`Operation '${operation}' timed out after ${timeoutMs}ms`, 'TIMEOUT', {
-      operation,
-      timeoutMs,
-      ...details,
-    });
-    this.name = 'TimeoutError';
-    this.timeoutMs = timeoutMs;
-  }
-}
-
-/**
- * Error codes enum for reference
- */
-const ErrorCodes = {
-  // Resource errors
-  DECISION_NOT_FOUND: 'DECISION_NOT_FOUND',
-  CHECKPOINT_NOT_FOUND: 'CHECKPOINT_NOT_FOUND',
-  LINK_NOT_FOUND: 'LINK_NOT_FOUND',
-
-  // Validation errors
-  INVALID_INPUT: 'INVALID_INPUT',
-  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
-  INVALID_FORMAT: 'INVALID_FORMAT',
-
-  // Database errors
-  DATABASE_ERROR: 'DATABASE_ERROR',
-  CONNECTION_FAILED: 'CONNECTION_FAILED',
-  QUERY_FAILED: 'QUERY_FAILED',
-
-  // Processing errors
-  EMBEDDING_ERROR: 'EMBEDDING_ERROR',
-  CONFIG_ERROR: 'CONFIG_ERROR',
-  LINK_ERROR: 'LINK_ERROR',
-
-  // Operational errors
-  RATE_LIMITED: 'RATE_LIMITED',
-  TIMEOUT: 'TIMEOUT',
-  INTERNAL_ERROR: 'INTERNAL_ERROR',
-};
-
-/**
- * Helper function to wrap unknown errors
- *
- * @param {Error|unknown} error - Error to wrap
- * @param {string} context - Context for the error
- * @returns {MAMAError} Wrapped MAMA error
- */
-function wrapError(error, context = 'Unknown operation') {
-  if (error instanceof MAMAError) {
-    return error;
-  }
-
-  const message = error instanceof Error ? error.message : String(error);
-  const stack = error instanceof Error ? error.stack : undefined;
-
-  return new MAMAError(`${context}: ${message}`, 'INTERNAL_ERROR', {
-    originalError: message,
-    originalStack: stack,
-  });
-}
-
-/**
- * Helper function to check if an error is a MAMA error
- *
- * @param {unknown} error - Error to check
- * @returns {boolean} True if MAMA error
- */
-function isMAMAError(error) {
-  return error instanceof MAMAError;
-}
-
-module.exports = {
-  // Base class
-  MAMAError,
-
-  // Specific error types
-  NotFoundError,
-  ValidationError,
-  DatabaseError,
-  EmbeddingError,
-  ConfigurationError,
-  LinkError,
-  RateLimitError,
-  TimeoutError,
-
-  // Utilities
-  ErrorCodes,
-  wrapError,
-  isMAMAError,
-};

package/src/index.js

@@ -1,41 +0,0 @@
-/**
- * MAMA Core - Main exports
- *
- * Shared modules for Memory-Augmented MCP Assistant.
- * Used by mcp-server, claude-code-plugin, and standalone packages.
- *
- * @module mama-core
- * @version 1.0.0
- */
-
-const embeddings = require('./embeddings');
-const embeddingCache = require('./embedding-cache');
-const embeddingClient = require('./embedding-client');
-
-const dbManager = require('./db-manager');
-const dbAdapter = require('./db-adapter');
-const memoryStore = require('./memory-store');
-
-const mamaApi = require('./mama-api');
-const configLoader = require('./config-loader');
-const relevanceScorer = require('./relevance-scorer');
-const decisionTracker = require('./decision-tracker');
-const tierValidator = require('./tier-validator');
-const progressIndicator = require('./progress-indicator');
-
-module.exports = {
-  ...embeddings,
-  embeddingCache,
-  ...embeddingClient,
-
-  ...dbManager,
-  ...dbAdapter,
-  ...memoryStore,
-
-  ...mamaApi,
-  ...configLoader,
-  ...relevanceScorer,
-  ...decisionTracker,
-  ...tierValidator,
-  ...progressIndicator,
-};