@jungjaehoon/mama-server 1.12.1 → 1.14.0

package/README.md

@@ -75,23 +75,25 @@ Any MCP-compatible client can use MAMA with:
 npx -y @jungjaehoon/mama-server
 ```
 
-## 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                             |
+## Available Tools
+
+The MCP server exposes 13 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 with scopes, strictness controls, and diagnostics       |
+| `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                             |
+| `search_decisions_and_contracts` | Decision + contract lookup for tooling and hook pipelines               |
+| `case_timeline_range`            | Read bounded case timeline windows for case-first workflows             |
 
 ### Edge Types
 
@@ -104,6 +106,25 @@ Decisions connect through relationships. Include patterns in your reasoning:
 | `debates`     | `debates: decision_xxx`    | Alternative view           |
 | `synthesizes` | `synthesizes: [id1, id2]`  | Merges multiple approaches |
 
+### Search Quality Controls
+
+`suggest_decision` accepts optional search-quality parameters for agents and operators:
+
+| Parameter           | Use                                                           |
+| ------------------- | ------------------------------------------------------------- |
+| `strictness`        | `'recall'`, `'balanced'`, or `'strict'` retrieval mode        |
+| `strict`            | Shortcut for strict mode                                      |
+| `threshold`         | Override the mode's minimum candidate threshold               |
+| `disableRecency`    | Remove recency boosting when relevance matters more than time |
+| `includeRelated`    | Include or suppress graph-expanded related hits               |
+| `topicPrefix`       | Limit search to a topic namespace                             |
+| `minLexicalSupport` | Require independent relevance confirmation                    |
+| `diagnostics`       | Return why each result was included or rejected               |
+| `scopes`            | Limit search to project/channel/user/global memory scopes     |
+
+Use `strictness: "balanced"` for normal agent work and `strictness: "strict"` when a result will
+drive a code change, user-facing answer, or provenance claim.
+
 ## Usage Example
 
 Once configured, use MAMA through your MCP client:
@@ -261,4 +282,4 @@ MAMA was inspired by [mem0](https://github.com/mem0ai/mem0) (Apache 2.0). While
 ---
 
 **Author:** SpineLift Team
-**Version:** 1.9.0
+**Version:** 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-server",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "MAMA MCP Server - Memory-Augmented MCP Assistant for Claude Code & Desktop",
   "main": "src/server.js",
   "bin": {
@@ -39,10 +39,11 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@jungjaehoon/mama-core": "^1.4.0",
+    "@jungjaehoon/mama-core": "^1.6.0",
     "@modelcontextprotocol/sdk": "^1.0.1"
   },
   "devDependencies": {
+    "better-sqlite3": "^12.8.0",
     "vitest": "^1.0.0"
   },
   "files": [

package/src/server.js

@@ -26,7 +26,6 @@ const {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } = require('@modelcontextprotocol/sdk/types.js');
-const path = require('path');
 
 // Import all MAMA tools from src/tools/ — single source of truth for tool definitions
 const { createMemoryTools } = require('./tools/index.js');
@@ -35,8 +34,6 @@ const mama = require('@jungjaehoon/mama-core/mama-api');
 
 // Import core modules from mama-core
 const { initDB } = require('@jungjaehoon/mama-core/db-manager');
-const { generateEmbedding } = require('@jungjaehoon/mama-core/embeddings');
-const { vectorSearch } = require('@jungjaehoon/mama-core/memory-store');
 const embeddingServer = require('@jungjaehoon/mama-core/embedding-server');
 const http = require('http');
 
@@ -330,6 +327,41 @@ class MAMAServer {
               description: "Filter by type. Default: 'all'",
             },
             limit: { type: 'number', description: 'Max results. Default: 10' },
+            threshold: {
+              type: 'number',
+              minimum: 0,
+              maximum: 1,
+              description: 'Minimum retrieval threshold. Omit for mode default.',
+            },
+            strict: {
+              type: 'boolean',
+              description: 'Shortcut for strict search mode.',
+            },
+            strictness: {
+              type: 'string',
+              enum: ['recall', 'balanced', 'strict'],
+              description: "Search quality mode. Default: 'recall'.",
+            },
+            disableRecency: {
+              type: 'boolean',
+              description: 'Disable recency weighting in search.',
+            },
+            includeRelated: {
+              type: 'boolean',
+              description: 'Include related graph-expanded results.',
+            },
+            topicPrefix: {
+              type: 'string',
+              description: 'Restrict search to topics with this prefix.',
+            },
+            minLexicalSupport: {
+              type: 'boolean',
+              description: 'Require lexical/entity/exact-topic confirmation.',
+            },
+            diagnostics: {
+              type: 'boolean',
+              description: 'Return retrieval diagnostics for search quality inspection.',
+            },
             scopes: {
               type: 'array',
               items: {
@@ -369,24 +401,17 @@ After failure → save a NEW decision with same topic to create evolution histor
           required: ['id', 'outcome'],
         },
       },
-      // 4. SEARCH_DECISIONS_AND_CONTRACTS — PreToolUse hook RPC
+      // 4. SEARCH_DECISIONS_AND_CONTRACTS — PreToolUse hook RPC (defined in src/tools/)
       {
-        name: 'search_decisions_and_contracts',
-        description: 'Search decisions and contracts for PreToolUse hook injection.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            query: { type: 'string', description: 'Search query for decisions.' },
-            filePath: { type: 'string', description: 'File path context.' },
-            toolName: { type: 'string', description: 'Tool name (Edit/Write/apply_patch).' },
-            decisionLimit: { type: 'number', description: 'Max decisions (default: 5).' },
-            contractLimit: { type: 'number', description: 'Max contracts (default: 3).' },
-            similarityThreshold: {
-              type: 'number',
-              description: 'Similarity threshold (default: 0.7).',
-            },
-          },
-        },
+        name: memoryTools.search_decisions_and_contracts.name,
+        description: memoryTools.search_decisions_and_contracts.description,
+        inputSchema: memoryTools.search_decisions_and_contracts.inputSchema,
+      },
+      // 5. CASE_TIMELINE_RANGE — Phase 3 case timeline RPC (defined in src/tools/)
+      {
+        name: memoryTools.case_timeline_range.name,
+        description: memoryTools.case_timeline_range.description,
+        inputSchema: memoryTools.case_timeline_range.inputSchema,
       },
     ];
 
@@ -516,14 +541,39 @@ After failure → save a NEW decision with same topic to create evolution histor
    * Handle unified search (decisions + checkpoints)
    */
   async handleSearch(args) {
-    const { query, type = 'all', limit = 10, scopes } = args;
+    const {
+      query,
+      type = 'all',
+      limit = 10,
+      scopes,
+      threshold,
+      strict,
+      strictness,
+      disableRecency,
+      includeRelated,
+      topicPrefix,
+      minLexicalSupport,
+      diagnostics,
+    } = args;
 
-    // type='checkpoint' without query → load latest checkpoint (resume session)
+    // type='checkpoint' without query → load latest checkpoint (resume session).
+    // load_checkpoint does not yet honor scopes, so reject scoped checkpoint reads
+    // explicitly rather than silently bypass scope isolation.
     if (type === 'checkpoint' && !query) {
+      if (Array.isArray(scopes) && scopes.length > 0) {
+        return {
+          success: false,
+          code: 'scoped_checkpoint_unsupported',
+          count: 0,
+          results: [],
+          message: 'Scoped checkpoint reads are not supported yet',
+        };
+      }
       return await memoryTools.load_checkpoint.handler(args);
     }
 
     const results = [];
+    let searchDiagnostics;
 
     // Search decisions
     if (type === 'all' || type === 'decision') {
@@ -532,8 +582,52 @@ After failure → save a NEW decision with same topic to create evolution histor
         const suggestResult = await mama.suggest(query, {
           limit,
           ...(scopes && { scopes }),
+          ...(threshold !== undefined && { threshold }),
+          ...(strict !== undefined && { strict }),
+          ...(strictness !== undefined && { strictness }),
+          ...(disableRecency !== undefined && { disableRecency }),
+          ...(includeRelated !== undefined && { includeRelated }),
+          ...(topicPrefix !== undefined && { topicPrefix }),
+          ...(minLexicalSupport !== undefined && { minLexicalSupport }),
+          ...(diagnostics !== undefined && { diagnostics }),
         });
-        decisions = suggestResult?.results || [];
+        // Preserve the failure signal — collapsing a null/invalid suggest
+        // response to [] would make callers unable to distinguish "no matches"
+        // from "search pipeline failed". Mirror the standalone handler's
+        // suggest_returned_null code so behavior stays consistent across
+        // transports.
+        if (!suggestResult || typeof suggestResult !== 'object') {
+          return {
+            success: false,
+            code: 'suggest_returned_null',
+            count: 0,
+            results: [],
+            message: 'Search failed: suggest() returned no result for query',
+          };
+        }
+        // Forward explicit { success: false, code, error } failures from
+        // mama.suggest() unchanged so callers see the real cause instead of
+        // a synthetic empty success.
+        if (suggestResult.success === false) {
+          const hasOwn = Object.prototype.hasOwnProperty;
+          const forwarded = {
+            ...suggestResult,
+            success: false,
+            code: suggestResult.code || 'suggest_failed',
+          };
+          if (!hasOwn.call(forwarded, 'count')) {
+            forwarded.count = 0;
+          }
+          if (!hasOwn.call(forwarded, 'results')) {
+            forwarded.results = [];
+          }
+          if (!hasOwn.call(forwarded, 'message')) {
+            forwarded.message = suggestResult.error || 'Search pipeline failed';
+          }
+          return forwarded;
+        }
+        searchDiagnostics = suggestResult.diagnostics;
+        decisions = Array.isArray(suggestResult.results) ? suggestResult.results : [];
       } else {
         decisions = await mama.list({ limit, ...(scopes && { scopes }) });
       }
@@ -547,8 +641,25 @@ After failure → save a NEW decision with same topic to create evolution histor
       }
     }
 
+    // mama.listCheckpoints() does not yet honor the scopes filter, so any
+    // checkpoint read with scopes provided would silently bypass scope
+    // isolation. Reject explicitly when the caller requested scopes — for
+    // type='checkpoint' this fails the whole search; for type='all' we let
+    // decisions (which DO honor scopes via mama.suggest/list) return alone
+    // and skip the checkpoint blocks below.
+    const checkpointReadsBlockedByScope = Array.isArray(scopes) && scopes.length > 0;
+    if (checkpointReadsBlockedByScope && type === 'checkpoint') {
+      return {
+        success: false,
+        code: 'scoped_checkpoint_unsupported',
+        count: 0,
+        results: [],
+        message: 'Scoped checkpoint reads are not supported yet',
+      };
+    }
+
     // Search checkpoints (with query = search, without = handled above as load)
-    if ((type === 'all' || type === 'checkpoint') && query) {
+    if ((type === 'all' || type === 'checkpoint') && query && !checkpointReadsBlockedByScope) {
       const checkpoints = await mama.listCheckpoints(limit);
       results.push(
         ...checkpoints
@@ -564,7 +675,7 @@ After failure → save a NEW decision with same topic to create evolution histor
     }
 
     // type='all' without query — include recent checkpoints
-    if (type === 'all' && !query) {
+    if (type === 'all' && !query && !checkpointReadsBlockedByScope) {
       const checkpoints = await mama.listCheckpoints(limit);
       results.push(
         ...checkpoints.map((c) => ({
@@ -587,76 +698,10 @@ After failure → save a NEW decision with same topic to create evolution histor
 
     return {
       success: true,
+      ...(query ? { query } : {}),
       count: limited.length,
       results: limited,
-    };
-  }
-
-  /**
-   * Handle PreToolUse search for decisions + contracts
-   */
-  async handleSearchDecisionsAndContracts(args = {}) {
-    const {
-      query = '',
-      filePath = '',
-      toolName = '',
-      decisionLimit = 5,
-      contractLimit = 3,
-      similarityThreshold = 0.7,
-    } = args;
-
-    await initDB();
-
-    let decisionResults = [];
-    let contractResults = [];
-
-    // Decision search
-    if (decisionLimit > 0 && query) {
-      try {
-        const queryEmbedding = await generateEmbedding(query);
-        const results = await vectorSearch(queryEmbedding, decisionLimit, similarityThreshold);
-        if (Array.isArray(results)) {
-          decisionResults = results.slice(0, decisionLimit);
-        }
-      } catch (err) {
-        console.error('[MAMA MCP] Decision search failed:', err.message);
-      }
-    }
-
-    // Contract search (file-specific)
-    const contractTools = ['Edit', 'Write', 'apply_patch'];
-    const codeExtensions = ['.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java'];
-    const ext = filePath ? path.extname(filePath) : '';
-
-    if (
-      contractLimit > 0 &&
-      filePath &&
-      contractTools.includes(toolName) &&
-      codeExtensions.includes(ext)
-    ) {
-      const basename = path.basename(filePath, ext);
-      const keywords = basename.split(/[-_]/).filter(Boolean);
-      const contractQuery = `contract api ${keywords.join(' ')}`.trim();
-
-      if (contractQuery) {
-        try {
-          const contractEmbedding = await generateEmbedding(contractQuery);
-          const contractMatches = await vectorSearch(contractEmbedding, 10, similarityThreshold);
-          if (Array.isArray(contractMatches)) {
-            contractResults = contractMatches
-              .filter((r) => r.topic && r.topic.startsWith('contract_'))
-              .slice(0, contractLimit);
-          }
-        } catch (err) {
-          console.error('[MAMA MCP] Contract search failed:', err.message);
-        }
-      }
-    }
-
-    return {
-      success: true,
-      decisionResults,
-      contractResults,
+      ...(searchDiagnostics !== undefined ? { diagnostics: searchDiagnostics } : {}),
     };
   }
 

package/src/tools/case-timeline-range.js

@@ -0,0 +1,77 @@
+/**
+ * MCP Tool: case_timeline_range
+ *
+ * Thin MCP wrapper around mama-core caseTimelineRange().
+ */
+
+const { caseTimelineRange } = require('@jungjaehoon/mama-core');
+const { initDB, getAdapter } = require('@jungjaehoon/mama-core/db-manager');
+
+let adapterOverrideForTest = null;
+
+const caseTimelineRangeTool = {
+  name: 'case_timeline_range',
+  description:
+    'Return a bounded, chronological timeline for a case. Includes decision, event, observation, and artifact memberships resolved through canonical case chains.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      case_id: {
+        type: 'string',
+        description: 'Case UUID to read. Merged cases resolve through their canonical case chain.',
+      },
+      from: {
+        oneOf: [{ type: 'string' }, { type: 'number' }],
+        description: 'Optional inclusive lower date bound. ISO 8601 string or epoch milliseconds.',
+      },
+      to: {
+        oneOf: [{ type: 'string' }, { type: 'number' }],
+        description: 'Optional inclusive upper date bound. ISO 8601 string or epoch milliseconds.',
+      },
+      order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+        description: "Timeline order. Default: 'asc'.",
+      },
+      limit: {
+        type: 'number',
+        minimum: 0,
+        maximum: 500,
+        description: 'Maximum items to return. Default: 100. Maximum: 500.',
+      },
+      include_connector_enrichments: {
+        type: 'boolean',
+        description: 'Include connector event snapshots for observations/artifacts when available.',
+      },
+    },
+    required: ['case_id'],
+  },
+
+  async handler(args) {
+    const adapter = await getCaseTimelineRangeAdapter();
+    return caseTimelineRange(adapter, args || {});
+  },
+};
+
+async function getCaseTimelineRangeAdapter() {
+  if (adapterOverrideForTest) {
+    return adapterOverrideForTest;
+  }
+
+  await initDB();
+  return getAdapter();
+}
+
+function setCaseTimelineRangeAdapterForTest(adapter) {
+  adapterOverrideForTest = adapter;
+}
+
+function resetCaseTimelineRangeAdapterForTest() {
+  adapterOverrideForTest = null;
+}
+
+module.exports = {
+  caseTimelineRangeTool,
+  setCaseTimelineRangeAdapterForTest,
+  resetCaseTimelineRangeAdapterForTest,
+};

package/src/tools/index.js

@@ -16,6 +16,7 @@
  * - 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 ✅
+ * - case_timeline_range: Read bounded case timeline ranges ✅
  *
  * @module tools
  */
@@ -29,6 +30,8 @@ const { saveCheckpointTool, loadCheckpointTool } = require('./checkpoint-tools.j
 const { searchNarrativeTool } = require('./search-narrative.js');
 const { generateQualityReportTool, getRestartMetricsTool } = require('./quality-metrics-tools.js');
 const { ingestConversationTool } = require('./ingest-conversation.js');
+const { searchDecisionsAndContractsTool } = require('./search-decisions-and-contracts.js');
+const { caseTimelineRangeTool } = require('./case-timeline-range.js');
 
 /**
  * Create all MAMA memory tools
@@ -50,6 +53,8 @@ function createMemoryTools() {
     generate_quality_report: generateQualityReportTool,
     get_restart_metrics: getRestartMetricsTool,
     ingest_conversation: ingestConversationTool,
+    search_decisions_and_contracts: searchDecisionsAndContractsTool,
+    case_timeline_range: caseTimelineRangeTool,
   };
 }
 
@@ -67,4 +72,6 @@ module.exports = {
   generateQualityReportTool,
   getRestartMetricsTool,
   ingestConversationTool,
+  searchDecisionsAndContractsTool,
+  caseTimelineRangeTool,
 };

package/src/tools/search-decisions-and-contracts.js

@@ -0,0 +1,109 @@
+/**
+ * MCP Tool: search_decisions_and_contracts
+ *
+ * PreToolUse hook RPC — searches decisions and contract-specific memories
+ * for file-aware context injection before Edit/Write/apply_patch tool calls.
+ *
+ * @module search-decisions-and-contracts
+ */
+
+const path = require('path');
+const { initDB } = require('@jungjaehoon/mama-core/db-manager');
+const { generateEmbedding } = require('@jungjaehoon/mama-core/embeddings');
+const { vectorSearch } = require('@jungjaehoon/mama-core/memory-store');
+
+/**
+ * search_decisions_and_contracts tool definition
+ */
+const searchDecisionsAndContractsTool = {
+  name: 'search_decisions_and_contracts',
+  description: 'Search decisions and contracts for PreToolUse hook injection.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query for decisions.' },
+      filePath: { type: 'string', description: 'File path context.' },
+      toolName: { type: 'string', description: 'Tool name (Edit/Write/apply_patch).' },
+      decisionLimit: { type: 'number', description: 'Max decisions (default: 5).' },
+      contractLimit: { type: 'number', description: 'Max contracts (default: 3).' },
+      similarityThreshold: {
+        type: 'number',
+        description: 'Similarity threshold (default: 0.7).',
+      },
+    },
+  },
+
+  async handler(args = {}) {
+    try {
+      const {
+        query = '',
+        filePath = '',
+        toolName = '',
+        decisionLimit = 5,
+        contractLimit = 3,
+        similarityThreshold = 0.7,
+      } = args;
+
+      await initDB();
+
+      let decisionResults = [];
+      let contractResults = [];
+
+      // Decision search
+      if (decisionLimit > 0 && query) {
+        try {
+          const queryEmbedding = await generateEmbedding(query);
+          const results = await vectorSearch(queryEmbedding, decisionLimit, similarityThreshold);
+          if (Array.isArray(results)) {
+            decisionResults = results.slice(0, decisionLimit);
+          }
+        } catch (err) {
+          console.error('[MAMA MCP] Decision search failed:', err.message);
+        }
+      }
+
+      // Contract search (file-specific)
+      const contractTools = ['Edit', 'Write', 'apply_patch'];
+      const codeExtensions = ['.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java'];
+      const ext = filePath ? path.extname(filePath) : '';
+
+      if (
+        contractLimit > 0 &&
+        filePath &&
+        contractTools.includes(toolName) &&
+        codeExtensions.includes(ext)
+      ) {
+        const basename = path.basename(filePath, ext);
+        const keywords = basename.split(/[-_]/).filter(Boolean);
+        const contractQuery = `contract api ${keywords.join(' ')}`.trim();
+
+        if (contractQuery) {
+          try {
+            const contractEmbedding = await generateEmbedding(contractQuery);
+            const contractMatches = await vectorSearch(contractEmbedding, 10, similarityThreshold);
+            if (Array.isArray(contractMatches)) {
+              contractResults = contractMatches
+                .filter((r) => r.topic && r.topic.startsWith('contract_'))
+                .slice(0, contractLimit);
+            }
+          } catch (err) {
+            console.error('[MAMA MCP] Contract search failed:', err.message);
+          }
+        }
+      }
+
+      return {
+        success: true,
+        decisionResults,
+        contractResults,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  },
+};
+
+module.exports = { searchDecisionsAndContractsTool };