@jungjaehoon/mama-server 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,146 @@
+# @jungjaehoon/mama-server
+
+MCP server for MAMA (Memory-Augmented MCP Assistant) - Tracks decision evolution across your coding sessions.
+
+## What is MAMA?
+
+MAMA remembers why you made decisions, what you tried before, and what didn't work. It stores decisions with semantic search, so relevant context surfaces automatically when you need it.
+
+**Key feature:** Session continuity - save your session state, resume tomorrow with full context.
+
+## Installation
+
+MAMA works with any MCP-compatible client. Add it to your client's configuration:
+
+### Claude Code
+
+```bash
+# Quick install via marketplace
+/plugin marketplace add jungjaehoon-lifegamez/claude-plugins
+/plugin install mama
+```
+
+The plugin automatically uses this MCP server via `npx -y @jungjaehoon/mama-server`.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mama": {
+      "command": "npx",
+      "args": ["-y", "@jungjaehoon/mama-server"]
+    }
+  }
+}
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mama]
+  command = "npx"
+  args = ["-y", "@jungjaehoon/mama-server"]
+  disabled = false
+  disabled_tools = []
+```
+
+### Antigravity IDE (Gemini)
+
+Add to `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mama": {
+      "command": "npx",
+      "args": ["-y", "@jungjaehoon/mama-server"],
+      "disabled": false,
+      "disabledTools": []
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP-compatible client can use MAMA with:
+
+```bash
+npx -y @jungjaehoon/mama-server
+```
+
+## Available Tools
+
+The MCP server exposes these tools:
+
+- `save_decision` - Save decisions with reasoning and confidence
+- `recall_decision` - View full evolution history for a topic
+- `suggest_decision` - Semantic search across all decisions
+- `list_decisions` - Browse recent decisions chronologically
+- `update_outcome` - Update decision outcomes (success/failure/partial)
+- `save_checkpoint` - Save session state for later resumption
+- `load_checkpoint` - Restore previous session context
+
+## Usage Example
+
+Once configured, use MAMA through your MCP client:
+
+```bash
+# Save a decision (in Claude Code)
+/mama-save topic="auth_strategy" decision="JWT with refresh tokens" reasoning="Need stateless auth for API scaling"
+
+# Search for related decisions
+/mama-suggest "How should I handle authentication?"
+
+# View decision history
+/mama-recall auth_strategy
+
+# Save session before closing
+/mama-checkpoint
+
+# Resume next time
+/mama-resume
+```
+
+## Features
+
+- **Session Continuity** - Save/resume work sessions with full context
+- **Decision Evolution** - Track how your thinking changes over time
+- **Semantic Search** - Natural language queries find relevant decisions
+- **Local-First** - All data stored on your device (~/.claude/mama-memory.db)
+- **Multilingual** - Supports English, Korean, and other languages
+- **Shared Database** - One database works across all your MCP clients
+
+## Technical Details
+
+- **Database:** SQLite + sqlite-vec extension
+- **Embeddings:** Transformers.js (Xenova/all-MiniLM-L6-v2, 384-dim)
+- **Transport:** stdio-based MCP protocol
+- **Storage:** ~/.claude/mama-memory.db (configurable via MAMA_DB_PATH)
+- **Node.js:** >= 18.0.0 required
+- **Disk Space:** ~500MB for embedding model cache
+
+## 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)
+- [Claude Code Plugin](https://github.com/jungjaehoon-lifegamez/claude-plugins/tree/main/mama)
+
+## License
+
+MIT - see [LICENSE](https://github.com/jungjaehoon-lifegamez/MAMA/blob/main/LICENSE)
+
+## Acknowledgments
+
+MAMA was inspired by [mem0](https://github.com/mem0ai/mem0) (Apache 2.0). While MAMA is a distinct implementation focused on local-first SQLite/MCP architecture, we appreciate their pioneering work in LLM memory management.
+
+---
+
+**Author:** SpineLift Team
+**Version:** 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
   "main": "src/server.js",
   "bin": {
@@ -47,6 +47,7 @@
   },
   "files": [
     "src/**/*.js",
+    "src/db/migrations/*.sql",
     "README.md",
     "LICENSE"
   ]

package/src/db/migrations/001-initial-decision-graph.sql

@@ -0,0 +1,140 @@
+-- ══════════════════════════════════════════════════════════════
+-- MAMA (Memory-Augmented MCP Architecture) - Initial Schema
+-- ══════════════════════════════════════════════════════════════
+-- Version: 1.0
+-- Date: 2025-11-14
+-- Purpose: Decision Graph schema for Evolutionary Decision Memory
+-- ══════════════════════════════════════════════════════════════
+
+-- ══════════════════════════════════════════════════════════════
+-- 1. Decision Nodes (Core)
+-- ══════════════════════════════════════════════════════════════
+-- Task 1.1: Create decisions table with all fields
+
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY,              -- "decision_mesh_structure_001"
+  topic TEXT NOT NULL,              -- "mesh_structure", "auth_strategy"
+  decision TEXT NOT NULL,           -- "COMPLEX", "JWT", "< 20 lines"
+  reasoning TEXT,                   -- "Flexibility is important initially"
+
+  -- Outcome Tracking (Learn-Unlearn-Relearn)
+  outcome TEXT,                     -- "SUCCESS", "FAILED", "PARTIAL", NULL
+  failure_reason TEXT,              -- "Performance bottleneck at 10K+ meshes"
+  limitation TEXT,                  -- "Missing layer information"
+  duration_days INTEGER,            -- Days until outcome determined
+
+  -- User Involvement
+  user_involvement TEXT,            -- "requested", "approved", "rejected"
+  session_id TEXT,                  -- Foreign key to sessions
+
+  -- Relationships (Explicit)
+  supersedes TEXT,                  -- Previous decision ID
+  superseded_by TEXT,               -- Next decision ID (NULL if current)
+  refined_from TEXT,                -- JSON array: ["id1", "id2"]
+
+  -- Confidence Evolution
+  confidence REAL DEFAULT 0.5,      -- Bayesian updated (0.0-1.0)
+
+  -- Timestamps
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch()),
+
+  FOREIGN KEY (supersedes) REFERENCES decisions(id),
+  FOREIGN KEY (superseded_by) REFERENCES decisions(id),
+
+  CHECK (confidence >= 0.0 AND confidence <= 1.0),
+  CHECK (outcome IN ('SUCCESS', 'FAILED', 'PARTIAL') OR outcome IS NULL),
+  CHECK (user_involvement IN ('requested', 'approved', 'rejected') OR user_involvement IS NULL)
+);
+
+-- Task 1.5: Add indexes for performance
+CREATE INDEX IF NOT EXISTS idx_decisions_topic ON decisions(topic);
+CREATE INDEX IF NOT EXISTS idx_decisions_outcome ON decisions(outcome);
+CREATE INDEX IF NOT EXISTS idx_decisions_session ON decisions(session_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_supersedes ON decisions(supersedes);
+CREATE INDEX IF NOT EXISTS idx_decisions_created_at ON decisions(created_at);
+
+-- ══════════════════════════════════════════════════════════════
+-- 2. Decision Edges (Explicit Relationships)
+-- ══════════════════════════════════════════════════════════════
+-- Task 1.2: Create decision_edges table
+
+CREATE TABLE IF NOT EXISTS decision_edges (
+  from_id TEXT NOT NULL,            -- Source decision
+  to_id TEXT NOT NULL,              -- Target decision
+  relationship TEXT NOT NULL,       -- "supersedes", "refines", "contradicts"
+  reason TEXT,                      -- "Learned from performance failure"
+  weight REAL DEFAULT 1.0,          -- Strength of relationship
+  created_at INTEGER DEFAULT (unixepoch()),
+
+  PRIMARY KEY (from_id, to_id, relationship),
+  FOREIGN KEY (from_id) REFERENCES decisions(id),
+  FOREIGN KEY (to_id) REFERENCES decisions(id),
+
+  CHECK (relationship IN ('supersedes', 'refines', 'contradicts')),
+  CHECK (weight >= 0.0 AND weight <= 1.0)
+);
+
+-- Task 1.5: Add indexes for graph traversal
+CREATE INDEX IF NOT EXISTS idx_edges_from ON decision_edges(from_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON decision_edges(to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_relationship ON decision_edges(relationship);
+
+-- ══════════════════════════════════════════════════════════════
+-- 3. Sessions (Context Preservation)
+-- ══════════════════════════════════════════════════════════════
+-- Task 1.3: Create sessions table
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,              -- "session_2025-11-14-1000"
+  project_path TEXT,                -- "/home/hoons/spineLiftWASM"
+
+  -- Rolling Summary (for next session)
+  rolling_summary TEXT,             -- Condensed session summary
+  latest_exchange TEXT,             -- Last 5 messages (JSON)
+
+  -- Metrics
+  action_count INTEGER DEFAULT 0,
+  decision_count INTEGER DEFAULT 0,
+
+  -- Timestamps
+  started_at INTEGER DEFAULT (unixepoch()),
+  last_active_at INTEGER DEFAULT (unixepoch()),
+  ended_at INTEGER,
+
+  CHECK (action_count >= 0),
+  CHECK (decision_count >= 0)
+);
+
+-- Task 1.5: Add indexes for session queries
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_path);
+CREATE INDEX IF NOT EXISTS idx_sessions_ended ON sessions(ended_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_last_active ON sessions(last_active_at);
+
+-- ══════════════════════════════════════════════════════════════
+-- 4. Vector Search (sqlite-vss)
+-- ══════════════════════════════════════════════════════════════
+-- Task 1.4: Create vss_memories virtual table
+-- Note: This will be initialized programmatically in memory-store.js
+-- because sqlite-vss requires extension loading first
+--
+-- CREATE VIRTUAL TABLE vss_memories USING vss0(
+--   embedding(384)                    -- multilingual-e5-small embeddings
+-- );
+
+-- ══════════════════════════════════════════════════════════════
+-- Migration Metadata
+-- ══════════════════════════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER DEFAULT (unixepoch()),
+  description TEXT
+);
+
+INSERT INTO schema_version (version, description)
+VALUES (1, 'Initial Decision Graph schema');
+
+-- ══════════════════════════════════════════════════════════════
+-- End of Migration 001
+-- ══════════════════════════════════════════════════════════════

package/src/db/migrations/002-add-error-patterns.sql

@@ -0,0 +1,114 @@
+-- ═══════════════════════════════════════════════════════════
+-- MAMA (Memory-Augmented MCP Architecture) - Error Patterns Table
+-- Migration 002: Add error_patterns table
+--
+-- Purpose: Store error patterns and their solutions for auto-resolution
+-- Tasks: 3.1-3.4 (Error pattern schema)
+-- AC #2, #3: Error pattern storage and auto-resolution
+--
+-- Version: 1.0
+-- Date: 2025-11-14
+-- ═══════════════════════════════════════════════════════════
+
+-- Error Patterns Table
+-- Stores error patterns, solutions, and success metrics
+CREATE TABLE IF NOT EXISTS error_patterns (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+
+  -- Pattern Identification
+  error_pattern TEXT NOT NULL,     -- Regex pattern or error signature
+  error_type TEXT,                 -- Error category (e.g., 'EADDRINUSE', 'ECONNREFUSED')
+
+  -- Solution
+  solution TEXT NOT NULL,          -- Command or action to resolve
+  solution_type TEXT DEFAULT 'bash',  -- 'bash', 'manual', 'code_fix'
+
+  -- Success Metrics
+  success_rate REAL DEFAULT 1.0,   -- Success rate (0.0-1.0)
+  occurrences INTEGER DEFAULT 1,   -- Total number of times encountered
+  successes INTEGER DEFAULT 1,     -- Number of successful resolutions
+
+  -- Temporal Data
+  last_seen INTEGER NOT NULL,      -- Last occurrence timestamp
+  first_seen INTEGER NOT NULL,     -- First occurrence timestamp
+
+  -- Vector Embedding (for semantic matching)
+  embedding BLOB,                  -- 384-dim embedding (multilingual-e5-small)
+
+  -- Metadata
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch()),
+
+  -- Constraints
+  UNIQUE(error_pattern)            -- One pattern per entry
+);
+
+-- Indexes for Performance
+CREATE INDEX IF NOT EXISTS idx_error_patterns_last_seen
+  ON error_patterns(last_seen DESC);
+
+CREATE INDEX IF NOT EXISTS idx_error_patterns_success_rate
+  ON error_patterns(success_rate DESC);
+
+CREATE INDEX IF NOT EXISTS idx_error_patterns_error_type
+  ON error_patterns(error_type);
+
+-- ═══════════════════════════════════════════════════════════
+-- VSS Table Extension for Error Patterns
+-- ═══════════════════════════════════════════════════════════
+
+-- Note: Error pattern embeddings will be stored in the same vss_memories table
+-- We'll use rowid mapping: error_patterns.id → vss_memories.rowid
+-- This allows unified vector search across decisions AND error patterns
+
+-- ═══════════════════════════════════════════════════════════
+-- Sample Data (Optional - for testing)
+-- ═══════════════════════════════════════════════════════════
+
+-- Uncomment to insert sample error patterns for testing:
+
+/*
+INSERT INTO error_patterns (
+  error_pattern,
+  error_type,
+  solution,
+  solution_type,
+  success_rate,
+  occurrences,
+  successes,
+  last_seen,
+  first_seen
+) VALUES
+(
+  'EADDRINUSE.*port.*already in use',
+  'EADDRINUSE',
+  'lsof -ti:{{PORT}} | xargs kill',
+  'bash',
+  1.0,
+  5,
+  5,
+  unixepoch(),
+  unixepoch() - (30 * 24 * 60 * 60)  -- 30 days ago
+),
+(
+  'ECONNREFUSED.*Connection refused',
+  'ECONNREFUSED',
+  'Check if service is running: systemctl status {{SERVICE}}',
+  'manual',
+  0.8,
+  3,
+  2,
+  unixepoch(),
+  unixepoch() - (7 * 24 * 60 * 60)   -- 7 days ago
+);
+*/
+
+-- ═══════════════════════════════════════════════════════════
+-- Migration Verification
+-- ═══════════════════════════════════════════════════════════
+
+-- Check table creation
+SELECT
+  'Migration 002 Complete: error_patterns table created' AS status,
+  COUNT(*) AS row_count
+FROM error_patterns;

package/src/db/migrations/003-add-validation-fields.sql

@@ -0,0 +1,28 @@
+-- Migration 003: Add Validation Tracking Fields
+-- Story: 014.7.6 - Interactive Learning Loop
+-- Task: 1.2 - Add needs_validation field to decisions table
+-- AC #1, #2: Validation tracking and user feedback collection
+-- Date: 2025-11-14
+
+-- Note: This migration is idempotent - duplicate column errors are handled gracefully
+-- SQLite doesn't have "IF NOT EXISTS" for ALTER TABLE
+-- The migration system treats "duplicate column" errors as success (idempotent)
+
+-- Add validation tracking fields to decisions table (idempotent via migration system)
+ALTER TABLE decisions ADD COLUMN needs_validation INTEGER DEFAULT 0 CHECK (needs_validation IN (0, 1));
+ALTER TABLE decisions ADD COLUMN validation_attempts INTEGER DEFAULT 0;
+ALTER TABLE decisions ADD COLUMN last_validated_at INTEGER;
+ALTER TABLE decisions ADD COLUMN usage_count INTEGER DEFAULT 0;
+
+-- Indexes for efficient queries (CREATE INDEX IF NOT EXISTS is supported)
+CREATE INDEX IF NOT EXISTS idx_decisions_needs_validation ON decisions(needs_validation) WHERE needs_validation = 1;
+CREATE INDEX IF NOT EXISTS idx_decisions_last_validated ON decisions(last_validated_at);
+CREATE INDEX IF NOT EXISTS idx_decisions_usage_count ON decisions(usage_count) WHERE usage_count >= 10;
+
+-- Update existing decisions: user_involvement='approved' don't need validation
+-- Only update rows that don't have needs_validation set
+UPDATE decisions SET needs_validation = 0 WHERE user_involvement = 'approved' AND needs_validation IS NULL;
+UPDATE decisions SET needs_validation = 1 WHERE user_involvement = 'system_generated' AND needs_validation IS NULL;
+
+-- Note: SQLite doesn't support DROP COLUMN, so rollback keeps columns
+-- Rollback would require recreating the table (not recommended for production)

package/src/db/migrations/004-add-trust-context.sql

@@ -0,0 +1,17 @@
+-- Migration 004: Add Trust Context Support
+-- Story 014.7.10: Claude-Friendly Context Formatting
+-- AC #2: Trust Context Schema
+-- Date: 2025-11-14
+
+-- Add trust_context JSON field for 5 trust components
+ALTER TABLE decisions ADD COLUMN trust_context TEXT;
+
+-- Add usage tracking fields for implicit feedback
+ALTER TABLE decisions ADD COLUMN usage_success INTEGER DEFAULT 0;
+ALTER TABLE decisions ADD COLUMN usage_failure INTEGER DEFAULT 0;
+ALTER TABLE decisions ADD COLUMN time_saved INTEGER DEFAULT 0;  -- milliseconds saved
+
+-- Indexes for performance
+CREATE INDEX IF NOT EXISTS idx_decisions_usage_success ON decisions(usage_success DESC);
+CREATE INDEX IF NOT EXISTS idx_decisions_time_saved ON decisions(time_saved DESC);
+CREATE INDEX IF NOT EXISTS idx_decisions_needs_validation_usage ON decisions(needs_validation, usage_success) WHERE needs_validation = 1;