heyspex 0.1.0 → 0.2.1

package/scripts/claude-hooks/check-auto-memory-budget.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+// Claude Code SessionStart hook → auto-memory index (MEMORY.md) self-healing + budget check.
+//
+// The Claude Code auto-memory index at ~/.claude/projects/<repo>/memory/MEMORY.md
+// is injected into context at the start of every session, but only the first 200
+// lines OR 25KB (whichever comes first) are loaded — content past that threshold
+// is silently dropped from session-start context, degrading recall. Detail kept
+// in the sibling topic files is NOT loaded at startup, so it is free.
+//
+// Per the research-backed retention policy ([[auto-memory-index-hygiene]] /
+// [[HS-VN9W-RES]]), the auto-memory index is a thin curated-working-set + ROUTER
+// over the HeySpex vault — it must NOT mirror vault memory. The vault
+// (specs/memory/) is the retrieval store, served dynamically by
+// heyspex_recall_memories. So any index entry whose link already targets
+// specs/memory/... is, by construction, a duplicate of content that lives in the
+// vault — provably safe to remove from the always-loaded index.
+//
+// This hook therefore does two things at session start:
+//   1. SELF-HEAL (write) — evicts those provably-mirrored entries in place (content
+//      stays in the vault; only the redundant index line leaves). A sanctioned
+//      PINNED allowlist (lines tagged [pinned]) is never touched. This is the
+//      eviction mechanism that keeps the index from re-bloating (MemGPT/Letta
+//      eviction pattern applied to the index tier).
+//   2. ADVISE (emit) — for whatever remains, stays SILENT while healthy and, once
+//      the index crosses ~70% of the cap, names the specific over-length entries
+//      to relocate. The advisory half never blocks.
+//
+// Eviction is conservative: it only removes entries whose link path contains
+// `specs/memory/` (those have a guaranteed vault home). Domain entries backed by
+// local topic files are left for the one-time migration + the PreToolUse
+// write-guard; this hook never drops a line it cannot prove is mirrored.
+//
+// Env gate (mirrors wip-checkpoint.mjs):
+//   CLAUDE_AGENT=true                    opt in (unset → silent + no self-heal, so
+//                                        interactive humans aren't spammed/mutated).
+//   HEYSPEX_AUTO_MEMORY_BUDGET_OFF=1     hard kill switch — silent + no self-heal.
+//   HEYSPEX_AUTO_MEMORY_SELF_HEAL_OFF=1  disable only the WRITE (stay advisory-only).
+//   HEYSPEX_AUTO_MEMORY_FILE=<path>      override the resolved MEMORY.md path
+//                                        (used by the smoke test; also a manual escape hatch).
+//
+// MUST exit 0 on every path — a hook that breaks Claude Code is worse than one
+// that silently does nothing. Writes are best-effort: a failed write is swallowed
+// and the advisory still emits.
+//
+// Output shape: { hookSpecificOutput: { hookEventName, additionalContext } }.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defaultConfigRoot } from '../../spexharness/src/config-root.mjs';
+
+export const CAP_BYTES = 25000; // harness session-start load cap (~24.4 KiB), per the official memory docs
+export const CAP_LINES = 200;
+export const TRIGGER = 0.7; // compact proactively at 70% of the cap, not at overflow
+export const HOOK_MAX_CHARS = 200; // per-entry index-hook limit ([[auto-memory-index-hygiene]])
+const MAX_OFFENDERS = 8;
+
+// A top-level index entry whose markdown link target contains `specs/memory/` is a
+// duplicate of content that already lives in the vault retrieval store — provably
+// safe to evict from the always-loaded index. Captures the link target so the
+// eviction can confirm the vault home actually exists before dropping the line
+// (a dangling link has no other home, so evicting it would be lossy).
+const VAULT_MIRROR_RE = /^- \[[^\]]*\]\(([^)]*specs\/memory\/[^)]*)\)/;
+
+// Lines carrying an explicit pinned marker are the sanctioned curated working set
+// (identity / mode / standing rules) — never evicted, even if they somehow match.
+const PINNED_RE = /\[pinned\]|\(pinned\)/i;
+
+function repoRoot() {
+  // scripts/claude-hooks/ → up two levels.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+  });
+}
+
+function emit(eventName, additionalContext) {
+  if (!additionalContext) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: eventName, additionalContext },
+    }),
+  );
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Claude Code derives the auto-memory dir name by replacing path separators and
+// the drive colon with '-' (e.g. C:\Users\pwher\dev-projects\workflow-protocol →
+// C--Users-pwher-dev-projects-workflow-protocol).
+function mangleProjectDir(dir) {
+  return dir.replace(/[:\\/]+/g, '-');
+}
+
+function resolveAutoMemoryDir(projectDir) {
+  // Honor an explicit autoMemoryDirectory setting (local overrides project).
+  for (const name of ['settings.local.json', 'settings.json']) {
+    const settings = readJsonSafe(path.join(repoRoot(), '.claude', name));
+    const dir = settings?.autoMemoryDirectory;
+    if (typeof dir === 'string' && dir.trim()) {
+      return dir.startsWith('~/') ? path.join(os.homedir(), dir.slice(2)) : dir;
+    }
+  }
+  return path.join(os.homedir(), '.claude', 'projects', mangleProjectDir(projectDir), 'memory');
+}
+
+function resolveMemoryFile(projectDir) {
+  const override = process.env.HEYSPEX_AUTO_MEMORY_FILE;
+  if (override && override.trim()) return override;
+  return path.join(resolveAutoMemoryDir(projectDir), 'MEMORY.md');
+}
+
+function analyze(content) {
+  const bytes = Buffer.byteLength(content, 'utf8');
+  const allLines = content.split(/\r?\n/);
+  const offenders = [];
+  for (const line of allLines) {
+    if (!line.startsWith('- ')) continue; // only top-level index entries
+    if (line.length <= HOOK_MAX_CHARS) continue;
+    const m = line.match(/^- \[([^\]]+)\]/);
+    offenders.push({ label: m ? m[1] : line.slice(2, 60), length: line.length });
+  }
+  offenders.sort((a, b) => b.length - a.length);
+  return { bytes, lineCount: allLines.length, offenders };
+}
+
+// Remove provably-mirrored entries (link → specs/memory/) from the index. Pinned
+// lines and any non-entry lines (router line, headers, blank lines) are preserved
+// verbatim. Returns the rewritten content, the evicted entry labels, and whether
+// anything changed. Pure — does not touch disk.
+export function evictVaultMirrors(content, vaultHomeExists) {
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
+  const kept = [];
+  const evicted = [];
+  for (const line of lines) {
+    const m = VAULT_MIRROR_RE.exec(line);
+    // Evict only a non-pinned line whose specs/memory/ target ACTUALLY resolves —
+    // a dangling link has no vault home, so dropping it would lose the only pointer.
+    if (m && !PINNED_RE.test(line) && vaultHomeExists(m[1])) {
+      const label = line.match(/^- \[([^\]]+)\]/);
+      evicted.push(label ? label[1] : line.slice(2, 60));
+      continue; // drop the redundant index line
+    }
+    kept.push(line);
+  }
+  return { newContent: kept.join(eol), evicted, changed: evicted.length > 0 };
+}
+
+function buildEvictionNote(evicted) {
+  if (!evicted.length) return null;
+  const shown = evicted.slice(0, MAX_OFFENDERS);
+  const out = [
+    `Auto-memory self-heal — evicted ${evicted.length} vault-mirrored ` +
+      `${evicted.length === 1 ? 'entry' : 'entries'} from the always-loaded index ` +
+      `(their content lives in the vault; recall via heyspex_recall_memories). ` +
+      `Per [[auto-memory-index-hygiene]], the index must not mirror specs/memory/.`,
+  ];
+  for (const label of shown) out.push(`  • ${label}`);
+  if (evicted.length > MAX_OFFENDERS) out.push(`  • …and ${evicted.length - MAX_OFFENDERS} more`);
+  return out.join('\n');
+}
+
+// ── Compaction engine ────────────────────────────────────────────────────────
+// [[HS-AE28-NYPR-TASK-add-a-compaction-rule-that-runs-when]]: eviction above
+// only removes entries with a PROVABLE vault home (specs/memory/ mirrors) —
+// safe, but not sufficient on its own once the index is bloated with long,
+// non-mirrored hook entries too. This adds the second lever: once the index
+// (post-eviction) has crossed `trigger` (70%) of its byte/line cap, truncate
+// any remaining over-`hookMaxChars` entry to a one-line hook in place. Pure —
+// does not touch disk; `compactMemoryIndex` is a fixture-testable engine
+// module callers can run against ANY injected content/path (never the
+// caller's real MEMORY.md by default — the caller decides what to read/write).
+
+/** Truncate every non-pinned, over-length `- ` entry to `hookMaxChars`. Pure. */
+export function truncateOverLengthEntries(content, { hookMaxChars = HOOK_MAX_CHARS } = {}) {
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
+  const truncated = [];
+  const out = lines.map((line) => {
+    if (!line.startsWith('- ')) return line; // only top-level index entries
+    if (PINNED_RE.test(line)) return line; // sanctioned curated working set — never touched
+    if (line.length <= hookMaxChars) return line;
+    const m = line.match(/^- \[([^\]]+)\]/);
+    truncated.push({ label: m ? m[1] : line.slice(2, 60), originalLength: line.length });
+    const cut = line.slice(0, Math.max(0, hookMaxChars - 1)).trimEnd();
+    return `${cut}…`;
+  });
+  return { newContent: out.join(eol), truncated, changed: truncated.length > 0 };
+}
+
+/**
+ * The compaction rule: runs ONLY once `content` has crossed `trigger` (70% by
+ * default) of its byte/line cap, and truncates over-length entries to bring it
+ * back down. Returns `ranCompaction: false` (no-op, `newContent === content`)
+ * below the trigger — the rule stays silent while the index is healthy, same
+ * discipline as the advisory report.
+ *
+ * @param {string} content
+ * @param {{ capBytes?: number, capLines?: number, trigger?: number, hookMaxChars?: number }} [opts]
+ */
+export function compactMemoryIndex(
+  content,
+  { capBytes = CAP_BYTES, capLines = CAP_LINES, trigger = TRIGGER, hookMaxChars = HOOK_MAX_CHARS } = {},
+) {
+  const bytes = Buffer.byteLength(content, 'utf8');
+  const lineCount = content.split(/\r?\n/).length;
+  const before = { bytes, lineCount };
+  if (bytes < capBytes * trigger && lineCount < capLines * trigger) {
+    return { newContent: content, ranCompaction: false, changed: false, truncated: [], before, after: before };
+  }
+  const { newContent, truncated, changed } = truncateOverLengthEntries(content, { hookMaxChars });
+  return {
+    newContent,
+    ranCompaction: true,
+    changed,
+    truncated,
+    before,
+    after: { bytes: Buffer.byteLength(newContent, 'utf8'), lineCount: newContent.split(/\r?\n/).length },
+  };
+}
+
+function buildCompactionNote(result, { capBytes = CAP_BYTES, capLines = CAP_LINES, hookMaxChars = HOOK_MAX_CHARS } = {}) {
+  if (!result.ranCompaction || result.truncated.length === 0) return null;
+  const capKb = (capBytes / 1024).toFixed(1);
+  const out = [
+    `Auto-memory compaction — MEMORY.md crossed ${Math.round(TRIGGER * 100)}% of its ${capKb}KB / ${capLines}-line ` +
+      `cap, so ${result.truncated.length} over-length ${result.truncated.length === 1 ? 'entry was' : 'entries were'} ` +
+      `truncated to ${hookMaxChars} chars in place (detail belongs in the linked topic file / vault, not the ` +
+      `always-loaded index — [[auto-memory-index-hygiene]]).`,
+  ];
+  for (const t of result.truncated.slice(0, MAX_OFFENDERS)) {
+    out.push(`  • ${t.originalLength} → ${hookMaxChars} chars — ${t.label}`);
+  }
+  if (result.truncated.length > MAX_OFFENDERS) out.push(`  • …and ${result.truncated.length - MAX_OFFENDERS} more`);
+  return out.join('\n');
+}
+
+function buildReport(analysis, filePath) {
+  const { bytes, lineCount, offenders } = analysis;
+  if (bytes < CAP_BYTES * TRIGGER && lineCount < CAP_LINES * TRIGGER) return null; // healthy → silent
+  const kb = (bytes / 1024).toFixed(1);
+  const capKb = (CAP_BYTES / 1024).toFixed(1);
+  const pct = Math.round((bytes / CAP_BYTES) * 100);
+  const out = [
+    `Auto-memory index budget check — ${filePath}`,
+    `MEMORY.md is ${kb}KB / ${lineCount} lines (${pct}% of the ${capKb}KB / ${CAP_LINES}-line ` +
+      `session-start load cap). Compact toward one-line hooks per ` +
+      `[[auto-memory-index-hygiene]] before it overflows — detail belongs in the linked ` +
+      `topic files, which are not loaded at startup.`,
+  ];
+  if (offenders.length) {
+    out.push(`Entries over ${HOOK_MAX_CHARS} chars (compact these first):`);
+    for (const o of offenders.slice(0, MAX_OFFENDERS)) out.push(`  • ${o.length} chars — ${o.label}`);
+    if (offenders.length > MAX_OFFENDERS) out.push(`  • …and ${offenders.length - MAX_OFFENDERS} more`);
+  }
+  return out.join('\n');
+}
+
+async function main() {
+  if (process.env.HEYSPEX_AUTO_MEMORY_BUDGET_OFF === '1') return;
+  // No CLAUDE_AGENT gate ([[HS-DT9L-NLR7-DIAG-nine-hooks-are-switched-off-in]]).
+  // The memory index is loaded into EVERY session, interactive included, so the
+  // context it costs is paid in both — gating the check on unattended sessions
+  // only meant the one place a human reads the warning never got it.
+  // Safe to run everywhere: it emits NOTHING while the index is inside budget
+  // (measured 0 bytes on 2026-08-15). Break-glass stays HEYSPEX_AUTO_MEMORY_BUDGET_OFF=1.
+
+  const raw = await readStdinJson();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (payload?.hook_event_name !== 'SessionStart') return;
+
+  const projectDir =
+    (typeof payload.cwd === 'string' && payload.cwd) || process.env.CLAUDE_PROJECT_DIR || repoRoot();
+  const file = resolveMemoryFile(projectDir);
+
+  let content;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+  } catch {
+    return; // absent / unreadable → silent
+  }
+
+  // 1. Self-heal: evict provably-mirrored entries and persist (best-effort).
+  //    A `specs/memory/<…>` link is resolved against the repo before eviction —
+  //    a dangling link is kept (its content has no other home). `specs/` is a
+  //    VAULT artifact (per ADR-0009's two-root split, spexharness/src/config-
+  //    root.mjs), not a code-checkout one — since the 2026-08-31 repo split put
+  //    the vault in its own checkout, resolving against `repoRoot()` (this code
+  //    repo) would find `specs/` nowhere and treat every real mirror as
+  //    dangling. `defaultConfigRoot()` resolves the ACTIVE vault the same way
+  //    every other hook's config-gated rule does (env HEYSPEX_VAULT_DIR /
+  //    HEYSPEX_VAULT_ROOT wins outright; falls back to a cwd-contained vault,
+  //    then the registry pointer, then this code root).
+  const base = defaultConfigRoot();
+  const vaultHomeExists = (rel) => {
+    try {
+      return fs.existsSync(path.resolve(base, rel.split('#')[0].trim()));
+    } catch {
+      return false;
+    }
+  };
+  let evictionNote = null;
+  const { newContent, evicted, changed } = evictVaultMirrors(content, vaultHomeExists);
+  if (changed) {
+    if (process.env.HEYSPEX_AUTO_MEMORY_SELF_HEAL_OFF === '1') {
+      // Write disabled — fall back to flagging the mirrors without mutating.
+      evictionNote = buildEvictionNote(evicted).replace('evicted', 'would evict');
+    } else {
+      try {
+        fs.writeFileSync(file, newContent);
+        content = newContent; // advise against the healed file
+        evictionNote = buildEvictionNote(evicted);
+      } catch {
+        // Write failed (permissions, etc.) — keep going; advise against the original.
+        evictionNote = buildEvictionNote(evicted).replace('evicted', 'could not evict');
+      }
+    }
+  }
+
+  // 1.5. Compact: eviction alone only removes provably-mirrored entries: once
+  //    what remains has crossed 70% of the cap, truncate remaining over-length
+  //    entries in place too. [[HS-AE28-NYPR-TASK-add-a-compaction-rule-that-runs-when]]
+  let compactionNote = null;
+  const compaction = compactMemoryIndex(content);
+  if (compaction.changed) {
+    if (process.env.HEYSPEX_AUTO_MEMORY_SELF_HEAL_OFF === '1') {
+      compactionNote = buildCompactionNote(compaction)?.replace('were truncated', 'would be truncated') ?? null;
+    } else {
+      try {
+        fs.writeFileSync(file, compaction.newContent);
+        content = compaction.newContent; // advise against the compacted file
+        compactionNote = buildCompactionNote(compaction);
+      } catch {
+        compactionNote = buildCompactionNote(compaction)?.replace('were truncated', 'could not be truncated') ?? null;
+      }
+    }
+  }
+
+  // 2. Advise: budget report for whatever remains.
+  const report = buildReport(analyze(content), file);
+  const combined = [evictionNote, compactionNote, report].filter(Boolean).join('\n\n') || null;
+  emit('SessionStart', combined);
+}
+
+// Only run the hook when this file is executed directly (the Claude Code hooks
+// runner spawns it as a subprocess) — NOT on import. Without this guard, a
+// test/gate script importing the pure engine functions above (evictVaultMirrors,
+// compactMemoryIndex, truncateOverLengthEntries) would also trigger main()'s
+// stdin read as a side effect, hanging the importing process
+// ([[HS-STRB-NYPR-TASK-replace-every-inline-copy-of-a]] found the same defect
+// in check-claude-md-budget.mjs).
+const isDirectExecution =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectExecution) {
+  main().catch(() => {
+    // Never break Claude Code on a hook failure.
+  });
+}