@stackmemoryai/stackmemory 1.2.0 → 1.2.2

package/templates/claude-hooks/auto-checkpoint.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-Checkpoint Hook (PostToolUse)
+ *
+ * Counts tool calls per project session. Every 25 calls, writes a lightweight
+ * checkpoint to ~/.stackmemory/checkpoints/{project-hash}/latest.json.
+ * Must complete in <50ms -- pure file I/O only.
+ *
+ * State is keyed per-session (process.ppid) to avoid race conditions
+ * when multiple Claude instances run concurrently.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const CHECKPOINT_INTERVAL = 25;
+const SAVE_INTERVAL = 5;
+const MAX_RECENT_TOOLS = 20;
+const MAX_FILES_TRACKED = 50;
+const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+const HOME = process.env.HOME || '/tmp';
+const SESSION_ID = process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+const STATE_FILE = path.join(
+  HOME,
+  '.stackmemory',
+  `checkpoint-state-${SESSION_ID}.json`
+);
+
+function projectHash(cwd) {
+  return crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
+}
+
+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 loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+      const cutoff = Date.now() - TTL_MS;
+      for (const [cwd, proj] of Object.entries(state.projects)) {
+        if (
+          proj.sessionStart &&
+          new Date(proj.sessionStart).getTime() < cutoff
+        ) {
+          delete state.projects[cwd];
+        }
+      }
+      return state;
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return { projects: {} };
+}
+
+function saveState(state) {
+  try {
+    ensureDir(path.dirname(STATE_FILE));
+    safeWriteFile(STATE_FILE, JSON.stringify(state));
+  } catch {
+    // Best-effort
+  }
+}
+
+function getProjectState(state, cwd) {
+  if (!state.projects[cwd]) {
+    state.projects[cwd] = {
+      toolCount: 0,
+      checkpointCount: 0,
+      lastCheckpoint: null,
+      sessionStart: new Date().toISOString(),
+      filesModified: [],
+      recentTools: [],
+    };
+  }
+  return state.projects[cwd];
+}
+
+function writeCheckpoint(proj, cwd) {
+  const hash = projectHash(cwd);
+  const cpDir = path.join(HOME, '.stackmemory', 'checkpoints', hash);
+  ensureDir(cpDir);
+
+  const checkpoint = {
+    toolCount: proj.toolCount,
+    checkpointNumber: proj.checkpointCount,
+    timestamp: new Date().toISOString(),
+    filesModified: proj.filesModified.slice(-MAX_FILES_TRACKED),
+    recentTools: proj.recentTools.slice(-MAX_RECENT_TOOLS),
+    cwd,
+  };
+
+  safeWriteFile(
+    path.join(cpDir, 'latest.json'),
+    JSON.stringify(checkpoint, null, 2)
+  );
+}
+
+function trackFile(proj, toolInput) {
+  const filePath = toolInput?.file_path;
+  if (filePath && !proj.filesModified.includes(filePath)) {
+    proj.filesModified.push(filePath);
+    if (proj.filesModified.length > MAX_FILES_TRACKED) {
+      proj.filesModified = proj.filesModified.slice(-MAX_FILES_TRACKED);
+    }
+  }
+}
+
+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;
+
+    const cwd = process.cwd();
+    const state = loadState();
+    const proj = getProjectState(state, cwd);
+
+    // Increment counter
+    proj.toolCount++;
+
+    // Track tool name
+    proj.recentTools.push(tool_name);
+    if (proj.recentTools.length > MAX_RECENT_TOOLS) {
+      proj.recentTools = proj.recentTools.slice(-MAX_RECENT_TOOLS);
+    }
+
+    // Track modified files from Edit/Write
+    if (
+      tool_name === 'Edit' ||
+      tool_name === 'Write' ||
+      tool_name === 'MultiEdit'
+    ) {
+      trackFile(proj, tool_input);
+    }
+
+    // Checkpoint every N calls
+    const isCheckpoint = proj.toolCount % CHECKPOINT_INTERVAL === 0;
+    if (isCheckpoint) {
+      proj.checkpointCount++;
+      proj.lastCheckpoint = new Date().toISOString();
+      writeCheckpoint(proj, cwd);
+    }
+
+    // Only persist state every SAVE_INTERVAL calls or on checkpoint boundaries
+    if (isCheckpoint || proj.toolCount % SAVE_INTERVAL === 0) {
+      saveState(state);
+    }
+  } catch {
+    // Silent fail -- never block the agent
+  }
+}
+
+main();

package/templates/claude-hooks/chime-on-stop.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Chime once when Claude Code needs user input
+# Uses macOS system sound
+
+# Prevent multiple chimes by checking if we recently played
+CHIME_LOCK="/tmp/claude-chime-lock"
+CHIME_COOLDOWN=2  # seconds
+
+if [ -f "$CHIME_LOCK" ]; then
+  LAST_CHIME=$(cat "$CHIME_LOCK")
+  NOW=$(date +%s)
+  DIFF=$((NOW - LAST_CHIME))
+  if [ "$DIFF" -lt "$CHIME_COOLDOWN" ]; then
+    exit 0  # Skip chime if too recent
+  fi
+fi
+
+# Record chime time
+date +%s > "$CHIME_LOCK"
+
+# Play system sound (Glass is a nice subtle chime)
+afplay /System/Library/Sounds/Glass.aiff &

package/templates/claude-hooks/session-rescue.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# session-rescue.sh — Auto-capture stackmemory handoff on session close
+# Runs as a Stop hook. Silent on failure. Skips non-stackmemory projects.
+
+set -euo pipefail
+
+# Only run in stackmemory-initialized projects
+[ -d ".stackmemory" ] || exit 0
+
+# Require stackmemory CLI
+command -v stackmemory >/dev/null 2>&1 || exit 0
+
+# Capture without committing, compact format, 10s timeout
+timeout 10 stackmemory capture --no-commit --format compact \
+  -m "auto-rescue on session close" >/dev/null 2>&1 || true

package/templates/claude-hooks/stop-checkpoint.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Stop-Checkpoint Hook
+ *
+ * Fires on session stop. Reads checkpoint state for current project.
+ * If 3+ checkpoints accumulated, outputs a "context heavy" message.
+ * Writes a final checkpoint with session stop metadata.
+ *
+ * State is keyed per-session (process.ppid) to avoid race conditions
+ * when multiple Claude instances run concurrently.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const HOME = process.env.HOME || '/tmp';
+const SESSION_ID = process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+const STATE_FILE = path.join(
+  HOME,
+  '.stackmemory',
+  `checkpoint-state-${SESSION_ID}.json`
+);
+const MAX_FILES_TRACKED = 50;
+const MAX_RECENT_TOOLS = 20;
+
+function projectHash(cwd) {
+  return crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
+}
+
+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 loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+      const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+      for (const [cwd, proj] of Object.entries(state.projects)) {
+        if (
+          proj.sessionStart &&
+          new Date(proj.sessionStart).getTime() < cutoff
+        ) {
+          delete state.projects[cwd];
+        }
+      }
+      return state;
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return { projects: {} };
+}
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const state = loadState();
+    const proj = state.projects?.[cwd];
+
+    if (!proj) return;
+
+    const { toolCount, checkpointCount, sessionStart, filesModified } = proj;
+
+    // Write final checkpoint
+    const hash = projectHash(cwd);
+    const cpDir = path.join(HOME, '.stackmemory', 'checkpoints', hash);
+    ensureDir(cpDir);
+
+    // NaN duration guard
+    const startMs = sessionStart ? new Date(sessionStart).getTime() : 0;
+    const duration =
+      startMs > 0 ? Math.round((Date.now() - startMs) / 1000) : 0;
+
+    const finalCheckpoint = {
+      reason: 'session_stop',
+      toolCount,
+      checkpointNumber: checkpointCount,
+      totalFiles: filesModified?.length || 0,
+      duration,
+      timestamp: new Date().toISOString(),
+      filesModified: (filesModified || []).slice(-MAX_FILES_TRACKED),
+      recentTools: (proj.recentTools || []).slice(-MAX_RECENT_TOOLS),
+      cwd,
+    };
+
+    safeWriteFile(
+      path.join(cpDir, 'latest.json'),
+      JSON.stringify(finalCheckpoint, null, 2)
+    );
+
+    // Output context-heavy message if 3+ checkpoints
+    if (checkpointCount >= 3) {
+      console.error(
+        `\nContext heavy (${checkpointCount} checkpoints, ${toolCount} tool calls). State saved. Consider /clear to reload from checkpoint.\n`
+      );
+    }
+
+    // Clean up session state file since session is ending
+    try {
+      fs.unlinkSync(STATE_FILE);
+    } catch {
+      // Best-effort cleanup
+    }
+  } catch {
+    // Silent fail -- never block the agent
+  }
+}
+
+main();