@pcircle/memesh 4.5.1 → 4.6.1

package/scripts/hooks/guard-check.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+// Lesson guards — PreToolUse hook for Bash (G1).
+//
+// A guard is a failure-lesson a human promoted (via the dream proposal
+// queue) to speak at the moment its mistake is about to repeat: a regex
+// over the command about to run. This hook is the Bash evaluation point;
+// the Edit/Write point lives inside pre-edit-recall, which is already
+// wired to that matcher.
+//
+// Contract, in order of importance:
+//   1. NEVER block or slow the user's work: every failure path is a
+//      silent pass (with a stderr trace), and v1 guards only WARN — the
+//      warning is additionalContext, exit code stays 0.
+//   2. The guard message is memory content — attacker-influenced in the
+//      general case — so it is fenced by buildReferenceContext exactly
+//      like every other injection path.
+//   3. Every fire is counted (metadata.guard.fires): a guard that never
+//      fires or fires constantly is a review item, and the count is what
+//      surfaces it.
+
+import { existsSync } from 'fs';
+import {
+  buildReferenceContext,
+  getDbPath,
+  loadActiveGuards,
+  matchingGuards,
+  guardWarningLines,
+  recordGuardFires,
+} from './_shared.js';
+import { MemeshDatabase } from './_generated/sqlite.js';
+
+const dbPath = getDbPath();
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const command = data?.tool_input?.command;
+    if (!command || typeof command !== 'string') return pass();
+    if (!existsSync(dbPath)) return pass();
+
+    // `readOnly`, not `readonly`: node:sqlite ignores the lowercase
+    // spelling and hands back a WRITABLE handle. This hook only reads;
+    // the fire counter opens its own writable handle for the one UPDATE.
+    const db = new MemeshDatabase(dbPath, { readOnly: true });
+    let matches;
+    try {
+      matches = matchingGuards(loadActiveGuards(db, 'Bash'), 'Bash', command);
+    } finally {
+      db.close();
+    }
+    if (!matches || matches.length === 0) return pass();
+
+    recordGuardFires(dbPath, matches.map((g) => g.lessonId));
+
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: buildReferenceContext(guardWarningLines(matches, 'Bash')),
+      },
+    }));
+    process.exit(0);
+  } catch (err) {
+    // Never crash Claude Code, but trace — a silent break here means
+    // every accepted guard stops firing and nothing reports it.
+    try { process.stderr.write(`[memesh guard-check] ${err?.message || err}\n`); } catch {}
+    pass();
+  }
+});
+
+function pass() {
+  process.exit(0);
+}

package/scripts/hooks/post-commit.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'child_process';
-import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun } from './_shared.js';
+import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
 
 let input = '';
 process.stdin.setEncoding('utf8');
@@ -133,6 +133,32 @@ process.stdin.on('end', () => {
         // git show failed — no diff stats recorded, existing behavior unchanged
       }
 
+      // Commit → session linkage, the hop `memesh why` walks. The payload has
+      // carried session_id all along; this hook just never recorded it, so
+      // every commit entity was an island (no file list, no session, no
+      // relations). Recorded as METADATA, not tags, on purpose: a `file:*`
+      // tag here would make pre-edit-recall inject commit noise into every
+      // edit of a touched file (Strategy 1 joins on exactly that tag).
+      const whyMetadata = {};
+      if (typeof data.session_id === 'string' && data.session_id) {
+        whyMetadata.session_id = data.session_id;
+      }
+      try {
+        const nameOnly = execFileSync('git', ['-C', data.cwd, 'show', '--name-only', '--format=', commitHash], {
+          encoding: 'utf8',
+          timeout: 5000,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        if (nameOnly) {
+          // Repo-relative paths, capped: a lockfile-churn commit can touch
+          // thousands of files and metadata rides every entity read.
+          const files = nameOnly.split('\n').map(l => l.trim()).filter(Boolean);
+          if (files.length > 0) whyMetadata.files = files.slice(0, 50);
+        }
+      } catch {
+        // Best-effort like the diff stats above — no file list recorded.
+      }
+
       // Shared write dance — upsert entity + observations + tags AND reindex FTS.
       //
       // `source:auto-capture` is the provenance marker every capture hook
@@ -140,11 +166,15 @@ process.stdin.on('end', () => {
       // this one did not). `memesh doctor` counts it to answer "is the
       // auto-capture loop alive" — a question it used to answer from entity
       // TYPE, which a hand-typed `memesh learn` satisfied all by itself.
+      // The commit subject IS the title — git authors already wrote a
+      // one-line human summary; nothing to synthesize.
       const written = captureEntity(db, {
         name: entityName,
         type: 'commit',
         observations,
         tags: [AUTO_CAPTURE_TAG, `project:${projectName}`],
+        title: truncateTitle(commitMsg),
+        metadata: whyMetadata,
       });
 
       // Heartbeat AFTER capture, so the stamp certifies "the capture loop

package/scripts/hooks/pre-compact.js

@@ -2,7 +2,7 @@
 
 import { basename } from 'path';
 import { existsSync, readFileSync } from 'fs';
-import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun } from './_shared.js';
+import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
 
 // Timeout guard: always exit within 10 seconds
 const TIMEOUT_MS = 10000;
@@ -95,6 +95,17 @@ process.stdin.on('end', () => {
 
     // Build observation content
     const obsLines = [`Compaction reason: ${reason}`, `Tool calls: ${toolCallCount}`];
+
+    // No free-form human text exists for a pre-compact save (unlike a commit
+    // subject) — same date+project+verb heuristic as session-summary.js.
+    // This hook was the one missed by the original design (it hand-rolls the
+    // same captureEntity dance as its two siblings but was overlooked as a
+    // "write hook" until a code audit found it), so its entities were the
+    // clearest case of a raw machine key (`pre-compact-<sessionId>`) with a
+    // terse observation ("Compaction reason: manual") standing in as the
+    // display label.
+    const titleDate = new Date().toISOString().slice(0, 10);
+    const title = truncateTitle(`${titleDate} ${projectName}: ${reason} compaction (${toolCallCount} tool calls)`);
     if (editedFiles.size > 0) {
       obsLines.push(`Files edited: ${Array.from(editedFiles).join(', ')}`);
     }
@@ -111,6 +122,7 @@ process.stdin.on('end', () => {
         type: 'session-summary',
         observations: obsLines,
         tags: [AUTO_CAPTURE_TAG, 'urgency:pre-compact', `project:${projectName}`],
+        title,
       });
 
       // Heartbeat AFTER capture, so the stamp certifies "the capture loop

package/scripts/hooks/pre-edit-recall.js

@@ -3,6 +3,12 @@
 // Continuous Recall — PreToolUse hook for Edit/Write
 // When editing a file, checks if MeMesh has relevant memories
 // and injects them as context. Throttled: max 1 recall per file per session.
+//
+// Also the Edit/Write evaluation point for lesson guards (G1): accepted
+// guards match against the path plus the content about to be written, and
+// a hit injects the lesson's warning at the exact moment its mistake is
+// about to repeat. Guards are NOT throttled — a dangerous edit is
+// dangerous every time.
 
 import { basename, join } from 'path';
 import { existsSync, readFileSync } from 'fs';
@@ -15,6 +21,10 @@ import {
   isTrustedForAutoContext,
   writePrivateJson,
   hookMatchExpression,
+  loadActiveGuards,
+  matchingGuards,
+  guardWarningLines,
+  recordGuardFires,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
 
@@ -43,10 +53,9 @@ process.stdin.on('end', () => {
       return pass();
     }
 
-    // Get project name from cwd for project-scoped filtering
-    const projectName = getProjectName(data.cwd);
-
-    // Throttle: skip if we already recalled for this file
+    // Throttle — the RECALL half runs once per file per session. The guard
+    // half is deliberately outside it, so a throttled call still opens the
+    // database for the guard pass.
     const fileKey = filePath.toLowerCase();
     let seenFiles = [];
     try {
@@ -57,146 +66,175 @@ process.stdin.on('end', () => {
     } catch {
       seenFiles = [];
     }
-
-    if (seenFiles.includes(fileKey)) {
-      return pass();
-    }
+    const throttled = seenFiles.includes(fileKey);
 
     if (!existsSync(dbPath)) return pass();
 
+    // Get project name from cwd for project-scoped RECALL filtering — this
+    // spawns 1-2 git subprocesses, and the throttled path (every repeat
+    // edit of the same file) must not pay for it. Guards are global by
+    // design: a mistake recorded in one project is usually a mistake
+    // everywhere (the pipe-eats-exit-code shape), and the warning names
+    // its source lesson either way.
+    const projectName = throttled ? null : getProjectName(data.cwd);
+
     // `readOnly`, not `readonly`: node:sqlite ignores the lowercase spelling
-    // and hands back a WRITABLE handle. This hook only reads.
+    // and hands back a WRITABLE handle. This hook only reads; the guard
+    // fire counter opens its own writable handle for its one UPDATE.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    let guardMatches = [];
+    const recallLines = [];
     try {
+      // Guard pass (G1) — matched against the path plus the content about
+      // to land, which is what the mistake would be made OF.
+      const toolName = data.tool_name === 'Write' ? 'Write' : 'Edit';
+      const guardHaystack = `${filePath}\n${toolInput.new_string ?? toolInput.content ?? ''}`;
+      guardMatches = matchingGuards(loadActiveGuards(db, toolName), toolName, guardHaystack);
 
-      // Check if entities table exists
-      // Both tables, not just `entities`. Strategy 2 below joins entities_fts,
-      // and this hook opens the database READ-ONLY without going through
-      // openHookDb, so it never creates that table. Checking only `entities`
-      // meant a structurally-absent index reached the query and failed there —
-      // which, now that the failure is no longer swallowed, would print on
-      // every single Edit.
-      const tables = new Set(
-        db.prepare(
-          "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('entities','entities_fts')"
-        ).all().map((r) => r.name)
-      );
-      if (!tables.has('entities')) return pass();
-      const hasFts = tables.has('entities_fts');
-
-      const hasStatus = db.prepare("PRAGMA table_info(entities)").all()
-        .some(c => c.name === 'status');
-      const statusFilter = hasStatus ? "AND e.status = 'active'" : '';
+      // Recall pass — throttled, project-scoped.
+      if (!throttled) {
+        // Check if entities table exists
+        // Both tables, not just `entities`. Strategy 2 below joins entities_fts,
+        // and this hook opens the database READ-ONLY without going through
+        // openHookDb, so it never creates that table. Checking only `entities`
+        // meant a structurally-absent index reached the query and failed there —
+        // which, now that the failure is no longer swallowed, would print on
+        // every single Edit.
+        const tables = new Set(
+          db.prepare(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('entities','entities_fts')"
+          ).all().map((r) => r.name)
+        );
+        if (tables.has('entities')) {
+          const hasFts = tables.has('entities_fts');
 
-      // Search strategies:
-      // 1. Entities tagged with the file's basename (e.g., "file:auth.ts")
-      // 2. Entities with name matching the file's basename (without extension)
-      // 3. FTS5 search on the basename (without extension)
-      const fileName = basename(filePath);
-      const fileNameNoExt = fileName.replace(/\.[^.]+$/, '');
+          const hasStatus = db.prepare("PRAGMA table_info(entities)").all()
+            .some(c => c.name === 'status');
+          const statusFilter = hasStatus ? "AND e.status = 'active'" : '';
 
-      const results = [];
+          // Search strategies:
+          // 1. Entities tagged with the file's basename (e.g., "file:auth.ts")
+          // 2. Entities with name matching the file's basename (without extension)
+          // 3. FTS5 search on the basename (without extension)
+          const fileName = basename(filePath);
+          const fileNameNoExt = fileName.replace(/\.[^.]+$/, '');
 
-      // Strategy 1: Tag-based search (file:name or mentions of the file)
-      // CRITICAL: Filter by project to prevent cross-project memory injection
-      const projectTag = `project:${projectName}`;
-      const tagResults = db.prepare(`
-        SELECT DISTINCT e.id, e.name, e.type, e.metadata
-        FROM entities e
-        JOIN tags t1 ON t1.entity_id = e.id
-        JOIN tags t2 ON t2.entity_id = e.id
-        WHERE (t1.tag = ? OR t1.tag = ?)
-          AND t2.tag = ?
-        ${statusFilter}
-        LIMIT ?
-      `).all(`file:${fileName}`, `file:${fileNameNoExt}`, projectTag, MAX_RESULTS * 3);
-      results.push(...tagResults.filter((row) => isTrustedForAutoContext(row.metadata)));
+          const results = [];
 
-      // Strategy 2: FTS5 search on file name (if not enough results)
-      // CRITICAL: Filter by project to prevent cross-project memory injection
-      if (hasFts && results.length < MAX_RESULTS && fileNameNoExt.length >= 4) {
-        // Built by the same function core uses, so this query asks for the
-        // tokens the index actually holds. Quoting the raw basename here meant
-        // a CJK or decomposed-Unicode filename matched nothing at all against
-        // the segmented index — and the catch below made that invisible.
-        const matchExpr = hookMatchExpression(fileNameNoExt);
-        try {
-          // ORDER BY rank is load-bearing now that terms are OR-ed.
-          //
-          // The match expression used to be a single phrase, so `LIMIT` picked
-          // from a handful of rows that all genuinely contained the basename and
-          // arbitrary selection was tolerable. `hookMatchExpression` now emits
-          // `"knowledge" OR "graph"` for `knowledge-graph.ts` — necessary,
-          // because a CJK basename has to be reachable by its bigrams — which
-          // makes the match set large and unranked selection IS the result:
-          // editing that file in a project whose memories merely mention
-          // "graph" injected whatever the scan happened to reach first, where
-          // the old code correctly injected nothing. BM25 is what makes the OR
-          // safe; without it the fix trades a CJK miss for an ASCII false hit.
-          const ftsResults = matchExpr === null ? [] : db.prepare(`
+          // Strategy 1: Tag-based search (file:name or mentions of the file)
+          // CRITICAL: Filter by project to prevent cross-project memory injection
+          const projectTag = `project:${projectName}`;
+          const tagResults = db.prepare(`
             SELECT DISTINCT e.id, e.name, e.type, e.metadata
             FROM entities e
-            JOIN entities_fts fts ON fts.rowid = e.id
-            JOIN tags t ON t.entity_id = e.id
-            WHERE entities_fts MATCH ?
-              AND t.tag = ?
+            JOIN tags t1 ON t1.entity_id = e.id
+            JOIN tags t2 ON t2.entity_id = e.id
+            WHERE (t1.tag = ? OR t1.tag = ?)
+              AND t2.tag = ?
             ${statusFilter}
-            ORDER BY fts.rank, e.id DESC
             LIMIT ?
-          `).all(matchExpr, projectTag, (MAX_RESULTS - results.length) * 3);
-          // Deduplicate
-          for (const r of ftsResults) {
-            if (!isTrustedForAutoContext(r.metadata)) continue;
-            if (!results.some(existing => existing.id === r.id)) {
-              results.push(r);
+          `).all(`file:${fileName}`, `file:${fileNameNoExt}`, projectTag, MAX_RESULTS * 3);
+          results.push(...tagResults.filter((row) => isTrustedForAutoContext(row.metadata)));
+
+          // Strategy 2: FTS5 search on file name (if not enough results)
+          // CRITICAL: Filter by project to prevent cross-project memory injection
+          if (hasFts && results.length < MAX_RESULTS && fileNameNoExt.length >= 4) {
+            // Built by the same function core uses, so this query asks for the
+            // tokens the index actually holds. Quoting the raw basename here meant
+            // a CJK or decomposed-Unicode filename matched nothing at all against
+            // the segmented index — and the catch below made that invisible.
+            const matchExpr = hookMatchExpression(fileNameNoExt);
+            try {
+              // ORDER BY rank is load-bearing now that terms are OR-ed.
+              //
+              // The match expression used to be a single phrase, so `LIMIT` picked
+              // from a handful of rows that all genuinely contained the basename and
+              // arbitrary selection was tolerable. `hookMatchExpression` now emits
+              // `"knowledge" OR "graph"` for `knowledge-graph.ts` — necessary,
+              // because a CJK basename has to be reachable by its bigrams — which
+              // makes the match set large and unranked selection IS the result:
+              // editing that file in a project whose memories merely mention
+              // "graph" injected whatever the scan happened to reach first, where
+              // the old code correctly injected nothing. BM25 is what makes the OR
+              // safe; without it the fix trades a CJK miss for an ASCII false hit.
+              const ftsResults = matchExpr === null ? [] : db.prepare(`
+                SELECT DISTINCT e.id, e.name, e.type, e.metadata
+                FROM entities e
+                JOIN entities_fts fts ON fts.rowid = e.id
+                JOIN tags t ON t.entity_id = e.id
+                WHERE entities_fts MATCH ?
+                  AND t.tag = ?
+                ${statusFilter}
+                ORDER BY fts.rank, e.id DESC
+                LIMIT ?
+              `).all(matchExpr, projectTag, (MAX_RESULTS - results.length) * 3);
+              // Deduplicate
+              for (const r of ftsResults) {
+                if (!isTrustedForAutoContext(r.metadata)) continue;
+                if (!results.some(existing => existing.id === r.id)) {
+                  results.push(r);
+                }
+              }
+            } catch (err) {
+              // Never fail the user's edit over a recall miss, but do not pretend
+              // nothing happened either: a silently-skipped FTS query is how this
+              // hook injected zero memories for months without anyone noticing.
+              //
+              // Throttled, because PreToolUse fires a fresh process per Edit/Write
+              // and a persistent fault would otherwise print on every keystroke's
+              // worth of tool calls. Once per distinct message per day is enough to
+              // be noticed without becoming noise the user learns to ignore.
+              reportOnce(`fts:${err?.message || err}`, `filename search failed: ${err?.message || err}`);
             }
           }
-        } catch (err) {
-          // Never fail the user's edit over a recall miss, but do not pretend
-          // nothing happened either: a silently-skipped FTS query is how this
-          // hook injected zero memories for months without anyone noticing.
-          //
-          // Throttled, because PreToolUse fires a fresh process per Edit/Write
-          // and a persistent fault would otherwise print on every keystroke's
-          // worth of tool calls. Once per distinct message per day is enough to
-          // be noticed without becoming noise the user learns to ignore.
-          reportOnce(`fts:${err?.message || err}`, `filename search failed: ${err?.message || err}`);
-        }
-      }
 
-      if (results.length === 0) {
-        // Record as seen even with no results (avoid re-querying)
-        recordSeen(seenFiles, fileKey);
-        return pass();
-      }
+          if (results.length > 0) {
+            // Fetch first observation for each result
+            const getObs = db.prepare(
+              'SELECT content FROM observations WHERE entity_id = ? ORDER BY id ASC LIMIT 1'
+            );
 
-      // Fetch first observation for each result
-      const getObs = db.prepare(
-        'SELECT content FROM observations WHERE entity_id = ? ORDER BY id ASC LIMIT 1'
-      );
+            recallLines.push(`Relevant memories for ${fileName}:`);
+            for (const r of results.slice(0, MAX_RESULTS)) {
+              const obs = getObs.get(r.id);
+              const snippet = obs ? obs.content.slice(0, 120) : '';
+              recallLines.push(snippet
+                ? `• ${r.name} (${r.type}): ${snippet}`
+                : `• ${r.name} (${r.type})`
+              );
+            }
+          }
 
-      const lines = [`Relevant memories for ${fileName}:`];
-      for (const r of results.slice(0, MAX_RESULTS)) {
-        const obs = getObs.get(r.id);
-        const snippet = obs ? obs.content.slice(0, 120) : '';
-        lines.push(snippet
-          ? `• ${r.name} (${r.type}): ${snippet}`
-          : `• ${r.name} (${r.type})`
-        );
+          // Record as seen either way (avoid re-querying a no-result file)
+          recordSeen(seenFiles, fileKey);
+        }
       }
-
-      // Record as seen
-      recordSeen(seenFiles, fileKey);
-
-      console.log(JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          additionalContext: buildReferenceContext(lines),
-        },
-      }));
     } finally {
       db.close();
     }
+
+    if (guardMatches.length === 0 && recallLines.length === 0) {
+      return pass();
+    }
+
+    if (guardMatches.length > 0) {
+      recordGuardFires(dbPath, guardMatches.map((g) => g.lessonId));
+    }
+
+    // One fenced block, guards first — the warning about the edit at hand
+    // outranks background recall. Both halves are memory content, so both
+    // ride the same "background data" fence.
+    const toolLabel = data.tool_name === 'Write' ? 'Write' : 'Edit';
+    const lines = guardMatches.length > 0
+      ? [...guardWarningLines(guardMatches, toolLabel), ...(recallLines.length > 0 ? ['', ...recallLines] : [])]
+      : recallLines;
+
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: buildReferenceContext(lines),
+      },
+    }));
   } catch (err) {
     // Never crash Claude Code, but trace — peer hooks (post-commit,
     // pre-compact, session-summary) all stderr-trace their outer