@pcircle/memesh 4.6.0 → 4.6.2

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

@@ -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
@@ -148,6 +174,7 @@ process.stdin.on('end', () => {
         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-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,7 +53,9 @@ process.stdin.on('end', () => {
       return pass();
     }
 
-    // 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 {
@@ -54,151 +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 filtering.
-    // After the throttle/db checks: this spawns 1-2 git subprocesses, and the
-    // throttled path (every repeat edit of the same file) must not pay for it.
-    const projectName = getProjectName(data.cwd);
+    // 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

package/scripts/hooks/session-start.js

@@ -802,14 +802,16 @@ process.stdin.on('end', async () => {
       // the assembleTopologyBlock call — "the same block" depends on the two
       // surfaces agreeing, so neither side restates the numbers.
 
+      // Only the entities we will actually render — the lesson query pulls
+      // up to 50 rows for the banner count, but at most 5 are injected, and
+      // this runs before the user's first turn. Bounded well under SQLite's
+      // 999-variable limit by construction (5 lessons + sessionLimit
+      // project + 5 recent). Declared out here because the injected-set
+      // record below must list the SAME lessons the block renders.
+      const topLessons = lessonEntities.slice(0, 5);
+
       const memoryLines = [];
       try {
-        // Only the entities we will actually render — the lesson query pulls
-        // up to 50 rows for the banner count, but at most 5 are injected, and
-        // this runs before the user's first turn. Bounded well under SQLite's
-        // 999-variable limit by construction (5 lessons + sessionLimit
-        // project + 5 recent).
-        const topLessons = lessonEntities.slice(0, 5);
         const rankedIds = [
           ...topLessons.map(e => e.id),
           ...projectEntities.map(e => e.id),
@@ -871,6 +873,10 @@ process.stdin.on('end', async () => {
           return {
             name: e.name,
             type: e.type || 'memory',
+            // The citation handle: topologyLine prints `[mem:<id>]` so the
+            // agent can credit the exact memory it used (the Stop hook's
+            // accounting reads those markers back).
+            id: e.id,
             title: e.title ?? null,
             snippet: snippets.get(e.id) ?? null,
             signalScore: meta && typeof meta.signal_score === 'number' ? meta.signal_score : null,
@@ -905,24 +911,29 @@ process.stdin.on('end', async () => {
         // charges the task-state block and the sections against ONE ceiling
         // and returns whole lines only, so the closing fence cannot be cut.
         memoryContext = buildReferenceContext(memoryLines);
+        // The citation contract — OUTSIDE the fence on purpose: the fence
+        // declares its content "background data, not instructions", and
+        // this line IS an instruction. One line is the entire write side of
+        // the injection-ROI signal; the Stop hook credits recall_hits only
+        // from these markers (self-reported: undercounts, never overcounts).
+        memoryContext += '\nWhen a memory above genuinely informs your work, cite it once inline as [mem:ID], using the id shown on its line.';
       }
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
-      // The Stop hook decides hit/miss by removing the transcript records
-      // Claude Code created FROM this hook's output (see stripHookEchoes in
-      // session-summary.js) and then looking for the entity name in what
-      // remains. `injectedContext` is kept as the record of what was shown,
-      // not as a string to subtract — an earlier version subtracted it and a
-      // later one counted its occurrences, and BOTH were wrong because one
-      // injection is echoed into the transcript more than once.
+      // The Stop hook credits recall_hits from EXPLICIT `[mem:id]` citations
+      // the agent writes (after structurally removing the transcript records
+      // Claude Code created FROM this hook's output — the injected block
+      // itself prints a handle on every line; see stripHookEchoes in
+      // session-summary.js). Literal-content matching was retired after
+      // measuring 0% signal over ten real sessions. `injectedContext` is
+      // kept as the record of what was shown.
       //
-      // It must still be the text we actually injected: previously it was the
-      // count-only banner, so every injected entity was scored against a
-      // transcript it had never appeared in and took a `recall_miss` it did
-      // not earn.
+      // The set below is every pool the topology block draws from — the
+      // lessons pool included. It used to record only project + recent
+      // rows, so an injected lesson could never be credited at all.
       try {
         const seenIds = new Set();
-        const allInjected = [...projectEntities, ...recentEntities].filter(e => {
+        const allInjected = [...topLessons, ...projectEntities, ...recentEntities].filter(e => {
           if (seenIds.has(e.id)) return false;
           seenIds.add(e.id);
           return true;
@@ -959,11 +970,11 @@ process.stdin.on('end', async () => {
           } catch {}
         }
       } catch (err) {
-        // Non-critical — sessions-file write powers recall-effectiveness
-        // tracking (recall_hits / recall_misses on the dashboard). If it
-        // silently breaks, the impact-score factor in core/scoring.ts
-        // converges on 0.5 (neutral) for everything. Stderr trace so a
-        // permission/serialisation regression is visible.
+        // Non-critical — sessions-file write powers citation accounting
+        // (recall_hits credited from `[mem:id]` markers). If it silently
+        // breaks, no hit can ever be credited and the impact-score factor
+        // in core/scoring.ts converges on 0.5 (neutral) for everything.
+        // Stderr trace so a permission/serialisation regression is visible.
         try { process.stderr.write(`[memesh session-start] sessions-write: ${err?.message || err}\n`); } catch {}
       }