@jungjaehoon/mama-core 1.0.1

package/src/memory-inject.js

@@ -0,0 +1,174 @@
+/**
+ * MAMA (Memory-Augmented MCP Architecture) - Memory Injection Hook
+ *
+ * UserPromptSubmit hook that injects decision history into Claude's context
+ * Tasks: 1.1-1.9 (Hook setup, timeout handling, context injection)
+ * AC #1: Query intent → Graph query → Format → Inject (5s timeout for LLM latency)
+ * AC #2: No history → null (graceful fallback)
+ * AC #3: Timeout → graceful fallback
+ *
+ * @module memory-inject
+ * @version 1.0
+ * @date 2025-11-14
+ */
+
+// Error handling policy:
+// - Timeout errors: thrown (caller handles retry/fallback)
+// - Vector search unavailable: returns empty array (recoverable, not critical)
+const { info, error: logError } = require('./debug-logger');
+const { vectorSearch } = require('./memory-store');
+const { formatContext } = require('./decision-formatter');
+
+// Configuration
+const TIMEOUT_MS = 5000; // LLM-based intent detection, user accepts longer thinking
+const TOKEN_BUDGET = 500; // AC #1: Max 500 tokens per injection
+
+/**
+ * UserPromptSubmit Hook Handler
+ *
+ * Task 1.1-1.9: Main entry point for memory injection
+ * AC #1, #2, #3: Intent analysis → Query → Format → Inject
+ *
+ * @param {string} userMessage - User's message from prompt
+ * @returns {Promise<string|null>} Injected context or null
+ */
+async function injectDecisionContext(userMessage) {
+  const startTime = Date.now();
+  let timeoutId = null;
+
+  try {
+    // Task 1.3: Implement timeout wrapper (Promise.race with timeout)
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`Memory injection timeout (${TIMEOUT_MS}ms)`));
+      }, TIMEOUT_MS);
+    });
+
+    const context = await Promise.race([
+      performMemoryInjection(userMessage, startTime),
+      timeoutPromise,
+    ]);
+
+    // Clear timeout on success to prevent timer leak
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    return context;
+  } catch (error) {
+    // Clear timeout on error to prevent timer leak
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    // CLAUDE.md Rule #1: NO FALLBACK
+    // Errors must be thrown for debugging (including timeout)
+    logError(`[MAMA] Memory injection FAILED: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Perform memory injection with all steps
+ *
+ * Simplified: Direct vector search without LLM intent analysis
+ * Faster, more reliable, works with all query types
+ *
+ * @param {string} userMessage - User's message
+ * @param {number} startTime - Start timestamp for latency tracking
+ * @returns {Promise<string|null>} Formatted context or null
+ */
+async function performMemoryInjection(userMessage, startTime) {
+  // 1. Generate query embedding
+  const { generateEmbedding } = require('./embeddings');
+  const queryEmbedding = await generateEmbedding(userMessage);
+
+  const embeddingLatency = Date.now() - startTime;
+  info(`[MAMA] Embedding generation: ${embeddingLatency}ms`);
+
+  // 2. Adaptive threshold (shorter queries need higher confidence)
+  const wordCount = userMessage.split(/\s+/).length;
+  const adaptiveThreshold = wordCount < 3 ? 0.7 : 0.6;
+
+  // 3. Vector search (returns [] on error for graceful degradation)
+  let results;
+  try {
+    results = await vectorSearch(queryEmbedding, 10, 0.5); // Get more candidates
+  } catch (error) {
+    // Vector search unavailability should not block the main conversation flow
+    logError(`[MAMA] Vector search failed: ${error.message}`);
+    return null;
+  }
+
+  // 4. Filter by adaptive threshold
+  results = results.filter((r) => r.similarity >= adaptiveThreshold);
+
+  const searchLatency = Date.now() - startTime;
+  info(
+    `[MAMA] Vector search: ${searchLatency - embeddingLatency}ms (${results.length} results, threshold: ${adaptiveThreshold})`
+  );
+
+  // 5. Check if we have any decisions
+  if (results.length === 0) {
+    // Redact user content for privacy - only log length, not content
+    info(`[MAMA] No relevant decisions found (query length: ${userMessage.length} chars)`);
+    return null;
+  }
+
+  // 6. Format context summary
+  const formattedContext = formatContext(results, {
+    maxTokens: TOKEN_BUDGET,
+  });
+
+  const formatLatency = Date.now() - startTime;
+  info(`[MAMA] Format context: ${formatLatency - searchLatency}ms (total: ${formatLatency}ms)`);
+
+  // 7. Return formatted context (Claude Code will inject it)
+  return formattedContext;
+}
+
+// Export API
+module.exports = {
+  injectDecisionContext,
+};
+
+// CLI execution for testing
+if (require.main === module) {
+  info('🧠 MAMA Memory Injection - Test\n');
+
+  // Test memory injection flow
+  (async () => {
+    const testMessages = [
+      'Why did we choose COMPLEX mesh structure?',
+      'Read the file please',
+      'We chose JWT authentication, why?',
+    ];
+
+    for (const message of testMessages) {
+      info(`═══════════════════════════`);
+      info(`📋 Testing: "${message}"\n`);
+
+      try {
+        const startTime = Date.now();
+        const context = await injectDecisionContext(message);
+        const latency = Date.now() - startTime;
+
+        if (context) {
+          info('\n✅ Context injected:');
+          info(context);
+          info(`\n⏱️  Latency: ${latency}ms (target: <${TIMEOUT_MS}ms)`);
+        } else {
+          info('\n⚠️  No context injected (null returned)');
+          info(`⏱️  Latency: ${latency}ms`);
+        }
+      } catch (error) {
+        logError(`\n❌ Error: ${error.message}`);
+      }
+
+      info('');
+    }
+
+    info('═══════════════════════════');
+    info('✅ Memory injection tests complete');
+    info('═══════════════════════════');
+  })();
+}

package/src/memory-store.js

@@ -0,0 +1,89 @@
+/**
+ * MAMA Memory Store - Compatibility Wrapper
+ *
+ * This file now serves as a compatibility layer that re-exports db-manager functions.
+ * The actual database logic has been moved to db-manager.js which supports both
+ * SQLite (local development) and PostgreSQL (Railway production).
+ *
+ * Migration Note:
+ * - Old: memory-store.js directly used better-sqlite3 + sqlite-vss
+ * - New: memory-store.js → db-manager.js → db-adapter (SQLite or PostgreSQL)
+ *
+ * All MAMA modules can continue to require('memory-store') without changes.
+ *
+ * @module memory-store
+ * @version 2.0
+ * @date 2025-11-17
+ */
+
+const dbManager = require('./db-manager');
+
+// Re-export all db-manager functions for backward compatibility
+// These maintain the same interface as the original memory-store.js
+module.exports = {
+  // Core database functions
+  initDB: dbManager.initDB, // Now async, returns Promise<connection>
+  getDB: dbManager.getDB, // Sync, throws if not initialized
+  getAdapter: dbManager.getAdapter, // Get database adapter (PostgreSQL or SQLite)
+  closeDB: dbManager.closeDB, // Async
+
+  // Vector search functions
+  insertEmbedding: dbManager.insertEmbedding, // Async
+  vectorSearch: dbManager.vectorSearch, // Async (returns null if unavailable)
+  queryVectorSearch: dbManager.queryVectorSearch, // Async - Story 014.14
+
+  // Decision functions
+  insertDecisionWithEmbedding: dbManager.insertDecisionWithEmbedding, // Async
+  queryDecisionGraph: dbManager.queryDecisionGraph, // Async
+  querySemanticEdges: dbManager.querySemanticEdges, // Async - Graph traversal
+  updateDecisionOutcome: dbManager.updateDecisionOutcome, // Async
+
+  // Compatibility functions
+  getPreparedStmt: dbManager.getPreparedStmt, // Deprecated
+  getDbPath: dbManager.getDbPath, // Returns adapter name
+
+  // Legacy exports (for backward compatibility with old code)
+  traverseDecisionChain: dbManager.queryDecisionGraph, // Alias
+  getSessionDecisions: async (sessionId) => {
+    // Fallback implementation
+    const adapter = dbManager.getAdapter();
+    const stmt = adapter.prepare(`
+      SELECT * FROM decisions
+      WHERE session_id = ?
+      ORDER BY created_at DESC
+    `);
+    return await stmt.all(sessionId);
+  },
+  incrementUsageSuccess: async (decisionId, timeSaved = 0) => {
+    const adapter = dbManager.getAdapter();
+    const stmt = adapter.prepare(`
+      UPDATE decisions
+      SET usage_success = usage_success + 1,
+          time_saved = time_saved + ?,
+          updated_at = ?
+      WHERE id = ?
+    `);
+    await stmt.run(timeSaved, Date.now(), decisionId);
+  },
+  incrementUsageFailure: async (decisionId) => {
+    const adapter = dbManager.getAdapter();
+    const stmt = adapter.prepare(`
+      UPDATE decisions
+      SET usage_failure = usage_failure + 1,
+          updated_at = ?
+      WHERE id = ?
+    `);
+    await stmt.run(Date.now(), decisionId);
+  },
+  getDecisionById: async (decisionId) => {
+    const adapter = dbManager.getAdapter();
+    const stmt = adapter.prepare('SELECT * FROM decisions WHERE id = ?');
+    return await stmt.get(decisionId);
+  },
+
+  // Path exports (for compatibility)
+  DB_PATH: process.env.MAMA_DATABASE_URL ? 'PostgreSQL' : 'SQLite',
+  DB_DIR: process.env.MAMA_DATABASE_URL ? 'PostgreSQL' : '~/.mama',
+  LEGACY_DB_PATH: '~/.spinelift/memories.db',
+  DEFAULT_DB_PATH: '~/.mama/memories.db',
+};

package/src/notification-manager.js

@@ -0,0 +1,3 @@
+module.exports = {
+  notifyInsight: () => null,
+};

package/src/ollama-client.js

@@ -0,0 +1,391 @@
+/**
+ * MAMA (Memory-Augmented MCP Architecture) - Ollama Client Wrapper
+ *
+ * Simple wrapper for Ollama API with EXAONE 3.5 support
+ * Tasks: 9.2-9.5 (HTTP client, EXAONE wrapper, Error handling, Testing)
+ * AC #1: LLM integration ready
+ *
+ * @module ollama-client
+ * @version 1.0
+ * @date 2025-11-14
+ */
+
+const { info, error: logError } = require('./debug-logger');
+const http = require('http');
+
+// Ollama configuration
+const OLLAMA_HOST = process.env.OLLAMA_HOST || 'localhost';
+const OLLAMA_PORT = process.env.OLLAMA_PORT || 11434;
+const DEFAULT_MODEL = 'exaone3.5:2.4b';
+const FALLBACK_MODEL = 'gemma:2b';
+
+/**
+ * Call Ollama API
+ *
+ * Task 9.2: Implement HTTP client for Ollama API
+ * AC #1: LLM API callable
+ *
+ * @param {string} endpoint - API endpoint (e.g., '/api/generate')
+ * @param {Object} payload - Request payload
+ * @param {number} timeout - Timeout in milliseconds (default: 30000)
+ * @returns {Promise<Object>} API response
+ * @throws {Error} If request fails
+ */
+function callOllamaAPI(endpoint, payload, timeout = 30000) {
+  return new Promise((resolve, reject) => {
+    const postData = JSON.stringify(payload);
+
+    const options = {
+      hostname: OLLAMA_HOST,
+      port: OLLAMA_PORT,
+      path: endpoint,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            // Ollama returns NDJSON (newline-delimited JSON)
+            // For non-streaming, we only get one line
+            const lines = data.trim().split('\n');
+            const response = JSON.parse(lines[lines.length - 1]);
+            resolve(response);
+          } catch (error) {
+            reject(new Error(`Failed to parse Ollama response: ${error.message}`));
+          }
+        } else {
+          reject(new Error(`Ollama API error: ${res.statusCode} - ${data}`));
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Ollama connection failed: ${error.message}`));
+    });
+
+    req.setTimeout(timeout, () => {
+      req.destroy();
+      reject(new Error(`Ollama request timeout (${timeout}ms)`));
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Generate text with EXAONE 3.5
+ *
+ * Task 9.3: Implement EXAONE wrapper (with fallback to Gemma)
+ * AC #1: Decision detection LLM ready
+ *
+ * @param {string} prompt - Input prompt
+ * @param {Object} options - Generation options
+ * @param {string} options.model - Model name (default: EXAONE 3.5)
+ * @param {string} options.format - Response format ('json' or null)
+ * @param {number} options.temperature - Temperature (default: 0.7)
+ * @param {number} options.max_tokens - Max tokens (default: 500)
+ * @returns {Promise<string|Object>} Generated text or JSON object
+ * @throws {Error} If generation fails
+ */
+async function generate(prompt, options = {}) {
+  const { model = DEFAULT_MODEL, format = null, temperature = 0.7, max_tokens = 500 } = options;
+
+  const payload = {
+    model,
+    prompt,
+    stream: false,
+    options: {
+      temperature,
+      num_predict: max_tokens,
+    },
+  };
+
+  if (format === 'json') {
+    payload.format = 'json';
+  }
+
+  try {
+    const response = await callOllamaAPI('/api/generate', payload);
+
+    // Extract response text
+    const responseText = response.response;
+
+    // Parse JSON if requested
+    if (format === 'json') {
+      try {
+        return JSON.parse(responseText);
+      } catch (error) {
+        throw new Error(`Failed to parse JSON response: ${responseText}`);
+      }
+    }
+
+    return responseText;
+  } catch (error) {
+    // Task 9.4: Try fallback model if EXAONE fails
+    // Match Ollama's specific "model 'xxx' not found" error pattern
+    const isModelNotFound =
+      /model ['"].*['"] not found/i.test(error.message) ||
+      (error.message.includes('404') && error.message.toLowerCase().includes('not found'));
+    if (model === DEFAULT_MODEL && isModelNotFound) {
+      console.warn(`[MAMA] EXAONE not found, trying fallback (${FALLBACK_MODEL})...`);
+
+      return generate(prompt, {
+        ...options,
+        model: FALLBACK_MODEL,
+      });
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Analyze decision from tool execution
+ *
+ * Wrapper for decision detection (used in Story 014.7.3)
+ *
+ * @param {Object} toolExecution - Tool execution data
+ * @param {Object} sessionContext - Session context
+ * @returns {Promise<Object>} Decision analysis result
+ */
+async function analyzeDecision(toolExecution, sessionContext) {
+  const prompt = `
+Analyze if this represents a DECISION (not just an action):
+
+Session Context:
+- Latest User Message: ${sessionContext.latest_user_message || 'N/A'}
+- Recent Exchange: ${sessionContext.recent_exchange || 'N/A'}
+
+Tool Execution:
+- Tool: ${toolExecution.tool_name}
+- Input: ${JSON.stringify(toolExecution.tool_input)}
+- Result: ${toolExecution.exit_code === 0 ? 'SUCCESS' : 'FAILED'}
+
+Decision Indicators:
+1. User explicitly chose between alternatives?
+   Example: "Let's use JWT" (not "Use JWT" - that's just action)
+
+2. User changed previous approach?
+   Example: "Complex → Simple approach"
+
+3. User expressed preference?
+   Example: "Let's do it this way from now", "This approach is better"
+
+4. Significant architectural choice?
+   Example: "Mesh structure: COMPLEX", "Authentication: JWT"
+
+Is this a DECISION? Return JSON with "topic" as a short snake_case identifier:
+{
+  "is_decision": boolean,
+  "topic": string or null (extract main technical topic in snake_case, e.g., "mesh_structure", "database_choice", "auth_strategy"),
+  "decision": string or null (the actual choice made, e.g., "COMPLEX", "PostgreSQL", "JWT"),
+  "reasoning": "Why this is/isn't a decision",
+  "confidence": 0.0-1.0
+}
+
+IMPORTANT: Generate "topic" freely based on context. Do NOT limit to predefined values.
+`;
+
+  try {
+    const response = await generate(prompt, {
+      format: 'json',
+      temperature: 0.3, // Lower temperature for structured output
+      max_tokens: 300,
+    });
+
+    return response;
+  } catch (error) {
+    // CLAUDE.md Rule #1: NO FALLBACK
+    // Errors must be thrown for debugging
+    logError(`[MAMA] Decision analysis FAILED: ${error.message}`);
+    throw new Error(`Decision analysis failed: ${error.message}`);
+  }
+}
+
+/**
+ * Analyze query intent
+ *
+ * Wrapper for query intent detection (used in Story 014.7.2)
+ *
+ * @param {string} userMessage - User's message
+ * @returns {Promise<Object>} Query intent analysis
+ */
+async function analyzeQueryIntent(userMessage) {
+  const prompt = `
+Analyze this user message to determine if it involves past decisions:
+
+User Message: "${userMessage}"
+
+Questions to answer:
+1. Does this query reference past decisions or choices?
+2. Is the user asking about previous approaches?
+3. What topic is being discussed? (e.g., "mesh_structure", "authentication", "testing")
+
+Return JSON:
+{
+  "involves_decision": boolean,
+  "topic": "topic_name" | null,
+  "query_type": "recall" | "evolution" | "none",
+  "reasoning": "Why this involves/doesn't involve decisions"
+}
+`;
+
+  try {
+    const response = await generate(prompt, {
+      format: 'json',
+      temperature: 0.3,
+      max_tokens: 200,
+    });
+
+    return response;
+  } catch (error) {
+    // CLAUDE.md Rule #1: NO FALLBACK
+    // Errors must be thrown for debugging
+    logError(`[MAMA] Query intent analysis FAILED: ${error.message}`);
+    throw new Error(`Query intent analysis failed: ${error.message}`);
+  }
+}
+
+/**
+ * Check if Ollama is available
+ *
+ * Utility for health checks
+ *
+ * @returns {Promise<boolean>} True if Ollama is accessible
+ */
+async function isAvailable() {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: OLLAMA_HOST,
+      port: OLLAMA_PORT,
+      path: '/api/tags',
+      method: 'GET', // Use GET for health check
+      timeout: 2000,
+    };
+
+    const req = http.request(options, (res) => {
+      resolve(res.statusCode >= 200 && res.statusCode < 300);
+    });
+
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+
+    req.end();
+  });
+}
+
+/**
+ * List available models
+ *
+ * Utility for setup script
+ *
+ * @returns {Promise<Array<string>>} Array of model names
+ */
+async function listModels() {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: OLLAMA_HOST,
+      port: OLLAMA_PORT,
+      path: '/api/tags',
+      method: 'GET', // Use GET for listing models
+      timeout: 5000,
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        try {
+          const response = JSON.parse(data);
+          resolve(response.models?.map((m) => m.name) || []);
+        } catch (error) {
+          reject(new Error(`Failed to parse models response: ${error.message}`));
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Failed to list models: ${error.message}`));
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('List models timeout'));
+    });
+
+    req.end();
+  });
+}
+
+// Export API
+module.exports = {
+  generate,
+  analyzeDecision,
+  analyzeQueryIntent,
+  isAvailable,
+  listModels,
+  DEFAULT_MODEL,
+  FALLBACK_MODEL,
+};
+
+// CLI execution for testing
+if (require.main === module) {
+  info('🧠 MAMA Ollama Client - Test\n');
+
+  // Task 9.5: Test Ollama connection and generation
+  (async () => {
+    try {
+      info('📋 Test 1: Check Ollama availability...');
+      const available = await isAvailable();
+      if (!available) {
+        throw new Error('Ollama is not available');
+      }
+      info('✅ Ollama is available\n');
+
+      info('📋 Test 2: List available models...');
+      const models = await listModels();
+      info(`✅ Found ${models.length} models:`, models.join(', '), '\n');
+
+      info('📋 Test 3: Generate text...');
+      const text = await generate('What is 2+2?', {
+        temperature: 0.1,
+        max_tokens: 50,
+      });
+      info(`✅ Generated: ${text.trim()}\n`);
+
+      info('📋 Test 4: Generate JSON...');
+      const json = await generate('Return {"test": true, "value": 42}', {
+        format: 'json',
+        temperature: 0.1,
+        max_tokens: 50,
+      });
+      info('✅ Generated JSON:', json, '\n');
+
+      info('═══════════════════════════');
+      info('✅ All tests passed!');
+      info('═══════════════════════════');
+    } catch (error) {
+      logError(`❌ Test failed: ${error.message}`);
+      process.exit(1);
+    }
+  })();
+}