@stackmemoryai/stackmemory 1.2.8 → 1.2.9

package/README.md

@@ -14,7 +14,7 @@ Lossless, project-scoped memory for AI coding tools. **[Website](https://stackme
 StackMemory is a **production-ready memory runtime** for AI coding tools that preserves full project context across sessions:
 
 - **Zero-config setup** — `stackmemory init` just works
-- **55 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team)
+- **56 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team, planning, providers, and more)
 - **FTS5 full-text search** with BM25 scoring and hybrid retrieval
 - **Full Linear integration** with bidirectional sync and OAuth/API key support
 - **Context persistence** that survives `/clear` operations
@@ -356,7 +356,7 @@ See [docs/cli.md](https://github.com/stackmemoryai/stackmemory/blob/main/docs/cl
 ## Documentation
 
 - [Getting Started](./docs/GETTING_STARTED.md) — Quick start guide (5 minutes)
-- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 55 MCP tools
+- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 56 MCP tools
 - [CLI Reference](./docs/cli.md) — Full command reference
 - [Setup Guide](./docs/SETUP.md) — Advanced setup options
 - [Development Guide](./docs/DEVELOPMENT.md) — Contributing and development

package/dist/src/cli/commands/daemon.js

@@ -5,8 +5,8 @@ const __dirname = __pathDirname(__filename);
 import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
-import { existsSync, readFileSync, unlinkSync } from "fs";
-import { spawn } from "child_process";
+import { existsSync, readFileSync, unlinkSync, statSync } from "fs";
+import { spawn, execSync } from "child_process";
 import { join } from "path";
 import {
   loadDaemonConfig,
@@ -23,6 +23,7 @@ Examples:
   stackmemory daemon start      Start the daemon
   stackmemory daemon stop       Stop the daemon
   stackmemory daemon status     Check daemon status
+  stackmemory daemon health     Check daemon health metrics
   stackmemory daemon logs       View daemon logs
   stackmemory daemon config     Show/edit configuration
 
@@ -302,6 +303,100 @@ The daemon provides:
       console.log(chalk.bold("To start: stackmemory daemon start"));
     }
   });
+  cmd.command("health").description("Check daemon health metrics").option("--json", "Output as JSON").action((options) => {
+    const status = readDaemonStatus();
+    const config = loadDaemonConfig();
+    const paths = getDaemonPaths();
+    if (options.json) {
+      const health = buildHealthReport(status, config, paths);
+      console.log(JSON.stringify(health, null, 2));
+      return;
+    }
+    console.log(chalk.bold("\nDaemon Health Check\n"));
+    if (!status.running) {
+      console.log(`${chalk.red("[DOWN]")} Daemon Process`);
+      console.log(chalk.gray("    Daemon is not running"));
+      console.log(chalk.cyan("    Fix: stackmemory daemon start"));
+      console.log("");
+      console.log(`Overall: ${chalk.red("RED")} - daemon not running`);
+      return;
+    }
+    const checks = [];
+    checks.push({
+      name: "Daemon Process",
+      status: "ok",
+      detail: `PID ${status.pid}`
+    });
+    if (status.uptime) {
+      const uptimeStr = formatDuration(status.uptime);
+      const uptimeStatus = status.uptime < 6e4 ? "warn" : "ok";
+      checks.push({
+        name: "Uptime",
+        status: uptimeStatus,
+        detail: uptimeStr
+      });
+    }
+    if (status.pid) {
+      const memInfo = getProcessMemory(status.pid);
+      if (memInfo) {
+        const mbUsed = Math.round(memInfo / 1024 / 1024);
+        const memStatus = mbUsed > 512 ? "error" : mbUsed > 256 ? "warn" : "ok";
+        checks.push({
+          name: "Memory (RSS)",
+          status: memStatus,
+          detail: `${mbUsed} MB`
+        });
+      } else {
+        checks.push({
+          name: "Memory (RSS)",
+          status: "warn",
+          detail: "Could not read process memory"
+        });
+      }
+    }
+    const serviceChecks = getServiceHealthChecks(status, config);
+    checks.push(...serviceChecks);
+    const errorInfo = countRecentErrors(paths.logFile);
+    const errorStatus = errorInfo.count > 10 ? "error" : errorInfo.count > 0 ? "warn" : "ok";
+    checks.push({
+      name: "Recent Errors (1h)",
+      status: errorStatus,
+      detail: errorInfo.count === 0 ? "None" : `${errorInfo.count} error${errorInfo.count !== 1 ? "s" : ""}${errorInfo.lastError ? ` (latest: ${errorInfo.lastError.slice(0, 60)})` : ""}`
+    });
+    if (existsSync(paths.logFile)) {
+      try {
+        const stat = statSync(paths.logFile);
+        const sizeMb = (stat.size / 1024 / 1024).toFixed(1);
+        const logStatus = stat.size > 100 * 1024 * 1024 ? "error" : stat.size > 50 * 1024 * 1024 ? "warn" : "ok";
+        checks.push({
+          name: "Log File Size",
+          status: logStatus,
+          detail: `${sizeMb} MB`
+        });
+      } catch {
+      }
+    }
+    const maxNameLen = Math.max(...checks.map((c) => c.name.length));
+    for (const check of checks) {
+      const icon = check.status === "ok" ? chalk.green("[OK]   ") : check.status === "warn" ? chalk.yellow("[WARN] ") : chalk.red("[ERROR]");
+      const paddedName = check.name.padEnd(maxNameLen + 2);
+      console.log(`  ${icon} ${paddedName} ${chalk.gray(check.detail)}`);
+    }
+    const hasError = checks.some((c) => c.status === "error");
+    const hasWarn = checks.some((c) => c.status === "warn");
+    console.log("");
+    if (hasError) {
+      console.log(
+        `Overall: ${chalk.red("RED")} - one or more critical issues detected`
+      );
+    } else if (hasWarn) {
+      console.log(
+        `Overall: ${chalk.yellow("YELLOW")} - healthy with warnings`
+      );
+    } else {
+      console.log(`Overall: ${chalk.green("GREEN")} - all services healthy`);
+    }
+  });
   cmd.command("logs").description("View daemon logs").option("-n, --lines <number>", "Number of lines to show", "50").option("-f, --follow", "Follow log output").option("--level <level>", "Filter by log level").action((options) => {
     const { logFile } = getDaemonPaths();
     if (!existsSync(logFile)) {
@@ -442,6 +537,215 @@ function getDaemonScriptPath() {
   }
   return candidates[0];
 }
+function formatDuration(ms) {
+  const totalSecs = Math.round(ms / 1e3);
+  const days = Math.floor(totalSecs / 86400);
+  const hours = Math.floor(totalSecs % 86400 / 3600);
+  const mins = Math.floor(totalSecs % 3600 / 60);
+  const secs = totalSecs % 60;
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (mins > 0) parts.push(`${mins}m`);
+  if (parts.length === 0 || secs > 0) parts.push(`${secs}s`);
+  return parts.join(" ");
+}
+function formatTimeAgo(timestamp) {
+  const ago = Date.now() - timestamp;
+  if (ago < 6e4) return `${Math.round(ago / 1e3)}s ago`;
+  if (ago < 36e5) return `${Math.round(ago / 6e4)}m ago`;
+  if (ago < 864e5) return `${(ago / 36e5).toFixed(1)}h ago`;
+  return `${(ago / 864e5).toFixed(1)}d ago`;
+}
+function getProcessMemory(pid) {
+  try {
+    const output = execSync(`ps -o rss= -p ${pid}`, {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: "pipe"
+    }).trim();
+    const rssKb = parseInt(output, 10);
+    if (isNaN(rssKb)) return null;
+    return rssKb * 1024;
+  } catch {
+    return null;
+  }
+}
+function getServiceHealthChecks(status, config) {
+  const checks = [];
+  const ctx = status.services.context;
+  if (ctx.enabled) {
+    const intervalMs = config.context.interval * 6e4;
+    const overdue = ctx.lastRun ? Date.now() - ctx.lastRun > intervalMs * 2 : false;
+    checks.push({
+      name: "Context Service",
+      status: overdue ? "warn" : "ok",
+      detail: ctx.lastRun ? `Last save: ${formatTimeAgo(ctx.lastRun)} | Saves: ${ctx.saveCount ?? 0}` : `Enabled (interval: ${config.context.interval}m) | No saves yet`
+    });
+  } else {
+    checks.push({
+      name: "Context Service",
+      status: "ok",
+      detail: "Disabled"
+    });
+  }
+  const lin = status.services.linear;
+  if (lin.enabled) {
+    const intervalMs = config.linear.interval * 6e4;
+    const overdue = lin.lastRun ? Date.now() - lin.lastRun > intervalMs * 2 : false;
+    checks.push({
+      name: "Linear Service",
+      status: overdue ? "warn" : "ok",
+      detail: lin.lastRun ? `Last sync: ${formatTimeAgo(lin.lastRun)} | Syncs: ${lin.syncCount ?? 0}` : `Enabled (interval: ${config.linear.interval}m) | No syncs yet`
+    });
+  } else {
+    checks.push({
+      name: "Linear Service",
+      status: "ok",
+      detail: "Disabled"
+    });
+  }
+  const maint = status.services.maintenance;
+  if (maint?.enabled) {
+    const intervalMs = config.maintenance.interval * 6e4;
+    const overdue = maint.lastRun ? Date.now() - maint.lastRun > intervalMs * 2 : false;
+    checks.push({
+      name: "Maintenance Service",
+      status: overdue ? "warn" : "ok",
+      detail: maint.lastRun ? `Last run: ${formatTimeAgo(maint.lastRun)} | FTS rebuilds: ${maint.ftsRebuilds ?? 0} | Stale cleaned: ${maint.staleFramesCleaned ?? 0}` : `Enabled (interval: ${config.maintenance.interval}m) | No runs yet`
+    });
+  } else {
+    checks.push({
+      name: "Maintenance Service",
+      status: "ok",
+      detail: "Disabled"
+    });
+  }
+  const mem = status.services.memory;
+  if (mem?.enabled) {
+    const ramStr = mem.currentRamPercent !== void 0 ? `RAM: ${Math.round(mem.currentRamPercent * 100)}%` : "RAM: n/a";
+    const triggerStr = `Triggers: ${mem.triggerCount ?? 0}`;
+    checks.push({
+      name: "Memory Service",
+      status: "ok",
+      detail: `${ramStr} | ${triggerStr}`
+    });
+  } else {
+    checks.push({
+      name: "Memory Service",
+      status: "ok",
+      detail: "Disabled"
+    });
+  }
+  const fw = status.services.fileWatch;
+  checks.push({
+    name: "FileWatch Service",
+    status: "ok",
+    detail: fw.enabled ? `Active | Events: ${fw.eventsProcessed ?? 0}` : "Disabled"
+  });
+  return checks;
+}
+function countRecentErrors(logFile) {
+  if (!existsSync(logFile)) {
+    return { count: 0 };
+  }
+  try {
+    const content = readFileSync(logFile, "utf8");
+    const lines = content.trim().split("\n");
+    const oneHourAgo = Date.now() - 36e5;
+    let count = 0;
+    let lastError;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]);
+        const timestamp = new Date(entry.timestamp).getTime();
+        if (timestamp < oneHourAgo) break;
+        if (entry.level === "ERROR") {
+          count++;
+          if (!lastError) {
+            lastError = entry.message;
+          }
+        }
+      } catch {
+      }
+    }
+    return { count, lastError };
+  } catch {
+    return { count: 0 };
+  }
+}
+function buildHealthReport(status, config, paths) {
+  if (!status.running) {
+    return {
+      overall: "RED",
+      running: false,
+      services: {},
+      errors: { recentCount: 0 }
+    };
+  }
+  const errorInfo = countRecentErrors(paths.logFile);
+  let memoryMb;
+  if (status.pid) {
+    const memBytes = getProcessMemory(status.pid);
+    if (memBytes) memoryMb = Math.round(memBytes / 1024 / 1024);
+  }
+  const services = {};
+  const svcEntries = [
+    {
+      key: "context",
+      enabled: status.services.context.enabled,
+      lastRun: status.services.context.lastRun
+    },
+    {
+      key: "linear",
+      enabled: status.services.linear.enabled,
+      lastRun: status.services.linear.lastRun
+    },
+    {
+      key: "maintenance",
+      enabled: status.services.maintenance?.enabled ?? false,
+      lastRun: status.services.maintenance?.lastRun
+    },
+    {
+      key: "memory",
+      enabled: status.services.memory?.enabled ?? false,
+      lastRun: status.services.memory?.lastTrigger
+    },
+    {
+      key: "fileWatch",
+      enabled: status.services.fileWatch.enabled
+    }
+  ];
+  for (const svc of svcEntries) {
+    services[svc.key] = {
+      enabled: svc.enabled,
+      status: svc.enabled ? "running" : "disabled",
+      lastRun: svc.lastRun,
+      lastRunAgo: svc.lastRun ? formatTimeAgo(svc.lastRun) : void 0
+    };
+  }
+  let logFileSizeMb;
+  if (existsSync(paths.logFile)) {
+    try {
+      const stat = statSync(paths.logFile);
+      logFileSizeMb = parseFloat((stat.size / 1024 / 1024).toFixed(1));
+    } catch {
+    }
+  }
+  const hasError = errorInfo.count > 10 || memoryMb !== void 0 && memoryMb > 512 || logFileSizeMb !== void 0 && logFileSizeMb > 100;
+  const hasWarn = errorInfo.count > 0 || memoryMb !== void 0 && memoryMb > 256 || status.uptime !== void 0 && status.uptime < 6e4 || logFileSizeMb !== void 0 && logFileSizeMb > 50;
+  return {
+    overall: hasError ? "RED" : hasWarn ? "YELLOW" : "GREEN",
+    running: true,
+    pid: status.pid,
+    uptime: status.uptime,
+    uptimeFormatted: status.uptime ? formatDuration(status.uptime) : void 0,
+    memoryMb,
+    services,
+    errors: { recentCount: errorInfo.count, lastError: errorInfo.lastError },
+    logFileSizeMb
+  };
+}
 var daemon_default = createDaemonCommand();
 export {
   createDaemonCommand,

package/dist/src/cli/commands/desires.js

@@ -0,0 +1,117 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import chalk from "chalk";
+const DESIRE_DIR = join(homedir(), ".stackmemory", "desire-paths");
+function loadEntries(since) {
+  if (!existsSync(DESIRE_DIR)) return [];
+  const files = readdirSync(DESIRE_DIR).filter((f) => f.startsWith("desire-") && f.endsWith(".jsonl")).sort();
+  const entries = [];
+  for (const file of files) {
+    const lines = readFileSync(join(DESIRE_DIR, file), "utf-8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (since && new Date(entry.ts).getTime() < since) continue;
+        entries.push(entry);
+      } catch {
+      }
+    }
+  }
+  return entries;
+}
+function createDesiresCommands() {
+  const desires = new Command("desires").description(
+    "Analyze desire path logs \u2014 failed tool calls and unmet agent needs"
+  );
+  desires.command("summary").description("Show aggregated failure counts by tool").action(() => {
+    const entries = loadEntries();
+    if (entries.length === 0) {
+      console.log(chalk.yellow("No desire path data found."));
+      console.log(chalk.gray(`  Logs dir: ${DESIRE_DIR}`));
+      return;
+    }
+    const byTool = /* @__PURE__ */ new Map();
+    for (const e of entries) {
+      const existing = byTool.get(e.tool);
+      if (!existing || e.ts > existing.lastSeen) {
+        byTool.set(e.tool, {
+          count: (existing?.count || 0) + 1,
+          category: e.category,
+          lastSeen: e.ts
+        });
+      } else {
+        existing.count++;
+      }
+    }
+    const sorted = [...byTool.entries()].sort(
+      (a, b) => b[1].count - a[1].count
+    );
+    console.log(chalk.bold("Desire Path Summary"));
+    console.log(chalk.gray(`Total failures: ${entries.length}
+`));
+    const toolW = 30;
+    const countW = 7;
+    const catW = 16;
+    console.log(
+      chalk.gray(
+        `${"Tool".padEnd(toolW)} ${"Count".padStart(countW)} ${"Category".padEnd(catW)} Last Seen`
+      )
+    );
+    console.log(chalk.gray("-".repeat(toolW + countW + catW + 22)));
+    for (const [tool, data] of sorted) {
+      const catColor = data.category === "unknown_tool" ? chalk.red : data.category === "invalid_params" ? chalk.yellow : chalk.gray;
+      const lastDate = data.lastSeen.slice(0, 19).replace("T", " ");
+      console.log(
+        `${tool.padEnd(toolW)} ${String(data.count).padStart(countW)} ${catColor(data.category.padEnd(catW))} ${chalk.gray(lastDate)}`
+      );
+    }
+    const byCat = /* @__PURE__ */ new Map();
+    for (const e of entries) {
+      byCat.set(e.category, (byCat.get(e.category) || 0) + 1);
+    }
+    console.log(chalk.bold("\nBy Category:"));
+    for (const [cat, count] of [...byCat.entries()].sort(
+      (a, b) => b[1] - a[1]
+    )) {
+      console.log(`  ${cat}: ${count}`);
+    }
+  });
+  desires.command("list").description("Show recent failures with details").option("-l, --limit <n>", "Max entries to show", "20").option("-s, --since <epoch>", "Filter entries after this epoch (ms)").option("-u, --unknown-only", "Show only unknown_tool category").action(
+    (options) => {
+      const since = options.since ? parseInt(options.since, 10) : void 0;
+      let entries = loadEntries(since);
+      if (options.unknownOnly) {
+        entries = entries.filter((e) => e.category === "unknown_tool");
+      }
+      if (entries.length === 0) {
+        console.log(chalk.yellow("No desire path data found."));
+        console.log(chalk.gray(`  Logs dir: ${DESIRE_DIR}`));
+        return;
+      }
+      const limit = parseInt(options.limit, 10) || 20;
+      const recent = entries.sort((a, b) => b.ts.localeCompare(a.ts)).slice(0, limit);
+      console.log(
+        chalk.bold(`Recent Desire Paths (${recent.length}/${entries.length})`)
+      );
+      console.log("");
+      for (const e of recent) {
+        const catColor = e.category === "unknown_tool" ? chalk.red : e.category === "invalid_params" ? chalk.yellow : chalk.gray;
+        const ts = e.ts.slice(0, 19).replace("T", " ");
+        console.log(
+          `${chalk.gray(ts)} ${chalk.bold(e.tool)} ${catColor(`[${e.category}]`)}`
+        );
+        console.log(`  ${chalk.gray(e.error.slice(0, 120))}`);
+      }
+    }
+  );
+  return desires;
+}
+export {
+  createDesiresCommands
+};