specmem-hardwicksoftware 3.7.31 → 3.7.33

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/bin/specmem-cli.cjs

@@ -779,7 +779,7 @@ function manageProxy(args) {
   switch (sub) {
     case 'disable':
     case 'off': {
-      // Create disabled flag
+      // Create disabled flag — daemon stays running but in passthrough mode
       try {
         if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
         fs.writeFileSync(disabledFile, new Date().toISOString(), { mode: 0o644 });
@@ -788,40 +788,17 @@ function manageProxy(args) {
         process.exit(1);
       }
 
-      // Remove port file so wrapper won't try
-      try { if (fs.existsSync(portFile)) fs.unlinkSync(portFile); } catch (e) { /* ok */ }
-
-      // Kill the running proxy if it's up
-      const port = process.env.COMPACTION_PROXY_PORT || '4080';
+      // Switch the running proxy to paused (passthrough) mode — don't kill it
+      const disablePort = process.env.COMPACTION_PROXY_PORT || '4080';
       try {
-        execSync(`curl -sf http://127.0.0.1:${port}/health`, { timeout: 1000, stdio: 'pipe' });
-        // Proxy is running — find and kill it
-        try {
-          const pid = execSync(`lsof -ti tcp:${port} -s tcp:listen 2>/dev/null`, { encoding: 'utf8' }).trim();
-          if (pid) {
-            process.kill(parseInt(pid), 'SIGTERM');
-            console.log(`${GREEN}✓${RESET} Killed running proxy (PID ${pid})`);
-          }
-        } catch (e) { /* couldn't find pid, that's ok */ }
+        execSync(`curl -sf -X POST http://127.0.0.1:${disablePort}/pause`, { timeout: 2000, stdio: 'pipe' });
+        console.log(`${GREEN}✓${RESET} Proxy switched to ${YELLOW}passthrough${RESET} mode`);
       } catch (e) {
-        // Proxy not running
+        // Proxy not running — that's fine, flag will keep next start paused
       }
 
-      // Remove the bashrc block that sets ANTHROPIC_BASE_URL so new shells don't get it
-      try {
-        const bashrc = path.join(os.homedir(), '.bashrc');
-        if (fs.existsSync(bashrc)) {
-          const content = fs.readFileSync(bashrc, 'utf8');
-          const cleaned = content.replace(/\n?# specmem-proxy-env\n(?:# [^\n]*\n)*if \[ -f "\$HOME\/\.claude\/\.compaction-proxy-port" \];[\s\S]*?fi\n?/g, '\n');
-          if (cleaned !== content) {
-            fs.writeFileSync(bashrc, cleaned);
-            console.log(`${GREEN}✓${RESET} Removed proxy env from .bashrc`);
-          }
-        }
-      } catch (e) { /* non-fatal */ }
-
-      console.log(`${GREEN}✓${RESET} Compaction proxy ${RED}disabled${RESET}`);
-      console.log(`  ${DIM}Proxy won't start on next session${RESET}`);
+      console.log(`${GREEN}✓${RESET} Compaction proxy ${RED}disabled${RESET} (passthrough — traffic still flows)`);
+      console.log(`  ${DIM}Proxy stays running but passes all requests through untouched${RESET}`);
       console.log(`\n  ${DIM}Re-enable with: ${CYAN}specmem proxy enable${RESET}`);
       break;
     }
@@ -831,9 +808,17 @@ function manageProxy(args) {
       // Remove disabled flag
       try { if (fs.existsSync(disabledFile)) fs.unlinkSync(disabledFile); } catch (e) { /* ok */ }
 
+      // Unpause the running proxy — activate compression immediately
+      const enablePort = process.env.COMPACTION_PROXY_PORT || '4080';
+      try {
+        execSync(`curl -sf -X POST http://127.0.0.1:${enablePort}/resume`, { timeout: 2000, stdio: 'pipe' });
+        console.log(`${GREEN}✓${RESET} Proxy compression ${GREEN}activated${RESET}`);
+      } catch (e) {
+        // Proxy not running — will start active on next session
+      }
+
       console.log(`${GREEN}✓${RESET} Compaction proxy ${GREEN}enabled${RESET}`);
-      console.log(`  ${DIM}Proxy will start on next Claude session${RESET}`);
-      console.log(`  ${DIM}Or restart Claude now to activate immediately${RESET}`);
+      console.log(`  ${DIM}Compression active immediately (no restart needed)${RESET}`);
       break;
     }
 

package/bootstrap.cjs

@@ -955,7 +955,11 @@ function syncProjectConfigs() {
       // Backup and write
       const backupPath = `${claudeJsonPath}.backup.${Date.now()}`;
       fs.copyFileSync(claudeJsonPath, backupPath);
-      fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+      // ATOMIC WRITE: write to temp file then rename to prevent corruption
+      // fs.writeFileSync truncates first, so Claude Code can read a partial file mid-write
+      const tmpPath = claudeJsonPath + '.tmp.' + process.pid;
+      fs.writeFileSync(tmpPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+      fs.renameSync(tmpPath, claudeJsonPath);
       startupLog(`CONFIG SYNC: Fixed ${fixedProjects.length} stale project configs: ${fixedProjects.join(', ')}`);
 
       // Clean up old backups (keep last 3)

package/claude-hooks/agent-loading-hook.js

@@ -734,53 +734,37 @@ async function loadSkills() {
 function getMinimalTeamContext() {
   return `
 
-[MANDATORY-FIRST-ACTION]
-Before doing ANYTHING else, you MUST announce yourself:
-send_team_message({type:"status", message:"Starting: [your task summary]"})
-If you skip this, ALL your tool calls will be BLOCKED. No exceptions.
-[/MANDATORY-FIRST-ACTION]
-
-[TEAM CONTEXT]
-You are a developer on a software development team. The senior engineer on this team is skeptical of AI assistance, so you must perform your tasks efficiently and communicate well with your fellow developers.
-
-⚠️ CRITICAL: YOU MUST USE MCP TOOLS TO COMPLETE YOUR TASK ⚠️
-There is NO alternative path. The system ENFORCES MCP tool usage:
-- You CANNOT proceed without announcing via send_team_message FIRST
-- You CANNOT write code without claiming files via claim_task
-- You CANNOT search more than 3 times without using find_memory/find_code_pointers
-- Every 4 tool calls, you WILL BE BLOCKED until you check read_team_messages (team comms)
-- Every 5 tool calls, you WILL BE BLOCKED until you check read_team_messages with include_broadcasts:true
-- Every 8 tool calls, you WILL BE BLOCKED until you check get_team_status for help requests
-- These counters apply to ALL tool calls, including memory tools and searches - no exceptions
-If you want to complete your goal, you MUST use MCP tools. There is no workaround.
-
-TEAM COMMUNICATION (mcp__specmem__ prefix):
-- send_team_message({message, channel:"main"|"swarm-1".."swarm-5", type:"status"|"question"|"update", priority})
-- read_team_messages({limit:5, include_swarms:true}) - MANDATORY every 4 tool calls!
-- read_team_messages({include_broadcasts:true, include_swarms:true, limit:10}) - MANDATORY every 5 calls!
-- broadcast_to_team({message, broadcast_type:"status"|"progress"|"announcement", priority})
-- claim_task({description, files:["path1","path2"]}) - REQUIRED before editing
-- release_task({claimId:"all"|"<id>"}) - release when done
-- get_team_status({}) - see active claims, help requests, team activity
-- request_help({question, context, skills_needed:["skill1"]}) - ASK OTHER SWARMS FOR HELP!
-- respond_to_help({requestId, response}) - HELP OTHER SWARMS! Helping hands make the world go round!
-
-MEMORY TOOLS (MANDATORY - enforced by hooks):
-- find_memory({query, limit:10}) - semantic search for past conversations and decisions
-- find_code_pointers({query, limit:10, includeTracebacks:true}) - semantic code search with callers/callees
-- save_memory({content, importance, memoryType, tags}) - save important findings
-- drill_down({drilldownID}) - get full context on a memory result
-- getMemoryFull({id}) - get full memory with live code
-
-WORKFLOW (enforced - you cannot skip steps):
-1. START: send_team_message({type:"status", message:"Starting: [task]"})
-2. CLAIM: claim_task({description, files}) - REQUIRED before any writes
-3. SEARCH: find_memory/find_code_pointers FIRST, then Grep/Glob if needed
-4. EVERY 4 CALLS: read_team_messages({include_swarms:true, limit:5}) - MANDATORY, you WILL be blocked
-5. EVERY 5 CALLS: read_team_messages({include_broadcasts:true, include_swarms:true, limit:10}) - MANDATORY
-6. EVERY 8 CALLS: get_team_status() - check if anyone needs help!
-6. DONE: release_task({claimId:"all"}), send completion status
-[/TEAM CONTEXT]`;
+[TEAM COLLABORATION]
+Welcome! You're joining a team of developers working on this project together. To keep things running smoothly and avoid stepping on each other's toes, here's how the team stays coordinated:
+
+GETTING STARTED:
+First, let the team know you're here and what you'll be working on:
+  send_team_message({type:"status", message:"Starting: [your task summary]"})
+
+SEARCHING FOR CODE & CONTEXT:
+The project has semantic search tools that are much more effective than grep — use these first:
+  find_code_pointers({query:"what you're looking for"}) — semantic code search with tracebacks, shows who calls what
+  find_memory({query:"topic"}) — finds past discussions, decisions, and context from the user and other team members
+  drill_down({drilldownID: N}) — expand a result from find_code_pointers or find_memory for full detail
+If semantic search doesn't cover it, Grep/Glob are still available as a fallback.
+
+EDITING FILES:
+To avoid merge conflicts with other team members:
+  1. claim_task({description:"what you're doing", files:["path/to/file"]}) — claim before editing
+  2. Make your edits
+  3. release_task({claimId:"all"}) — release so others can work on those files
+If a file is already claimed by someone else, coordinate via send_team_message first.
+
+STAYING IN SYNC:
+Check in with the team periodically — other team members may have updates that affect your work:
+  read_team_messages({include_swarms:true, limit:5}) — see recent team activity
+  get_team_status() — see who's working on what, and if anyone needs help
+  respond_to_help({requestId, response}) — if you can help a teammate, do it!
+
+WHEN YOU'RE DONE:
+  release_task({claimId:"all"}) — free your claimed files
+  send_team_message({type:"status", message:"Completed: [summary of what you did]"})
+[/TEAM COLLABORATION]`;
 }
 
 // ============================================================================

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