devsh-memory-mcp 0.3.9 → 0.4.0

package/README.md

@@ -125,7 +125,7 @@ Logged items are reviewed by team leads and may be promoted to active orchestrat
 |----------|-------------|
 | `CMUX_TASK_RUN_JWT` | JWT for authenticating orchestration API calls |
 | `CMUX_ORCHESTRATION_ID` | Current orchestration session ID |
-| `CMUX_API_BASE_URL` | API base URL (default: https://cmux.sh) |
+| `CMUX_API_BASE_URL` | API base URL (default: https://cmux-www.karldigi.dev) |
 
 ## Memory Directory Structure
 

package/dist/{chunk-4CUOHQV6.js → chunk-R25AQROL.js}

@@ -23,6 +23,7 @@ function extractTeamIdFromJwt(jwt) {
   }
 }
 var DEFAULT_MEMORY_DIR = "/root/lifecycle/memory";
+var DEFAULT_CMUX_API_BASE_URL = "https://cmux-www.karldigi.dev";
 function createMemoryMcpServer(config) {
   const memoryDir = config?.memoryDir ?? DEFAULT_MEMORY_DIR;
   const resolvedAgentName = config?.agentName ?? process.env.CMUX_AGENT_NAME;
@@ -37,9 +38,316 @@ function createMemoryMcpServer(config) {
   const orchestrationDir = path.join(memoryDir, "orchestration");
   const mailboxPath = path.join(memoryDir, "MAILBOX.json");
   const tasksPath = path.join(memoryDir, "TASKS.json");
+  const usageStatsPath = path.join(memoryDir, "USAGE_STATS.json");
   const planPath = path.join(orchestrationDir, "PLAN.json");
   const agentsPath = path.join(orchestrationDir, "AGENTS.json");
   const eventsPath = path.join(orchestrationDir, "EVENTS.jsonl");
+  function readUsageStats() {
+    const content = readFile(usageStatsPath);
+    if (!content) return { version: 1, entries: {} };
+    try {
+      return JSON.parse(content);
+    } catch {
+      return { version: 1, entries: {} };
+    }
+  }
+  function writeUsageStats(stats) {
+    return writeFile(usageStatsPath, JSON.stringify(stats, null, 2));
+  }
+  function trackRead(memoryType) {
+    const stats = readUsageStats();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (!stats.entries[memoryType]) {
+      stats.entries[memoryType] = {
+        readCount: 0,
+        lastRead: now,
+        createdAt: now
+      };
+    }
+    stats.entries[memoryType].readCount++;
+    stats.entries[memoryType].lastRead = now;
+    writeUsageStats(stats);
+  }
+  function trackWrite(memoryType) {
+    const stats = readUsageStats();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (!stats.entries[memoryType]) {
+      stats.entries[memoryType] = {
+        readCount: 0,
+        lastRead: now,
+        createdAt: now
+      };
+    }
+    stats.entries[memoryType].lastWrite = now;
+    writeUsageStats(stats);
+  }
+  let syncConfig = null;
+  let syncConfigResolved = false;
+  const debounceMap = /* @__PURE__ */ new Map();
+  const retryQueue = [];
+  const DEBOUNCE_MS = 2e3;
+  const MAX_RETRIES = 3;
+  const SYNC_CONFIG_CACHE_PATH = path.join(memoryDir, ".sync-config.json");
+  const SYNC_FILE_MAP = {
+    append_daily_log: {
+      memoryType: "daily",
+      getFilePath: () => path.join(dailyDir, `${getTodayDateString()}.md`),
+      getFileName: (date) => `daily/${date ?? getTodayDateString()}.md`,
+      getDate: () => getTodayDateString()
+    },
+    update_knowledge: {
+      memoryType: "knowledge",
+      getFilePath: () => path.join(knowledgeDir, "MEMORY.md"),
+      getFileName: () => "knowledge/MEMORY.md"
+    },
+    add_task: {
+      memoryType: "tasks",
+      getFilePath: () => tasksPath,
+      getFileName: () => "TASKS.json"
+    },
+    update_task: {
+      memoryType: "tasks",
+      getFilePath: () => tasksPath,
+      getFileName: () => "TASKS.json"
+    },
+    send_message: {
+      memoryType: "mailbox",
+      getFilePath: () => mailboxPath,
+      getFileName: () => "MAILBOX.json"
+    },
+    mark_read: {
+      memoryType: "mailbox",
+      getFilePath: () => mailboxPath,
+      getFileName: () => "MAILBOX.json"
+    },
+    append_event: {
+      memoryType: "events",
+      getFilePath: () => eventsPath,
+      getFileName: () => "orchestration/EVENTS.jsonl"
+    },
+    update_plan_task: {
+      memoryType: "events",
+      getFilePath: () => eventsPath,
+      getFileName: () => "orchestration/EVENTS.jsonl"
+    },
+    check_stale_entries: {
+      memoryType: "knowledge",
+      getFilePath: () => path.join(knowledgeDir, "MEMORY.md"),
+      getFileName: () => "knowledge/MEMORY.md"
+    }
+  };
+  function readDotEnv(envPath) {
+    try {
+      const content = fs.readFileSync(envPath, "utf-8");
+      const vars = {};
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1) continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+          value = value.slice(1, -1);
+        }
+        vars[key] = value;
+      }
+      return vars;
+    } catch {
+      return {};
+    }
+  }
+  async function resolveSyncConfig() {
+    const envJwt = process.env.CMUX_TASK_RUN_JWT;
+    const envCallbackUrl = process.env.CMUX_CALLBACK_URL;
+    if (envJwt && envCallbackUrl) {
+      console.error(`[devsh-memory-mcp] Sync enabled via env vars: ${envCallbackUrl}`);
+      return { syncUrl: envCallbackUrl, authToken: envJwt };
+    }
+    try {
+      const cachedRaw = fs.readFileSync(SYNC_CONFIG_CACHE_PATH, "utf-8");
+      const cached = JSON.parse(cachedRaw);
+      if (cached.jwt && cached.syncUrl && cached.expiresAt > Date.now()) {
+        console.error(`[devsh-memory-mcp] Sync enabled via cached config: ${cached.syncUrl}`);
+        return { syncUrl: cached.syncUrl, authToken: cached.jwt };
+      }
+    } catch {
+    }
+    const envPaths = [
+      path.join(memoryDir, "..", "..", ".env"),
+      "/root/workspace/.env",
+      path.join(process.env.HOME ?? "/root", "workspace", ".env")
+    ];
+    let jwtSecret;
+    let convexUrl;
+    let teamId;
+    for (const envPath of envPaths) {
+      const vars = readDotEnv(envPath);
+      jwtSecret = jwtSecret ?? vars.CMUX_TASK_RUN_JWT_SECRET;
+      convexUrl = convexUrl ?? vars.CONVEX_SITE_URL ?? vars.CONVEX_SELF_HOSTED_URL;
+      teamId = teamId ?? vars.CMUX_TEAM_ID;
+    }
+    teamId = teamId ?? process.env.CMUX_TEAM_ID;
+    if (!jwtSecret || !convexUrl) {
+      console.error("[devsh-memory-mcp] Sync disabled: no JWT or Convex URL found");
+      return null;
+    }
+    if (!teamId) {
+      console.error("[devsh-memory-mcp] Sync disabled: no teamId found for bootstrap");
+      return null;
+    }
+    try {
+      const response = await fetch(`${convexUrl}/api/memory/bootstrap`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-cmux-bootstrap-key": jwtSecret
+        },
+        body: JSON.stringify({
+          teamId,
+          agentName
+        })
+      });
+      if (!response.ok) {
+        const errText = await response.text().catch(() => "");
+        console.error(`[devsh-memory-mcp] Bootstrap failed: ${response.status} ${errText}`);
+        return null;
+      }
+      const result = await response.json();
+      if (!result.ok || !result.jwt) {
+        console.error("[devsh-memory-mcp] Bootstrap returned invalid response");
+        return null;
+      }
+      const cacheData = {
+        jwt: result.jwt,
+        taskRunId: result.taskRunId,
+        syncUrl: convexUrl,
+        expiresAt: Date.now() + 6 * 24 * 60 * 60 * 1e3
+      };
+      try {
+        fs.writeFileSync(SYNC_CONFIG_CACHE_PATH, JSON.stringify(cacheData), "utf-8");
+      } catch {
+      }
+      console.error(
+        `[devsh-memory-mcp] Sync enabled via bootstrap: ${convexUrl} (reused=${result.reused})`
+      );
+      return { syncUrl: convexUrl, authToken: result.jwt };
+    } catch (error) {
+      console.error("[devsh-memory-mcp] Bootstrap error:", error);
+      return null;
+    }
+  }
+  async function doSync(memoryType, content, fileName, date) {
+    if (!syncConfig) return;
+    const url = `${syncConfig.syncUrl}/api/memory/sync`;
+    const body = {
+      files: [
+        {
+          memoryType,
+          content,
+          fileName,
+          date
+        }
+      ]
+    };
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-cmux-token": syncConfig.authToken
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const errText = await response.text().catch(() => "");
+        console.error(
+          `[devsh-memory-mcp] Sync failed for ${memoryType}: ${response.status} ${errText}`
+        );
+        enqueueRetry(memoryType, content, fileName, date);
+        return;
+      }
+      drainRetryQueue();
+    } catch (error) {
+      console.error(
+        `[devsh-memory-mcp] Sync error for ${memoryType}:`,
+        error instanceof Error ? error.message : error
+      );
+      enqueueRetry(memoryType, content, fileName, date);
+    }
+  }
+  function enqueueRetry(memoryType, content, fileName, date) {
+    const key = date ? `${memoryType}:${date}` : memoryType;
+    const existingIdx = retryQueue.findIndex(
+      (r) => (r.date ? `${r.memoryType}:${r.date}` : r.memoryType) === key
+    );
+    if (existingIdx >= 0) {
+      const existing = retryQueue[existingIdx];
+      if (existing.retryCount >= MAX_RETRIES) {
+        console.error(
+          `[devsh-memory-mcp] Dropping retry for ${memoryType} after ${MAX_RETRIES} attempts`
+        );
+        retryQueue.splice(existingIdx, 1);
+        return;
+      }
+      retryQueue[existingIdx] = {
+        memoryType,
+        content,
+        fileName,
+        date,
+        retryCount: existing.retryCount + 1
+      };
+    } else {
+      retryQueue.push({ memoryType, content, fileName, date, retryCount: 1 });
+    }
+  }
+  async function drainRetryQueue() {
+    if (!syncConfig || retryQueue.length === 0) return;
+    const items = [...retryQueue];
+    retryQueue.length = 0;
+    for (const item of items) {
+      if (item.retryCount >= MAX_RETRIES) {
+        console.error(
+          `[devsh-memory-mcp] Dropping retry for ${item.memoryType} after ${MAX_RETRIES} attempts`
+        );
+        continue;
+      }
+      await doSync(item.memoryType, item.content, item.fileName, item.date);
+    }
+  }
+  function scheduleSyncForFile(toolName) {
+    if (!syncConfigResolved) return;
+    if (!syncConfig) return;
+    const mapping = SYNC_FILE_MAP[toolName];
+    if (!mapping) return;
+    const { memoryType } = mapping;
+    const date = mapping.getDate?.();
+    const debounceKey = date ? `${memoryType}:${date}` : memoryType;
+    let entry = debounceMap.get(debounceKey);
+    if (!entry) {
+      entry = { timer: null };
+      debounceMap.set(debounceKey, entry);
+    }
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+    }
+    entry.timer = setTimeout(() => {
+      const filePath = mapping.getFilePath();
+      const content = readFile(filePath);
+      if (!content) return;
+      const fileName = mapping.getFileName(date);
+      doSync(memoryType, content, fileName, date).catch((err) => {
+        console.error("[devsh-memory-mcp] Sync error in debounce callback:", err);
+      });
+    }, DEBOUNCE_MS);
+  }
+  resolveSyncConfig().then((config2) => {
+    syncConfig = config2;
+    syncConfigResolved = true;
+  }).catch((err) => {
+    console.error("[devsh-memory-mcp] Sync config resolution failed:", err);
+    syncConfigResolved = true;
+  });
   function readFile(filePath) {
     try {
       return fs.readFileSync(filePath, "utf-8");
@@ -79,6 +387,9 @@ function createMemoryMcpServer(config) {
       fs.mkdirSync(dirPath, { recursive: true });
     }
   }
+  function getCmuxApiBaseUrl() {
+    return process.env.CMUX_API_BASE_URL ?? DEFAULT_CMUX_API_BASE_URL;
+  }
   function readPlan() {
     const content = readFile(planPath);
     if (!content) return null;
@@ -241,6 +552,31 @@ function createMemoryMcpServer(config) {
           required: ["query"]
         }
       },
+      {
+        name: "get_memory_usage",
+        description: "Get usage statistics for memory files. Shows read/write counts and timestamps for freshness tracking.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
+      {
+        name: "archive_stale_memories",
+        description: "Archive stale memory entries from MEMORY.md. Moves low-freshness entries to an archive section. Use dryRun=true to preview without changes.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            dryRun: {
+              type: "boolean",
+              description: "Preview changes without modifying files (default: true)"
+            },
+            maxScoreToArchive: {
+              type: "number",
+              description: "Archive entries with freshness score below this threshold (default: 30)"
+            }
+          }
+        }
+      },
       {
         name: "send_message",
         description: 'Send a message to another agent on the same task. Use "*" to broadcast to all agents. Aligned with Claude Code SendMessage pattern.',
@@ -603,6 +939,14 @@ function createMemoryMcpServer(config) {
           properties: {}
         }
       },
+      {
+        name: "get_context_health",
+        description: "Get context health summary for the current task run. Returns context window usage, warning state, and recent compaction events. Use this to monitor context pressure and decide when to summarize or archive context.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
       {
         name: "bind_provider_session",
         description: "Bind a provider-specific session ID to the current task. Use to enable session resume on task retry. Claude agents should call this with their session ID, Codex agents with their thread ID.",
@@ -750,6 +1094,56 @@ function createMemoryMcpServer(config) {
             }
           }
         }
+      },
+      // Operator Input Queue Tools (Active-Turn Steering)
+      {
+        name: "get_pending_operator_inputs",
+        description: "Check if there are pending operator steering inputs in the queue. Call this at turn boundaries to see if the operator has sent guidance. Returns queue status without draining.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID (optional, uses CMUX_ORCHESTRATION_ID env var if not provided)"
+            }
+          }
+        }
+      },
+      {
+        name: "acknowledge_operator_inputs",
+        description: "Drain and acknowledge all pending operator inputs. Returns merged content (newline-separated, priority-ordered). Call this at turn boundaries to process operator steering.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID (optional, uses CMUX_ORCHESTRATION_ID env var if not provided)"
+            }
+          }
+        }
+      },
+      {
+        name: "queue_operator_input",
+        description: "Queue an operator steering input for the agent. Use this as a head agent to send guidance to workers, or for testing. Returns QUEUE_FULL error if at capacity.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orchestrationId: {
+              type: "string",
+              description: "The orchestration ID (optional, uses CMUX_ORCHESTRATION_ID env var if not provided)"
+            },
+            content: {
+              type: "string",
+              description: "The steering instruction content"
+            },
+            priority: {
+              type: "string",
+              enum: ["high", "normal", "low"],
+              description: "Input priority (default: normal). High for interrupts, low for background guidance."
+            }
+          },
+          required: ["content"]
+        }
       }
     ]
   }));
@@ -758,6 +1152,7 @@ function createMemoryMcpServer(config) {
     switch (name) {
       case "read_memory": {
         const { type, includeCompleted, limit } = args;
+        trackRead(type);
         let content = null;
         if (type === "knowledge") {
           content = readFile(path.join(knowledgeDir, "MEMORY.md"));
@@ -814,6 +1209,120 @@ function createMemoryMcpServer(config) {
         const formatted = results.map((r) => `[${r.source}${r.line ? `:${r.line}` : ""}] ${r.content}`).join("\n");
         return { content: [{ type: "text", text: formatted }] };
       }
+      case "get_memory_usage": {
+        const stats = readUsageStats();
+        if (Object.keys(stats.entries).length === 0) {
+          return { content: [{ type: "text", text: "No usage statistics recorded yet." }] };
+        }
+        const now = Date.now();
+        const entries = Object.entries(stats.entries).map(([key, value]) => {
+          const daysSinceRead = Math.floor((now - new Date(value.lastRead).getTime()) / (1e3 * 60 * 60 * 24));
+          const daysSinceWrite = value.lastWrite ? Math.floor((now - new Date(value.lastWrite).getTime()) / (1e3 * 60 * 60 * 24)) : null;
+          const recencyScore = Math.max(0, 100 - daysSinceRead * 3);
+          const usageScore = Math.min(100, value.readCount * 10);
+          const priorityScore = key.includes("P0") ? 100 : key.includes("P1") ? 50 : key.includes("P2") ? 25 : 50;
+          const freshnessScore = Math.round(recencyScore * 0.4 + usageScore * 0.4 + priorityScore * 0.2);
+          let recommendation;
+          if (freshnessScore >= 60) recommendation = "keep";
+          else if (freshnessScore >= 30) recommendation = "review";
+          else recommendation = "archive";
+          return {
+            type: key,
+            readCount: value.readCount,
+            daysSinceRead,
+            daysSinceWrite,
+            freshnessScore,
+            recommendation
+          };
+        });
+        const keepCount = entries.filter((e) => e.recommendation === "keep").length;
+        const reviewCount = entries.filter((e) => e.recommendation === "review").length;
+        const archiveCount = entries.filter((e) => e.recommendation === "archive").length;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              summary: { keep: keepCount, review: reviewCount, archive: archiveCount },
+              entries
+            }, null, 2)
+          }]
+        };
+      }
+      case "archive_stale_memories": {
+        const { dryRun = true, maxScoreToArchive = 30 } = args;
+        const knowledgePath = path.join(knowledgeDir, "MEMORY.md");
+        const content = readFile(knowledgePath);
+        if (!content) {
+          return { content: [{ type: "text", text: "No MEMORY.md file found." }] };
+        }
+        const lines = content.split("\n");
+        const dateEntryPattern = /^- \[(\d{4}-\d{2}-\d{2})\] (.+)$/;
+        const now = Date.now();
+        const entriesToArchive = [];
+        for (let i = 0; i < lines.length; i++) {
+          const match = lines[i].match(dateEntryPattern);
+          if (match) {
+            const entryDate = new Date(match[1]).getTime();
+            const daysSince = Math.floor((now - entryDate) / (1e3 * 60 * 60 * 24));
+            const score = Math.max(0, 100 - daysSince * 2);
+            if (score < maxScoreToArchive) {
+              entriesToArchive.push({
+                line: i,
+                date: match[1],
+                text: match[2],
+                score
+              });
+            }
+          }
+        }
+        if (entriesToArchive.length === 0) {
+          return { content: [{ type: "text", text: "No stale entries found to archive." }] };
+        }
+        if (dryRun) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                dryRun: true,
+                wouldArchive: entriesToArchive.length,
+                entries: entriesToArchive,
+                message: "Set dryRun=false to actually archive these entries."
+              }, null, 2)
+            }]
+          };
+        }
+        const linesToRemove = new Set(entriesToArchive.map((e) => e.line));
+        const newLines = lines.filter((_, i) => !linesToRemove.has(i));
+        const archiveHeader = "## Archive (Stale Entries)";
+        let archiveContent = newLines.join("\n");
+        if (!archiveContent.includes(archiveHeader)) {
+          archiveContent += `
+
+${archiveHeader}
+<!-- Entries moved here by archive_stale_memories tool -->
+`;
+        }
+        const archiveEntries = entriesToArchive.map((e) => `- [${e.date}] [archived] ${e.text}`).join("\n");
+        archiveContent = archiveContent.replace(
+          archiveHeader,
+          `${archiveHeader}
+${archiveEntries}`
+        );
+        if (writeFile(knowledgePath, archiveContent)) {
+          trackWrite("knowledge.archive");
+          scheduleSyncForFile("update_knowledge");
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                archived: entriesToArchive.length,
+                entries: entriesToArchive.map((e) => e.text.slice(0, 50) + "...")
+              }, null, 2)
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: "Failed to write archived content." }] };
+      }
       case "send_message": {
         const { to, message, type, correlationId, replyTo, priority, metadata } = args;
         const mailbox = readMailbox();
@@ -832,6 +1341,7 @@ function createMemoryMcpServer(config) {
         };
         mailbox.messages.push(newMessage);
         writeMailbox(mailbox);
+        scheduleSyncForFile("send_message");
         const responseText = correlationId ? `Message sent successfully. ID: ${newMessage.id}, correlationId: ${correlationId}` : `Message sent successfully. ID: ${newMessage.id}`;
         return { content: [{ type: "text", text: responseText }] };
       }
@@ -876,6 +1386,7 @@ function createMemoryMcpServer(config) {
         }
         message.read = true;
         writeMailbox(mailbox);
+        scheduleSyncForFile("mark_read");
         return { content: [{ type: "text", text: `Message ${messageId} marked as read.` }] };
       }
       // Write tool handlers
@@ -894,12 +1405,25 @@ function createMemoryMcpServer(config) {
         const newContent = existing + `
 - [${timestamp}] ${content}`;
         if (writeFile(logPath, newContent)) {
+          scheduleSyncForFile("append_daily_log");
           return { content: [{ type: "text", text: `Appended to daily/${today}.md` }] };
         }
         return { content: [{ type: "text", text: `Failed to append to daily log` }] };
       }
       case "update_knowledge": {
         const { section, content } = args;
+        if (content.length > 200) {
+          return {
+            content: [{
+              type: "text",
+              text: `Entry too long (${content.length} chars). Keep memory entries concise (max 200 chars). Consider splitting into multiple entries or being more specific.`
+            }]
+          };
+        }
+        if (!content.trim()) {
+          return { content: [{ type: "text", text: "Cannot add empty memory entry." }] };
+        }
+        trackWrite(`knowledge.${section}`);
         ensureDir(knowledgeDir);
         const knowledgePath = path.join(knowledgeDir, "MEMORY.md");
         let existing = readFile(knowledgePath);
@@ -934,6 +1458,45 @@ function createMemoryMcpServer(config) {
         if (headerIndex === -1) {
           return { content: [{ type: "text", text: `Section ${section} not found in MEMORY.md` }] };
         }
+        const contentLower = content.toLowerCase();
+        const existingEntries = existing.match(/- \[\d{4}-\d{2}-\d{2}\] .+/g) || [];
+        for (const entry of existingEntries) {
+          const entryText = entry.replace(/- \[\d{4}-\d{2}-\d{2}\] /, "").toLowerCase();
+          if (entryText === contentLower || entryText.includes(contentLower) || contentLower.includes(entryText)) {
+            return {
+              content: [{
+                type: "text",
+                text: `Duplicate detected. Similar entry already exists: "${entry.slice(0, 80)}...". Update the existing entry instead of adding a duplicate.`
+              }]
+            };
+          }
+        }
+        if (section === "P0") {
+          const p0Section = existing.slice(headerIndex, existing.indexOf("## P1"));
+          const usesPattern = /uses?\s+(\w+)/gi;
+          const newUses = [...contentLower.matchAll(usesPattern)].map((m) => m[1]);
+          const existingUses = [...p0Section.toLowerCase().matchAll(usesPattern)].map((m) => m[1]);
+          const alternatives = {
+            bun: ["npm", "yarn", "pnpm"],
+            npm: ["bun", "yarn", "pnpm"],
+            yarn: ["npm", "bun", "pnpm"],
+            vitest: ["jest", "mocha"],
+            jest: ["vitest", "mocha"]
+          };
+          for (const newTool of newUses) {
+            const conflicts = alternatives[newTool] || [];
+            for (const existingTool of existingUses) {
+              if (conflicts.includes(existingTool)) {
+                return {
+                  content: [{
+                    type: "text",
+                    text: `Potential P0 contradiction: New entry mentions "${newTool}" but P0 already contains "${existingTool}". These are typically alternatives. Verify this is intentional before adding.`
+                  }]
+                };
+              }
+            }
+          }
+        }
         const afterHeader = existing.slice(headerIndex + header.length);
         const nextSectionMatch = afterHeader.match(/\n## /);
         const insertPoint = nextSectionMatch ? headerIndex + header.length + (nextSectionMatch.index ?? afterHeader.length) : existing.length;
@@ -942,6 +1505,7 @@ function createMemoryMcpServer(config) {
         const actualInsertPoint = Math.min(commentEnd, insertPoint);
         const updated = existing.slice(0, actualInsertPoint) + newEntry + "\n" + existing.slice(actualInsertPoint);
         if (writeFile(knowledgePath, updated)) {
+          scheduleSyncForFile("update_knowledge");
           return { content: [{ type: "text", text: `Added entry to ${section} section in MEMORY.md` }] };
         }
         return { content: [{ type: "text", text: `Failed to update MEMORY.md` }] };
@@ -960,6 +1524,7 @@ function createMemoryMcpServer(config) {
         };
         tasks.tasks.push(newTask);
         if (writeTasks(tasks)) {
+          scheduleSyncForFile("add_task");
           return { content: [{ type: "text", text: `Task created with ID: ${newTask.id}` }] };
         }
         return { content: [{ type: "text", text: `Failed to create task` }] };
@@ -974,6 +1539,7 @@ function createMemoryMcpServer(config) {
         task.status = status;
         task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
         if (writeTasks(tasks)) {
+          scheduleSyncForFile("update_task");
           return { content: [{ type: "text", text: `Task ${taskId} updated to status: ${status}` }] };
         }
         return { content: [{ type: "text", text: `Failed to update task` }] };
@@ -1003,6 +1569,7 @@ function createMemoryMcpServer(config) {
         if (agentName2) eventObj.agentName = agentName2;
         if (taskRunId) eventObj.taskRunId = taskRunId;
         if (appendEvent(eventObj)) {
+          scheduleSyncForFile("append_event");
           return { content: [{ type: "text", text: `Event appended to EVENTS.jsonl` }] };
         }
         return { content: [{ type: "text", text: `Failed to append event` }] };
@@ -1027,6 +1594,7 @@ function createMemoryMcpServer(config) {
           task.completedAt = (/* @__PURE__ */ new Date()).toISOString();
         }
         if (writePlan(plan)) {
+          scheduleSyncForFile("update_plan_task");
           return { content: [{ type: "text", text: `Plan task ${taskId} updated to status: ${status}` }] };
         }
         return { content: [{ type: "text", text: `Failed to update plan task` }] };
@@ -1035,7 +1603,7 @@ function createMemoryMcpServer(config) {
         const { orchestrationId: argOrchId } = args;
         const orchestrationId = argOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         if (!orchestrationId) {
           return {
             content: [{
@@ -1146,7 +1714,7 @@ function createMemoryMcpServer(config) {
         const { orchestrationId: argOrchId, headAgentStatus, message, taskIds } = args;
         const orchestrationId = argOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         if (!orchestrationId) {
           return {
             content: [{
@@ -1483,7 +2051,7 @@ function createMemoryMcpServer(config) {
       case "list_spawned_agents": {
         const { status: filterStatus } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         const orchestrationId = process.env.CMUX_ORCHESTRATION_ID;
         if (!jwt) {
           return {
@@ -1542,7 +2110,7 @@ function createMemoryMcpServer(config) {
       case "cancel_agent": {
         const { orchestrationTaskId, cascade = false } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         if (!jwt) {
           return {
             content: [{
@@ -1610,7 +2178,7 @@ function createMemoryMcpServer(config) {
       }
       case "get_orchestration_summary": {
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         const orchestrationId = process.env.CMUX_ORCHESTRATION_ID;
         if (!jwt) {
           return {
@@ -1680,10 +2248,77 @@ function createMemoryMcpServer(config) {
           };
         }
       }
+      case "get_context_health": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const callbackUrl = process.env.CMUX_CALLBACK_URL;
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_TASK_RUN_JWT environment variable not set. This tool requires JWT authentication."
+            }]
+          };
+        }
+        if (!callbackUrl) {
+          return {
+            content: [{
+              type: "text",
+              text: "CMUX_CALLBACK_URL environment variable not set."
+            }]
+          };
+        }
+        try {
+          const url = `${callbackUrl}/api/v1/cmux/orchestration/context-health`;
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              "x-cmux-token": jwt
+            }
+          });
+          if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            return {
+              content: [{
+                type: "text",
+                text: `Error getting context health: ${response.status} ${errorData.message ?? response.statusText}`
+              }]
+            };
+          }
+          const data = await response.json();
+          const usageStr = data.contextWindow ? `${data.totalInputTokens.toLocaleString()} / ${data.contextWindow.toLocaleString()} tokens (${data.usagePercent ?? 0}%)` : `${data.totalInputTokens.toLocaleString()} input tokens`;
+          const warningStr = data.latestWarningSeverity ? `${data.latestWarningSeverity.toUpperCase()} - ${data.topWarningReasons[0] ?? "No details"}` : "None";
+          const summary = [
+            `Provider: ${data.provider}`,
+            `Context Usage: ${usageStr}`,
+            `Output Tokens: ${data.totalOutputTokens.toLocaleString()}`,
+            `Warning State: ${warningStr}`,
+            `Warning Count: ${data.warningCount}`,
+            `Compaction Count: ${data.recentCompactionCount}`
+          ].join("\n");
+          return {
+            content: [{
+              type: "text",
+              text: `Context Health Summary:
+${summary}
+
+Raw Data:
+${JSON.stringify(data, null, 2)}`
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error getting context health: ${errorMsg}`
+            }]
+          };
+        }
+      }
       case "bind_provider_session": {
         const { providerSessionId, providerThreadId, replyChannel } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         const orchestrationId = process.env.CMUX_ORCHESTRATION_ID;
         const taskRunId = process.env.CMUX_TASK_RUN_ID;
         if (!jwt) {
@@ -1746,7 +2381,7 @@ function createMemoryMcpServer(config) {
       case "get_provider_session": {
         const { taskId: providedTaskId } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         const taskId = providedTaskId ?? process.env.CMUX_TASK_RUN_ID;
         if (!jwt) {
           return {
@@ -1824,7 +2459,7 @@ function createMemoryMcpServer(config) {
       case "wait_for_events": {
         const { orchestrationId, eventTypes = [], timeout = 3e4 } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         if (!jwt) {
           return {
             content: [{
@@ -1939,7 +2574,7 @@ function createMemoryMcpServer(config) {
       case "get_pending_approvals": {
         const { orchestrationId: providedOrchId } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         const orchestrationId = providedOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
         if (!jwt) {
           return {
@@ -1999,7 +2634,7 @@ function createMemoryMcpServer(config) {
       case "resolve_approval": {
         const { requestId, resolution, note } = args;
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBaseUrl = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBaseUrl = getCmuxApiBaseUrl();
         if (!jwt) {
           return {
             content: [{
@@ -2231,7 +2866,7 @@ function createMemoryMcpServer(config) {
       }
       case "log_learning": {
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBase = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBase = getCmuxApiBaseUrl();
         if (!jwt) {
           return {
             content: [{
@@ -2291,7 +2926,7 @@ function createMemoryMcpServer(config) {
       }
       case "get_active_orchestration_rules": {
         const jwt = process.env.CMUX_TASK_RUN_JWT;
-        const apiBase = process.env.CMUX_API_BASE_URL ?? "https://cmux.sh";
+        const apiBase = getCmuxApiBaseUrl();
         if (!jwt) {
           return {
             content: [{
@@ -2359,6 +2994,242 @@ function createMemoryMcpServer(config) {
           };
         }
       }
+      // Operator Input Queue Tools (Active-Turn Steering)
+      case "get_pending_operator_inputs": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBase = getCmuxApiBaseUrl();
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: CMUX_TASK_RUN_JWT not set. This tool requires authentication."
+            }]
+          };
+        }
+        const { orchestrationId: inputOrchId } = args;
+        const orchestrationId = inputOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
+        if (!orchestrationId) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: No orchestration ID provided and CMUX_ORCHESTRATION_ID not set."
+            }]
+          };
+        }
+        try {
+          const response = await fetch(
+            `${apiBase}/api/orchestrate/input/${orchestrationId}/status`,
+            {
+              method: "GET",
+              headers: {
+                "x-cmux-token": jwt
+              }
+            }
+          );
+          if (!response.ok) {
+            const errText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Error getting queue status: ${response.status} ${errText}`
+              }]
+            };
+          }
+          const status = await response.json();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                hasPendingInputs: status.hasPendingInputs,
+                depth: status.depth,
+                capacity: status.capacity,
+                oldestInputAt: status.oldestInputAt,
+                message: status.hasPendingInputs ? `${status.depth} pending operator input(s). Call acknowledge_operator_inputs to process.` : "No pending operator inputs."
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error checking operator inputs: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "acknowledge_operator_inputs": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBase = getCmuxApiBaseUrl();
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: CMUX_TASK_RUN_JWT not set. This tool requires authentication."
+            }]
+          };
+        }
+        const { orchestrationId: ackOrchId } = args;
+        const orchestrationId = ackOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
+        if (!orchestrationId) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: No orchestration ID provided and CMUX_ORCHESTRATION_ID not set."
+            }]
+          };
+        }
+        try {
+          const response = await fetch(
+            `${apiBase}/api/orchestrate/input/${orchestrationId}/drain`,
+            {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                "x-cmux-token": jwt
+              },
+              body: JSON.stringify({})
+            }
+          );
+          if (!response.ok) {
+            const errText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Error draining operator inputs: ${response.status} ${errText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          if (result.count === 0) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  count: 0,
+                  content: "",
+                  batchId: result.batchId,
+                  message: "No operator inputs to process."
+                }, null, 2)
+              }]
+            };
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                count: result.count,
+                content: result.content,
+                batchId: result.batchId,
+                inputIds: result.inputIds,
+                message: `Processed ${result.count} operator input(s). Content merged above.`
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error acknowledging operator inputs: ${errorMsg}`
+            }]
+          };
+        }
+      }
+      case "queue_operator_input": {
+        const jwt = process.env.CMUX_TASK_RUN_JWT;
+        const apiBase = getCmuxApiBaseUrl();
+        if (!jwt) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: CMUX_TASK_RUN_JWT not set. This tool requires authentication."
+            }]
+          };
+        }
+        const {
+          orchestrationId: queueOrchId,
+          content,
+          priority
+        } = args;
+        const orchestrationId = queueOrchId ?? process.env.CMUX_ORCHESTRATION_ID;
+        if (!orchestrationId) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: No orchestration ID provided and CMUX_ORCHESTRATION_ID not set."
+            }]
+          };
+        }
+        if (!content || content.trim().length === 0) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: Content is required."
+            }]
+          };
+        }
+        try {
+          const response = await fetch(
+            `${apiBase}/api/orchestrate/input/${orchestrationId}`,
+            {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                "x-cmux-token": jwt
+              },
+              body: JSON.stringify({
+                content: content.trim(),
+                priority: priority ?? "normal"
+              })
+            }
+          );
+          if (!response.ok) {
+            const errText = await response.text();
+            return {
+              content: [{
+                type: "text",
+                text: `Error queuing input: ${response.status} ${errText}`
+              }]
+            };
+          }
+          const result = await response.json();
+          if (!result.success) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  queued: false,
+                  error: result.error,
+                  queueDepth: result.queueDepth,
+                  queueCapacity: result.queueCapacity,
+                  message: `Queue is full (${result.queueDepth}/${result.queueCapacity}). Wait for agent to drain before sending more.`
+                }, null, 2)
+              }]
+            };
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                queued: true,
+                inputId: result.inputId,
+                queueDepth: result.queueDepth,
+                priority: priority ?? "normal",
+                message: `Input queued successfully (${result.queueDepth} in queue).`
+              }, null, 2)
+            }]
+          };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{
+              type: "text",
+              text: `Error queuing operator input: ${errorMsg}`
+            }]
+          };
+        }
+      }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runServer
-} from "./chunk-4CUOHQV6.js";
+} from "./chunk-R25AQROL.js";
 
 // src/cli.ts
 function parseArgs() {

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   createMemoryMcpServer,
   runServer
-} from "./chunk-4CUOHQV6.js";
+} from "./chunk-R25AQROL.js";
 export {
   createMemoryMcpServer,
   runServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsh-memory-mcp",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "MCP server for devsh/cmux agent memory - enables Claude Desktop and external clients to access sandbox memory and orchestrate multi-agent workflows",
   "type": "module",
   "main": "dist/index.js",