@jungjaehoon/mama-server 1.2.4 → 1.3.0

package/README.md

@@ -74,17 +74,27 @@ Any MCP-compatible client can use MAMA with:
 npx -y @jungjaehoon/mama-server
 ```
 
-## Available Tools
+## Available Tools (v1.3)
 
-The MCP server exposes these tools:
+The MCP server exposes 4 core 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
+| Tool              | Description                                                           |
+| ----------------- | --------------------------------------------------------------------- |
+| `save`            | Save decision (`type='decision'`) or checkpoint (`type='checkpoint'`) |
+| `search`          | Semantic search (with `query`) or list recent items (without `query`) |
+| `update`          | Update decision outcome (case-insensitive: success/failed/partial)    |
+| `load_checkpoint` | Resume previous session                                               |
+
+### Edge Types
+
+Decisions connect through relationships. Include patterns in your reasoning:
+
+| Edge Type     | Pattern                    | Meaning                    |
+| ------------- | -------------------------- | -------------------------- |
+| `supersedes`  | (automatic for same topic) | Newer replaces older       |
+| `builds_on`   | `builds_on: decision_xxx`  | Extends prior work         |
+| `debates`     | `debates: decision_xxx`    | Alternative view           |
+| `synthesizes` | `synthesizes: [id1, id2]`  | Merges multiple approaches |
 
 ## Usage Example
 
@@ -197,4 +207,4 @@ MAMA was inspired by [mem0](https://github.com/mem0ai/mem0) (Apache 2.0). While
 ---
 
 **Author:** SpineLift Team
-**Version:** 1.1.0
+**Version:** 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-server",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
   "main": "src/server.js",
   "bin": {

package/src/db/migrations/010-extend-edge-types.sql

@@ -0,0 +1,56 @@
+-- ══════════════════════════════════════════════════════════════
+-- MAMA Migration 010: Extend Edge Types
+-- ══════════════════════════════════════════════════════════════
+-- Version: 1.3
+-- Date: 2025-11-26
+-- Purpose: Add builds_on, debates, synthesizes relationship types
+-- Story: 2.1 - Edge Type Extension
+-- ══════════════════════════════════════════════════════════════
+
+-- SQLite doesn't support ALTER TABLE to modify CHECK constraints.
+-- We need to recreate the table with expanded CHECK constraint.
+
+-- Step 1: Create new table with extended edge types
+CREATE TABLE IF NOT EXISTS decision_edges_new (
+  from_id TEXT NOT NULL,
+  to_id TEXT NOT NULL,
+  relationship TEXT NOT NULL,
+  reason TEXT,
+  weight REAL DEFAULT 1.0,
+  created_at INTEGER DEFAULT (unixepoch()),
+  created_by TEXT DEFAULT 'user' CHECK (created_by IN ('llm', 'user')),
+  approved_by_user INTEGER DEFAULT 1 CHECK (approved_by_user IN (0, 1)),
+  decision_id TEXT,
+  evidence TEXT,
+
+  PRIMARY KEY (from_id, to_id, relationship),
+  FOREIGN KEY (from_id) REFERENCES decisions(id),
+  FOREIGN KEY (to_id) REFERENCES decisions(id),
+
+  -- Extended CHECK constraint: original + v1.3 types
+  CHECK (relationship IN ('supersedes', 'refines', 'contradicts', 'builds_on', 'debates', 'synthesizes')),
+  CHECK (weight >= 0.0 AND weight <= 1.0)
+);
+
+-- Step 2: Copy existing data (explicit columns to handle schema variations)
+INSERT OR IGNORE INTO decision_edges_new (from_id, to_id, relationship, reason, weight, created_at, created_by, approved_by_user, decision_id, evidence)
+SELECT from_id, to_id, relationship, reason, weight, created_at, created_by, approved_by_user, decision_id, evidence FROM decision_edges;
+
+-- Step 3: Drop old table
+DROP TABLE IF EXISTS decision_edges;
+
+-- Step 4: Rename new table
+ALTER TABLE decision_edges_new RENAME TO decision_edges;
+
+-- Step 5: Recreate indexes
+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);
+
+-- Update schema version
+INSERT OR REPLACE INTO schema_version (version, description, applied_at)
+VALUES (10, 'Extend edge types: builds_on, debates, synthesizes', unixepoch());
+
+-- ══════════════════════════════════════════════════════════════
+-- End of Migration 010
+-- ══════════════════════════════════════════════════════════════

package/src/embedding-http-server.js

@@ -184,6 +184,12 @@ async function startEmbeddingServer(port = DEFAULT_PORT) {
         );
         // Not a fatal error - another server instance may be running
         resolve(null);
+      } else if (error.code === 'EPERM' || error.code === 'EACCES') {
+        console.error(
+          `[EmbeddingHTTP] Permission denied opening port ${port}, skipping HTTP embedding server (sandboxed environment)`
+        );
+        // Some environments block listening on localhost; keep MCP server running without HTTP embeddings
+        resolve(null);
       } else {
         reject(error);
       }

package/src/mama/db-manager.js

@@ -386,30 +386,46 @@ async function queryDecisionGraph(topic) {
  * for refines and contradicts relationships
  *
  * @param {Array<string>} decisionIds - Decision IDs to query edges for
- * @returns {Promise<Object>} Categorized edges { refines, refined_by, contradicts, contradicted_by }
+ * @returns {Promise<Object>} Categorized edges { refines, refined_by, contradicts, contradicted_by, builds_on, built_on_by, debates, debated_by, synthesizes, synthesized_by }
  */
 async function querySemanticEdges(decisionIds) {
   const adapter = getAdapter();
 
   if (!decisionIds || decisionIds.length === 0) {
-    return { refines: [], refined_by: [], contradicts: [], contradicted_by: [] };
+    return {
+      refines: [],
+      refined_by: [],
+      contradicts: [],
+      contradicted_by: [],
+      // Story 2.1: Extended edge types
+      builds_on: [],
+      built_on_by: [],
+      debates: [],
+      debated_by: [],
+      synthesizes: [],
+      synthesized_by: [],
+    };
   }
 
   try {
     // Build placeholders for IN clause
     const placeholders = decisionIds.map(() => '?').join(',');
 
+    // Story 2.1: Include new edge types in query
+    const edgeTypes = ['refines', 'contradicts', 'builds_on', 'debates', 'synthesizes'];
+    const edgeTypePlaceholders = edgeTypes.map(() => '?').join(',');
+
     // Query outgoing edges (from_id = decision)
     const outgoingStmt = adapter.prepare(`
       SELECT e.*, d.topic, d.decision, d.confidence, d.created_at
       FROM decision_edges e
       JOIN decisions d ON e.to_id = d.id
       WHERE e.from_id IN (${placeholders})
-        AND e.relationship IN ('refines', 'contradicts')
+        AND e.relationship IN (${edgeTypePlaceholders})
         AND (e.approved_by_user = 1 OR e.approved_by_user IS NULL)
       ORDER BY e.created_at DESC
     `);
-    const outgoingEdges = await outgoingStmt.all(...decisionIds);
+    const outgoingEdges = await outgoingStmt.all(...decisionIds, ...edgeTypes);
 
     // Query incoming edges (to_id = decision)
     const incomingStmt = adapter.prepare(`
@@ -417,23 +433,36 @@ async function querySemanticEdges(decisionIds) {
       FROM decision_edges e
       JOIN decisions d ON e.from_id = d.id
       WHERE e.to_id IN (${placeholders})
-        AND e.relationship IN ('refines', 'contradicts')
+        AND e.relationship IN (${edgeTypePlaceholders})
         AND (e.approved_by_user = 1 OR e.approved_by_user IS NULL)
       ORDER BY e.created_at DESC
     `);
-    const incomingEdges = await incomingStmt.all(...decisionIds);
+    const incomingEdges = await incomingStmt.all(...decisionIds, ...edgeTypes);
 
-    // Categorize edges
+    // Categorize edges (original + v1.3 extended)
     const refines = outgoingEdges.filter((e) => e.relationship === 'refines');
     const refined_by = incomingEdges.filter((e) => e.relationship === 'refines');
     const contradicts = outgoingEdges.filter((e) => e.relationship === 'contradicts');
     const contradicted_by = incomingEdges.filter((e) => e.relationship === 'contradicts');
+    // Story 2.1: New edge type categories
+    const builds_on = outgoingEdges.filter((e) => e.relationship === 'builds_on');
+    const built_on_by = incomingEdges.filter((e) => e.relationship === 'builds_on');
+    const debates = outgoingEdges.filter((e) => e.relationship === 'debates');
+    const debated_by = incomingEdges.filter((e) => e.relationship === 'debates');
+    const synthesizes = outgoingEdges.filter((e) => e.relationship === 'synthesizes');
+    const synthesized_by = incomingEdges.filter((e) => e.relationship === 'synthesizes');
 
     return {
       refines,
       refined_by,
       contradicts,
       contradicted_by,
+      builds_on,
+      built_on_by,
+      debates,
+      debated_by,
+      synthesizes,
+      synthesized_by,
     };
   } catch (error) {
     throw new Error(`Semantic edges query failed: ${error.message}`);

package/src/mama/decision-tracker.js

@@ -24,6 +24,21 @@ const {
   getAdapter,
 } = require('./memory-store');
 
+// ════════════════════════════════════════════════════════════════════════════
+// Story 2.1: Extended Edge Types
+// ════════════════════════════════════════════════════════════════════════════
+// Valid relationship types for decision_edges
+// Original: supersedes, refines, contradicts
+// v1.3 Extension: builds_on, debates, synthesizes
+const VALID_EDGE_TYPES = [
+  'supersedes', // Original: New decision replaces old one
+  'refines', // Original: Decision refines another
+  'contradicts', // Original: Decision contradicts another
+  'builds_on', // v1.3: Extends existing decision with new insights
+  'debates', // v1.3: Presents counter-argument with evidence
+  'synthesizes', // v1.3: Merges multiple decisions into unified approach
+];
+
 /**
  * Generate decision ID
  *
@@ -74,32 +89,68 @@ async function getPreviousDecision(topic) {
 }
 
 /**
- * Create supersedes edge
+ * Create a decision edge with specified relationship type
  *
- * Task 3.5: Create supersedes edge (INSERT INTO decision_edges)
- * AC #2: Supersedes relationship creation
+ * Story 2.1: Generic edge creation supporting all relationship types
  *
- * @param {string} fromId - New decision ID
- * @param {string} toId - Previous decision ID
- * @param {string} reason - Reason for superseding
+ * @param {string} fromId - Source decision ID
+ * @param {string} toId - Target decision ID
+ * @param {string} relationship - Edge type (supersedes, builds_on, debates, synthesizes, etc.)
+ * @param {string} reason - Reason for the relationship
+ * @returns {Promise<boolean>} Success status
  */
-async function createSupersedesEdge(fromId, toId, reason) {
+async function createEdge(fromId, toId, relationship, reason) {
   const adapter = getAdapter();
 
+  // Story 2.1: Runtime validation of edge types
+  if (!VALID_EDGE_TYPES.includes(relationship)) {
+    throw new Error(
+      `Invalid edge type: "${relationship}". Valid types: ${VALID_EDGE_TYPES.join(', ')}`
+    );
+  }
+
   try {
-    // Auto-generated links: created_by='llm', approved_by_user=0 (pending approval)
-    // This ensures they appear in get_pending_links and require explicit approval
+    // Note: SQLite CHECK constraint only allows supersedes/refines/contradicts
+    // New types (builds_on, debates, synthesizes) bypass CHECK via runtime validation
+    // The INSERT will fail for new types due to CHECK constraint
+    // WORKAROUND: Use PRAGMA ignore_check_constraints or recreate table
+    // For now, we'll catch the error and handle gracefully
+
+    // Story 2.1: LLM auto-detected edges are approved by default (approved_by_user=1)
+    // This allows them to appear in search results via querySemanticEdges
     const stmt = adapter.prepare(`
-      INSERT INTO decision_edges (from_id, to_id, relationship, reason, created_at, created_by, approved_by_user)
-      VALUES (?, ?, 'supersedes', ?, ?, 'llm', 0)
+      INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, created_at, created_by, approved_by_user)
+      VALUES (?, ?, ?, ?, ?, 'llm', 1)
     `);
 
-    await stmt.run(fromId, toId, reason, Date.now());
+    await stmt.run(fromId, toId, relationship, reason, Date.now());
+    return true;
   } catch (error) {
-    throw new Error(`Failed to create supersedes edge: ${error.message}`);
+    // Handle CHECK constraint failure for new edge types
+    if (error.message.includes('CHECK constraint failed')) {
+      info(
+        `[decision-tracker] Edge type "${relationship}" not yet supported in schema, skipping edge creation`
+      );
+      return false;
+    }
+    throw new Error(`Failed to create ${relationship} edge: ${error.message}`);
   }
 }
 
+/**
+ * Create supersedes edge
+ *
+ * Task 3.5: Create supersedes edge (INSERT INTO decision_edges)
+ * AC #2: Supersedes relationship creation
+ *
+ * @param {string} fromId - New decision ID
+ * @param {string} toId - Previous decision ID
+ * @param {string} reason - Reason for superseding
+ */
+async function createSupersedesEdge(fromId, toId, reason) {
+  return createEdge(fromId, toId, 'supersedes', reason);
+}
+
 /**
  * Update previous decision's superseded_by field
  *
@@ -175,6 +226,163 @@ function detectRefinement(_detection, _sessionContext) {
   return null;
 }
 
+// ════════════════════════════════════════════════════════════════════════════
+// Story 2.2: Reasoning Field Parsing
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse reasoning field for relationship references
+ *
+ * Story 2.2: Detect patterns like:
+ * - builds_on: <decision_id>
+ * - debates: <decision_id>
+ * - synthesizes: [id1, id2]
+ *
+ * @param {string} reasoning - Decision reasoning text
+ * @returns {Array<{type: string, targetIds: string[]}>} Detected relationships
+ */
+function parseReasoningForRelationships(reasoning) {
+  if (!reasoning || typeof reasoning !== 'string') {
+    return [];
+  }
+
+  const relationships = [];
+
+  // Pattern 1: builds_on: <id> or builds_on: decision_xxx
+  const buildsOnMatch = reasoning.match(/builds_on:\s*(decision_[a-z0-9_]+)/gi);
+  if (buildsOnMatch) {
+    buildsOnMatch.forEach((match) => {
+      const id = match.replace(/builds_on:\s*/i, '').trim();
+      if (id) {
+        relationships.push({ type: 'builds_on', targetIds: [id] });
+      }
+    });
+  }
+
+  // Pattern 2: debates: <id> or debates: decision_xxx
+  const debatesMatch = reasoning.match(/debates:\s*(decision_[a-z0-9_]+)/gi);
+  if (debatesMatch) {
+    debatesMatch.forEach((match) => {
+      const id = match.replace(/debates:\s*/i, '').trim();
+      if (id) {
+        relationships.push({ type: 'debates', targetIds: [id] });
+      }
+    });
+  }
+
+  // Pattern 3: synthesizes: [id1, id2] or synthesizes: decision_xxx, decision_yyy
+  const synthesizesMatch = reasoning.match(
+    /synthesizes:\s*\[?\s*(decision_[a-z0-9_]+(?:\s*,\s*decision_[a-z0-9_]+)*)\s*\]?/gi
+  );
+  if (synthesizesMatch) {
+    synthesizesMatch.forEach((match) => {
+      const idsStr = match.replace(/synthesizes:\s*\[?\s*/i, '').replace(/\s*\]?\s*$/, '');
+      const ids = idsStr.split(/\s*,\s*/).filter((id) => id.startsWith('decision_'));
+      if (ids.length > 0) {
+        relationships.push({ type: 'synthesizes', targetIds: ids });
+      }
+    });
+  }
+
+  return relationships;
+}
+
+/**
+ * Create edges from parsed reasoning relationships
+ *
+ * Story 2.2: Auto-create edges when reasoning references other decisions
+ *
+ * @param {string} fromId - Source decision ID
+ * @param {string} reasoning - Decision reasoning text
+ * @returns {Promise<{created: number, failed: number}>} Edge creation stats
+ */
+async function createEdgesFromReasoning(fromId, reasoning) {
+  const relationships = parseReasoningForRelationships(reasoning);
+  let created = 0;
+  let failed = 0;
+
+  for (const rel of relationships) {
+    for (const targetId of rel.targetIds) {
+      try {
+        // Verify target decision exists
+        const adapter = getAdapter();
+        const stmt = adapter.prepare('SELECT id FROM decisions WHERE id = ?');
+        const target = await stmt.get(targetId);
+
+        if (!target) {
+          info(`[decision-tracker] Referenced decision not found: ${targetId}, skipping edge`);
+          failed++;
+          continue;
+        }
+
+        // Create the edge
+        const reason = `Auto-detected from reasoning: ${rel.type} reference`;
+        const success = await createEdge(fromId, targetId, rel.type, reason);
+
+        if (success) {
+          created++;
+          info(`[decision-tracker] Created ${rel.type} edge: ${fromId} -> ${targetId}`);
+        } else {
+          failed++;
+        }
+      } catch (error) {
+        info(`[decision-tracker] Failed to create edge to ${targetId}: ${error.message}`);
+        failed++;
+      }
+    }
+  }
+
+  return { created, failed };
+}
+
+/**
+ * Get supersedes chain depth for a topic
+ *
+ * Story 2.2: Calculate how many times a topic has been superseded
+ *
+ * @param {string} topic - Decision topic
+ * @returns {Promise<{depth: number, chain: string[]}>} Chain depth and decision IDs
+ */
+async function getSupersededChainDepth(topic) {
+  const adapter = getAdapter();
+  const chain = [];
+
+  try {
+    // Start from the latest decision (superseded_by IS NULL)
+    let stmt = adapter.prepare(`
+      SELECT id, supersedes FROM decisions
+      WHERE topic = ? AND superseded_by IS NULL
+      ORDER BY created_at DESC
+      LIMIT 1
+    `);
+
+    let current = await stmt.get(topic);
+
+    if (!current) {
+      return { depth: 0, chain: [] };
+    }
+
+    chain.push(current.id);
+
+    // Walk back through supersedes chain
+    while (current && current.supersedes) {
+      stmt = adapter.prepare('SELECT id, supersedes FROM decisions WHERE id = ?');
+      current = await stmt.get(current.supersedes);
+
+      if (current) {
+        chain.push(current.id);
+      }
+    }
+
+    return {
+      depth: chain.length - 1, // depth = number of supersedes edges
+      chain: chain.reverse(), // oldest to newest
+    };
+  } catch (error) {
+    throw new Error(`Failed to get supersedes chain: ${error.message}`);
+  }
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // NOTE: Auto-link functions REMOVED in v1.2.0
 //
@@ -387,7 +595,10 @@ function updateConfidence(prior, evidence) {
 // NOTE: Auto-link functions (createRefinesEdge, createContradictsEdge,
 // findRelatedDecisions, isConflicting, detectConflicts) removed from exports.
 // LLM infers relationships from search results instead.
+//
+// Story 2.1/2.2: Added new edge type support and reasoning parsing
 module.exports = {
+  // Core functions
   learnDecision,
   generateDecisionId,
   getPreviousDecision,
@@ -396,4 +607,11 @@ module.exports = {
   calculateCombinedConfidence,
   detectRefinement,
   updateConfidence,
+  // Story 2.1: Edge type extension
+  VALID_EDGE_TYPES,
+  createEdge,
+  // Story 2.2: Reasoning field parsing
+  parseReasoningForRelationships,
+  createEdgesFromReasoning,
+  getSupersededChainDepth,
 };

package/src/mama/mama-api.js

@@ -8,11 +8,21 @@
  * - MAMA stores (organize books), retrieves (find books), indexes (catalog)
  * - Claude decides what to save and how to use recalled decisions
  *
+ * v1.3 Update: Collaborative Reasoning Graph
+ * - Auto-search on save: Find similar decisions before saving
+ * - Collaborative invitation: Suggest build-on/debate/synthesize
+ * - AX-first: Soft warnings, not hard blocks
+ *
  * @module mama-api
- * @version 1.0
- * @date 2025-11-14
+ * @version 1.3
+ * @date 2025-11-26
  */
 
+// Session-level warning cooldown cache (Story 1.1, 1.2)
+// Prevents spam by tracking warned topics per session
+const warnedTopicsCache = new Map();
+const WARNING_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+
 const { learnDecision } = require('./decision-tracker');
 // eslint-disable-next-line no-unused-vars
 const { injectDecisionContext } = require('./memory-inject');
@@ -182,7 +192,158 @@ async function save({
     await stmt.run(...values);
   }
 
-  return decisionId;
+  // ════════════════════════════════════════════════════════════════════════════
+  // Story 1.1: Auto-Search on Save
+  // Story 1.2: Response Enhancement
+  // ════════════════════════════════════════════════════════════════════════════
+  let similar_decisions = [];
+  let warning = null;
+  let collaboration_hint = null;
+  let reasoning_graph = null;
+
+  // Only run auto-search for decisions (not checkpoints) with a topic
+  if (topic) {
+    try {
+      // Story 1.1: Auto-search using suggest()
+      const searchResults = await suggest(topic, {
+        limit: 3,
+        threshold: 0.7,
+        disableRecency: true, // Pure semantic similarity for comparison
+      });
+
+      if (searchResults && searchResults.results) {
+        // Filter out the decision we just saved
+        similar_decisions = searchResults.results
+          .filter((d) => d.id !== decisionId)
+          .map((d) => ({
+            id: d.id,
+            topic: d.topic,
+            decision: d.decision,
+            similarity: d.similarity,
+            created_at: d.created_at,
+          }));
+
+        // Story 1.2: Warning logic (similarity >= 0.85)
+        const highSimilarity = similar_decisions.find((d) => d.similarity >= 0.85);
+        if (highSimilarity && !_isTopicInCooldown(topic)) {
+          warning = `High similarity (${(highSimilarity.similarity * 100).toFixed(0)}%) with existing decision "${highSimilarity.decision.substring(0, 50)}..."`;
+          _markTopicWarned(topic);
+        }
+
+        // Story 1.2: Collaboration hint
+        if (similar_decisions.length > 0) {
+          collaboration_hint = _generateCollaborationHint(similar_decisions);
+        }
+      }
+    } catch (error) {
+      // Story 1.1 AC3: Best-effort - save succeeds even if auto-search fails
+      console.error('Auto-search failed:', error.message);
+    }
+
+    // Story 1.2: Reasoning graph info
+    try {
+      reasoning_graph = await _getReasoningGraphInfo(topic, decisionId);
+    } catch (error) {
+      console.error('Reasoning graph query failed:', error.message);
+    }
+
+    // Story 2.2: Parse reasoning for relationship edges (builds_on, debates, synthesizes)
+    if (reasoning) {
+      try {
+        const { createEdgesFromReasoning } = require('./decision-tracker.js');
+        await createEdgesFromReasoning(decisionId, reasoning);
+      } catch (error) {
+        // Best-effort - save succeeds even if edge creation fails
+        console.error('Edge creation from reasoning failed:', error.message);
+      }
+    }
+  }
+
+  // Story 1.2: Enhanced response (backward compatible)
+  return {
+    success: true,
+    id: decisionId,
+    ...(similar_decisions.length > 0 && { similar_decisions }),
+    ...(warning && { warning }),
+    ...(collaboration_hint && { collaboration_hint }),
+    ...(reasoning_graph && { reasoning_graph }),
+  };
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Story 1.2: Helper functions for Response Enhancement
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a topic is in warning cooldown
+ * @param {string} topic - Topic to check
+ * @returns {boolean} True if topic was warned recently
+ */
+function _isTopicInCooldown(topic) {
+  const lastWarned = warnedTopicsCache.get(topic);
+  if (!lastWarned) {
+    return false;
+  }
+  return Date.now() - lastWarned < WARNING_COOLDOWN_MS;
+}
+
+/**
+ * Mark a topic as warned (start cooldown)
+ * @param {string} topic - Topic to mark
+ */
+function _markTopicWarned(topic) {
+  warnedTopicsCache.set(topic, Date.now());
+}
+
+/**
+ * Generate collaboration hint message
+ * @param {Array} similarDecisions - Similar decisions found
+ * @returns {string} Collaboration hint message
+ */
+function _generateCollaborationHint(similarDecisions) {
+  const count = similarDecisions.length;
+  if (count === 0) {
+    return null;
+  }
+
+  return `Found ${count} related decision(s). Consider:
+- SUPERSEDE: Same topic replaces prior (automatic)
+- BUILD-ON: Add "builds_on: <id>" in reasoning to extend
+- DEBATE: Add "debates: <id>" in reasoning for alternative view
+- SYNTHESIZE: Add "synthesizes: [id1, id2]" in reasoning to unify`;
+}
+
+/**
+ * Get reasoning graph info for a topic
+ * @param {string} topic - Topic to query
+ * @param {string} currentId - Current decision ID
+ * @returns {Object} Reasoning graph info
+ */
+async function _getReasoningGraphInfo(topic, currentId) {
+  try {
+    const { queryDecisionGraph } = require('./memory-store');
+    const chain = await queryDecisionGraph(topic);
+
+    if (!chain || chain.length === 0) {
+      return {
+        topic,
+        depth: 1,
+        latest: currentId,
+      };
+    }
+
+    return {
+      topic,
+      depth: chain.length,
+      latest: chain[0]?.id || currentId,
+    };
+  } catch (error) {
+    return {
+      topic,
+      depth: 1,
+      latest: currentId,
+    };
+  }
 }
 
 /**
@@ -333,7 +494,10 @@ async function updateOutcome(decisionId, { outcome, failure_reason, limitation }
     throw new Error('mama.updateOutcome() requires decisionId (string)');
   }
 
-  if (!outcome || !['SUCCESS', 'FAILED', 'PARTIAL'].includes(outcome)) {
+  // AX Improvement: Be forgiving with case sensitivity
+  const normalizedOutcome = outcome ? outcome.toUpperCase() : null;
+
+  if (!normalizedOutcome || !['SUCCESS', 'FAILED', 'PARTIAL'].includes(normalizedOutcome)) {
     throw new Error('mama.updateOutcome() outcome must be "SUCCESS", "FAILED", or "PARTIAL"');
   }
 
@@ -353,7 +517,7 @@ async function updateOutcome(decisionId, { outcome, failure_reason, limitation }
     `
     );
     const result = stmt.run(
-      outcome,
+      normalizedOutcome,
       failure_reason || null,
       limitation || null,
       Date.now(),
@@ -416,91 +580,112 @@ async function expandWithGraph(candidates) {
       console.warn(`Failed to get supersedes chain for ${candidate.topic}: ${error.message}`);
     }
 
-    // 2. Add semantic edges (refines, contradicts)
+    // 2. Add semantic edges (refines, contradicts, builds_on, debates, synthesizes)
     try {
       const edges = await querySemanticEdges([candidate.id]);
 
-      // Add refines edges
-      for (const edge of edges.refines) {
-        if (!graphEnhanced.has(edge.to_id)) {
-          graphEnhanced.set(edge.to_id, {
-            id: edge.to_id,
+      // Helper to add edge to graph
+      const addEdge = (edge, idField, source, rank, simFactor) => {
+        const id = edge[idField];
+        if (!graphEnhanced.has(id)) {
+          graphEnhanced.set(id, {
+            id: id,
             topic: edge.topic,
             decision: edge.decision,
             confidence: edge.confidence,
             created_at: edge.created_at,
-            graph_source: 'refines',
-            graph_rank: 0.7,
-            similarity: candidate.similarity * 0.85,
+            graph_source: source,
+            graph_rank: rank,
+            similarity: candidate.similarity * simFactor,
             related_to: candidate.id,
             edge_reason: edge.reason,
           });
         }
+      };
+
+      // Add refines edges
+      for (const edge of edges.refines) {
+        addEdge(edge, 'to_id', 'refines', 0.7, 0.85);
       }
 
       // Add refined_by edges
       for (const edge of edges.refined_by) {
-        if (!graphEnhanced.has(edge.from_id)) {
-          graphEnhanced.set(edge.from_id, {
-            id: edge.from_id,
-            topic: edge.topic,
-            decision: edge.decision,
-            confidence: edge.confidence,
-            created_at: edge.created_at,
-            graph_source: 'refined_by',
-            graph_rank: 0.7,
-            similarity: candidate.similarity * 0.85,
-            related_to: candidate.id,
-            edge_reason: edge.reason,
-          });
-        }
+        addEdge(edge, 'from_id', 'refined_by', 0.7, 0.85);
       }
 
       // Add contradicts edges (lower rank, but still relevant)
       for (const edge of edges.contradicts) {
-        if (!graphEnhanced.has(edge.to_id)) {
-          graphEnhanced.set(edge.to_id, {
-            id: edge.to_id,
-            topic: edge.topic,
-            decision: edge.decision,
-            confidence: edge.confidence,
-            created_at: edge.created_at,
-            graph_source: 'contradicts',
-            graph_rank: 0.6,
-            similarity: candidate.similarity * 0.8,
-            related_to: candidate.id,
-            edge_reason: edge.reason,
-          });
-        }
+        addEdge(edge, 'to_id', 'contradicts', 0.6, 0.8);
+      }
+
+      // Story 2.1: Add builds_on edges (high relevance - extending prior work)
+      for (const edge of edges.builds_on) {
+        addEdge(edge, 'to_id', 'builds_on', 0.75, 0.9);
+      }
+
+      // Add built_on_by edges (someone built on this decision)
+      for (const edge of edges.built_on_by) {
+        addEdge(edge, 'from_id', 'built_on_by', 0.75, 0.9);
+      }
+
+      // Add debates edges (alternative view)
+      for (const edge of edges.debates) {
+        addEdge(edge, 'to_id', 'debates', 0.65, 0.85);
+      }
+
+      // Add debated_by edges
+      for (const edge of edges.debated_by) {
+        addEdge(edge, 'from_id', 'debated_by', 0.65, 0.85);
+      }
+
+      // Add synthesizes edges (unified approach)
+      for (const edge of edges.synthesizes) {
+        addEdge(edge, 'to_id', 'synthesizes', 0.7, 0.88);
+      }
+
+      // Add synthesized_by edges
+      for (const edge of edges.synthesized_by) {
+        addEdge(edge, 'from_id', 'synthesized_by', 0.7, 0.88);
       }
     } catch (error) {
       console.warn(`Failed to get semantic edges for ${candidate.id}: ${error.message}`);
     }
   }
 
-  // 3. Convert Map to Array and sort by graph_rank + similarity
-  const results = Array.from(graphEnhanced.values());
+  // 3. Convert Map to Array
+  const allResults = Array.from(graphEnhanced.values());
+
+  // 4. Sort: Interleave expanded results after their related primary
+  // This ensures edge-connected decisions appear near their source
+  const primaryResults = allResults
+    .filter((r) => primaryIds.has(r.id))
+    .sort((a, b) => {
+      const scoreA = a.final_score || a.similarity || 0;
+      const scoreB = b.final_score || b.similarity || 0;
+      return scoreB - scoreA;
+    });
 
-  // 4. Sort: Primary first, then by graph_rank, then by final_score (or similarity)
-  results.sort((a, b) => {
-    // Primary candidates always first
-    if (primaryIds.has(a.id) && !primaryIds.has(b.id)) {
-      return -1;
-    }
-    if (!primaryIds.has(a.id) && primaryIds.has(b.id)) {
-      return 1;
-    }
+  const expandedResults = allResults.filter((r) => !primaryIds.has(r.id));
 
-    // Then by graph_rank
-    if (a.graph_rank !== b.graph_rank) {
-      return b.graph_rank - a.graph_rank;
-    }
+  // Build final results: each primary followed by its related expanded results
+  const results = [];
+  for (const primary of primaryResults) {
+    results.push(primary);
 
-    // Finally by final_score (recency-boosted) or similarity (fallback)
-    const scoreA = a.final_score || a.similarity || 0;
-    const scoreB = b.final_score || b.similarity || 0;
-    return scoreB - scoreA;
-  });
+    // Find expanded results related to this primary
+    const relatedExpanded = expandedResults.filter((e) => e.related_to === primary.id);
+
+    // Sort related by graph_rank (higher first)
+    relatedExpanded.sort((a, b) => (b.graph_rank || 0) - (a.graph_rank || 0));
+
+    // Add related expanded results right after their primary
+    results.push(...relatedExpanded);
+  }
+
+  // Add any orphaned expanded results (shouldn't happen, but safety net)
+  const includedIds = new Set(results.map((r) => r.id));
+  const orphaned = expandedResults.filter((e) => !includedIds.has(e.id));
+  results.push(...orphaned);
 
   return results;
 }

package/src/server.js

@@ -241,8 +241,8 @@ class MAMAServer {
               },
               outcome: {
                 type: 'string',
-                enum: ['success', 'failure', 'partial'],
-                description: 'New outcome status.',
+                description:
+                  "New outcome status (case-insensitive): 'success' or 'SUCCESS', 'failed' or 'FAILED', 'partial' or 'PARTIAL'.",
               },
               reason: {
                 type: 'string',
@@ -363,7 +363,8 @@ class MAMAServer {
       let decisions;
       if (query) {
         // suggest() returns { results: [...] } object or null
-        const suggestResult = await mama.suggest(query, limit);
+        // Note: suggest() takes options object as second parameter
+        const suggestResult = await mama.suggest(query, { limit });
         decisions = suggestResult?.results || [];
       } else {
         decisions = await mama.list(limit);
@@ -406,6 +407,7 @@ class MAMAServer {
 
   /**
    * Handle update (decision outcome)
+   * Story 3.1: Case-insensitive outcome support
    */
   async handleUpdate(args) {
     const { id, outcome, reason } = args;
@@ -414,10 +416,20 @@ class MAMAServer {
       return { success: false, message: '❌ Update requires: id, outcome' };
     }
 
-    await mama.updateOutcome(id, outcome.toUpperCase(), reason);
+    // Story 3.1: Normalize outcome - handle both 'failure' and 'failed' variants
+    let normalizedOutcome = outcome.toUpperCase();
+    if (normalizedOutcome === 'FAILURE') {
+      normalizedOutcome = 'FAILED';
+    }
+
+    await mama.updateOutcome(id, {
+      outcome: normalizedOutcome,
+      failure_reason: reason,
+    });
+
     return {
       success: true,
-      message: `✅ Updated ${id} → ${outcome}`,
+      message: `✅ Updated ${id} → ${normalizedOutcome}`,
     };
   }
 
@@ -440,7 +452,7 @@ class MAMAServer {
         // Pre-warm model in background (don't block MCP startup)
         warmModel().catch((err) => console.error('[MAMA MCP] Model warmup error:', err.message));
       } else {
-        console.error('[MAMA MCP] HTTP embedding server skipped (port in use)');
+        console.error('[MAMA MCP] HTTP embedding server skipped (port unavailable or blocked)');
       }
 
       // Start server with stdio transport

package/src/tools/save-decision.js

@@ -17,8 +17,37 @@ const mama = require('../mama/mama-api.js');
  */
 const createSaveDecisionTool = (mamaApi) => ({
   name: 'save_decision',
-  description:
-    "Save a decision or insight to MAMA's memory for future reference. Use this when the user explicitly wants to remember something important (e.g., architectural decisions, parameter choices, lessons learned). The decision will be stored with semantic embeddings for later retrieval.\n\n⚡ IMPORTANT - Graph Connectivity: Reuse the SAME topic name for related decisions to create decision graphs (supersedes/refines/contradicts edges). Example: Use 'auth_strategy' for all authentication decisions, not 'auth_strategy_v1', 'auth_strategy_v2'. This enables Learn/Unlearn/Relearn workflows.",
+  description: `Save your architectural decisions, lessons learned, or insights to MAMA's shared memory.
+
+**WHY USE THIS:**
+You are not just an AI assistant; you are a partner in this project. Your insights and reasoning are valuable assets. By saving them here, you allow future agents (including yourself in later sessions) to:
+1. Understand *WHY* a decision was made (Reasoning), not just *WHAT* was done.
+2. Avoid repeating the same mistakes (Lessons Learned).
+3. Build a connected graph of knowledge.
+
+**WHEN TO USE (Be Proactive!):**
+- **Decisions**: Whenever you make a significant choice (e.g., "Use SQLite instead of JSON"), save it. Don't wait for the user to ask. If you thought hard about it, it's worth saving.
+- **Insights**: If you discover something new ("Ah, this library conflicts with that one"), save it.
+- **Requests**: If the user says "Remember this" or "Note that", use this tool immediately.
+
+**COLLABORATION MODES:**
+When you find similar past decisions (returned in similar_decisions), choose your approach:
+- **build_on**: Extend the existing decision with new insights. Use same topic to create supersedes edge.
+- **debate**: Present a counter-argument with evidence. Explain why the prior decision may be wrong.
+- **synthesize**: Merge multiple decisions into a new unified approach.
+
+**5-LAYER REASONING (CoT Guide):**
+Structure your reasoning with these layers for maximum value:
+1. **Context**: What problem/situation prompted this decision?
+2. **Evidence**: What proves this works? (tests, benchmarks, prior experience)
+3. **Alternatives**: What other options were considered and why rejected?
+4. **Risks**: Known limitations or failure modes
+5. **Rationale**: Final reasoning that ties it all together
+
+**INSTRUCTIONS:**
+1. **Search First**: Before saving, try to search for related past decisions.
+2. **Link**: If you find a related decision, mention its ID or topic in the 'reasoning' field to create a mental link.
+3. **Reasoning**: Explain your logic clearly so future agents can "empathize" with your decision.`,
   inputSchema: {
     type: 'object',
     properties: {
@@ -104,24 +133,31 @@ const createSaveDecisionTool = (mamaApi) => ({
       }
 
       // Call MAMA API (mama.save will handle outcome mapping to DB format)
-      const id = await mamaApi.save({
+      // Story 1.1/1.2: save() now returns enhanced response object
+      const result = await mamaApi.save({
         topic,
         decision,
         reasoning,
         confidence,
-        type, // Assuming mama.saveDecision now expects 'type' directly
+        type,
         outcome,
         evidence,
         alternatives,
         risks,
       });
 
+      // Story 1.2: Return enhanced response with collaborative fields
       return {
-        success: true,
-        decision_id: id,
+        success: result.success,
+        decision_id: result.id,
         topic: topic,
-        message: `✅ Decision saved successfully (ID: ${id})`,
+        message: `✅ Decision saved successfully (ID: ${result.id})`,
         recall_command: `To recall: mama.recall('${topic}')`,
+        // Story 1.1/1.2: Collaborative fields (optional)
+        ...(result.similar_decisions && { similar_decisions: result.similar_decisions }),
+        ...(result.warning && { warning: result.warning }),
+        ...(result.collaboration_hint && { collaboration_hint: result.collaboration_hint }),
+        ...(result.reasoning_graph && { reasoning_graph: result.reasoning_graph }),
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';

package/src/tools/update-outcome.js

@@ -12,13 +12,79 @@
 
 const mama = require('../mama/mama-api.js');
 
+/**
+ * Valid outcome values (uppercase canonical form)
+ */
+const VALID_OUTCOMES = ['SUCCESS', 'FAILED', 'PARTIAL'];
+
+/**
+ * Suggest the closest valid outcome for typos/case errors
+ * @param {string} input - User's input
+ * @returns {string} Suggested outcome
+ */
+function suggestOutcome(input) {
+  if (!input || typeof input !== 'string') {
+    return 'SUCCESS';
+  }
+
+  const normalized = input.toUpperCase().trim();
+
+  // Exact match after normalization
+  if (VALID_OUTCOMES.includes(normalized)) {
+    return normalized;
+  }
+
+  // Prefix matching (e.g., "suc" -> "SUCCESS", "fail" -> "FAILED")
+  const prefixMatch = VALID_OUTCOMES.find((o) => o.startsWith(normalized.slice(0, 3)));
+  if (prefixMatch) {
+    return prefixMatch;
+  }
+
+  // Common typos/variations
+  const typoMap = {
+    SUCCEED: 'SUCCESS',
+    SUCCEEDED: 'SUCCESS',
+    PASS: 'SUCCESS',
+    PASSED: 'SUCCESS',
+    OK: 'SUCCESS',
+    FAIL: 'FAILED',
+    FAILURE: 'FAILED',
+    ERROR: 'FAILED',
+    PART: 'PARTIAL',
+    PARTIALLY: 'PARTIAL',
+  };
+
+  return typoMap[normalized] || 'SUCCESS';
+}
+
 /**
  * Update outcome tool definition
  */
 const updateOutcomeTool = {
   name: 'update_outcome',
-  description:
-    "Update a decision's outcome based on real-world results. Use this to mark decisions as SUCCESS, FAILED, or PARTIAL after implementation/validation. This enables tracking decision success rates and surfacing failures for improvement.\n\n⚡ OUTCOME TYPES:\n• SUCCESS: Decision worked as expected\n• FAILED: Decision caused problems (provide failure_reason)\n• PARTIAL: Decision partially worked (provide limitation)\n\n⚡ USE CASES:\n• After testing: Mark experimental decisions as SUCCESS/FAILED\n• After deployment: Update outcomes based on production metrics\n• After user feedback: Capture failure reasons from complaints",
+  description: `Update decision outcome after real-world validation.
+
+**WHEN TO USE:**
+• Days/weeks later when issues are discovered → mark FAILED with reason
+• After production deployment confirms success → mark SUCCESS
+• After partial success with known limitations → mark PARTIAL with limitation
+
+**WHY IMPORTANT:**
+Tracks decision evolution - failure outcomes help future LLMs avoid same mistakes.
+TIP: If decision failed, save a new decision with same topic to supersede it.
+
+**OUTCOME TYPES (case-insensitive):**
+• SUCCESS / success: Decision worked as expected
+• FAILED / failed: Decision caused problems (provide failure_reason)
+• PARTIAL / partial: Decision partially worked (provide limitation)
+
+**EVIDENCE TYPES:**
+When providing failure_reason or limitation, consider including:
+• url: Link to documentation, PR, or external resource
+• file_path: Path to relevant code file
+• log_snippet: Relevant log output or error message
+• observation: Direct observation or user feedback
+• reasoning_ref: Reference to another decision's reasoning`,
   inputSchema: {
     type: 'object',
     properties: {
@@ -29,9 +95,8 @@ const updateOutcomeTool = {
       },
       outcome: {
         type: 'string',
-        enum: ['SUCCESS', 'FAILED', 'PARTIAL'],
         description:
-          "Outcome status:\n• 'SUCCESS': Decision worked well in practice\n• 'FAILED': Decision caused problems (explain in failure_reason)\n• 'PARTIAL': Decision partially worked (explain in limitation)",
+          "Outcome status (case-insensitive):\n• 'SUCCESS' / 'success': Decision worked well in practice\n• 'FAILED' / 'failed': Decision caused problems (explain in failure_reason)\n• 'PARTIAL' / 'partial': Decision partially worked (explain in limitation)",
       },
       failure_reason: {
         type: 'string',
@@ -55,23 +120,33 @@ const updateOutcomeTool = {
       if (!decisionId || typeof decisionId !== 'string' || decisionId.trim() === '') {
         return {
           success: false,
-          message: '❌ Validation error: decisionId must be a non-empty string',
+          message:
+            '❌ Validation error: decisionId must be a non-empty string\n' +
+            '   💡 Use search tool to find valid decision IDs.',
         };
       }
 
-      if (!outcome || !['SUCCESS', 'FAILED', 'PARTIAL'].includes(outcome)) {
+      // Story 3.1: Case-insensitive outcome normalization
+      const normalizedOutcome =
+        outcome && typeof outcome === 'string' ? outcome.toUpperCase().trim() : outcome;
+
+      if (!normalizedOutcome || !VALID_OUTCOMES.includes(normalizedOutcome)) {
+        const suggestion = suggestOutcome(outcome);
         return {
           success: false,
-          message: '❌ Validation error: outcome must be "SUCCESS", "FAILED", or "PARTIAL"',
+          message:
+            '❌ Validation error: outcome must be "SUCCESS", "FAILED", or "PARTIAL"\n' +
+            `   💡 Did you mean "${suggestion}"? (case-insensitive, e.g., "success" works too)`,
         };
       }
 
       // Validation: failure_reason required for FAILED
-      if (outcome === 'FAILED' && (!failure_reason || failure_reason.trim() === '')) {
+      if (normalizedOutcome === 'FAILED' && (!failure_reason || failure_reason.trim() === '')) {
         return {
           success: false,
           message:
-            '❌ Validation error: failure_reason is required when outcome="FAILED" (explain what went wrong)',
+            '❌ Validation error: failure_reason is required when outcome="FAILED"\n' +
+            '   💡 Explain what went wrong so future agents can learn from this.',
         };
       }
 
@@ -90,9 +165,9 @@ const updateOutcomeTool = {
         };
       }
 
-      // Call MAMA API
+      // Call MAMA API with normalized outcome
       await mama.updateOutcome(decisionId, {
-        outcome,
+        outcome: normalizedOutcome,
         failure_reason,
         limitation,
       });
@@ -101,8 +176,8 @@ const updateOutcomeTool = {
       return {
         success: true,
         decision_id: decisionId,
-        outcome,
-        message: `✅ Decision outcome updated to ${outcome}${
+        outcome: normalizedOutcome,
+        message: `✅ Decision outcome updated to ${normalizedOutcome}${
           failure_reason
             ? `\n   Reason: ${failure_reason.substring(0, 100)}${failure_reason.length > 100 ? '...' : ''}`
             : ''