@jungjaehoon/mama-server 1.9.2 → 1.10.0

package/README.md

@@ -75,16 +75,23 @@ Any MCP-compatible client can use MAMA with:
 npx -y @jungjaehoon/mama-server
 ```
 
-## Available Tools (v1.3)
-
-The MCP server exposes 4 core tools:
-
-| 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                                               |
+## Available Tools (v1.9)
+
+The MCP server exposes 11 tools:
+
+| Tool                      | Description                                                             |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `save_decision`           | Save decision with optional scopes and event_date for temporal tracking |
+| `recall_decision`         | Recall decision history by topic, scope-filtered via recallMemory v2    |
+| `suggest_decision`        | Semantic search for relevant past decisions, scope-aware                |
+| `list_decisions`          | List recent decisions, scope-filterable                                 |
+| `update_outcome`          | Update decision outcome (case-insensitive: success/failed/partial)      |
+| `search_narrative`        | Narrative search with link expansion (depth 0-2)                        |
+| `ingest_conversation`     | Ingest conversation messages into memory with optional LLM extraction   |
+| `save_checkpoint`         | Save session checkpoint for later resumption                            |
+| `load_checkpoint`         | Resume previous session                                                 |
+| `generate_quality_report` | Quality metrics and observability report                                |
+| `get_restart_metrics`     | Restart success rate and latency monitoring                             |
 
 ### Edge Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-server",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
   "main": "src/server.js",
   "bin": {
@@ -39,7 +39,7 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@jungjaehoon/mama-core": "^1.3.2",
+    "@jungjaehoon/mama-core": "^1.4.0",
     "@modelcontextprotocol/sdk": "^1.0.1"
   },
   "devDependencies": {

package/src/server.js

@@ -415,6 +415,8 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
     // Handle tool execution - 4 core tools only
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name, arguments: args } = request.params;
+      const toolStart = Date.now();
+      console.error(`[MAMA MCP] Tool start: ${name}`);
 
       try {
         let result;
@@ -446,6 +448,8 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
           this.legacyNoticeEmittedInToolResponse = true;
         }
 
+        console.error(`[MAMA MCP] Tool done: ${name} (${Date.now() - toolStart}ms)`);
+
         return {
           content: [
             {
@@ -464,6 +468,7 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
           ],
         };
       } catch (error) {
+        console.error(`[MAMA MCP] Tool failed: ${name} (${Date.now() - toolStart}ms)`);
         console.error('[MAMA MCP] Tool execution error:', error);
         return {
           content: [
@@ -489,7 +494,7 @@ Returns: summary (4-section), next_steps (DoD + commands), open_files
       if (!topic || !decision || !reasoning) {
         return { success: false, message: '❌ Decision requires: topic, decision, reasoning' };
       }
-      const id = await mama.save({ topic, decision, reasoning, confidence });
+      const id = await mama.save({ type: 'user_decision', topic, decision, reasoning, confidence });
       return {
         success: true,
         id,

package/src/tools/checkpoint-tools.js

@@ -235,10 +235,6 @@ const loadCheckpointTool = {
   inputSchema: {
     type: 'object',
     properties: {
-      session_id: {
-        type: 'string',
-        description: 'Optional session ID. If not provided, loads the most recent checkpoint.',
-      },
       include_narrative: {
         type: 'boolean',
         description: 'Include related narrative/decisions (default: true)',
@@ -258,8 +254,7 @@ const loadCheckpointTool = {
   },
   handler: async (args = {}) => {
     const start = Date.now();
-    // eslint-disable-next-line no-unused-vars
-    const { session_id, include_narrative = true, include_links = true, link_depth = 1 } = args;
+    const { include_narrative = true, include_links = true, link_depth = 1 } = args;
 
     try {
       const adapter = getAdapter();
@@ -338,7 +333,7 @@ const loadCheckpointTool = {
       const formattedResponse = formatRestart(checkpoint, narrative, links);
 
       // BMad Workflow Integration: Add Story context
-      const currentStory = inferCurrentStory(checkpoint.summary);
+      const currentStory = include_narrative ? inferCurrentStory(checkpoint.summary) : null;
       let bmadWorkflowContext = '';
 
       if (currentStory && currentStory.details) {

package/src/tools/index.js

@@ -15,6 +15,7 @@
  * - search_narrative: Semantic search with link expansion ✅
  * - generate_quality_report: Generate coverage and quality metrics report ✅
  * - get_restart_metrics: Get restart success rate and latency metrics ✅
+ * - ingest_conversation: Ingest conversation messages into memory ✅
  *
  * @module tools
  */
@@ -27,6 +28,7 @@ const { updateOutcomeTool } = require('./update-outcome.js');
 const { saveCheckpointTool, loadCheckpointTool } = require('./checkpoint-tools.js');
 const { searchNarrativeTool } = require('./search-narrative.js');
 const { generateQualityReportTool, getRestartMetricsTool } = require('./quality-metrics-tools.js');
+const { ingestConversationTool } = require('./ingest-conversation.js');
 
 /**
  * Create all MAMA memory tools
@@ -47,6 +49,7 @@ function createMemoryTools() {
     search_narrative: searchNarrativeTool,
     generate_quality_report: generateQualityReportTool,
     get_restart_metrics: getRestartMetricsTool,
+    ingest_conversation: ingestConversationTool,
   };
 }
 
@@ -63,4 +66,5 @@ module.exports = {
   searchNarrativeTool,
   generateQualityReportTool,
   getRestartMetricsTool,
+  ingestConversationTool,
 };

package/src/tools/ingest-conversation.js

@@ -0,0 +1,99 @@
+/**
+ * MCP Tool: ingest_conversation
+ *
+ * Ingests conversation messages into MAMA memory with optional extraction.
+ *
+ * @module ingest-conversation
+ */
+
+const { ingestConversation } = require('@jungjaehoon/mama-core');
+
+const createIngestConversationTool = (mamaApi) => ({
+  name: 'ingest_conversation',
+  description:
+    "Ingest a conversation into MAMA's memory. Stores the raw conversation and optionally extracts structured memories (decisions, facts, preferences) using LLM. Use this to import past conversations or chat logs into memory.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      messages: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            role: { type: 'string', enum: ['user', 'assistant', 'system'] },
+            content: { type: 'string' },
+          },
+          required: ['role', 'content'],
+        },
+        description: 'Conversation messages to ingest.',
+      },
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            kind: { type: 'string', enum: ['global', 'user', 'channel', 'project'] },
+            id: { type: 'string' },
+          },
+          required: ['kind', 'id'],
+        },
+        description: 'Memory scopes for isolation.',
+      },
+      session_date: {
+        type: 'string',
+        description: 'ISO 8601 date when the conversation occurred (e.g., "2024-01-15").',
+      },
+      extract: {
+        type: 'boolean',
+        description: 'Whether to extract structured memories from the conversation. Default: false',
+      },
+    },
+    required: ['messages'],
+  },
+
+  async handler(params, _context) {
+    const { messages, scopes, session_date, extract = false } = params || {};
+
+    try {
+      if (!messages || !Array.isArray(messages) || messages.length === 0) {
+        return {
+          success: false,
+          message: '❌ Validation error: messages must be a non-empty array',
+        };
+      }
+
+      const ingestFn = mamaApi.ingestConversation || ingestConversation;
+      const result = await ingestFn({
+        messages,
+        scopes: scopes || [],
+        source: {
+          package: 'mcp-server',
+          source_type: 'mcp_ingest_conversation',
+        },
+        ...(session_date && { sessionDate: session_date }),
+        ...(extract && { extract: { enabled: true } }),
+      });
+
+      return {
+        success: true,
+        raw_id: result.rawId,
+        extracted_memories: result.extractedMemories || [],
+        message: `✅ Conversation ingested (ID: ${result.rawId})${
+          result.extractedMemories?.length
+            ? `, extracted ${result.extractedMemories.length} memories`
+            : ''
+        }`,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      return {
+        success: false,
+        message: `❌ Failed to ingest conversation: ${errorMessage}`,
+      };
+    }
+  },
+});
+
+const ingestConversationTool = createIngestConversationTool({});
+
+module.exports = { ingestConversationTool, createIngestConversationTool };

package/src/tools/list-decisions.js

@@ -26,7 +26,7 @@ const mama = require('@jungjaehoon/mama-core/mama-api');
 const listDecisionsTool = {
   name: 'list_decisions',
   description:
-    'List recent decisions in chronological order. Returns formatted list showing time, type (user/assistant), topic, preview, confidence, and status. Use this to see recent activity or find decisions by browsing.',
+    'List recent decisions in chronological order. Returns formatted list showing time, type (user/assistant), topic, preview, confidence, and status. Use this to see recent activity or find decisions by browsing. Use scopes to filter by project/channel.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -36,12 +36,24 @@ const listDecisionsTool = {
         minimum: 1,
         maximum: 100,
       },
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            kind: { type: 'string', enum: ['global', 'user', 'channel', 'project'] },
+            id: { type: 'string' },
+          },
+          required: ['kind', 'id'],
+        },
+        description: 'Filter list by scope. If omitted, lists all scopes.',
+      },
     },
     required: [],
   },
 
   async handler(params, _context) {
-    const { limit = 20 } = params || {};
+    const { limit = 20, scopes } = params || {};
 
     try {
       // Validation: Limit range check
@@ -52,9 +64,7 @@ const listDecisionsTool = {
         };
       }
 
-      // Call MAMA API with markdown format for human display
-      // mama.list() defaults to JSON (LLM-first), but we need markdown for user display
-      const list = await mama.list({ limit, format: 'markdown' });
+      const list = await mama.list({ limit, format: 'markdown', ...(scopes && { scopes }) });
 
       // Return success response with formatted list
       return {

package/src/tools/recall-decision.js

@@ -4,15 +4,8 @@
  * Story M1.3: MCP Tool - recall_decision (ported from mcp-server)
  * Priority: P1 (Core Feature)
  *
- * Recalls full decision history for a specific topic.
- * This is a wrapper around the existing mama.recall() API.
- *
- * Flow:
- * 1. User (via Claude Desktop): "Recall my decision about auth strategy"
- * 2. Claude: Calls recall_decision MCP tool
- * 3. Tool: Validates input, calls mama.recall()
- * 4. mama.recall(): Queries decision history + formats as markdown
- * 5. Tool: Returns formatted markdown response
+ * Recalls decision history for a specific topic using v2 recallMemory API.
+ * Supports scope-based filtering.
  *
  * @module recall-decision
  */
@@ -20,26 +13,51 @@
 const mama = require('@jungjaehoon/mama-core/mama-api');
 
 /**
- * Recall decision tool definition
+ * Create recall decision tool with dependencies
+ * @param {Object} mamaApi - MAMA API instance
  */
-const recallDecisionTool = {
+const createRecallDecisionTool = (mamaApi) => ({
   name: 'recall_decision',
   description:
-    'Recall full decision history for a specific topic. Returns all past decisions on this topic in chronological order with reasoning, confidence, and outcomes. Use this when you need to review previous decisions, understand decision evolution, or check current position on a topic.\n\n⚡ GRAPH TRAVERSAL: When the same topic is reused across multiple decisions, this tool automatically shows the decision evolution chain (supersedes graph), enabling Learn/Unlearn/Relearn workflows.',
+    'Recall decision history for a topic using semantic search. Returns past decisions filtered by scope if provided. Use this when you need to review previous decisions, understand decision evolution, or check current position on a topic.\n\n⚡ GRAPH TRAVERSAL: When the same topic is reused across multiple decisions, this tool automatically shows the decision evolution chain (supersedes graph), enabling Learn/Unlearn/Relearn workflows.',
   inputSchema: {
     type: 'object',
     properties: {
       topic: {
         type: 'string',
         description:
-          "Decision topic to recall (e.g., 'auth_strategy', 'mesh_detail_choice'). Use the EXACT SAME topic name used in save_decision to see full decision evolution graph. Different topic names will show separate, disconnected decisions.",
+          "Decision topic to recall (e.g., 'auth_strategy', 'mesh_detail_choice'). Use the EXACT SAME topic name used in save_decision to see full decision evolution graph.",
+      },
+      format: {
+        type: 'string',
+        enum: ['markdown', 'json'],
+        description: "Output format. Default: 'markdown'",
+      },
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            kind: {
+              type: 'string',
+              enum: ['global', 'user', 'channel', 'project'],
+              description: 'Scope type',
+            },
+            id: {
+              type: 'string',
+              description: 'Scope identifier (e.g., project path, channel ID)',
+            },
+          },
+          required: ['kind', 'id'],
+        },
+        description: 'Filter recall results by scope. If omitted, returns all scopes.',
       },
     },
     required: ['topic'],
   },
 
   async handler(params, _context) {
-    const { topic } = params || {};
+    const { topic, format = 'markdown', scopes } = params || {};
 
     try {
       // Validation: Non-empty string check
@@ -50,26 +68,53 @@ const recallDecisionTool = {
         };
       }
 
-      // Call MAMA API with markdown format for human display
-      // mama.recall() defaults to JSON (LLM-first), but we need markdown for user display
-      const history = await mama.recall(topic, { format: 'markdown' });
+      if (scopes && scopes.length > 0) {
+        // Use v2 recallMemory for scope-aware semantic recall
+        const bundle = await mamaApi.recallMemory(topic, {
+          scopes,
+          includeHistory: true,
+        });
+
+        if (format === 'json') {
+          return { success: true, history: bundle, message: bundle };
+        }
+
+        const memories = bundle.memories || [];
+        let md = `🧠 **Recall: ${topic}** (${memories.length} results)\n\n`;
+        for (const m of memories) {
+          md += `### ${m.topic}\n`;
+          md += `${m.summary}\n`;
+          if (m.details && m.details !== m.summary) {
+            md += `> ${m.details}\n`;
+          }
+          md += `- Confidence: ${m.confidence} | Status: ${m.status}`;
+          if (m.event_date) {
+            md += ` | Event: ${m.event_date}`;
+          }
+          md += '\n\n';
+        }
+        return { success: true, history: md, message: md };
+      }
+
+      // Legacy path: topic-exact-match recall (no scopes)
+      const history = await mamaApi.recall(topic, { format });
 
-      // Return success response with formatted history
       return {
         success: true,
         history,
-        message: history, // For backward compatibility with MCP response format
+        message: history,
       };
     } catch (error) {
-      // Error handling: Return user-friendly message
       const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-
       return {
         success: false,
         message: `❌ Failed to recall decisions: ${errorMessage}`,
       };
     }
   },
-};
+});
+
+// Default instance with real dependency
+const recallDecisionTool = createRecallDecisionTool(mama);
 
-module.exports = { recallDecisionTool };
+module.exports = { recallDecisionTool, createRecallDecisionTool };

package/src/tools/save-decision.js

@@ -149,6 +149,10 @@ When you find similar past decisions (returned in similar_decisions), choose you
 - **debate**: Present a counter-argument with evidence. Explain why the prior decision may be wrong.
 - **synthesize**: Merge multiple decisions into a new unified approach.
 
+**SCOPES & TEMPORAL:**
+- Use 'scopes' to isolate decisions per project/channel/user (e.g., [{"kind": "project", "id": "/my/app"}])
+- Use 'event_date' (ISO 8601) to record when events actually happened vs. when they were saved
+
 **5-LAYER REASONING (CoT Guide):**
 Structure your reasoning with these layers for maximum value:
 1. **Context**: What problem/situation prompted this decision?
@@ -211,6 +215,31 @@ Structure your reasoning with these layers for maximum value:
         type: 'string',
         description: 'Potential risks or downsides (Tension layer).',
       },
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            kind: {
+              type: 'string',
+              enum: ['global', 'user', 'channel', 'project'],
+              description: 'Scope type',
+            },
+            id: {
+              type: 'string',
+              description: 'Scope identifier (e.g., project path, channel ID)',
+            },
+          },
+          required: ['kind', 'id'],
+        },
+        description:
+          'Memory scopes for isolation. Decisions are stored per-scope. If omitted, decision is unscoped (global). Example: [{"kind": "project", "id": "/path/to/project"}]',
+      },
+      event_date: {
+        type: 'string',
+        description:
+          'ISO 8601 date when the event actually occurred (e.g., "2024-01-15"). If omitted, defaults to current time. Use this when recording decisions about past events.',
+      },
     },
     required: ['topic', 'decision', 'reasoning'],
   },
@@ -226,6 +255,8 @@ Structure your reasoning with these layers for maximum value:
       evidence,
       alternatives,
       risks,
+      scopes,
+      event_date,
     } = params || {};
 
     try {
@@ -305,6 +336,8 @@ Structure your reasoning with these layers for maximum value:
         alternatives,
         risks,
         trust_context: trustContext,
+        ...(scopes && { scopes }),
+        ...(event_date && { event_date }),
       });
 
       // Story 1.2: Return enhanced response with collaborative fields

package/src/tools/suggest-decision.js

@@ -17,7 +17,7 @@ const mama = require('@jungjaehoon/mama-core/mama-api');
 const suggestDecisionTool = {
   name: 'suggest_decision',
   description:
-    "Auto-suggest relevant past decisions based on user's question. Uses semantic search to find decisions related to the current context. Returns null if no relevant decisions found. Supports multilingual queries (English, Korean, etc.).",
+    "Auto-suggest relevant past decisions based on user's question. Uses semantic search to find decisions related to the current context. Returns null if no relevant decisions found. Supports multilingual queries (English, Korean, etc.). Use 'scopes' to filter by project/channel.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -48,12 +48,24 @@ const suggestDecisionTool = {
         description: 'Optional: Disable recency weighting entirely. Default: false',
         default: false,
       },
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            kind: { type: 'string', enum: ['global', 'user', 'channel', 'project'] },
+            id: { type: 'string' },
+          },
+          required: ['kind', 'id'],
+        },
+        description: 'Filter suggestions by scope. If omitted, searches all scopes.',
+      },
     },
     required: ['userQuestion'],
   },
 
   async handler(params, _context) {
-    const { userQuestion, recencyWeight, recencyScale, recencyDecay, disableRecency } =
+    const { userQuestion, recencyWeight, recencyScale, recencyDecay, disableRecency, scopes } =
       params || {};
 
     try {
@@ -65,13 +77,13 @@ const suggestDecisionTool = {
         };
       }
 
-      // Call MAMA API with markdown format
       const suggestions = await mama.suggest(userQuestion, {
         format: 'markdown',
         recencyWeight,
         recencyScale,
         recencyDecay,
         disableRecency,
+        ...(scopes && { scopes }),
       });
 
       if (!suggestions) {