@stackmemoryai/stackmemory 1.2.4 → 1.2.6

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

@@ -889,6 +889,25 @@ class ClaudeSkillsManager {
             };
         }
       }
+      case "theory": {
+        const { TheorySkill } = await import("./theory-skill.js");
+        const theorySkill = new TheorySkill(this.context);
+        switch (args[0]) {
+          case "show":
+            return theorySkill.show();
+          case "update":
+            return theorySkill.update(args.slice(1).join(" "));
+          case "init":
+            return theorySkill.init(args.slice(1).join(" "));
+          case "status":
+            return theorySkill.status();
+          default:
+            return {
+              success: false,
+              message: "Usage: theory show|init|update|status"
+            };
+        }
+      }
       case "linear-run": {
         if (!this.linearTaskRunner) {
           return {
@@ -931,7 +950,8 @@ class ClaudeSkillsManager {
       "dashboard",
       "api",
       "spec",
-      "agent"
+      "agent",
+      "theory"
     ];
     if (this.rlmOrchestrator) {
       skills.push("rlm", "lint");
@@ -1088,6 +1108,22 @@ Options:
 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 "theory":
+        return `
+/theory show
+/theory init "<problem statement>"
+/theory update "<full content>"
+/theory status
+
+Maintain a living THEORY.MD at repo root \u2014 a narrative operating theory:
+  show   \u2014 Display current THEORY.MD content
+  init   \u2014 Create THEORY.MD with scaffold sections
+  update \u2014 Overwrite THEORY.MD (validates length, warns on anti-patterns)
+  status \u2014 Show metadata: exists, line count, sections, last modified
+
+Sections: Problem, Operating Theory, Strategy, Key Discoveries, Open Questions
+Based on Theorist by @blader (MIT).
 `;
       case "linear-run":
         return `

package/dist/src/skills/theory-skill.js

@@ -0,0 +1,191 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { logger } from "../core/monitoring/logger.js";
+const THEORY_FILE = "THEORY.MD";
+const MIN_CONTENT_LENGTH = 100;
+const MAX_LINE_WARNING = 200;
+const TEMPLATE_SECTIONS = [
+  "## Problem",
+  "## Operating Theory",
+  "## Strategy",
+  "## Key Discoveries",
+  "## Open Questions"
+];
+function getGitRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function generateTemplate(problemStatement) {
+  return `# THEORY.MD
+
+## Problem
+
+${problemStatement}
+
+## Operating Theory
+
+_What is your current mental model of how this system works or should work?_
+
+## Strategy
+
+_What approach are you taking and why?_
+
+## Key Discoveries
+
+_What have you learned that changed your thinking?_
+
+## Open Questions
+
+_What don't you know yet? What assumptions need validation?_
+`;
+}
+class TheorySkill {
+  constructor(context) {
+    this.context = context;
+    this.rootDir = getGitRoot() || process.cwd();
+  }
+  rootDir;
+  get theoryPath() {
+    return path.join(this.rootDir, THEORY_FILE);
+  }
+  show() {
+    if (!fs.existsSync(this.theoryPath)) {
+      return {
+        success: false,
+        message: `No ${THEORY_FILE} found. Run \`theory init "<problem>"\` to create one.`
+      };
+    }
+    const content = fs.readFileSync(this.theoryPath, "utf-8");
+    return {
+      success: true,
+      message: content,
+      data: { path: this.theoryPath, length: content.length }
+    };
+  }
+  init(problemStatement) {
+    if (!problemStatement || problemStatement.trim().length === 0) {
+      return {
+        success: false,
+        message: "A problem statement is required to initialize THEORY.MD."
+      };
+    }
+    if (fs.existsSync(this.theoryPath)) {
+      return {
+        success: false,
+        message: `${THEORY_FILE} already exists at ${this.theoryPath}. Use \`theory update\` to modify it.`
+      };
+    }
+    const content = generateTemplate(problemStatement.trim());
+    fs.writeFileSync(this.theoryPath, content, "utf-8");
+    logger.info("Created THEORY.MD", { path: this.theoryPath });
+    return {
+      success: true,
+      message: `Created ${THEORY_FILE} at ${this.theoryPath}`,
+      data: { path: this.theoryPath, sections: TEMPLATE_SECTIONS }
+    };
+  }
+  update(content) {
+    if (!content || content.trim().length === 0) {
+      return { success: false, message: "Content is required for update." };
+    }
+    if (content.trim().length < MIN_CONTENT_LENGTH) {
+      return {
+        success: false,
+        message: `Content too short (${content.trim().length} chars). THEORY.MD should be at least ${MIN_CONTENT_LENGTH} characters to be meaningful.`
+      };
+    }
+    const warnings = [];
+    if (/\[[ x]\]/i.test(content)) {
+      warnings.push(
+        "Contains checkboxes \u2014 THEORY.MD is narrative, not a checklist."
+      );
+    }
+    if (/\d{4}-\d{2}-\d{2}/.test(content)) {
+      warnings.push(
+        "Contains dates \u2014 THEORY.MD captures current thinking, not a changelog."
+      );
+    }
+    const lineCount = content.split("\n").length;
+    if (lineCount > MAX_LINE_WARNING) {
+      warnings.push(
+        `${lineCount} lines is long. Consider distilling to keep THEORY.MD focused.`
+      );
+    }
+    fs.writeFileSync(this.theoryPath, content, "utf-8");
+    if (this.context.frameManager) {
+      try {
+        const frameId = this.context.frameManager.createFrame(
+          "write",
+          "theory-update",
+          { source: THEORY_FILE, length: content.length }
+        );
+        this.context.frameManager.addEvent(
+          "artifact",
+          {
+            type: "theory-update",
+            path: this.theoryPath,
+            length: content.length,
+            lineCount
+          },
+          frameId
+        );
+        this.context.frameManager.closeFrame(frameId, {
+          theory_updated: true
+        });
+      } catch (err) {
+        logger.warn("Failed to record theory update frame", { error: err });
+      }
+    }
+    logger.info("Updated THEORY.MD", {
+      path: this.theoryPath,
+      length: content.length
+    });
+    const message = warnings.length > 0 ? `Updated ${THEORY_FILE}. Warnings:
+${warnings.map((w) => `  - ${w}`).join("\n")}` : `Updated ${THEORY_FILE} (${lineCount} lines)`;
+    return {
+      success: true,
+      message,
+      data: { path: this.theoryPath, lineCount, warnings }
+    };
+  }
+  status() {
+    if (!fs.existsSync(this.theoryPath)) {
+      return {
+        success: true,
+        message: `No ${THEORY_FILE} found.`,
+        data: { exists: false }
+      };
+    }
+    const content = fs.readFileSync(this.theoryPath, "utf-8");
+    const lines = content.split("\n");
+    const stat = fs.statSync(this.theoryPath);
+    const sections = TEMPLATE_SECTIONS.filter((s) => content.includes(s));
+    return {
+      success: true,
+      message: `${THEORY_FILE}: ${lines.length} lines, ${sections.length}/${TEMPLATE_SECTIONS.length} sections`,
+      data: {
+        exists: true,
+        path: this.theoryPath,
+        lineCount: lines.length,
+        charCount: content.length,
+        sections,
+        totalSections: TEMPLATE_SECTIONS.length,
+        lastModified: stat.mtime.toISOString()
+      }
+    };
+  }
+}
+export {
+  TheorySkill
+};

package/dist/src/utils/hook-installer.js

@@ -39,6 +39,14 @@ const CANONICAL_HOOKS = [
     timeout: 2,
     commandPrefix: "node",
     required: true
+  },
+  {
+    scriptName: "theory-capture.js",
+    eventType: "PostToolUse",
+    matcher: "Edit|Write|MultiEdit",
+    timeout: 2,
+    commandPrefix: "node",
+    required: false
   }
 ];
 const DEAD_HOOKS = ["sms-response-handler.js"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "1.2.4",
-  "description": "Project-scoped memory for AI coding tools. Durable context across sessions with MCP integration, frames, smart retrieval, Claude Code skills, and automatic hooks.",
+  "version": "1.2.6",
+  "description": "Project-scoped memory for AI coding tools. Durable context across sessions with 32 MCP tools, FTS5 search, Claude/Codex/OpenCode wrappers, Linear sync, automatic hooks, and log analysis.",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"

package/templates/claude-hooks/theory-capture.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * Theory Capture Hook (PostToolUse)
+ *
+ * Detects writes to THEORY.MD and:
+ *   1. Caches metadata to .stackmemory/theory-cache.json
+ *   2. Fire-and-forget: records a StackMemory frame via CLI
+ *
+ * Must complete in <50ms -- file I/O only, CLI exec is detached.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+
+const WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit'];
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function safeWriteFile(filePath, content) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, filePath);
+}
+
+function isTheoryPath(filePath) {
+  if (!filePath) return false;
+  const lower = filePath.toLowerCase();
+  return (
+    lower.endsWith('/theory.md') ||
+    lower.endsWith('\\theory.md') ||
+    lower === 'theory.md'
+  );
+}
+
+async function readInput() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return JSON.parse(input);
+}
+
+async function main() {
+  try {
+    const input = await readInput();
+    const { tool_name, tool_input } = input;
+
+    // Only care about file-write tools
+    if (!WRITE_TOOLS.includes(tool_name)) return;
+
+    const fp = tool_input?.file_path || '';
+    if (!isTheoryPath(fp)) return;
+
+    // Read current content
+    let content;
+    try {
+      content = fs.readFileSync(fp, 'utf-8');
+    } catch {
+      return; // File doesn't exist or unreadable
+    }
+
+    // Cache metadata for next session start
+    const cacheDir = path.join(process.cwd(), '.stackmemory');
+    ensureDir(cacheDir);
+
+    const lineCount = content.split('\n').length;
+    safeWriteFile(
+      path.join(cacheDir, 'theory-cache.json'),
+      JSON.stringify({
+        path: fp,
+        timestamp: new Date().toISOString(),
+        hash: crypto.createHash('md5').update(content).digest('hex'),
+        lineCount,
+      })
+    );
+
+    // Fire-and-forget: record as frame via CLI
+    const child = spawn(
+      'stackmemory',
+      ['context', 'add', 'artifact', `THEORY.MD updated (${lineCount} lines)`],
+      {
+        cwd: process.cwd(),
+        stdio: 'ignore',
+        detached: true,
+      }
+    );
+    child.unref();
+  } catch {
+    // Silent fail -- never block the agent
+  }
+}
+
+main();

package/dist/src/hooks/graphiti-hooks.js

@@ -1,253 +0,0 @@
-import { fileURLToPath as __fileURLToPath } from 'url';
-import { dirname as __pathDirname } from 'path';
-const __filename = __fileURLToPath(import.meta.url);
-const __dirname = __pathDirname(__filename);
-import { logger } from "../core/monitoring/logger.js";
-import { GraphitiClient } from "../integrations/graphiti/client.js";
-import { DEFAULT_GRAPHITI_CONFIG } from "../integrations/graphiti/config.js";
-class GraphitiHooks {
-  client;
-  config;
-  constructor(config = {}) {
-    this.config = { ...DEFAULT_GRAPHITI_CONFIG, ...config };
-    this.client = new GraphitiClient(this.config);
-  }
-  register(emitter) {
-    if (!this.config.enabled) {
-      logger.debug("Graphiti hooks disabled");
-      return;
-    }
-    emitter.registerHandler("session_start", this.onSessionStart.bind(this));
-    emitter.registerHandler("file_change", this.onFileChange.bind(this));
-    emitter.registerHandler("session_end", this.onSessionEnd.bind(this));
-    emitter.registerHandler("input_idle", this.onInputIdle.bind(this));
-    emitter.registerHandler("context_switch", this.onContextSwitch.bind(this));
-    emitter.registerHandler("prompt_submit", this.onPromptSubmit.bind(this));
-    emitter.registerHandler("tool_use", this.onToolUse.bind(this));
-    emitter.registerHandler(
-      "suggestion_ready",
-      this.onSuggestionReady.bind(this)
-    );
-    emitter.registerHandler("agent_start", this.onAgentStart.bind(this));
-    emitter.registerHandler("agent_complete", this.onAgentComplete.bind(this));
-    emitter.registerHandler("agent_error", this.onAgentError.bind(this));
-    logger.info("Graphiti hooks registered", {
-      endpoint: this.config.endpoint,
-      backend: this.config.backend,
-      maxHops: this.config.maxHops
-    });
-  }
-  async onSessionStart(event) {
-    try {
-      const status = await this.client.getStatus();
-      if (!status.connected) {
-        logger.warn("Graphiti not available - operating in degraded mode");
-        return;
-      }
-      const episode = {
-        type: "session_start",
-        content: event.data || {},
-        timestamp: Date.now(),
-        source: "stackmemory",
-        metadata: { severity: "info" }
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti session_start failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onFileChange(event) {
-    const fileEvent = event;
-    try {
-      const episode = {
-        type: "file_change",
-        content: {
-          path: fileEvent.data.path,
-          changeType: fileEvent.data.changeType,
-          size: typeof fileEvent.data.content === "string" ? fileEvent.data.content.length : void 0
-        },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti file_change episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onSessionEnd(event) {
-    try {
-      const episode = {
-        type: "session_end",
-        content: event.data || {},
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti session_end failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onInputIdle(event) {
-    const idle = event;
-    try {
-      const episode = {
-        type: "input_idle",
-        content: {
-          idleDuration: idle.data.idleDuration,
-          lastInput: idle.data.lastInput
-        },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti input_idle episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onContextSwitch(event) {
-    const ctx = event;
-    try {
-      const episode = {
-        type: "context_switch",
-        content: {
-          fromBranch: ctx.data.fromBranch,
-          toBranch: ctx.data.toBranch,
-          fromProject: ctx.data.fromProject,
-          toProject: ctx.data.toProject
-        },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti context_switch episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onPromptSubmit(event) {
-    try {
-      const episode = {
-        type: "prompt_submit",
-        content: event.data || {},
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti prompt_submit episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onToolUse(event) {
-    try {
-      const episode = {
-        type: "tool_use",
-        content: event.data || {},
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti tool_use episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onSuggestionReady(event) {
-    const suggestion = event;
-    try {
-      const episode = {
-        type: "suggestion_ready",
-        content: {
-          source: suggestion.data.source,
-          confidence: suggestion.data.confidence,
-          preview: suggestion.data.preview
-        },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti suggestion_ready episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onAgentStart(event) {
-    const e = event;
-    try {
-      const episode = {
-        type: "agent_start",
-        content: { agentType: e.data.agentType, task: e.data.task },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti agent_start episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onAgentComplete(event) {
-    const e = event;
-    try {
-      const episode = {
-        type: "agent_complete",
-        content: { ...e.data },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti agent_complete episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  async onAgentError(event) {
-    const e = event;
-    try {
-      const episode = {
-        type: "agent_error",
-        content: { agentType: e.data.agentType, error: e.data.error },
-        timestamp: Date.now(),
-        source: "stackmemory"
-      };
-      await this.client.upsertEpisode(episode);
-    } catch (error) {
-      logger.debug("Graphiti agent_error episode failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  // Expose a simple temporal query helper for future MCP tooling
-  async buildTemporalContext(query = {}) {
-    const now = Date.now();
-    const q = {
-      query: query.query || void 0,
-      entityTypes: query.entityTypes || void 0,
-      relationTypes: query.relationTypes || void 0,
-      validFrom: query.validFrom ?? now - 1e3 * 60 * 60 * 24 * 30,
-      // 30d default
-      validTo: query.validTo ?? now,
-      maxHops: query.maxHops ?? this.config.maxHops,
-      k: query.k ?? 20,
-      rerank: query.rerank ?? true
-    };
-    return this.client.queryTemporal(q);
-  }
-}
-export {
-  GraphitiHooks
-};