@shodh/memory-mcp 0.1.80 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Shodh-Memory MCP Server</h1>
 
 <p align="center">
-  <strong>v0.1.70</strong> | Persistent cognitive memory for AI agents
+  <strong>v0.1.90</strong> | Persistent cognitive memory for AI agents
 </p>
 
 <p align="center">
@@ -29,9 +29,11 @@
 - **Semantic Search**: Find memories by meaning using MiniLM-L6 embeddings
 - **Knowledge Graph**: Entity extraction and relationship tracking
 - **Memory Consolidation**: Automatic decay, replay, and strengthening
+- **Idempotent**: Content-hash dedup — identical memories are never stored twice
 - **1-Click Install**: Auto-downloads native server binary for your platform
 - **Offline-First**: All models auto-downloaded on first run (~38MB total), no internet required after
-- **Fast**: Sub-millisecond graph lookup, 30-50ms semantic search
+- **Fast**: <200ms API response, sub-millisecond graph lookup, 30-50ms semantic search
+- **GTD Task Management**: Full todo system with projects, subtasks, comments, and reminders
 
 ## Installation
 
@@ -81,25 +83,80 @@ env = { SHODH_API_KEY = "your-api-key-here" }
 | `SHODH_STREAM` | Enable/disable streaming ingestion | `true` |
 | `SHODH_PROACTIVE` | Enable/disable proactive memory surfacing | `true` |
 
-## MCP Tools (15 total)
+## MCP Tools (47 total)
+
+<details>
+<summary><b>Memory</b> — Store, search, and manage memories</summary>
 
 | Tool | Description |
 |------|-------------|
-| `remember` | Store a memory with optional type and tags |
+| `remember` | Store a memory with optional type, tags, and metadata |
 | `recall` | Semantic search to find relevant memories |
 | `proactive_context` | Auto-surface relevant memories for current context |
 | `context_summary` | Get categorized context for session bootstrap |
 | `list_memories` | List all stored memories |
+| `read_memory` | Read full content of a specific memory by ID |
 | `forget` | Delete a specific memory by ID |
-| `forget_by_tags` | Delete memories matching any of the specified tags |
-| `forget_by_date` | Delete memories within a date range |
+| `reinforce` | Reinforce a memory (boost importance) |
+</details>
+
+<details>
+<summary><b>Todos (GTD)</b> — Task management with projects and subtasks</summary>
+
+| Tool | Description |
+|------|-------------|
+| `add_todo` | Create a task with priority, due date, project, contexts |
+| `list_todos` | List/search todos with semantic or GTD-style filtering |
+| `update_todo` | Update task properties (status, priority, notes) |
+| `complete_todo` | Mark a task as done (auto-creates next for recurring) |
+| `delete_todo` | Permanently delete a task |
+| `reorder_todo` | Move a task up or down within its status group |
+| `list_subtasks` | List subtasks of a parent todo |
+| `add_todo_comment` | Add a comment to a task (progress, resolution) |
+| `list_todo_comments` | List all comments on a task |
+| `update_todo_comment` | Edit an existing comment |
+| `delete_todo_comment` | Delete a comment |
+| `todo_stats` | Get todo statistics by status, overdue items |
+</details>
+
+<details>
+<summary><b>Projects</b> — Organize todos into groups</summary>
+
+| Tool | Description |
+|------|-------------|
+| `add_project` | Create a project with optional parent (sub-projects) |
+| `list_projects` | List all projects with todo counts |
+| `archive_project` | Archive a project (hidden but restorable) |
+| `delete_project` | Permanently delete a project |
+</details>
+
+<details>
+<summary><b>Reminders</b> — Time, duration, and context-triggered reminders</summary>
+
+| Tool | Description |
+|------|-------------|
+| `set_reminder` | Set a reminder (time, duration, or keyword trigger) |
+| `list_reminders` | List pending/triggered/dismissed reminders |
+| `dismiss_reminder` | Acknowledge a triggered reminder |
+</details>
+
+<details>
+<summary><b>System</b> — Health, backups, and diagnostics</summary>
+
+| Tool | Description |
+|------|-------------|
 | `memory_stats` | Get statistics about stored memories |
-| `recall_by_tags` | Find memories by tag |
-| `recall_by_date` | Find memories within a date range |
-| `verify_index` | Check vector index health |
-| `repair_index` | Repair orphaned memories |
+| `verify_index` | Check vector index integrity |
+| `repair_index` | Re-index orphaned memories |
+| `token_status` | Get current session token usage |
+| `reset_token_session` | Reset token counter for new session |
 | `consolidation_report` | View memory consolidation activity |
-| `streaming_status` | Check WebSocket streaming connection status |
+| `backup_create` | Create a backup of all memories |
+| `backup_list` | List available backups |
+| `backup_verify` | Verify backup integrity (SHA-256) |
+| `backup_restore` | Restore from a backup |
+| `backup_purge` | Purge old backups, keep most recent N |
+</details>
 
 ## REST API (for Developers)
 

package/dist/index.js

@@ -4881,28 +4881,125 @@ class StdioServerTransport {
 import { spawn } from "child_process";
 import * as path from "path";
 import * as fs from "fs";
+import * as crypto from "crypto";
 import { fileURLToPath } from "url";
-var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path.dirname(__filename2);
-var API_URL = process.env.SHODH_API_URL || "http://127.0.0.1:3030";
+
+// security-utils.ts
+function isLocalHostFromUrl(apiUrl) {
+  try {
+    const url = new URL(apiUrl);
+    const host = url.hostname;
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+function shouldWarnInsecureApiUrl(apiUrl, allowHttpEnv) {
+  return !isLocalHostFromUrl(apiUrl) && apiUrl.startsWith("http://") && allowHttpEnv !== "true";
+}
+function serializeAndValidateBody(body, maxLength) {
+  const serialized = JSON.stringify(body);
+  if (serialized.length > maxLength) {
+    return { ok: false, error: `Request body exceeds maximum length of ${maxLength} characters` };
+  }
+  return { ok: true, serialized };
+}
+function nextReconnectDelay(currentDelayMs, maxDelayMs) {
+  const safeCurrent = Math.max(currentDelayMs, 1000);
+  return Math.min(safeCurrent * 2, maxDelayMs);
+}
+
+// string-utils.ts
+function stripSystemNoise(text) {
+  let result = text;
+  const tagPatterns = [
+    /<task-notification>[\s\S]*?<\/task-notification>/g,
+    /<system-reminder>[\s\S]*?<\/system-reminder>/g,
+    /<shodh-context[\s\S]*?<\/shodh-context>/g,
+    /<shodh-memory[\s\S]*?<\/shodh-memory>/g,
+    /<command-name>[\s\S]*?<\/command-name>/g
+  ];
+  for (const pattern of tagPatterns) {
+    result = result.replace(pattern, "");
+  }
+  result = result.replace(/\s{3,}/g, " ").trim();
+  return result;
+}
+
+// index.ts
+var __filename2 = typeof import.meta !== "undefined" && import.meta.url ? fileURLToPath(import.meta.url) : "";
+var __dirname2 = __filename2 ? path.dirname(__filename2) : process.cwd();
+function resolveApiUrl() {
+  if (process.env.SHODH_API_URL)
+    return process.env.SHODH_API_URL;
+  const host = process.env.SHODH_HOST;
+  const port = process.env.SHODH_PORT;
+  if (host) {
+    const scheme = port === "443" ? "https" : "http";
+    const portSuffix = port && port !== "443" && port !== "80" ? `:${port}` : "";
+    return `${scheme}://${host}${portSuffix}`;
+  }
+  if (port)
+    return `http://127.0.0.1:${port}`;
+  return "http://127.0.0.1:3030";
+}
+var API_URL = resolveApiUrl();
 var WS_URL = API_URL.replace(/^http/, "ws") + "/api/stream";
 var USER_ID = process.env.SHODH_USER_ID || "claude-code";
-var API_KEY = process.env.SHODH_API_KEY;
+function isLocalServer() {
+  try {
+    const url = new URL(API_URL);
+    const host = url.hostname;
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+var SANDBOX_MODE = process.env.SMITHERY_SANDBOX === "true";
+var API_KEY = "";
+var apiKeySource = "";
+if (process.env.SHODH_API_KEY) {
+  API_KEY = process.env.SHODH_API_KEY;
+  apiKeySource = "SHODH_API_KEY";
+} else if (process.env.SHODH_DEV_API_KEY) {
+  API_KEY = process.env.SHODH_DEV_API_KEY;
+  apiKeySource = "SHODH_DEV_API_KEY";
+} else if (process.env.SHODH_API_KEYS?.split(",")[0]?.trim()) {
+  API_KEY = process.env.SHODH_API_KEYS.split(",")[0].trim();
+  apiKeySource = "SHODH_API_KEYS";
+} else if (SANDBOX_MODE) {
+  API_KEY = "sandbox";
+  apiKeySource = "sandbox";
+}
 if (!API_KEY) {
-  console.error("ERROR: SHODH_API_KEY environment variable not set.");
-  console.error("");
-  console.error("To fix, add to your MCP config (claude_desktop_config.json or mcp.json):");
-  console.error(`  "env": { "SHODH_API_KEY": "your-api-key" }`);
-  console.error("");
-  console.error("Or set in your shell:");
-  console.error("  export SHODH_API_KEY=your-api-key");
-  console.error("");
-  console.error("For local development, use the same key set in SHODH_DEV_API_KEY on the server.");
-  process.exit(1);
+  if (isLocalServer()) {
+    API_KEY = crypto.randomBytes(32).toString("hex");
+    apiKeySource = "auto-generated";
+    console.error("[shodh-memory] No API key set — auto-generated for local server.");
+  } else {
+    console.error("ERROR: SHODH_API_KEY is required for remote servers.");
+    console.error("");
+    console.error("To fix, add to your MCP config (claude_desktop_config.json or mcp.json):");
+    console.error(`  "env": { "SHODH_API_KEY": "your-api-key" }`);
+    console.error("");
+    console.error("Or set in your shell:");
+    console.error("  export SHODH_API_KEY=your-api-key");
+    process.exit(1);
+  }
+}
+if (apiKeySource === "SHODH_DEV_API_KEY") {
+  console.error("[shodh-memory] WARNING: API key loaded from SHODH_DEV_API_KEY — this is a development key. Use SHODH_API_KEY for production.");
+} else if (apiKeySource && apiKeySource !== "auto-generated" && apiKeySource !== "sandbox") {
+  console.error(`[shodh-memory] API key loaded from ${apiKeySource}.`);
 }
 var RETRY_ATTEMPTS = 3;
 var RETRY_DELAY_MS = 1000;
 var REQUEST_TIMEOUT_MS = 1e4;
+var WRITE_TIMEOUT_MS = 30000;
+if (shouldWarnInsecureApiUrl(API_URL, process.env.SHODH_ALLOW_HTTP)) {
+  console.error("[shodh-memory] WARNING: Using HTTP for a non-localhost server is insecure.");
+  console.error("[shodh-memory] Set SHODH_API_URL to an https:// URL, or set SHODH_ALLOW_HTTP=true to suppress this warning.");
+}
 var MAX_CONTENT_LENGTH = 1e5;
 var MAX_QUERY_LENGTH = 1e4;
 var MAX_LIMIT = 250;
@@ -4930,10 +5027,15 @@ var STREAM_ENABLED = process.env.SHODH_STREAM !== "false";
 var STREAM_MIN_CONTENT_LENGTH = 50;
 var PROACTIVE_SURFACING = process.env.SHODH_PROACTIVE !== "false";
 var PROACTIVE_MIN_CONTEXT_LENGTH = 30;
+var MAX_CONTEXT_LENGTH = 4000;
 var lastProactiveResponse = "";
+var lastUserContext = "";
+var proactiveCallInFlight = false;
 var streamSocket = null;
 var streamConnecting = false;
 var streamReconnectTimer = null;
+var streamReconnectDelay = 1000;
+var STREAM_RECONNECT_MAX_DELAY = 60000;
 var streamBuffer = [];
 var MAX_BUFFER_SIZE = 100;
 var streamHandshakeComplete = false;
@@ -4944,9 +5046,15 @@ async function connectStream() {
   streamConnecting = true;
   streamHandshakeComplete = false;
   try {
-    streamSocket = new WebSocket(WS_URL);
+    const wsUrlWithAuth = WS_URL + (WS_URL.includes("?") ? "&" : "?") + "api_key=" + encodeURIComponent(API_KEY);
+    streamSocket = new WebSocket(wsUrlWithAuth, {
+      headers: {
+        "X-API-Key": API_KEY
+      }
+    });
     streamSocket.onopen = () => {
       streamConnecting = false;
+      streamReconnectDelay = 1000;
       console.error("[Stream] WebSocket connected to", WS_URL);
       const handshake = JSON.stringify({
         user_id: USER_ID,
@@ -4988,11 +5096,13 @@ async function connectStream() {
       streamConnecting = false;
       streamHandshakeComplete = false;
       if (STREAM_ENABLED && !streamReconnectTimer) {
+        const delay = streamReconnectDelay;
+        streamReconnectDelay = nextReconnectDelay(streamReconnectDelay, STREAM_RECONNECT_MAX_DELAY);
         streamReconnectTimer = setTimeout(() => {
           streamReconnectTimer = null;
-          console.error("[Stream] Attempting reconnect...");
+          console.error(`[Stream] Attempting reconnect (next delay: ${streamReconnectDelay}ms)...`);
           connectStream().catch((e) => console.error("[Stream] Reconnect failed:", e));
-        }, 5000);
+        }, delay);
       }
     };
     streamSocket.onerror = (error) => {
@@ -5063,10 +5173,12 @@ async function surfaceRelevant(context, maxResults = 3) {
       }),
       signal: controller.signal
     });
-    clearTimeout(timeoutId);
-    if (!response.ok)
+    if (!response.ok) {
+      clearTimeout(timeoutId);
       return null;
+    }
     const result = await response.json();
+    clearTimeout(timeoutId);
     return result.memories || null;
   } catch (e) {
     console.error("[Proactive] Failed to surface memories:", e);
@@ -5076,7 +5188,7 @@ async function surfaceRelevant(context, maxResults = 3) {
 function formatSurfacedMemories(memories) {
   if (!memories || memories.length === 0)
     return "";
-  const formatted = memories.map((m, i) => `  ${i + 1}. [${(m.relevance_score * 100).toFixed(0)}%] ${m.content.slice(0, 80)}...`).join(`
+  const formatted = memories.map((m, i) => `  ${i + 1}. [${((m.relevance_score ?? 0) * 100).toFixed(0)}%] ${m.content.slice(0, 80)}...`).join(`
 `);
   return `
 
@@ -5097,7 +5209,8 @@ async function apiCall(endpoint, method = "GET", body) {
   for (let attempt = 1;attempt <= RETRY_ATTEMPTS; attempt++) {
     try {
       const controller = new AbortController;
-      const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      const timeout = method === "GET" ? REQUEST_TIMEOUT_MS : WRITE_TIMEOUT_MS;
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
       const options = {
         method,
         headers: {
@@ -5107,7 +5220,11 @@ async function apiCall(endpoint, method = "GET", body) {
         signal: controller.signal
       };
       if (body) {
-        options.body = JSON.stringify(body);
+        const bodyValidation = serializeAndValidateBody(body, MAX_CONTENT_LENGTH);
+        if (!bodyValidation.ok) {
+          throw new Error(bodyValidation.error);
+        }
+        options.body = bodyValidation.serialized;
       }
       const response = await fetch(`${API_URL}${endpoint}`, options);
       clearTimeout(timeoutId);
@@ -5115,10 +5232,15 @@ async function apiCall(endpoint, method = "GET", body) {
         const errorText = await response.text().catch(() => "Unknown error");
         throw new Error(`API error ${response.status}: ${errorText}`);
       }
-      return await response.json();
+      try {
+        return await response.json();
+      } catch {
+        throw new Error(`API returned invalid JSON from ${endpoint}`);
+      }
     } catch (error) {
       lastError = error instanceof Error ? error : new Error(String(error));
-      if (lastError.message.includes("API error 4")) {
+      const statusMatch = lastError.message.match(/API error (\d+)/);
+      if (statusMatch && parseInt(statusMatch[1], 10) >= 400 && parseInt(statusMatch[1], 10) < 500) {
         throw lastError;
       }
       if (attempt < RETRY_ATTEMPTS) {
@@ -5148,7 +5270,7 @@ async function isServerAvailable() {
 }
 var server = new Server({
   name: "shodh-memory",
-  version: "0.1.61"
+  version: "0.1.90"
 }, {
   capabilities: {
     tools: {},
@@ -5220,6 +5342,57 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             parent_id: {
               type: "string",
               description: "Parent memory ID for hierarchical organization. Creates memory trees (e.g., '71-research' -> 'algebraic' -> '21×27≡-1')"
+            },
+            importance: {
+              type: "number",
+              description: "Optional importance override (0.0-1.0). Bypasses auto-calculation. Use for memories where importance is known: Decision=0.8, Learning=0.7, Error=0.7, Discovery=0.6, Observation=0.3"
+            },
+            robot_id: {
+              type: "string",
+              description: "Robot/drone identifier for multi-robot systems"
+            },
+            mission_id: {
+              type: "string",
+              description: "Mission identifier for grouping experiences"
+            },
+            geo_location: {
+              type: "array",
+              items: { type: "number" },
+              minItems: 3,
+              maxItems: 3,
+              description: "GPS coordinates [latitude, longitude, altitude] in WGS84"
+            },
+            local_position: {
+              type: "array",
+              items: { type: "number" },
+              minItems: 3,
+              maxItems: 3,
+              description: "Local position [x, y, z] in meters (robot-local frame)"
+            },
+            heading: {
+              type: "number",
+              description: "Heading in degrees (0-360)"
+            },
+            action_type: {
+              type: "string",
+              description: "Action type name (e.g., 'navigate', 'grasp', 'dock')"
+            },
+            reward: {
+              type: "number",
+              description: "Reinforcement learning reward signal (-1.0 to 1.0)"
+            },
+            sensor_data: {
+              type: "object",
+              additionalProperties: { type: "number" },
+              description: "Raw sensor readings (e.g., {battery: 72.5, temperature: 23.1})"
+            },
+            outcome_type: {
+              type: "string",
+              description: "Outcome type: success, failure, partial, aborted, timeout"
+            },
+            terrain_type: {
+              type: "string",
+              description: "Terrain type: indoor, outdoor, urban, rural, water, aerial"
             }
           },
           required: ["content"]
@@ -5227,7 +5400,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "recall",
-        description: "Search memories AND todos using semantic similarity. Returns both relevant memories and matching todos. Use this to find past experiences, decisions, context, or pending work. Modes: 'semantic' (vector similarity), 'associative' (graph traversal), 'hybrid' (combined).",
+        description: "Search memories AND todos using semantic similarity. Returns both relevant memories and matching todos. Use this to find past experiences, decisions, context, or pending work. Modes: 'semantic' (vector similarity), 'associative' (graph traversal), 'temporal' (time-based retrieval), 'hybrid' (combined), 'spatial' (geo-location based), 'mission' (mission context), 'action_outcome' (reward-based learning).",
         inputSchema: {
           type: "object",
           properties: {
@@ -5242,14 +5415,87 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             mode: {
               type: "string",
-              enum: ["semantic", "associative", "hybrid"],
-              description: "Retrieval mode: 'semantic' for pure vector similarity, 'associative' for graph-based traversal (follows learned connections), 'hybrid' for density-dependent combination (default)",
+              enum: ["semantic", "associative", "temporal", "hybrid", "spatial", "mission", "action_outcome"],
+              description: "Retrieval mode: 'semantic' for pure vector similarity, 'associative' for graph-based traversal (follows learned connections), 'temporal' for time-based retrieval, 'hybrid' for density-dependent combination (default), 'spatial' for geo-location based, 'mission' for mission context, 'action_outcome' for reward-based learning",
               default: "hybrid"
+            },
+            session_id: {
+              type: "string",
+              description: "Session ID for session-scoped retrieval. When provided, retrieves memories from that session's time window. Forces temporal mode."
+            },
+            robot_id: {
+              type: "string",
+              description: "Filter by robot/drone identifier (for multi-robot systems)"
+            },
+            mission_id: {
+              type: "string",
+              description: "Filter by mission identifier"
+            },
+            geo_lat: {
+              type: "number",
+              description: "Spatial filter: center latitude (-90 to 90). Requires geo_lon and geo_radius_meters."
+            },
+            geo_lon: {
+              type: "number",
+              description: "Spatial filter: center longitude (-180 to 180). Requires geo_lat and geo_radius_meters."
+            },
+            geo_radius_meters: {
+              type: "number",
+              description: "Spatial filter: search radius in meters. Requires geo_lat and geo_lon."
+            },
+            action_type: {
+              type: "string",
+              description: "Filter by action type (e.g., 'navigate', 'grasp', 'dock')"
+            },
+            reward_min: {
+              type: "number",
+              description: "Filter by minimum reward value (-1.0 to 1.0)"
+            },
+            reward_max: {
+              type: "number",
+              description: "Filter by maximum reward value (-1.0 to 1.0)"
+            },
+            outcome_type: {
+              type: "string",
+              description: "Filter by outcome type: success, failure, partial, aborted, timeout"
+            },
+            failures_only: {
+              type: "boolean",
+              description: "If true, only return failure/error experiences"
+            },
+            terrain_type: {
+              type: "string",
+              description: "Filter by terrain type: indoor, outdoor, urban, rural, water, aerial"
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by tags (any match)"
             }
           },
           required: ["query"]
         }
       },
+      {
+        name: "recall_by_tags",
+        description: "Find memories by tags. Returns memories matching ANY of the provided tags. Useful for finding memories by category (e.g., 'tool:Edit', 'file:src/main.rs', 'source:hook', 'error', 'session-summary').",
+        inputSchema: {
+          type: "object",
+          properties: {
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Tags to search for (returns memories matching ANY of these tags)"
+            },
+            limit: {
+              type: "number",
+              description: "Maximum number of results (default: 50)",
+              default: 50
+            }
+          },
+          required: ["tags"]
+        }
+      },
       {
         name: "context_summary",
         description: "Get a condensed summary of recent learnings, decisions, and context. Use this at the start of a session to quickly understand what you've learned before.",
@@ -5375,6 +5621,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           }
         }
       },
+      {
+        name: "backup_restore",
+        description: "Restore a previously created backup by ID. This replaces all current data for the user with the backup contents. Server restart is recommended after restore.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            backup_id: {
+              type: "number",
+              description: "The backup ID to restore (from backup_list)"
+            }
+          },
+          required: ["backup_id"]
+        }
+      },
       {
         name: "consolidation_report",
         description: "Get a report of what the memory system has been learning. Shows memory strengthening/decay events, edge formation, fact extraction, and maintenance cycles. Use this to understand how your memories are evolving.",
@@ -5431,6 +5691,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "boolean",
               description: "Automatically store the context as a Conversation memory (default: true). Set to false to only surface memories without storing.",
               default: true
+            },
+            tool_actions: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  tool_name: { type: "string", description: "Tool or actuator name (e.g., 'Edit', 'Bash', 'navigate', 'grasp')" },
+                  inputs: { type: "object", additionalProperties: { type: "string" }, description: "Key-value input parameters" },
+                  success: { type: "boolean", description: "Whether the action succeeded" },
+                  output_snippet: { type: "string", description: "First 200 chars of output" },
+                  reward: { type: "number", description: "Reward signal for robotics (-1.0 to 1.0)" }
+                },
+                required: ["tool_name", "success"]
+              },
+              description: "Tool/actuator actions performed since last proactive_context call. Used for causal feedback attribution."
             }
           },
           required: ["context"]
@@ -5489,6 +5764,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "array",
               items: { type: "string" },
               description: "Optional tags for categorization"
+            },
+            threshold: {
+              type: "number",
+              description: "Semantic similarity threshold for 'context' trigger (0.0-1.0, default: 0.7). Lower values match more broadly, higher values require closer semantic match."
             }
           },
           required: ["content", "trigger_type"]
@@ -5964,7 +6243,18 @@ To start: cd shodh-memory && cargo run`
           episode_id,
           sequence_number,
           preceding_memory_id,
-          parent_id
+          parent_id,
+          importance,
+          robot_id,
+          mission_id,
+          geo_location,
+          local_position,
+          heading,
+          action_type,
+          reward,
+          sensor_data,
+          outcome_type,
+          terrain_type
         } = args;
         if (!content || content.length === 0) {
           return { content: [{ type: "text", text: "Error: 'content' is required and cannot be empty" }], isError: true };
@@ -5986,7 +6276,18 @@ To start: cd shodh-memory && cargo run`
           ...episode_id && { episode_id },
           ...sequence_number !== undefined && { sequence_number },
           ...preceding_memory_id && { preceding_memory_id },
-          ...parent_id && { parent_id }
+          ...parent_id && { parent_id },
+          ...importance !== undefined && { importance },
+          ...robot_id && { robot_id },
+          ...mission_id && { mission_id },
+          ...geo_location && geo_location.length === 3 && { geo_location },
+          ...local_position && local_position.length === 3 && { local_position },
+          ...heading !== undefined && { heading },
+          ...action_type && { action_type },
+          ...reward !== undefined && { reward },
+          ...sensor_data && Object.keys(sensor_data).length > 0 && { sensor_data },
+          ...outcome_type && { outcome_type },
+          ...terrain_type && { terrain_type }
         });
         let response = `\uD83D\uDC18 Memory Stored
 `;
@@ -6001,20 +6302,37 @@ To start: cd shodh-memory && cargo run`
           response += ` │ Tags: ${tags.join(", ")}`;
         }
         response += `
-ID: ${result.id.slice(0, 8)}...`;
+ID: ${result.id}`;
         return {
           content: [{ type: "text", text: response }]
         };
       }
       case "recall": {
-        const { query, limit: rawLimit = 5, mode = "hybrid" } = args;
+        const {
+          query,
+          limit: rawLimit = 5,
+          mode = "hybrid",
+          session_id,
+          robot_id,
+          mission_id,
+          geo_lat,
+          geo_lon,
+          geo_radius_meters,
+          action_type,
+          reward_min,
+          reward_max,
+          outcome_type,
+          failures_only,
+          terrain_type,
+          tags
+        } = args;
         if (!query || query.length === 0) {
           return { content: [{ type: "text", text: "Error: 'query' is required and cannot be empty" }], isError: true };
         }
         if (query.length > MAX_QUERY_LENGTH) {
           return { content: [{ type: "text", text: `Error: 'query' exceeds maximum length of ${MAX_QUERY_LENGTH} characters` }], isError: true };
         }
-        const validModes = ["semantic", "associative", "hybrid"];
+        const validModes = ["semantic", "associative", "temporal", "hybrid", "spatial", "mission", "action_outcome"];
         if (!validModes.includes(mode)) {
           return { content: [{ type: "text", text: `Error: 'mode' must be one of: ${validModes.join(", ")}` }], isError: true };
         }
@@ -6023,11 +6341,25 @@ ID: ${result.id.slice(0, 8)}...`;
           user_id: USER_ID,
           query,
           limit,
-          mode
+          mode,
+          ...session_id ? { session_id } : {},
+          ...robot_id ? { robot_id } : {},
+          ...mission_id ? { mission_id } : {},
+          ...geo_lat !== undefined ? { geo_lat } : {},
+          ...geo_lon !== undefined ? { geo_lon } : {},
+          ...geo_radius_meters !== undefined ? { geo_radius_meters } : {},
+          ...action_type ? { action_type } : {},
+          ...reward_min !== undefined ? { reward_min } : {},
+          ...reward_max !== undefined ? { reward_max } : {},
+          ...outcome_type ? { outcome_type } : {},
+          ...failures_only !== undefined ? { failures_only } : {},
+          ...terrain_type ? { terrain_type } : {},
+          ...tags && tags.length > 0 ? { tags } : {}
         });
         const memories = result.memories || [];
         const todos = result.todos || [];
         const stats = result.retrieval_stats;
+        const lineage = result.lineage || [];
         if (memories.length === 0 && todos.length === 0) {
           return {
             content: [
@@ -6070,21 +6402,24 @@ ID: ${result.id.slice(0, 8)}...`;
             return d.toLocaleDateString([], { month: "short", day: "numeric" });
           }
         };
+        const memoryDisplayScores = memories.map((m) => m.score || 0);
+        const todoDisplayScores = todos.map((t) => t.score || 0);
         if (memories.length > 0) {
           response += `\uD83D\uDCDD MEMORIES
 `;
           for (let i = 0;i < memories.length; i++) {
             const m = memories[i];
             const content = getContent(m);
-            const score = ((m.score || 0) * 100).toFixed(0);
-            const filled = Math.max(0, Math.min(10, Math.round((m.score || 0) * 10)));
+            const displayScore = memoryDisplayScores[i];
+            const score = (displayScore * 100).toFixed(0);
+            const filled = Math.max(0, Math.min(10, Math.round(displayScore * 10)));
             const matchBar = "█".repeat(filled) + "░".repeat(10 - filled);
             const timeStr = formatTime(m.created_at);
             response += `• ${matchBar} ${score}% │ ${timeStr}
 `;
             response += `  ${content.slice(0, 200)}${content.length > 200 ? "..." : ""}
 `;
-            response += `  ┗━ ${getType(m)}${m.tier ? ` │ ${m.tier}` : ""} │ ${m.id.slice(0, 8)}...
+            response += `  ┗━ ${getType(m)}${m.tier ? ` │ ${m.tier}` : ""} │ ${m.id}
 `;
             if (i < memories.length - 1)
               response += `
@@ -6099,8 +6434,9 @@ ID: ${result.id.slice(0, 8)}...`;
 `;
           for (let i = 0;i < todos.length; i++) {
             const t = todos[i];
-            const score = ((t.score || 0) * 100).toFixed(0);
-            const filled = Math.max(0, Math.min(10, Math.round((t.score || 0) * 10)));
+            const displayScore = todoDisplayScores[i];
+            const score = (displayScore * 100).toFixed(0);
+            const filled = Math.max(0, Math.min(10, Math.round(displayScore * 10)));
             const matchBar = "█".repeat(filled) + "░".repeat(10 - filled);
             const statusIcon = t.status === "done" ? "✓" : t.status === "in_progress" ? "▶" : t.status === "blocked" ? "⊗" : "○";
             const timeStr = formatTime(t.created_at);
@@ -6126,16 +6462,79 @@ ID: ${result.id.slice(0, 8)}...`;
 `;
           const graphPct = (stats.graph_weight * 100).toFixed(0);
           const semPct = (stats.semantic_weight * 100).toFixed(0);
-          response += `   Graph: ${graphPct}% │ Semantic: ${semPct}% │ Density: ${stats.graph_density.toFixed(2)}
+          response += `   Graph: ${graphPct}% │ Semantic: ${semPct}% │ Density: ${(stats.graph_density ?? 0).toFixed(2)}
 `;
           response += `   Candidates: ${stats.graph_candidates} graph + ${stats.semantic_candidates} semantic
 `;
           response += `   Entities: ${stats.entities_activated} │ Time: ${(stats.retrieval_time_us / 1000).toFixed(1)}ms`;
         }
+        if (lineage.length > 0) {
+          const idShort = (id) => id;
+          const idToContent = new Map;
+          for (const m of memories) {
+            idToContent.set(m.id, getContent(m).slice(0, 40));
+          }
+          response += `
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+          response += `\uD83D\uDD17 LINEAGE (${lineage.length} causal edge${lineage.length > 1 ? "s" : ""})
+`;
+          for (const edge of lineage) {
+            const fromLabel = idToContent.get(edge.from) || idShort(edge.from);
+            const toLabel = idToContent.get(edge.to) || idShort(edge.to);
+            const conf = (edge.confidence * 100).toFixed(0);
+            response += `  ${idShort(edge.from)} ──${edge.relation}──▶ ${idShort(edge.to)}  (${conf}%)
+`;
+            response += `    "${fromLabel}..." → "${toLabel}..."
+`;
+          }
+        }
         return {
           content: [{ type: "text", text: response }]
         };
       }
+      case "recall_by_tags": {
+        const { tags, limit: rawTagLimit = 50 } = args;
+        if (!tags || tags.length === 0) {
+          return {
+            content: [{ type: "text", text: "Error: 'tags' is required and must contain at least one tag" }],
+            isError: true
+          };
+        }
+        const tagLimit = Math.max(1, Math.min(Math.floor(rawTagLimit), MAX_LIMIT));
+        const tagResult = await apiCall("/api/recall/tags", "POST", {
+          user_id: USER_ID,
+          tags,
+          limit: tagLimit
+        });
+        const tagMemories = tagResult.memories || [];
+        if (tagMemories.length === 0) {
+          return {
+            content: [{ type: "text", text: `No memories found matching tags: ${tags.join(", ")}` }]
+          };
+        }
+        let tagResponse = `\uD83C\uDFF7️ Recall by Tags: ${tags.join(", ")}
+`;
+        tagResponse += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+        tagResponse += `Found ${tagMemories.length} memories
+
+`;
+        for (let i = 0;i < tagMemories.length; i++) {
+          const m = tagMemories[i];
+          const content = getContent(m);
+          const memTags = (m.experience?.tags || []).join(", ");
+          tagResponse += `${String(i + 1).padStart(2)}. ${content.slice(0, 150)}${content.length > 150 ? "..." : ""}
+`;
+          tagResponse += `    ┗━ ${getType(m)} │ tags: [${memTags}] │ ${m.id}
+
+`;
+        }
+        return {
+          content: [{ type: "text", text: tagResponse.trimEnd() }]
+        };
+      }
       case "context_summary": {
         const {
           include_decisions = true,
@@ -6303,7 +6702,7 @@ ID: ${result.id.slice(0, 8)}...`;
           }[getType(m)] || "\uD83D\uDCE6";
           response += `${String(i + 1).padStart(2)}. ${typeIcon} ${content.slice(0, 150)}${content.length > 150 ? "..." : ""}
 `;
-          response += `    ┗━ ${getType(m)}${m.tier ? ` │ ${m.tier}` : ""} │ ${m.id.slice(0, 8)}...
+          response += `    ┗━ ${getType(m)}${m.tier ? ` │ ${m.tier}` : ""} │ ${m.id}
 `;
         }
         return {
@@ -6317,7 +6716,7 @@ ID: ${result.id.slice(0, 8)}...`;
 `;
         response += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `;
-        response += `✓ Removed: ${id.slice(0, 8)}...`;
+        response += `✓ Removed: ${id}`;
         return {
           content: [{ type: "text", text: response }]
         };
@@ -6463,7 +6862,7 @@ By Type:
           response += `Created: ${new Date(b.created_at).toLocaleString()}
 `;
         } else {
-          response += `✗ Failed: ${result.message}
+          response += `✗ Failed: ${result.message || "Unknown backup creation error"}
 `;
         }
         return {
@@ -6520,7 +6919,7 @@ By Type:
 `;
         response += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `;
-        response += result.message;
+        response += result.message || "No verification details provided";
         return {
           content: [{ type: "text", text: response }]
         };
@@ -6546,6 +6945,32 @@ By Type:
           content: [{ type: "text", text: response }]
         };
       }
+      case "backup_restore": {
+        const { backup_id } = args;
+        const result = await apiCall("/api/backup/restore", "POST", {
+          user_id: USER_ID,
+          backup_id
+        });
+        let response = `\uD83D\uDD04 Backup Restore
+`;
+        response += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+        if (result.success) {
+          response += `✓ Backup #${backup_id} restored successfully
+`;
+          if (result.restored_stores.length > 0) {
+            response += `Restored stores: ${result.restored_stores.join(", ")}
+`;
+          }
+          response += `
+⚠️ ${result.message || "Restore completed with no additional details"}`;
+        } else {
+          response += `✗ Restore failed: ${result.message || "Unknown restore error"}`;
+        }
+        return {
+          content: [{ type: "text", text: response }]
+        };
+      }
       case "proactive_context": {
         const {
           context,
@@ -6554,19 +6979,33 @@ By Type:
           recency_weight = 0.2,
           max_results = 5,
           memory_types = [],
-          auto_ingest = true
+          auto_ingest = true,
+          tool_actions = []
         } = args;
+        const cleanedContext = stripSystemNoise(context).slice(0, MAX_CONTEXT_LENGTH);
+        if (cleanedContext.length < PROACTIVE_MIN_CONTEXT_LENGTH) {
+          return {
+            content: [{ type: "text", text: `No relevant memories surfaced (context too short after cleaning).
+
+[Latency: 0.0ms]` }]
+          };
+        }
+        const skipFeedback = proactiveCallInFlight;
+        proactiveCallInFlight = true;
+        const previousUserContext = skipFeedback ? "" : lastUserContext;
+        lastUserContext = cleanedContext;
         const result = await apiCall("/api/proactive_context", "POST", {
           user_id: USER_ID,
-          context,
+          context: cleanedContext,
           max_results,
           semantic_threshold,
           entity_match_weight,
           recency_weight,
           memory_types,
           auto_ingest,
-          previous_response: lastProactiveResponse || undefined,
-          user_followup: lastProactiveResponse ? context : undefined
+          previous_response: skipFeedback ? undefined : lastProactiveResponse || undefined,
+          user_followup: skipFeedback || !lastProactiveResponse ? undefined : previousUserContext || undefined,
+          ...tool_actions.length > 0 ? { tool_actions } : {}
         });
         const memories = result.memories || [];
         const entities = result.detected_entities || [];
@@ -6577,10 +7016,13 @@ By Type:
 Detected entities: ${entities.map((e) => `"${e.name}" (${e.entity_type})`).join(", ")}` : "";
           const feedbackNote2 = result.feedback_processed ? `
 [Feedback: ${result.feedback_processed.memories_evaluated} evaluated, ${result.feedback_processed.reinforced.length} reinforced, ${result.feedback_processed.weakened.length} weakened]` : "";
-          const emptyText = `No relevant memories surfaced for this context.${entityList}${feedbackNote2}
+          const temporalNote2 = result.temporal_credits_applied ? `
+[Temporal credits: ${result.temporal_credits_applied} multi-turn signals applied]` : "";
+          const emptyText = `No relevant memories surfaced for this context.${entityList}${feedbackNote2}${temporalNote2}
 
-[Latency: ${result.latency_ms.toFixed(1)}ms]`;
+[Latency: ${(result.latency_ms ?? 0).toFixed(1)}ms]`;
           lastProactiveResponse = emptyText;
+          proactiveCallInFlight = false;
           return {
             content: [{ type: "text", text: emptyText }]
           };
@@ -6605,7 +7047,7 @@ Detected entities: ${entities.map((e) => `"${e.name}" (${e.entity_type})`).join(
             for (const r of uniqueReminders) {
               const icon = r.overdue_seconds && r.overdue_seconds > 0 ? "⏰" : "\uD83D\uDCCC";
               const contentText = r.content.slice(0, 38);
-              reminderBlock += `┃  ${icon} ${contentText.padEnd(44)} [${r.id.slice(0, 8)}] ┃
+              reminderBlock += `┃  ${icon} ${contentText.padEnd(44)} [${r.id}] ┃
 `;
               if (r.overdue_seconds && r.overdue_seconds > 0) {
                 const mins = Math.round(r.overdue_seconds / 60);
@@ -6700,8 +7142,10 @@ Detected entities: ${entities.map((e) => `"${e.name}" (${e.entity_type})`).join(
 `);
         const feedbackNote = result.feedback_processed ? `
 [Feedback loop: ${result.feedback_processed.memories_evaluated} evaluated, ${result.feedback_processed.reinforced.length} reinforced, ${result.feedback_processed.weakened.length} weakened]` : "";
+        const temporalNote = result.temporal_credits_applied ? `
+[Temporal credits: ${result.temporal_credits_applied} multi-turn signals applied]` : "";
         const ingestNote = result.ingested_memory_id ? `
-[Context ingested: ${result.ingested_memory_id.slice(0, 8)}]` : "";
+[Context ingested: ${result.ingested_memory_id}]` : "";
         const summaryParts = [];
         if (memories.length > 0)
           summaryParts.push(`${memories.length} memories`);
@@ -6714,10 +7158,13 @@ Detected entities: ${entities.map((e) => `"${e.name}" (${e.entity_type})`).join(
         const summary = summaryParts.length > 0 ? `Surfaced ${summaryParts.join(", ")}` : "No relevant context found";
         const responseText = `${temporalHeader}${summary}:
 
-${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${feedbackNote}${ingestNote}
+${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${feedbackNote}${temporalNote}${ingestNote}
 
-[Latency: ${result.latency_ms.toFixed(1)}ms | Threshold: ${(semantic_threshold * 100).toFixed(0)}%]`;
-        lastProactiveResponse = responseText;
+[Latency: ${(result.latency_ms ?? 0).toFixed(1)}ms | Threshold: ${(semantic_threshold * 100).toFixed(0)}%]`;
+        const cleanContent = memories.map((m) => m.content || "").filter((c) => c.length > 0).join(`
+`);
+        lastProactiveResponse = cleanContent || responseText;
+        proactiveCallInFlight = false;
         return {
           content: [{ type: "text", text: responseText }]
         };
@@ -6855,7 +7302,7 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
         };
       }
       case "set_reminder": {
-        const { content, trigger_type, trigger_at, after_seconds, keywords, priority = 3, tags = [] } = args;
+        const { content, trigger_type, trigger_at, after_seconds, keywords, priority = 3, tags = [], threshold } = args;
         if (!content || content.length === 0) {
           return { content: [{ type: "text", text: "Error: 'content' is required and cannot be empty" }], isError: true };
         }
@@ -6892,7 +7339,8 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
                 isError: true
               };
             }
-            trigger = { type: "context", keywords, threshold: 0.7 };
+            const ctxThreshold = threshold !== undefined && threshold >= 0 && threshold <= 1 ? threshold : 0.7;
+            trigger = { type: "context", keywords, threshold: ctxThreshold };
             break;
           default:
             return {
@@ -6911,7 +7359,7 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
 `;
         response += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `;
-        response += `ID: ${result.id.slice(0, 8)}...
+        response += `ID: ${result.id}
 `;
         response += `Content: ${content}
 `;
@@ -6954,7 +7402,7 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
           const statusBadge = r.status === "triggered" ? " [TRIGGERED]" : "";
           response += `${icon} ${r.content.slice(0, 50)}${r.content.length > 50 ? "..." : ""}${statusBadge}
 `;
-          response += `   Type: ${r.trigger_type} | Priority: ${"★".repeat(r.priority)} | ID: ${r.id.slice(0, 8)}...
+          response += `   Type: ${r.trigger_type} | Priority: ${"★".repeat(r.priority)} | ID: ${r.id}
 `;
           if (r.due_at) {
             response += `   Due: ${new Date(r.due_at).toLocaleString()}
@@ -6981,7 +7429,7 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
           content: [
             {
               type: "text",
-              text: result.success ? `✓ Reminder dismissed: ${reminder_id.slice(0, 8)}...` : `⚠️ ${result.message}`
+              text: result.success ? `✓ Reminder dismissed: ${reminder_id}` : `⚠️ ${result.message || "No message returned"}`
             }
           ]
         };
@@ -7199,7 +7647,13 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
         };
       }
       case "read_memory": {
-        const { memory_id } = args;
+        const memory_id = args.memory_id || args.id;
+        if (!memory_id || typeof memory_id !== "string" || memory_id.trim().length === 0) {
+          return {
+            content: [{ type: "text", text: "Error: 'memory_id' is required. Pass the full UUID or 8+ character prefix from recall results." }],
+            isError: true
+          };
+        }
         let memory = null;
         try {
           memory = await apiCall(`/api/memory/${memory_id}?user_id=${encodeURIComponent(USER_ID)}`, "GET");
@@ -7222,11 +7676,11 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
         response += `Tier: ${memory.tier || "Unknown"} | Created: ${created} | Importance: ${(memory.importance * 100).toFixed(0)}%
 `;
         if (memory.parent_id) {
-          response += `Parent: ${memory.parent_id.slice(0, 8)}...
+          response += `Parent: ${memory.parent_id}
 `;
         }
         if (memory.children_count > 0) {
-          response += `Children: ${memory.children_count} (${memory.children_ids.map((id) => id.slice(0, 8)).join(", ")})
+          response += `Children: ${memory.children_count} (${memory.children_ids.join(", ")})
 `;
         }
         response += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -7261,13 +7715,13 @@ ${formattedWithTime}${entitySummary}${factsBlock}${reminderBlock}${todoBlock}${f
       const context = contextParts.join(" ").slice(0, 1000);
       if (context.length >= PROACTIVE_MIN_CONTEXT_LENGTH) {
         const surfaced = await surfaceRelevant(context, 3);
-        if (surfaced && surfaced.length > 0) {
+        if (surfaced && surfaced.length > 0 && result.content.length > 0) {
           const surfacedText = formatSurfacedMemories(surfaced);
           result.content[result.content.length - 1].text += surfacedText;
         }
       }
     }
-    if (tokenStatus.alert) {
+    if (tokenStatus.alert && result.content.length > 0) {
       const percentUsed = Math.round(tokenStatus.percent * 100);
       const warning = `⚠️ CONTEXT ALERT: ${percentUsed}% of token budget used (${tokenStatus.tokens.toLocaleString()}/${tokenStatus.budget.toLocaleString()}). Consider starting a new session or running consolidation.
 
@@ -7878,14 +8332,14 @@ function getBinaryPath() {
     wrapperName = "shodh-memory";
     fallbackName = "shodh-memory-server";
   }
-  const wrapperPath = path.join(binDir, wrapperName);
-  if (fs.existsSync(wrapperPath)) {
-    return wrapperPath;
-  }
   const binaryPath = path.join(binDir, fallbackName);
   if (fs.existsSync(binaryPath)) {
     return binaryPath;
   }
+  const wrapperPath = path.join(binDir, wrapperName);
+  if (fs.existsSync(wrapperPath)) {
+    return wrapperPath;
+  }
   return null;
 }
 async function isServerRunning() {
@@ -7910,9 +8364,32 @@ async function waitForServer(maxAttempts = 30) {
   }
   return false;
 }
+async function validateApiKey() {
+  try {
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const response = await fetch(`${API_URL}/api/health`, {
+      headers: { "X-API-Key": API_KEY },
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
 async function ensureServerRunning() {
   if (await isServerRunning()) {
     console.error("[shodh-memory] Backend server already running at", API_URL);
+    if (!process.env.SHODH_API_KEY && isLocalServer()) {
+      const keyWorks = await validateApiKey();
+      if (!keyWorks) {
+        console.error("[shodh-memory] WARNING: Auto-generated key rejected by running server.");
+        console.error("[shodh-memory] The server was started with a different API key.");
+        console.error("[shodh-memory] Set SHODH_API_KEY to match the server's key, or restart");
+        console.error("[shodh-memory] the server without SHODH_DEV_API_KEY to use auto-generated keys.");
+      }
+    }
     return;
   }
   if (!AUTO_SPAWN_ENABLED) {
@@ -7930,6 +8407,13 @@ async function ensureServerRunning() {
     console.error("[shodh-memory] Or download from: https://github.com/varun29ankuS/shodh-memory/releases");
     return;
   }
+  const expectedBinDir = fs.realpathSync(path.join(__dirname2, "..", "bin"));
+  const resolvedBinary = fs.realpathSync(binaryPath);
+  if (!resolvedBinary.startsWith(expectedBinDir + path.sep) && resolvedBinary !== expectedBinDir) {
+    console.error(`[shodh-memory] WARNING: Binary path resolves outside expected directory: ${resolvedBinary}`);
+    console.error(`[shodh-memory] Expected: ${expectedBinDir}`);
+    return;
+  }
   console.error("[shodh-memory] Starting backend server...");
   const serverEnv = {};
   const SERVER_ENV_ALLOWLIST = new Set([
@@ -7966,10 +8450,12 @@ async function ensureServerRunning() {
     }
   }
   serverEnv["SHODH_DEV_API_KEY"] = API_KEY;
+  const isBat = binaryPath.endsWith(".bat");
   serverProcess = spawn(binaryPath, [], {
     detached: true,
     stdio: "ignore",
-    env: serverEnv
+    env: serverEnv,
+    ...isBat && { shell: true }
   });
   serverProcess.unref();
   console.error("[shodh-memory] Waiting for server to start...");
@@ -7981,16 +8467,31 @@ async function ensureServerRunning() {
   }
 }
 function cleanupServer() {
+  if (streamReconnectTimer) {
+    clearTimeout(streamReconnectTimer);
+    streamReconnectTimer = null;
+  }
+  STREAM_ENABLED = false;
+  if (streamSocket) {
+    try {
+      streamSocket.close();
+    } catch (_) {}
+    streamSocket = null;
+  }
   if (serverProcess && !serverProcess.killed) {
     if (process.platform !== "win32" && serverProcess.pid) {
       try {
         process.kill(-serverProcess.pid, "SIGTERM");
       } catch (e) {
         console.error("[Cleanup] Process group kill failed, falling back to direct kill:", e);
-        serverProcess.kill("SIGTERM");
+        try {
+          serverProcess.kill("SIGTERM");
+        } catch (_) {}
       }
     } else {
-      serverProcess.kill();
+      try {
+        serverProcess.kill();
+      } catch (_) {}
     }
   }
 }
@@ -8005,14 +8506,42 @@ process.on("SIGTERM", () => {
   cleanupServer();
   process.exit(0);
 });
+var shuttingDown = false;
+function gracefulShutdown(reason, code = 0) {
+  if (shuttingDown)
+    return;
+  shuttingDown = true;
+  console.error(`[shodh-memory] ${reason}`);
+  cleanupServer();
+  setTimeout(() => process.exit(code), 100);
+}
+process.stdin.on("end", () => gracefulShutdown("stdin closed (MCP session ended), shutting down..."));
+process.stdin.on("close", () => gracefulShutdown("stdin pipe closed, shutting down..."));
+process.on("uncaughtException", (err) => {
+  console.error("[shodh-memory] Uncaught exception:", err);
+  gracefulShutdown("Shutting down after uncaught exception", 1);
+});
+process.on("unhandledRejection", (reason) => {
+  console.error("[shodh-memory] Unhandled rejection:", reason);
+  gracefulShutdown("Shutting down after unhandled rejection", 1);
+});
+function createSandboxServer() {
+  process.env.SMITHERY_SANDBOX = "true";
+  return server;
+}
 async function main() {
+  if (SANDBOX_MODE)
+    return;
   await ensureServerRunning();
   const transport = new StdioServerTransport;
   await server.connect(transport);
-  console.error("Shodh-Memory MCP server v0.1.80 running");
+  console.error("Shodh-Memory MCP server v0.1.90 running");
   console.error(`Connecting to: ${API_URL}`);
   console.error(`User ID: ${USER_ID}`);
   console.error(`Streaming: ${STREAM_ENABLED ? "enabled" : "disabled"}`);
   console.error(`Proactive surfacing: ${PROACTIVE_SURFACING ? "enabled" : "disabled (SHODH_PROACTIVE=false)"}`);
 }
 main().catch(console.error);
+export {
+  createSandboxServer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shodh/memory-mcp",
-  "version": "0.1.80",
+  "version": "0.2.0",
   "mcpName": "io.github.varun29ankuS/shodh-memory",
   "description": "MCP server for persistent AI memory - store and recall context across sessions",
   "type": "module",
@@ -11,6 +11,9 @@
   "scripts": {
     "start": "bun run index.ts",
     "build": "bun build index.ts --outdir dist --target node",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "postinstall": "node scripts/postinstall.cjs",
     "prepublishOnly": "npm run build"
   },
@@ -22,6 +25,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.0"
   },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9",
+    "vitest": "^2.1.8"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",

package/scripts/postinstall.cjs

@@ -9,9 +9,9 @@
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
-const VERSION = '0.1.74';
+const VERSION = require('../package.json').version;
 const REPO = 'varun29ankuS/shodh-memory';
 const BIN_DIR = path.join(__dirname, '..', 'bin');
 
@@ -71,10 +71,10 @@ function download(url, dest) {
 // Extract archive
 function extract(archive, dest, platformInfo) {
   if (platformInfo.ext === '.tar.gz') {
-    execSync(`tar -xzf "${archive}" -C "${dest}"`, { stdio: 'inherit' });
+    execFileSync('tar', ['-xzf', archive, '-C', dest], { stdio: 'inherit' });
   } else if (platformInfo.ext === '.zip') {
     // Use PowerShell on Windows
-    execSync(`powershell -Command "Expand-Archive -Path '${archive}' -DestinationPath '${dest}' -Force"`, { stdio: 'inherit' });
+    execFileSync('powershell', ['-Command', `Expand-Archive -Path '${archive}' -DestinationPath '${dest}' -Force`], { stdio: 'inherit' });
   }
 }