specmem-hardwicksoftware 3.7.31 → 3.7.32

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to SpecMem - we keep it real with semantic versioning. Deada
 
 ---
 
+## [3.7.32] - 2026-02-24
+
+### Fixed
+- Sync score `-100%` display bug — `writeSyncScore` now guards against negative values when indexing is pending
+- Concurrent MCP tool call failures — pLimit(2) concurrency cap in mcpProtocolHandler, toolRegistry eviction fix, connectionPool maxConnections reduced 20→6
+- CPU spike on large codebases — fileWatcher batch debounce 500ms, stabilityThreshold 300→500ms
+- `check_sync` returning 0% — `triggerBackgroundIndexing()` now wired into deferred init, syncChecker defensive handling added
+- TUI init flow rendering issues — Blessed screen render guard, pino SonicBoom fd intercept
+
+### Added
+- Auto-resync when sync score drops below 85% — debounced (15min default, `SPECMEM_LOW_SCORE_DEBOUNCE_MS`), configurable threshold via `SPECMEM_LOW_SCORE_THRESHOLD`
+- Offline ML model pipeline — embedding (MiniLM-L6-v2 ONNX quint8) + Argos neural translation bundled via git-lfs, auto-downloaded at init
+- Bash call enforcer hook — agents must call `send_team_message`, `find_code_pointers`, or `drill_down` every 3 Bash calls
+- Compaction proxy daemon — handles session compaction in background process
+
+### Improved
+- Token compression system — improved accuracy, self-healing codebook, round-trip verified
+- Install flow — root no longer required, simplified to 3 steps: install → cd → `specmem init`
+- Reduced npm permission requirements across the board
+
+---
+
 ## [3.7.24] - 2026-02-12
 
 ### Added

package/README.md

@@ -1,3 +1,15 @@
+<!-- Debian/Ubuntu/Mint/Kali notice -->
+<div align="center">
+<table><tr><td align="center" style="background:#0d1117;border:1px solid #30363d;border-radius:8px;padding:12px 20px">
+<strong>Debian-based Linux?</strong> &nbsp;
+<img src="https://upload.wikimedia.org/wikipedia/commons/4/4a/Debian-OpenLogo.svg" height="16" alt="Debian"/>
+<img src="https://upload.wikimedia.org/wikipedia/commons/a/ab/Logo-ubuntu_cof-orange-hex.svg" height="16" alt="Ubuntu"/>
+<img src="https://upload.wikimedia.org/wikipedia/commons/3/3f/Linux_Mint_logo_without_wordmark.svg" height="16" alt="Mint"/>
+<img src="https://upload.wikimedia.org/wikipedia/commons/4/4b/Kali_Linux_2.0_wordmark.svg" height="16" alt="Kali"/>
+&nbsp; <code>npm install -g specmem-hardwicksoftware</code> &nbsp;— root no longer required.
+</td></tr></table>
+</div>
+
 <div align="center">
 
 <!-- Demo GIF -->

package/claude-hooks/bash-call-enforcer.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * BASH CALL ENFORCER - PreToolUse Hook
+ * =====================================
+ * Agents MUST check in with SpecMem every 3 Bash calls.
+ *
+ * After 3 Bash calls → BLOCKED until they use:
+ *   - send_team_message (announce progress)
+ *   - find_code_pointers (semantic code search)
+ *   - drill_down (dig into memory)
+ *
+ * This prevents agents from running unlimited shell commands
+ * without pausing to share knowledge / use semantic context.
+ *
+ * Main session = never blocked.
+ * Agents only.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BASH_LIMIT = parseInt(process.env.SPECMEM_BASH_LIMIT || '3', 10);
+
+const RESET_TOOLS = [
+  'mcp__specmem__send_team_message',
+  'mcp__specmem__find_code_pointers',
+  'mcp__specmem__drill_down',
+  'mcp__specmem__find_memory',
+  'mcp__specmem__smart_search',
+  'mcp__specmem__broadcast_to_team',
+];
+
+// ── Agent detection: only enforce on full specmem team members ────────────────
+// Pure Bash agents (Task subagent_type:"Bash") don't have MCP tools and cannot
+// satisfy the reset requirement — skip them entirely.
+function isAgent() {
+  return process.env.SPECMEM_TEAM_MEMBER === 'true';
+}
+
+// ── State helpers ─────────────────────────────────────────────────────────────
+function stateFile() {
+  const sid = (process.env.CLAUDE_SESSION_ID || process.env.TASK_ID || 'default')
+    .replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `/tmp/specmem-bash-enforcer-${sid}.json`;
+}
+
+function getState() {
+  try {
+    const f = stateFile();
+    if (fs.existsSync(f)) {
+      const d = JSON.parse(fs.readFileSync(f, 'utf8'));
+      // Expire after 60 min
+      if (d.ts && Date.now() - d.ts < 3_600_000) return d;
+    }
+  } catch (_) {}
+  return { bashCount: 0, needsReset: false, ts: Date.now() };
+}
+
+function saveState(state) {
+  try {
+    state.ts = Date.now();
+    fs.writeFileSync(stateFile(), JSON.stringify(state));
+  } catch (_) {}
+}
+
+// ── Response helpers ──────────────────────────────────────────────────────────
+const deny = (reason) => JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: reason,
+  }
+});
+
+const allow = () => JSON.stringify({ continue: true });
+
+// ── Timeout guard — never stall the session ───────────────────────────────────
+setTimeout(() => { process.stdout.write(allow()); process.exit(0); }, 400);
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => { raw += c; });
+process.stdin.on('end', () => {
+  try {
+    const { tool_name: tool } = JSON.parse(raw);
+
+    // Reset tools: clear bash counter and allow immediately
+    if (RESET_TOOLS.includes(tool)) {
+      saveState({ bashCount: 0, needsReset: false, ts: Date.now() });
+      process.stdout.write(allow());
+      return;
+    }
+
+    // Only enforce on Bash, and only for agents
+    if (tool !== 'Bash' || !isAgent()) {
+      process.stdout.write(allow());
+      return;
+    }
+
+    const state = getState();
+
+    // Already needs a reset — block this Bash call
+    if (state.needsReset) {
+      process.stdout.write(deny(
+        `[BASH BLOCKED] You've run ${BASH_LIMIT} Bash commands without checking in.\n\n` +
+        `Before the next Bash call, you MUST do ONE of:\n` +
+        `  • send_team_message({message:"progress update..."}) — share what you found\n` +
+        `  • find_code_pointers({query:"..."})             — search the codebase semantically\n` +
+        `  • drill_down({drilldownID: N})                  — dig into a memory result\n\n` +
+        `This keeps you using SpecMem's knowledge, not just raw shell output.`
+      ));
+      return;
+    }
+
+    state.bashCount = (state.bashCount || 0) + 1;
+
+    if (state.bashCount >= BASH_LIMIT) {
+      state.needsReset = true;
+      saveState(state);
+      process.stdout.write(deny(
+        `[BASH BLOCKED] ${BASH_LIMIT} Bash calls hit — check in with SpecMem first.\n\n` +
+        `Do ONE of:\n` +
+        `  • send_team_message({message:"what you discovered..."}) — report progress\n` +
+        `  • find_code_pointers({query:"..."})             — semantic code search\n` +
+        `  • drill_down({drilldownID: N})                  — drill into memory\n\n` +
+        `After that, Bash is unlocked again (next ${BASH_LIMIT} calls).`
+      ));
+      return;
+    }
+
+    saveState(state);
+    process.stdout.write(allow());
+
+  } catch (_) {
+    process.stdout.write(allow());
+  }
+});

package/claude-hooks/settings.json

@@ -223,6 +223,14 @@
               "SPECMEM_PROJECT_PATH": "${cwd}"
             }
           },
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/bash-call-enforcer.cjs",
+            "timeout": 2,
+            "env": {
+              "SPECMEM_PROJECT_PATH": "${cwd}"
+            }
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -293,6 +301,31 @@
             "env": {
               "SPECMEM_PROJECT_PATH": "${cwd}"
             }
+          },
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/bash-call-enforcer.cjs",
+            "timeout": 2
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__specmem__send_team_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/bash-call-enforcer.cjs",
+            "timeout": 2
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__specmem__drill_down",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/bash-call-enforcer.cjs",
+            "timeout": 2
           }
         ]
       }

package/claude-hooks/specmem-drilldown-hook.cjs

@@ -15,6 +15,7 @@ const { spawn } = require('child_process');
 const net = require('net');
 const path = require('path');
 const os = require('os');
+const fs = require('fs');
 
 // Import shared path resolution utilities AND Pool
 const {
@@ -55,6 +56,45 @@ const SPECMEM_HOME = getSpecmemHome();
 const SPECMEM_PKG = getSpecmemPkg();
 const SPECMEM_RUN_DIR = expandCwd(process.env.SPECMEM_RUN_DIR) || getProjectSocketDir();
 
+// Prompt counter — fires on first prompt, then every 3rd (prompt 1, 4, 7, 10, ...)
+// No hard cap — cadence-based injection instead
+const DRILLDOWN_COUNT_FILE = path.join(SPECMEM_RUN_DIR || '/tmp', '.drilldown-prompt-count');
+
+function getPromptCount() {
+  try {
+    if (fs.existsSync(DRILLDOWN_COUNT_FILE)) {
+      const data = JSON.parse(fs.readFileSync(DRILLDOWN_COUNT_FILE, 'utf8'));
+      // Reset if older than 4 hours
+      if (Date.now() - (data.startedAt || 0) > 14400000) return 0;
+      return data.count || 0;
+    }
+  } catch (e) {}
+  return 0;
+}
+
+function incrementPromptCount() {
+  try {
+    let data = { count: 0, startedAt: Date.now() };
+    if (fs.existsSync(DRILLDOWN_COUNT_FILE)) {
+      try {
+        data = JSON.parse(fs.readFileSync(DRILLDOWN_COUNT_FILE, 'utf8'));
+        if (Date.now() - (data.startedAt || 0) > 14400000) {
+          data = { count: 0, startedAt: Date.now() };
+        }
+      } catch (e) {}
+    }
+    data.count = (data.count || 0) + 1;
+    fs.writeFileSync(DRILLDOWN_COUNT_FILE, JSON.stringify(data));
+  } catch (e) {}
+}
+
+function shouldFireThisPrompt() {
+  const count = getPromptCount(); // 0-indexed: 0 = first prompt
+  // Fire on prompt 0 (first), 3, 6, 9, ... (every 3rd starting from first)
+  return count % 3 === 0;
+}
+
+
 // Project path will be set from 's hook input (cwd field)
 // Fallback: 1. SPECMEM_PROJECT_PATH env var, 2. process.cwd()
 let PROJECT_PATH = expandCwd(process.env.SPECMEM_PROJECT_PATH) || process.cwd() || '/';
@@ -62,7 +102,7 @@ let PROJECT_PATH = expandCwd(process.env.SPECMEM_PROJECT_PATH) || process.cwd()
 // Configuration
 const CONFIG = {
   // SpecMem settings
-  searchLimit: parseInt(process.env.SPECMEM_SEARCH_LIMIT || '5'),
+  searchLimit: parseInt(process.env.SPECMEM_SEARCH_LIMIT || '4'),
   // ACCURACY FIX: Raised threshold from 0.3 to 0.4 to reduce false positives
   // Local embeddings score lower, but 0.4 filters out noise while keeping relevant results
   threshold: parseFloat(process.env.SPECMEM_THRESHOLD || '0.4'),
@@ -441,13 +481,18 @@ async function main() {
   // Debounce: skip if ran within last 5 seconds
   const DRILLDOWN_DEBOUNCE_FILE = path.join(SPECMEM_RUN_DIR, '.drilldown-debounce');
   try {
-    const fs = require('fs');
     if (fs.existsSync(DRILLDOWN_DEBOUNCE_FILE)) {
       const last = parseInt(fs.readFileSync(DRILLDOWN_DEBOUNCE_FILE, 'utf8').trim(), 10);
       if (Date.now() - last < 5000) process.exit(0);
     }
     fs.writeFileSync(DRILLDOWN_DEBOUNCE_FILE, String(Date.now()));
   } catch (e) {}
+  // Increment prompt counter first, then check if we should fire this prompt
+  incrementPromptCount();
+  if (!shouldFireThisPrompt()) {
+    process.exit(0);
+  }
+
 
   // Skip task notifications (background agent completions treated as prompts)
   if (prompt.includes('<task-notification>') || prompt.includes('</task-notification>')) {
@@ -473,6 +518,8 @@ async function main() {
 
       // Mark as injected to prevent duplicate injection this session
       contextDedup.markInjected(PROJECT_PATH, sessionId, prompt);
+
+
     }
   } catch (error) {
     // Silently fail - don't break the prompt

package/claude-hooks/specmem-drilldown-hook.js

@@ -15,6 +15,7 @@ const { spawn } = require('child_process');
 const net = require('net');
 const path = require('path');
 const os = require('os');
+const fs = require('fs');
 
 // Import shared path resolution utilities AND Pool
 const {
@@ -55,6 +56,45 @@ const SPECMEM_HOME = getSpecmemHome();
 const SPECMEM_PKG = getSpecmemPkg();
 const SPECMEM_RUN_DIR = expandCwd(process.env.SPECMEM_RUN_DIR) || getProjectSocketDir();
 
+// Prompt counter — fires on first prompt, then every 3rd (prompt 1, 4, 7, 10, ...)
+// No hard cap — cadence-based injection instead
+const DRILLDOWN_COUNT_FILE = path.join(SPECMEM_RUN_DIR || '/tmp', '.drilldown-prompt-count');
+
+function getPromptCount() {
+  try {
+    if (fs.existsSync(DRILLDOWN_COUNT_FILE)) {
+      const data = JSON.parse(fs.readFileSync(DRILLDOWN_COUNT_FILE, 'utf8'));
+      // Reset if older than 4 hours
+      if (Date.now() - (data.startedAt || 0) > 14400000) return 0;
+      return data.count || 0;
+    }
+  } catch (e) {}
+  return 0;
+}
+
+function incrementPromptCount() {
+  try {
+    let data = { count: 0, startedAt: Date.now() };
+    if (fs.existsSync(DRILLDOWN_COUNT_FILE)) {
+      try {
+        data = JSON.parse(fs.readFileSync(DRILLDOWN_COUNT_FILE, 'utf8'));
+        if (Date.now() - (data.startedAt || 0) > 14400000) {
+          data = { count: 0, startedAt: Date.now() };
+        }
+      } catch (e) {}
+    }
+    data.count = (data.count || 0) + 1;
+    fs.writeFileSync(DRILLDOWN_COUNT_FILE, JSON.stringify(data));
+  } catch (e) {}
+}
+
+function shouldFireThisPrompt() {
+  const count = getPromptCount(); // 0-indexed: 0 = first prompt
+  // Fire on prompt 0 (first), 3, 6, 9, ... (every 3rd starting from first)
+  return count % 3 === 0;
+}
+
+
 // Project path will be set from 's hook input (cwd field)
 // Fallback: 1. SPECMEM_PROJECT_PATH env var, 2. process.cwd()
 let PROJECT_PATH = expandCwd(process.env.SPECMEM_PROJECT_PATH) || process.cwd() || '/';
@@ -62,7 +102,7 @@ let PROJECT_PATH = expandCwd(process.env.SPECMEM_PROJECT_PATH) || process.cwd()
 // Configuration
 const CONFIG = {
   // SpecMem settings
-  searchLimit: parseInt(process.env.SPECMEM_SEARCH_LIMIT || '5'),
+  searchLimit: parseInt(process.env.SPECMEM_SEARCH_LIMIT || '4'),
   // ACCURACY FIX: Raised threshold from 0.3 to 0.4 to reduce false positives
   // Local embeddings score lower, but 0.4 filters out noise while keeping relevant results
   threshold: parseFloat(process.env.SPECMEM_THRESHOLD || '0.4'),
@@ -441,13 +481,18 @@ async function main() {
   // Debounce: skip if ran within last 5 seconds
   const DRILLDOWN_DEBOUNCE_FILE = path.join(SPECMEM_RUN_DIR, '.drilldown-debounce');
   try {
-    const fs = require('fs');
     if (fs.existsSync(DRILLDOWN_DEBOUNCE_FILE)) {
       const last = parseInt(fs.readFileSync(DRILLDOWN_DEBOUNCE_FILE, 'utf8').trim(), 10);
       if (Date.now() - last < 5000) process.exit(0);
     }
     fs.writeFileSync(DRILLDOWN_DEBOUNCE_FILE, String(Date.now()));
   } catch (e) {}
+  // Increment prompt counter first, then check if we should fire this prompt
+  incrementPromptCount();
+  if (!shouldFireThisPrompt()) {
+    process.exit(0);
+  }
+
 
   // Skip task notifications (background agent completions treated as prompts)
   if (prompt.includes('<task-notification>') || prompt.includes('</task-notification>')) {
@@ -473,6 +518,8 @@ async function main() {
 
       // Mark as injected to prevent duplicate injection this session
       contextDedup.markInjected(PROJECT_PATH, sessionId, prompt);
+
+
     }
   } catch (error) {
     // Silently fail - don't break the prompt