@jungjaehoon/mama-server 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jungjaehoon/mama-server",
+  "version": "1.0.0",
+  "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
+  "main": "src/server.js",
+  "bin": {
+    "mama-server": "src/server.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "clean": "rm -rf dist node_modules"
+  },
+  "keywords": [
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "memory-assistant",
+    "decision-tracking",
+    "semantic-search",
+    "embeddings"
+  ],
+  "author": "SpineLift Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jungjaehoon/MAMA.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/jungjaehoon/MAMA/issues"
+  },
+  "homepage": "https://github.com/jungjaehoon/MAMA#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@huggingface/transformers": "^3.0.0",
+    "better-sqlite3": "^11.0.0",
+    "sqlite-vec": "^0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0",
+    "@types/better-sqlite3": "^7.6.0"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/mama/config-loader.js

@@ -0,0 +1,218 @@
+/**
+ * MAMA Configuration Loader
+ *
+ * Story M1.4: Configurable embedding model selection
+ * Priority: P1 (Core Feature)
+ *
+ * Loads user configuration from ~/.mama/config.json with sensible defaults.
+ * Supports:
+ * - Model selection (default: multilingual-e5-small)
+ * - Embedding dimensions
+ * - Cache directory configuration
+ *
+ * @module config-loader
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { info, warn, error: logError } = require('./debug-logger');
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  modelName: 'Xenova/multilingual-e5-small',
+  embeddingDim: 384,
+  cacheDir: path.join(os.homedir(), '.cache', 'huggingface', 'transformers'),
+};
+
+// Config file path
+const CONFIG_DIR = path.join(os.homedir(), '.mama');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+// Cached configuration
+let cachedConfig = null;
+
+/**
+ * Ensure config directory exists
+ * @returns {void}
+ */
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    info(`[config] Created config directory: ${CONFIG_DIR}`);
+  }
+}
+
+/**
+ * Create default config file if it doesn't exist
+ * @returns {void}
+ */
+function ensureConfigFile() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    ensureConfigDir();
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf8');
+    info(`[config] Created default config file: ${CONFIG_PATH}`);
+    info(`[config] Model: ${DEFAULT_CONFIG.modelName} (${DEFAULT_CONFIG.embeddingDim}-dim)`);
+  }
+}
+
+/**
+ * Load MAMA configuration from ~/.mama/config.json
+ *
+ * Story M1.4 AC #1: Config parser loads ~/.mama/config.json
+ *
+ * @param {boolean} reload - Force reload from disk (default: false)
+ * @returns {Object} Configuration object with modelName, embeddingDim, cacheDir
+ */
+function loadConfig(reload = false) {
+  // Return cached config if available and not forcing reload
+  if (cachedConfig && !reload) {
+    return cachedConfig;
+  }
+
+  try {
+    // Ensure config file exists
+    ensureConfigFile();
+
+    // Read and parse config file
+    const configData = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const userConfig = JSON.parse(configData);
+
+    // Merge with defaults (user config overrides)
+    const config = {
+      ...DEFAULT_CONFIG,
+      ...userConfig,
+    };
+
+    // Validate configuration
+    if (!config.modelName || typeof config.modelName !== 'string') {
+      warn('[config] Invalid modelName, using default:', DEFAULT_CONFIG.modelName);
+      config.modelName = DEFAULT_CONFIG.modelName;
+    }
+
+    if (!Number.isInteger(config.embeddingDim) || config.embeddingDim <= 0) {
+      warn('[config] Invalid embeddingDim, using default:', DEFAULT_CONFIG.embeddingDim);
+      config.embeddingDim = DEFAULT_CONFIG.embeddingDim;
+    }
+
+    if (!config.cacheDir || typeof config.cacheDir !== 'string') {
+      warn('[config] Invalid cacheDir, using default:', DEFAULT_CONFIG.cacheDir);
+      config.cacheDir = DEFAULT_CONFIG.cacheDir;
+    }
+
+    // Cache the loaded config
+    cachedConfig = config;
+
+    // Log loaded configuration
+    if (reload) {
+      info(`[config] Configuration reloaded from ${CONFIG_PATH}`);
+      info(`[config] Model: ${config.modelName} (${config.embeddingDim}-dim)`);
+      info(`[config] Cache: ${config.cacheDir}`);
+    }
+
+    return config;
+  } catch (error) {
+    logError(`[config] Failed to load config file: ${error.message}`);
+    logError('[config] Using default configuration');
+
+    // Cache defaults on error
+    cachedConfig = { ...DEFAULT_CONFIG };
+    return cachedConfig;
+  }
+}
+
+/**
+ * Get current model name
+ * @returns {string} Current model name
+ */
+function getModelName() {
+  const config = loadConfig();
+  return config.modelName;
+}
+
+/**
+ * Get current embedding dimension
+ * @returns {number} Current embedding dimension
+ */
+function getEmbeddingDim() {
+  const config = loadConfig();
+  return config.embeddingDim;
+}
+
+/**
+ * Get current cache directory
+ * @returns {string} Current cache directory
+ */
+function getCacheDir() {
+  const config = loadConfig();
+  return config.cacheDir;
+}
+
+/**
+ * Update configuration and save to file
+ *
+ * Story M1.4 AC #3: Changing model via config triggers informative log + resets caches
+ *
+ * @param {Object} updates - Configuration updates
+ * @param {string} updates.modelName - New model name
+ * @param {number} updates.embeddingDim - New embedding dimension
+ * @param {string} updates.cacheDir - New cache directory
+ * @returns {boolean} Success status
+ */
+function updateConfig(updates) {
+  try {
+    ensureConfigFile();
+
+    // Load current config
+    const currentConfig = loadConfig();
+
+    // Check if model is changing
+    const modelChanged = updates.modelName && updates.modelName !== currentConfig.modelName;
+    const dimChanged = updates.embeddingDim && updates.embeddingDim !== currentConfig.embeddingDim;
+
+    // Merge updates
+    const newConfig = {
+      ...currentConfig,
+      ...updates,
+    };
+
+    // Save to file
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(newConfig, null, 2), 'utf8');
+
+    // Update cache
+    cachedConfig = newConfig;
+
+    // Story M1.4 AC #3: Informative log when model changes
+    if (modelChanged || dimChanged) {
+      info('[config] ⚠️  Embedding model configuration changed');
+      info(`[config] Old: ${currentConfig.modelName} (${currentConfig.embeddingDim}-dim)`);
+      info(`[config] New: ${newConfig.modelName} (${newConfig.embeddingDim}-dim)`);
+      info('[config] ⚡ Model cache will be reset on next embedding generation');
+      info('[config] ⚡ Existing embeddings in database remain unchanged');
+    }
+
+    info(`[config] Configuration saved to ${CONFIG_PATH}`);
+    return true;
+  } catch (error) {
+    logError(`[config] Failed to update config: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Get config file path
+ * @returns {string} Config file path
+ */
+function getConfigPath() {
+  return CONFIG_PATH;
+}
+
+module.exports = {
+  loadConfig,
+  getModelName,
+  getEmbeddingDim,
+  getCacheDir,
+  updateConfig,
+  getConfigPath,
+  DEFAULT_CONFIG,
+};

package/src/mama/db-adapter/README.md

@@ -0,0 +1,105 @@
+# Database Adapter Layer
+
+## Overview
+
+Abstraction layer for MAMA database to support both SQLite (development/testing) and PostgreSQL (production on Railway).
+
+## Architecture
+
+```
+mama-api.js
+    ↓
+memory-store.js (business logic)
+    ↓
+DatabaseAdapter (interface)
+    ↓
+├── SQLiteAdapter (better-sqlite3 + sqlite-vss)
+└── PostgreSQLAdapter (pg + pgvector)
+```
+
+## Decision Rationale
+
+**Topic**: mama_db_adapter_pattern
+**Decision**: Abstract database layer with driver-specific implementations
+**Reasoning**:
+1. **Environment Flexibility**: SQLite for local/testing, PostgreSQL for production
+2. **Zero Breaking Changes**: Existing memory-store.js API remains unchanged
+3. **Vector Search Portability**: sqlite-vss → pgvector migration path
+4. **Testing Simplicity**: Fast SQLite tests, production PostgreSQL validation
+
+## Adapter Interface
+
+All adapters must implement:
+
+```javascript
+class DatabaseAdapter {
+  // Connection
+  connect(config) → db
+  disconnect()
+  isConnected() → boolean
+
+  // Prepared Statements
+  prepare(sql) → Statement
+  exec(sql)
+  transaction(fn) → result
+
+  // Vector Search
+  vectorSearch(embedding, limit) → results
+  insertEmbedding(rowid, embedding)
+
+  // Utility
+  getLastInsertRowid() → number
+}
+```
+
+## Implementation Files
+
+- `index.js` - Factory + environment detection
+- `sqlite-adapter.js` - SQLite implementation (current behavior)
+- `postgresql-adapter.js` - PostgreSQL implementation
+- `statement.js` - Statement wrapper (unified interface)
+
+## Environment Variable
+
+```bash
+# Default: SQLite
+MAMA_DB_PATH=~/.mama/memories.db
+
+# PostgreSQL (Railway)
+MAMA_DATABASE_URL=postgresql://user:pass@host:5432/mama_db
+```
+
+**Detection Logic**:
+- If `MAMA_DATABASE_URL` set → PostgreSQL
+- Else → SQLite with `MAMA_DB_PATH`
+
+## Migration Strategy
+
+### Phase 1: Adapter Layer (Current)
+1. Create adapter interface
+2. Extract SQLite logic to SQLiteAdapter
+3. Update memory-store.js to use adapter
+
+### Phase 2: PostgreSQL Support
+1. Implement PostgreSQLAdapter
+2. Convert migration SQL files
+3. Add pgvector support
+
+### Phase 3: Testing
+1. Run existing tests with SQLite
+2. Add PostgreSQL integration tests
+3. Validate on Railway
+
+## Performance Requirements
+
+- Prepared statement caching
+- Connection pooling (PostgreSQL only)
+- Transaction batching support
+- Vector search < 100ms (p95)
+
+## Backward Compatibility
+
+✅ Existing code works without changes
+✅ SQLite remains default for development
+✅ Environment variable controls database type
+✅ No API changes to memory-store.js

package/src/mama/db-adapter/base-adapter.js

@@ -0,0 +1,91 @@
+/**
+ * Base Database Adapter Interface
+ * All adapters must implement these methods
+ */
+class DatabaseAdapter {
+  /**
+   * Connect to database
+   * @returns {Object} Database connection
+   */
+  connect() {
+    throw new Error('connect() must be implemented by subclass');
+  }
+
+  /**
+   * Disconnect from database
+   */
+  disconnect() {
+    throw new Error('disconnect() must be implemented by subclass');
+  }
+
+  /**
+   * Check if connected
+   * @returns {boolean} Connection status
+   */
+  isConnected() {
+    throw new Error('isConnected() must be implemented by subclass');
+  }
+
+  /**
+   * Prepare a SQL statement
+   * @param {string} sql - SQL query
+   * @returns {Statement} Prepared statement
+   */
+  prepare(sql) {
+    throw new Error('prepare() must be implemented by subclass');
+  }
+
+  /**
+   * Execute raw SQL
+   * @param {string} sql - SQL to execute
+   */
+  exec(sql) {
+    throw new Error('exec() must be implemented by subclass');
+  }
+
+  /**
+   * Execute function in transaction
+   * @param {Function} fn - Function to execute
+   * @returns {*} Function return value
+   */
+  transaction(fn) {
+    throw new Error('transaction() must be implemented by subclass');
+  }
+
+  /**
+   * Vector similarity search
+   * @param {number[]} embedding - Query embedding (384-dim)
+   * @param {number} limit - Max results
+   * @returns {Array<Object>} Search results with distance
+   */
+  vectorSearch(embedding, limit) {
+    throw new Error('vectorSearch() must be implemented by subclass');
+  }
+
+  /**
+   * Insert vector embedding
+   * @param {number} rowid - Decision rowid
+   * @param {number[]} embedding - Embedding vector
+   */
+  insertEmbedding(rowid, embedding) {
+    throw new Error('insertEmbedding() must be implemented by subclass');
+  }
+
+  /**
+   * Get last inserted row ID
+   * @returns {number} Last rowid
+   */
+  getLastInsertRowid() {
+    throw new Error('getLastInsertRowid() must be implemented by subclass');
+  }
+
+  /**
+   * Run migrations
+   * @param {string} migrationsDir - Path to migrations directory
+   */
+  runMigrations(migrationsDir) {
+    throw new Error('runMigrations() must be implemented by subclass');
+  }
+}
+
+module.exports = { DatabaseAdapter };

package/src/mama/db-adapter/index.js

@@ -0,0 +1,31 @@
+/**
+ * Database Adapter Factory (SQLite-only)
+ *
+ * MAMA Plugin uses SQLite exclusively for local storage.
+ * PostgreSQL support is only available in the legacy mcp-server.
+ *
+ * @module db-adapter
+ */
+
+const { info } = require('../debug-logger');
+const SQLiteAdapter = require('./sqlite-adapter');
+
+/**
+ * Create SQLite database adapter
+ *
+ * @param {Object} config - Database configuration
+ * @param {string} [config.dbPath] - SQLite file path (overrides env)
+ * @returns {DatabaseAdapter} Configured SQLite adapter instance
+ */
+function createAdapter(config = {}) {
+  info('[db-adapter] Using SQLite adapter (plugin mode)');
+  const dbPath = config.dbPath || process.env.MAMA_DB_PATH;
+  return new SQLiteAdapter({ dbPath });
+}
+
+const { DatabaseAdapter } = require('./base-adapter');
+
+module.exports = {
+  createAdapter,
+  DatabaseAdapter,
+};