@jungjaehoon/mama-core 1.0.1

package/README.md

@@ -0,0 +1,171 @@
+# @jungjaehoon/mama-core
+
+Shared core modules for MAMA (Memory-Augmented MCP Assistant).
+
+## What is MAMA Core?
+
+MAMA Core is a shared package containing the fundamental modules used by all MAMA packages:
+
+- **mcp-server**: MCP protocol server
+- **claude-code-plugin**: Claude Code plugin
+- **standalone**: Standalone HTTP server
+
+This package provides embedding generation, database management, decision tracking, and other core functionality without the transport layer (MCP/HTTP).
+
+## Installation
+
+```bash
+npm install @jungjaehoon/mama-core
+# or
+pnpm add @jungjaehoon/mama-core
+```
+
+## Usage
+
+### Import Everything
+
+```javascript
+const mama = require('@jungjaehoon/mama-core');
+
+// Access all exported functions
+const embedding = await mama.generateEmbedding('your text');
+await mama.initDB();
+```
+
+### Import Specific Modules
+
+```javascript
+const { generateEmbedding } = require('@jungjaehoon/mama-core/embeddings');
+const { initDB, getDB } = require('@jungjaehoon/mama-core/db-manager');
+const mamaApi = require('@jungjaehoon/mama-core/mama-api');
+```
+
+## Available Modules
+
+### Embedding Modules
+
+- **embeddings** - Generate embeddings using Transformers.js
+  - `generateEmbedding(text)` - Single text embedding
+  - `generateBatchEmbeddings(texts)` - Batch embedding generation
+  - `cosineSimilarity(a, b)` - Similarity calculation
+
+- **embedding-cache** - In-memory embedding cache
+  - `embeddingCache.get(key)` - Retrieve cached embedding
+  - `embeddingCache.set(key, value)` - Store embedding
+  - `embeddingCache.clear()` - Clear cache
+
+- **embedding-client** - HTTP client for embedding server
+  - `isServerRunning()` - Check server availability
+  - `getEmbeddingFromServer(text)` - Get embedding via HTTP
+  - `getServerStatus()` - Server health check
+
+### Database Modules
+
+- **db-manager** - SQLite database initialization
+  - `initDB()` - Initialize database with migrations
+  - `getDB()` - Get database connection
+  - `closeDB()` - Close connection
+
+- **db-adapter** - Database adapter interface
+  - `createAdapter(type)` - Create SQLite adapter
+  - Supports prepared statements and transactions
+
+- **memory-store** - Decision storage operations
+  - CRUD operations for decisions
+  - Vector similarity search
+
+### Core API
+
+- **mama-api** - High-level API interface
+  - `save(decision)` - Save decision
+  - `recall(topic)` - Retrieve decision history
+  - `suggest(query)` - Semantic search
+  - `updateOutcome(id, outcome)` - Update decision outcome
+
+- **decision-tracker** - Decision graph management
+  - `learnDecision(decision)` - Learn from decision
+  - `createEdgesFromReasoning(reasoning)` - Parse decision links
+
+- **relevance-scorer** - Semantic similarity scoring
+  - `scoreRelevance(query, decisions)` - Score decision relevance
+  - Combines vector, graph, and recency signals
+
+### Configuration
+
+- **config-loader** - Configuration management
+  - `loadConfig()` - Load MAMA configuration
+  - `getModelName()` - Get embedding model name
+  - `getEmbeddingDim()` - Get embedding dimensions
+  - `updateConfig(config)` - Update configuration
+
+## Environment Variables
+
+- `MAMA_DB_PATH` - Database file path (default: `~/.claude/mama-memory.db`)
+- `MAMA_HTTP_PORT` - Embedding server port (default: `3847`)
+
+## Dependencies
+
+- **@huggingface/transformers** - Local embedding generation
+- **better-sqlite3** - SQLite database
+- **sqlite-vec** - Vector similarity extension
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+```
+
+## Test Coverage
+
+- 35 unit tests
+- 100% passing
+- Tests cover:
+  - Config loader
+  - Database initialization
+  - Module exports
+
+## Architecture
+
+MAMA Core uses CommonJS modules and is designed to be shared across multiple packages:
+
+```
+packages/mama-core/
+├── src/
+│   ├── index.js              # Main exports
+│   ├── embeddings.js         # Embedding generation
+│   ├── db-manager.js         # Database management
+│   ├── mama-api.js           # High-level API
+│   └── db-adapter/           # Database adapter
+├── db/migrations/            # SQLite migrations
+└── tests/                    # Unit tests
+```
+
+## Migration Files
+
+Database migrations are included in `db/migrations/`:
+
+- 001-initial-decision-graph.sql
+- 002-add-error-patterns.sql
+- 003-add-validation-fields.sql
+- (and more...)
+
+## License
+
+MIT - see LICENSE file for details
+
+## Links
+
+- [GitHub Repository](https://github.com/jungjaehoon-lifegamez/MAMA)
+- [Documentation](https://github.com/jungjaehoon-lifegamez/MAMA/tree/main/docs)
+- [Issues](https://github.com/jungjaehoon-lifegamez/MAMA/issues)
+
+---
+
+**Part of the MAMA monorepo** - Memory-Augmented MCP Assistant

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jungjaehoon/mama-core",
+  "version": "1.0.1",
+  "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./embeddings": "./src/embeddings.js",
+    "./embedding-cache": "./src/embedding-cache.js",
+    "./embedding-client": "./src/embedding-client.js",
+    "./embedding-server": "./src/embedding-server/index.js",
+    "./memory-store": "./src/memory-store.js",
+    "./db-manager": "./src/db-manager.js",
+    "./db-adapter": "./src/db-adapter/index.js",
+    "./mama-api": "./src/mama-api.js",
+    "./config-loader": "./src/config-loader.js",
+    "./relevance-scorer": "./src/relevance-scorer.js",
+    "./decision-tracker": "./src/decision-tracker.js",
+    "./debug-logger": "./src/debug-logger.js",
+    "./decision-formatter": "./src/decision-formatter.js",
+    "./memory-inject": "./src/memory-inject.js",
+    "./ollama-client": "./src/ollama-client.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "clean": "rm -rf node_modules"
+  },
+  "keywords": [
+    "mama",
+    "memory-assistant",
+    "decision-tracking",
+    "semantic-search",
+    "embeddings",
+    "sqlite",
+    "mcp"
+  ],
+  "author": "SpineLift Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jungjaehoon-lifegamez/MAMA.git",
+    "directory": "packages/mama-core"
+  },
+  "bugs": {
+    "url": "https://github.com/jungjaehoon-lifegamez/MAMA/issues"
+  },
+  "homepage": "https://github.com/jungjaehoon-lifegamez/MAMA#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.72.1",
+    "@huggingface/transformers": "^3.8.1",
+    "better-sqlite3": "^11.0.0",
+    "sqlite-vec": "^0.1.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "vitest": "^1.0.0"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/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/db-adapter/README.md

@@ -0,0 +1,110 @@
+# 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/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/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,
+};