@stackmemoryai/stackmemory 1.2.2 → 1.2.6

package/templates/claude-hooks/cord-trace.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+/**
+ * Cord Trace Hook (PostToolUse)
+ *
+ * Fires on every cord_* MCP tool call, logging metrics to a JSONL trace file
+ * and accumulating session metrics in a per-session state file.
+ *
+ * Trace dir: ~/.stackmemory/cord-traces/
+ *   cord-trace-{date}.jsonl      — append-only trace log
+ *   cord-state-{session_id}.json — running session metrics
+ *
+ * Must complete in <50ms — pure file I/O only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HOME = process.env.HOME || '/tmp';
+const TRACE_DIR = path.join(HOME, '.stackmemory', 'cord-traces');
+const CORD_TOOLS = new Set([
+  'cord_spawn',
+  'cord_fork',
+  'cord_complete',
+  'cord_ask',
+  'cord_tree',
+]);
+
+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);
+}
+
+/**
+ * Extract the cord tool name from the full MCP tool name.
+ * e.g. "mcp__stackmemory-refactored__cord_spawn" -> "cord_spawn"
+ */
+function extractCordTool(toolName) {
+  if (!toolName) return null;
+  for (const t of CORD_TOOLS) {
+    if (toolName.endsWith(t)) return t;
+  }
+  return null;
+}
+
+function loadState(sessionId) {
+  const stateFile = path.join(TRACE_DIR, `cord-state-${sessionId}.json`);
+  try {
+    if (fs.existsSync(stateFile)) {
+      return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return {
+    session_id: sessionId,
+    started: new Date().toISOString(),
+    tool_counts: {},
+    task_ids: [],
+    context_modes: {},
+    unblocked_total: 0,
+    max_depth: 0,
+    completion_rate: 0,
+    ask_count: 0,
+    completed_count: 0,
+    spawn_fork_count: 0,
+  };
+}
+
+function saveState(sessionId, state) {
+  const stateFile = path.join(TRACE_DIR, `cord-state-${sessionId}.json`);
+  safeWriteFile(stateFile, JSON.stringify(state, null, 2));
+}
+
+function appendTrace(entry) {
+  const date = new Date().toISOString().slice(0, 10);
+  const traceFile = path.join(TRACE_DIR, `cord-trace-${date}.jsonl`);
+  fs.appendFileSync(traceFile, JSON.stringify(entry) + '\n');
+}
+
+/**
+ * Safely extract metadata from tool_response.
+ * MCP tool responses come as { content: [{ type, text }], metadata: {...} }.
+ * The hook receives tool_response which may be the raw MCP result or a string.
+ */
+function extractMetadata(toolResponse) {
+  if (!toolResponse) return {};
+  if (typeof toolResponse === 'string') {
+    try {
+      const parsed = JSON.parse(toolResponse);
+      return parsed.metadata || parsed;
+    } catch {
+      return {};
+    }
+  }
+  if (toolResponse.metadata) return toolResponse.metadata;
+  return toolResponse;
+}
+
+function updateState(state, cordTool, toolInput, toolResponse) {
+  // Increment tool count
+  state.tool_counts[cordTool] = (state.tool_counts[cordTool] || 0) + 1;
+
+  const meta = extractMetadata(toolResponse);
+
+  switch (cordTool) {
+    case 'cord_spawn':
+    case 'cord_fork': {
+      state.spawn_fork_count++;
+
+      // Track context mode
+      const mode = meta.context_mode || cordTool.replace('cord_', '');
+      state.context_modes[mode] = (state.context_modes[mode] || 0) + 1;
+
+      // Track task ID
+      if (meta.task_id && !state.task_ids.includes(meta.task_id)) {
+        state.task_ids.push(meta.task_id);
+      }
+
+      // Track max depth
+      const depth = meta.depth ?? 0;
+      if (depth > state.max_depth) {
+        state.max_depth = depth;
+      }
+      break;
+    }
+
+    case 'cord_complete': {
+      state.completed_count++;
+
+      // Count unblocked tasks
+      const unblocked = meta.unblocked;
+      if (Array.isArray(unblocked)) {
+        state.unblocked_total += unblocked.length;
+      }
+
+      // Update completion rate
+      if (state.spawn_fork_count > 0) {
+        state.completion_rate = +(
+          state.completed_count / state.spawn_fork_count
+        ).toFixed(3);
+      }
+      break;
+    }
+
+    case 'cord_ask': {
+      state.ask_count++;
+
+      // Track task ID
+      if (meta.task_id && !state.task_ids.includes(meta.task_id)) {
+        state.task_ids.push(meta.task_id);
+      }
+
+      // Track context mode
+      state.context_modes['ask'] = (state.context_modes['ask'] || 0) + 1;
+      break;
+    }
+
+    case 'cord_tree':
+      // Read-only — no state change
+      break;
+  }
+}
+
+function buildMetricsSummary(state) {
+  return {
+    task_count: state.task_ids.length,
+    active: state.spawn_fork_count - state.completed_count,
+    completed: state.completed_count,
+    asks: state.ask_count,
+  };
+}
+
+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, tool_response, session_id } = input;
+
+    const cordTool = extractCordTool(tool_name);
+    if (!cordTool) return; // Not a cord tool, shouldn't happen given matcher
+
+    const sid =
+      session_id || process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+
+    ensureDir(TRACE_DIR);
+
+    // Load and update state
+    const state = loadState(sid);
+    updateState(state, cordTool, tool_input, tool_response);
+
+    // Build trace entry
+    const entry = {
+      ts: new Date().toISOString(),
+      session_id: sid,
+      cwd: input.cwd || process.cwd(),
+      tool: cordTool,
+      input: tool_input || {},
+      response: extractMetadata(tool_response),
+      metrics: buildMetricsSummary(state),
+    };
+
+    // Append trace + save state
+    appendTrace(entry);
+    saveState(sid, state);
+  } catch {
+    // Silent fail — never block the agent
+  }
+}
+
+main();

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/core/config/storage-config.js

@@ -1,114 +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 { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-const DEFAULT_STORAGE_CONFIG = {
-  mode: "sqlite",
-  chromadb: {
-    enabled: false
-  }
-};
-const STACKMEMORY_DIR = join(homedir(), ".stackmemory");
-const CONFIG_FILE = join(STACKMEMORY_DIR, "storage-config.json");
-function loadStorageConfig() {
-  try {
-    if (existsSync(CONFIG_FILE)) {
-      const content = readFileSync(CONFIG_FILE, "utf-8");
-      const config = JSON.parse(content);
-      return {
-        mode: config.mode || DEFAULT_STORAGE_CONFIG.mode,
-        chromadb: {
-          ...DEFAULT_STORAGE_CONFIG.chromadb,
-          ...config.chromadb
-        }
-      };
-    }
-  } catch (error) {
-    console.warn("Failed to load storage config, using defaults:", error);
-  }
-  return DEFAULT_STORAGE_CONFIG;
-}
-function saveStorageConfig(config) {
-  try {
-    if (!existsSync(STACKMEMORY_DIR)) {
-      mkdirSync(STACKMEMORY_DIR, { recursive: true });
-    }
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
-  } catch (error) {
-    console.error("Failed to save storage config:", error);
-    throw error;
-  }
-}
-function isChromaDBEnabled() {
-  const config = loadStorageConfig();
-  if (!config.chromadb.enabled) {
-    return false;
-  }
-  const apiKey = config.chromadb.apiKey || process.env["CHROMADB_API_KEY"];
-  if (!apiKey) {
-    return false;
-  }
-  return true;
-}
-function getStorageMode() {
-  const config = loadStorageConfig();
-  if (config.mode === "hybrid" && !isChromaDBEnabled()) {
-    return "sqlite";
-  }
-  return config.mode;
-}
-function getChromaDBConfig() {
-  if (!isChromaDBEnabled()) {
-    return null;
-  }
-  const config = loadStorageConfig();
-  const apiKey = config.chromadb.apiKey || process.env["CHROMADB_API_KEY"];
-  const apiUrl = config.chromadb.apiUrl || process.env["CHROMADB_API_URL"] || "https://api.trychroma.com";
-  return {
-    enabled: true,
-    apiKey,
-    apiUrl,
-    tenant: config.chromadb.tenant || process.env["CHROMADB_TENANT"] || "default_tenant",
-    database: config.chromadb.database || process.env["CHROMADB_DATABASE"] || "default_database"
-  };
-}
-function enableChromaDB(chromaConfig) {
-  const config = loadStorageConfig();
-  config.mode = "hybrid";
-  config.chromadb = {
-    enabled: true,
-    apiKey: chromaConfig.apiKey,
-    apiUrl: chromaConfig.apiUrl || "https://api.trychroma.com",
-    tenant: chromaConfig.tenant || "default_tenant",
-    database: chromaConfig.database || "default_database"
-  };
-  saveStorageConfig(config);
-}
-function disableChromaDB() {
-  const config = loadStorageConfig();
-  config.mode = "sqlite";
-  config.chromadb = {
-    enabled: false
-  };
-  saveStorageConfig(config);
-}
-function getStorageModeDescription() {
-  const mode = getStorageMode();
-  if (mode === "hybrid") {
-    return "Hybrid (SQLite + ChromaDB for semantic search and cloud backup)";
-  }
-  return "SQLite (local storage only, fast, no external dependencies)";
-}
-export {
-  disableChromaDB,
-  enableChromaDB,
-  getChromaDBConfig,
-  getStorageMode,
-  getStorageModeDescription,
-  isChromaDBEnabled,
-  loadStorageConfig,
-  saveStorageConfig
-};