@stackmemoryai/stackmemory 1.2.0 → 1.2.2

package/dist/src/integrations/mcp/tool-definitions.js

@@ -13,7 +13,8 @@ class MCPToolDefinitions {
       ...this.getLinearTools(),
       ...this.getTraceTools(),
       ...this.getDiscoveryTools(),
-      ...this.getEditTools()
+      ...this.getEditTools(),
+      ...this.getGraphitiTools()
     ];
   }
   /**
@@ -705,6 +706,55 @@ class MCPToolDefinitions {
       }
     ];
   }
+  /**
+   * Graphiti knowledge graph tools
+   */
+  getGraphitiTools() {
+    return [
+      {
+        name: "graphiti_status",
+        description: "Check Graphiti temporal knowledge graph connection status",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
+      {
+        name: "graphiti_query",
+        description: "Query the Graphiti temporal knowledge graph for entities, relations, and episodes",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Semantic text query"
+            },
+            entityTypes: {
+              type: "array",
+              items: { type: "string" },
+              description: 'Entity types to filter (e.g., ["Person", "File", "Issue"])'
+            },
+            validFrom: {
+              type: "number",
+              description: "Start of time window (epoch ms)"
+            },
+            validTo: {
+              type: "number",
+              description: "End of time window (epoch ms)"
+            },
+            maxHops: {
+              type: "number",
+              description: "Graph traversal depth (default 2)"
+            },
+            k: {
+              type: "number",
+              description: "Top-k results (default 20)"
+            }
+          }
+        }
+      }
+    ];
+  }
   /**
    * Get tool definition by name
    */
@@ -728,6 +778,8 @@ class MCPToolDefinitions {
         return this.getDiscoveryTools();
       case "edit":
         return this.getEditTools();
+      case "graphiti":
+        return this.getGraphitiTools();
       default:
         return [];
     }

package/dist/src/skills/claude-skills.js

@@ -948,6 +948,25 @@ class ClaudeSkillsManager {
             };
         }
       }
+      case "agent": {
+        const { ParallelAgentSkill } = await import("./parallel-agent-skill.js");
+        const agentSkill = new ParallelAgentSkill(this.context);
+        const sub = args[0];
+        const agentOpts = { timeout: options?.timeout };
+        switch (sub) {
+          case "research":
+            return agentSkill.research(args.slice(1).join(" "), agentOpts);
+          case "maintain":
+            return agentSkill.maintain(args.slice(1).join(" "), agentOpts);
+          case "spec-run":
+            return agentSkill.specRun(args[1], agentOpts);
+          default:
+            return {
+              success: false,
+              message: `Unknown: agent ${sub}. Use: research|maintain|spec-run`
+            };
+        }
+      }
       case "linear-run": {
         if (!this.linearTaskRunner) {
           return {
@@ -983,7 +1002,15 @@ class ClaudeSkillsManager {
     }
   }
   getAvailableSkills() {
-    const skills = ["handoff", "checkpoint", "dig", "dashboard", "api", "spec"];
+    const skills = [
+      "handoff",
+      "checkpoint",
+      "dig",
+      "dashboard",
+      "api",
+      "spec",
+      "agent"
+    ];
     if (this.repoIngestionSkill) {
       skills.push("repo");
     }
@@ -1145,6 +1172,24 @@ Examples:
   /spec dev-spec
   /spec update prompt-plan "Initialize repository and tooling"
   /spec validate prompt-plan
+`;
+      case "agent":
+        return `
+/agent research "How does the FTS5 search work?"
+/agent maintain "Fix the deprecation warning in webhook.ts"
+/agent spec-run docs/specs/my-feature.md
+
+Parallel agent skill (Willison patterns) \u2014 spawn isolated Claude agents:
+  research  \u2014 Explore codebase, save findings as a frame (read-only)
+  maintain  \u2014 Low-stakes fix, produces a .patch file
+  spec-run  \u2014 Implement a spec on a branch, validate with lint+test+build
+
+Options:
+  --timeout <ms>  Agent timeout in milliseconds (default: 300000)
+
+Each agent runs in a disposable /tmp workspace (git clone --depth=1).
+Patches: git apply .stackmemory/patches/<file>.patch
+Spec branches: cd /tmp/sm-spec-* && git log --oneline
 `;
       case "linear-run":
         return `

package/dist/src/skills/parallel-agent-skill.js

@@ -0,0 +1,514 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { logger } from "../core/monitoring/logger.js";
+import { hookEmitter } from "../hooks/events.js";
+const DEFAULT_TIMEOUT = 5 * 60 * 1e3;
+function spawnAgent(prompt, opts) {
+  return new Promise((resolve, reject) => {
+    let workDir;
+    try {
+      workDir = fs.mkdtempSync(path.join("/tmp", `${opts.prefix}-`));
+    } catch (err) {
+      return reject(
+        new Error(`Failed to create temp dir: ${err.message}`)
+      );
+    }
+    try {
+      execSync(`git clone --depth=1 "${opts.repoRoot}" "${workDir}"`, {
+        stdio: "pipe",
+        timeout: 3e4
+      });
+    } catch (err) {
+      cleanupDir(workDir);
+      return reject(new Error(`git clone failed: ${err.message}`));
+    }
+    const child = spawn("claude", ["--print"], {
+      cwd: workDir,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGTERM");
+    }, opts.timeout);
+    if (child.stdout) {
+      child.stdout.on("data", (d) => stdout += d);
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (d) => stderr += d);
+    }
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode: code, workDir, timedOut: killed });
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        stdout,
+        stderr: err.message,
+        exitCode: 1,
+        workDir,
+        timedOut: false
+      });
+    });
+    if (child.stdin) {
+      child.stdin.write(prompt);
+      child.stdin.end();
+    }
+  });
+}
+function cleanupDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
+class ParallelAgentSkill {
+  constructor(context) {
+    this.context = context;
+    this.repoRoot = process.cwd();
+  }
+  repoRoot;
+  /**
+   * Research — explore codebase, save findings as a frame.
+   */
+  async research(question, options) {
+    if (!question?.trim()) {
+      return { success: false, message: "Question is required" };
+    }
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const prompt = [
+      "Explore this codebase and answer the following question.",
+      "Do NOT modify any files. Output your findings as structured markdown.",
+      "",
+      `Question: ${question}`
+    ].join("\n");
+    let result;
+    try {
+      hookEmitter.emitHook({
+        type: "agent_start",
+        timestamp: Date.now(),
+        data: { agentType: "research", workDir: "", task: question }
+      }).catch(() => {
+      });
+      result = await spawnAgent(prompt, {
+        prefix: "sm-research",
+        timeout,
+        repoRoot: this.repoRoot
+      });
+    } catch (err) {
+      const msg = err.message;
+      hookEmitter.emitHook({
+        type: "agent_error",
+        timestamp: Date.now(),
+        data: { agentType: "research", error: msg }
+      }).catch(() => {
+      });
+      return {
+        success: false,
+        message: `Agent failed to start: ${msg}`
+      };
+    }
+    try {
+      if (result.timedOut) {
+        hookEmitter.emitHook({
+          type: "agent_complete",
+          timestamp: Date.now(),
+          data: {
+            agentType: "research",
+            workDir: result.workDir,
+            exitCode: result.exitCode,
+            timedOut: true
+          }
+        }).catch(() => {
+        });
+        return {
+          success: false,
+          message: `Research agent timed out after ${timeout / 1e3}s`,
+          data: { partial: result.stdout.slice(0, 2e3) }
+        };
+      }
+      const findings = result.stdout || "(no output)";
+      let frameId;
+      try {
+        frameId = await this.saveFrame("research", question, findings);
+      } catch (err) {
+        logger.warn("Failed to save research frame:", err);
+      }
+      hookEmitter.emitHook({
+        type: "agent_complete",
+        timestamp: Date.now(),
+        data: {
+          agentType: "research",
+          workDir: result.workDir,
+          exitCode: result.exitCode,
+          timedOut: false,
+          frameId
+        }
+      }).catch(() => {
+      });
+      return {
+        success: true,
+        message: `Research complete${frameId ? ` (frame: ${frameId})` : ""}`,
+        data: { findings, frameId, exitCode: result.exitCode }
+      };
+    } finally {
+      cleanupDir(result.workDir);
+    }
+  }
+  /**
+   * Maintain — low-stakes fix, produces a .patch file.
+   */
+  async maintain(task, options) {
+    if (!task?.trim()) {
+      return { success: false, message: "Task description is required" };
+    }
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const prompt = [
+      task,
+      "",
+      "After making changes, verify by running: npm run lint && npm run test:run"
+    ].join("\n");
+    let result;
+    try {
+      hookEmitter.emitHook({
+        type: "agent_start",
+        timestamp: Date.now(),
+        data: { agentType: "maintain", workDir: "", task }
+      }).catch(() => {
+      });
+      result = await spawnAgent(prompt, {
+        prefix: "sm-maint",
+        timeout,
+        repoRoot: this.repoRoot
+      });
+    } catch (err) {
+      const msg = err.message;
+      hookEmitter.emitHook({
+        type: "agent_error",
+        timestamp: Date.now(),
+        data: { agentType: "maintain", error: msg }
+      }).catch(() => {
+      });
+      return {
+        success: false,
+        message: `Agent failed to start: ${msg}`
+      };
+    }
+    try {
+      if (result.timedOut) {
+        hookEmitter.emitHook({
+          type: "agent_complete",
+          timestamp: Date.now(),
+          data: {
+            agentType: "maintain",
+            workDir: result.workDir,
+            exitCode: result.exitCode,
+            timedOut: true
+          }
+        }).catch(() => {
+        });
+        return {
+          success: false,
+          message: `Maintenance agent timed out after ${timeout / 1e3}s`,
+          data: { partial: result.stdout.slice(0, 2e3) }
+        };
+      }
+      let diff = "";
+      try {
+        diff = execSync("git diff HEAD", {
+          cwd: result.workDir,
+          encoding: "utf-8",
+          timeout: 1e4
+        });
+      } catch {
+      }
+      if (!diff.trim()) {
+        hookEmitter.emitHook({
+          type: "agent_complete",
+          timestamp: Date.now(),
+          data: {
+            agentType: "maintain",
+            workDir: result.workDir,
+            exitCode: result.exitCode,
+            timedOut: false
+          }
+        }).catch(() => {
+        });
+        return {
+          success: false,
+          message: "Agent made no changes (empty diff)",
+          data: { output: result.stdout.slice(0, 2e3) }
+        };
+      }
+      let validated = false;
+      try {
+        execSync("npm run lint", {
+          cwd: result.workDir,
+          stdio: "pipe",
+          timeout: 6e4
+        });
+        validated = true;
+      } catch {
+      }
+      const patchDir = path.join(this.repoRoot, ".stackmemory", "patches");
+      fs.mkdirSync(patchDir, { recursive: true });
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+      const slug = slugify(task);
+      const patchFile = `${timestamp}-${slug}.patch`;
+      const patchPath = path.join(patchDir, patchFile);
+      fs.writeFileSync(patchPath, diff);
+      const diffLines = diff.split("\n");
+      const filesChanged = diffLines.filter(
+        (l) => l.startsWith("diff --git")
+      ).length;
+      const additions = diffLines.filter((l) => /^\+[^+]/.test(l)).length;
+      const deletions = diffLines.filter((l) => /^-[^-]/.test(l)).length;
+      hookEmitter.emitHook({
+        type: "agent_complete",
+        timestamp: Date.now(),
+        data: {
+          agentType: "maintain",
+          workDir: result.workDir,
+          exitCode: result.exitCode,
+          timedOut: false,
+          patchPath,
+          validated
+        }
+      }).catch(() => {
+      });
+      return {
+        success: true,
+        message: `Patch saved: ${patchFile}${validated ? "" : " (lint failed)"}`,
+        data: {
+          patchPath,
+          validated,
+          filesChanged,
+          additions,
+          deletions,
+          output: result.stdout.slice(0, 2e3)
+        },
+        action: `Apply with: git apply ${patchPath}`
+      };
+    } finally {
+      cleanupDir(result.workDir);
+    }
+  }
+  /**
+   * SpecRun — implement a spec file on a branch, validate.
+   */
+  async specRun(specPath, options) {
+    if (!specPath?.trim()) {
+      return { success: false, message: "Spec file path is required" };
+    }
+    const absSpec = path.isAbsolute(specPath) ? specPath : path.join(this.repoRoot, specPath);
+    if (!fs.existsSync(absSpec)) {
+      return { success: false, message: `Spec file not found: ${specPath}` };
+    }
+    const specContent = fs.readFileSync(absSpec, "utf-8");
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const prompt = [
+      "Implement the following specification. Follow it precisely.",
+      "",
+      "--- SPEC START ---",
+      specContent,
+      "--- SPEC END ---"
+    ].join("\n");
+    let workDir;
+    try {
+      workDir = fs.mkdtempSync(path.join("/tmp", "sm-spec-"));
+    } catch (err) {
+      return {
+        success: false,
+        message: `Failed to create temp dir: ${err.message}`
+      };
+    }
+    try {
+      execSync(`git clone --depth=1 "${this.repoRoot}" "${workDir}"`, {
+        stdio: "pipe",
+        timeout: 3e4
+      });
+    } catch (err) {
+      const msg = err.message;
+      cleanupDir(workDir);
+      hookEmitter.emitHook({
+        type: "agent_error",
+        timestamp: Date.now(),
+        data: { agentType: "spec-run", error: msg, workDir }
+      }).catch(() => {
+      });
+      return {
+        success: false,
+        message: `git clone failed: ${msg}`
+      };
+    }
+    const branchName = `agent/spec-${Date.now()}`;
+    try {
+      execSync(`git checkout -b "${branchName}"`, {
+        cwd: workDir,
+        stdio: "pipe",
+        timeout: 5e3
+      });
+    } catch (err) {
+      const msg = err.message;
+      cleanupDir(workDir);
+      hookEmitter.emitHook({
+        type: "agent_error",
+        timestamp: Date.now(),
+        data: { agentType: "spec-run", error: msg, workDir }
+      }).catch(() => {
+      });
+      return {
+        success: false,
+        message: `Failed to create branch: ${msg}`
+      };
+    }
+    hookEmitter.emitHook({
+      type: "agent_start",
+      timestamp: Date.now(),
+      data: { agentType: "spec-run", workDir, task: specPath }
+    }).catch(() => {
+    });
+    const child = spawn("claude", ["--print"], {
+      cwd: workDir,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const agentDone = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        killed = true;
+        child.kill("SIGTERM");
+      }, timeout);
+      if (child.stdout) {
+        child.stdout.on("data", (d) => stdout += d);
+      }
+      if (child.stderr) {
+        child.stderr.on("data", (d) => stderr += d);
+      }
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stdout, stderr, exitCode: code, timedOut: killed });
+      });
+      child.on("error", (err) => {
+        clearTimeout(timer);
+        resolve({
+          stdout,
+          stderr: err.message,
+          exitCode: 1,
+          timedOut: false
+        });
+      });
+    });
+    if (child.stdin) {
+      child.stdin.write(prompt);
+      child.stdin.end();
+    }
+    const agentResult = await agentDone;
+    if (agentResult.timedOut) {
+      return {
+        success: false,
+        message: `Spec agent timed out after ${timeout / 1e3}s`,
+        data: {
+          workDir,
+          branch: branchName,
+          partial: agentResult.stdout.slice(0, 2e3)
+        }
+      };
+    }
+    const validation = { lint: false, test: false, build: false };
+    try {
+      execSync("npm run lint", {
+        cwd: workDir,
+        stdio: "pipe",
+        timeout: 6e4
+      });
+      validation.lint = true;
+    } catch {
+    }
+    try {
+      execSync("npm run test:run", {
+        cwd: workDir,
+        stdio: "pipe",
+        timeout: 12e4
+      });
+      validation.test = true;
+    } catch {
+    }
+    try {
+      execSync("npm run build", {
+        cwd: workDir,
+        stdio: "pipe",
+        timeout: 6e4
+      });
+      validation.build = true;
+    } catch {
+    }
+    let diffStat = "";
+    try {
+      diffStat = execSync("git diff --stat HEAD~1", {
+        cwd: workDir,
+        encoding: "utf-8",
+        timeout: 5e3
+      });
+    } catch {
+    }
+    const allPassed = validation.lint && validation.test && validation.build;
+    hookEmitter.emitHook({
+      type: "agent_complete",
+      timestamp: Date.now(),
+      data: {
+        agentType: "spec-run",
+        workDir,
+        exitCode: agentResult.exitCode,
+        timedOut: false,
+        branch: branchName,
+        validation
+      }
+    }).catch(() => {
+    });
+    return {
+      success: allPassed,
+      message: allPassed ? `Spec implemented on branch ${branchName}` : `Spec implemented but validation failed on branch ${branchName}`,
+      data: {
+        workDir,
+        branch: branchName,
+        validation,
+        diffStat: diffStat.trim(),
+        output: agentResult.stdout.slice(0, 2e3)
+      },
+      action: allPassed ? `Review: cd ${workDir} && git log --oneline` : `Inspect: cd ${workDir} && git diff`
+    };
+  }
+  async saveFrame(type, query, content) {
+    const db = this.context.database;
+    if (!db) return void 0;
+    const frameId = await db.createFrame({
+      run_id: `agent-${Date.now()}`,
+      project_id: this.context.projectId,
+      type,
+      name: `Agent ${type}: ${query.slice(0, 60)}`,
+      state: "completed",
+      inputs: { query, agentType: type },
+      digest_text: content
+    });
+    return frameId;
+  }
+}
+export {
+  ParallelAgentSkill
+};