@pcircle/memesh 4.5.0 → 4.6.0

package/scripts/hooks/session-summary.js

@@ -3,14 +3,30 @@
 // Session Auto-Capture — Stop hook
 // Extracts knowledge from completed Claude Code sessions
 // and stores as session-insight entities in MeMesh.
+//
+// THIS HOOK STAYS, and that was an open question rather than an assumption.
+// `dream run --from-transcripts` reads the same sessions from their raw JSONL
+// and does not depend on this hook having fired, so the obvious next step was
+// to retire the hook as redundant. Measured first, on a real graph
+// (2026-08-09, 214 active entities, ollama nomic-embed-text, L2 over the same
+// `name + observations` text the runtime embeds):
+//
+//   every transcript-mined memory -> its nearest hook-captured entity
+//     min 0.784   p25 0.821   p50 0.865   max 0.946
+//     within 0.55: 0 of 47.   within 0.70: 0 of 47.
+//
+// Nothing the transcript miner produced came within 0.78 of anything this hook
+// recorded. They are not two views of the same material: this hook records what
+// HAPPENED (files touched, commands run, commits), the miner extracts what was
+// DECIDED and what was LEARNED. Retiring either one loses a whole category.
 
 import { createRequire } from 'module';
 import { basename, join } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
 import { spawn } from 'child_process';
-import os from 'os';
 import { pathToFileURL } from 'url';
 import {
+  AUTO_CAPTURE_TAG,
   captureEntity,
   decideAutoUpdateHook,
   getMemeshDirFromDbPath,
@@ -19,9 +35,12 @@ import {
   isAutoCaptureEnabled,
   openHookDb,
   readUpdateCheckCache,
+  recordHookRun,
+  stampHookRunOnly,
   resolveAutoUpdatePolicy,
   resolvePluginRoot,
   spawnAutoUpdate,
+  truncateTitle,
 } from './_shared.js';
 
 const require = createRequire(import.meta.url);
@@ -70,9 +89,16 @@ function parseTranscript(transcriptPath) {
   const bashCommands = [];
   const errorsEncountered = [];
   let toolCallCount = 0;
+  let readFailed = false;
+  // The raw file content, returned so downstream consumers (the
+  // recall-effectiveness block) reuse this single read instead of a second
+  // readFileSync — real transcripts reach 47MB, so a second full read plus
+  // re-parse doubles the Stop hook's dominant I/O cost.
+  let rawText = '';
 
   try {
-    const lines = readFileSync(transcriptPath, 'utf8').split('\n').filter(l => l.trim());
+    rawText = readFileSync(transcriptPath, 'utf8');
+    const lines = rawText.split('\n').filter(l => l.trim());
     for (const line of lines) {
       try {
         const entry = JSON.parse(line);
@@ -133,10 +159,15 @@ function parseTranscript(transcriptPath) {
   } catch (err) {
     // The transcript file itself could not be read, which empties this
     // session's entire capture — filesEdited/errors/toolCallCount all return
-    // zero, so downstream `toolCallCount < 3` bails and no session insight,
-    // failure analysis or lesson is produced. An absent file is the normal
-    // "not written yet" case; anything else is a real fault worth a trace.
+    // zero. Left unflagged, those zeros are indistinguishable from a
+    // genuinely quiet session, and the light-session bail downstream would
+    // STAMP the heartbeat — repeated permission/I-O failures keeping doctor
+    // green while every session's capture is lost. `readFailed` is the
+    // distinct signal: capture was lost, not skipped. An absent file
+    // (ENOENT) is the vanished-transcript race, which the caller already
+    // treats as a correct nothing-to-do decision.
     if (err?.code !== 'ENOENT') {
+      readFailed = true;
       try {
         process.stderr.write(
           `[memesh session-summary] transcript ${transcriptPath} unreadable ` +
@@ -146,7 +177,7 @@ function parseTranscript(transcriptPath) {
     }
   }
 
-  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount };
+  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount, readFailed, rawText };
 }
 
 // Main: read stdin, extract insights, store in DB
@@ -176,7 +207,23 @@ process.stdin.on('end', async () => {
 
     const sessionId = inputData.session_id || 'unknown';
     const transcriptPath = inputData.transcript_path;
-    const cwd = inputData.cwd || process.cwd();
+
+    // `cwd` decides the project tag, and the project tag decides which
+    // sessions `session-start` injects and which memories `pre-edit-recall`
+    // surfaces. Falling back to `process.cwd()` — the hook process's launch
+    // directory, which is unspecified for a Stop hook — tagged the session with
+    // whatever happened to be current. Measured: a payload with no `cwd` filed
+    // the whole session under `project:memesh-llm-memory`, a project it had
+    // nothing to do with, silently. That leaks one project's file names, bash
+    // commands and error text into another project's context.
+    //
+    // `post-commit` refuses this exact case and says why: better to miss one
+    // capture than to file it under the wrong project. Same rule here.
+    if (!inputData.cwd) {
+      try { process.stderr.write(`[memesh session-summary] cwd absent in payload (keys: ${Object.keys(inputData).join(',')}); cannot resolve project, skipping capture\n`); } catch {}
+      return exit0();
+    }
+    const cwd = inputData.cwd;
     // Default-allow: when Claude Code's Stop payload omits
     // `was_in_agentic_loop` (it has been silently absent in production
     // for an unknown number of releases — symptom: zero session-insight
@@ -198,7 +245,13 @@ process.stdin.on('end', async () => {
     // but did nothing, the exact sibling of the `was_in_agentic_loop` absence
     // above. Removed; the `toolCallCount < 3` check below is the real
     // low-signal filter.
-    if (!wasAgenticLoop) return exit0();
+    // From here down the payload is well-formed and attributable — every
+    // bail is the hook deciding "nothing worth saving", which is a
+    // successful run and stamps the heartbeat. The bails ABOVE this line
+    // (empty stdin, malformed JSON, missing cwd) are schema-flip shapes: if
+    // Claude Code's payload changed under us, capture is effectively dead,
+    // and a heartbeat would mask exactly that.
+    if (!wasAgenticLoop) { stampHookRunOnly(process.env, 'session-summary'); return exit0(); }
     // Trace why we're skipping. Two failure modes:
     //   (a) transcript_path absent — schema flip, Claude Code stopped
     //       sending the field. Same bug shape as `was_in_agentic_loop`
@@ -214,14 +267,26 @@ process.stdin.on('end', async () => {
     }
     if (!existsSync(transcriptPath)) {
       try { process.stderr.write(`[memesh session-summary] transcript_path ${transcriptPath} does not exist; skipping capture\n`); } catch {}
+      // The payload named a transcript and the FILE is gone (log rotation
+      // race) — the hook itself ran fine, so this stamps. A payload that
+      // never carried the field at all (schema flip) bails above, unstamped.
+      stampHookRunOnly(process.env, 'session-summary');
       return exit0();
     }
 
-    // Parse transcript
-    const { filesEdited, bashCommands, errorsEncountered, toolCallCount } = parseTranscript(transcriptPath);
+    // Parse transcript (single read — rawText is reused by the
+    // recall-effectiveness block below)
+    const { filesEdited, bashCommands, errorsEncountered, toolCallCount, readFailed, rawText: transcriptRawText } = parseTranscript(transcriptPath);
+
+    // An unreadable transcript is NOT a quiet session: the capture was
+    // LOST (permissions, I/O), and a heartbeat here would keep doctor green
+    // through exactly the repeated failure it exists to expose. No stamp —
+    // parseTranscript already traced the fault to stderr.
+    if (readFailed) return exit0();
 
-    // Skip sessions with too little activity
-    if (toolCallCount < 3) return exit0();
+    // Skip sessions with too little activity — the single most common
+    // healthy exit, so it MUST stamp (see stampHookRunOnly).
+    if (toolCallCount < 3) { stampHookRunOnly(process.env, 'session-summary'); return exit0(); }
 
     // Hoisted to outer-try scope so the LLM failure-analysis block
     // below (which runs AFTER db.close()) can reference it. Earlier
@@ -232,36 +297,27 @@ process.stdin.on('end', async () => {
     const projectName = getProjectName(cwd);
 
     // Open DB via shared helper — applies SCHEMA_SQL + status migration.
-    // sqlite-vec is loaded separately because only this hook needs it
-    // (for embedding-aware recall-effectiveness tracking).
     // { fts: true } guarantees the entities_fts table exists so captureEntity()
     // can keep it in sync — session-insight memories must be FTS-recallable.
-    const handle = openHookDb(process.env, { fts: true });
-    if (!handle) {
-      // Native module unavailable (plugin-marketplace cache install with no
-      // node_modules). Skip session-capture work, but still let the
-      // auto-update tail below run — auto-update is a separate concern from
-      // session-capture, and a transient DB-availability blip should not
-      // mask a security-override patch upgrade. Throwing this sentinel
-      // routes through the existing catch, which already stderr-traces;
-      // execution then falls through to runAutoUpdateAtStop().
-      throw new Error('skip-session-capture: better-sqlite3 unavailable');
-    }
-    const { db } = handle;
-    // sqlite-vec is also a native module; same plugin-cache scenario applies
-    // (the cache tarball ships neither node_module). Resolve through a
-    // try/require here so a missing vec module degrades the same way as a
-    // missing better-sqlite3 instead of throwing into the outer catch as a
-    // bug-shaped error.
-    let sqliteVec;
-    try {
-      sqliteVec = require('sqlite-vec');
-    } catch {
-      throw new Error('skip-session-capture: sqlite-vec unavailable');
-    }
+    //
+    // sqlite-vec is NOT loaded here, and used to be. The comment said it was
+    // needed "for embedding-aware recall-effectiveness tracking" — but this
+    // hook runs exactly two statements, `PRAGMA table_info(entities)` and
+    // `SELECT id FROM entities WHERE name = ?`, and `captureEntity` in
+    // _shared.js touches no vectors either. Nothing here has ever used the
+    // extension.
+    //
+    // It was not free. sqlite-vec ships its engine as a per-platform file
+    // through optionalDependencies, and on a platform it does not publish the
+    // load threw — past the `require` guard, which never fired because the JS
+    // wrapper resolves fine and the throw happens later inside
+    // `sqliteVec.load()`. Measured with the platform binary hidden: the whole
+    // Stop capture vanished (0 entities against a control run's 1) and the
+    // user got a `Require stack:` dump on stderr. An extension nobody calls
+    // was silently costing every session on those platforms its memory.
+    const { db } = openHookDb(process.env, { fts: true });
+    let writeFailed = false;
     try {
-      sqliteVec.load(db);
-
       // Duplicate detection: if we already captured this session, bail.
       //
       // Use the FULL session_id rather than the first 8 chars: real
@@ -270,11 +326,18 @@ process.stdin.on('end', async () => {
       // share the prefix and silently skipped the second session
       // entirely. The contract is one stored capture per distinct
       // session_id, so the dedup key has to be the full id.
+      //
+      // A dedup bail is a SUCCESSFUL run — the loop executed and correctly
+      // decided there was nothing to do — so it stamps the heartbeat like
+      // the capture path below does. Only a throw leaves no stamp.
       const alreadyCaptured = db.prepare("SELECT id FROM entities WHERE name = ?").get(`session-${sessionId}-files`);
-      if (alreadyCaptured) return exit0();
+      if (alreadyCaptured) {
+        recordHookRun(db, 'session-summary');
+        return exit0();
+      }
 
       // Build and store session memories
-      const baseTags = ['source:auto-capture', `session:${sessionId}`, `project:${projectName}`];
+      const baseTags = [AUTO_CAPTURE_TAG, `session:${sessionId}`, `project:${projectName}`];
 
       // Producer for pre-edit-recall's Strategy 1 (`file:<name>` tag lookup).
       // That read path queries both the full basename and the extension-less
@@ -298,10 +361,21 @@ process.stdin.on('end', async () => {
       // entities_fts too. This copy used to insert entity + observations + tags
       // only, skipping the FTS reindex the sibling hooks did — which left every
       // session-insight memory unrecallable via the FTS keyword path.
-      function storeMemory(name, type, observations, tags) {
-        captureEntity(db, { name, type, observations, tags });
+      function storeMemory(name, type, observations, tags, title) {
+        // null = the entity row could not be resolved = this write did NOT
+        // happen (captureEntity's contract). A run with a failed write must
+        // not stamp the heartbeat below — "alive" would be a lie about the
+        // exact thing the heartbeat certifies.
+        if (!captureEntity(db, { name, type, observations, tags, title })) writeFailed = true;
       }
 
+      // No free-form human text exists for these three entities the way a
+      // commit subject does — title is synthesized from the same structured
+      // counts the observations already report. date+project+verb, per the
+      // heuristic the design settled on for hooks with no natural title source.
+      const titleDate = new Date().toISOString().slice(0, 10);
+      const titlePrefix = `${titleDate} ${projectName}`;
+
       // Rule 1: File editing session summary
       if (filesEdited.length > 0) {
         storeMemory(
@@ -311,7 +385,8 @@ process.stdin.on('end', async () => {
             `Session edited ${filesEdited.length} file(s): ${filesEdited.join(', ')}`,
             `Total tool calls: ${toolCallCount}`,
           ],
-          [...baseTags, ...fileTagsFor(filesEdited)]
+          [...baseTags, ...fileTagsFor(filesEdited)],
+          truncateTitle(`${titlePrefix}: edited ${filesEdited.length} file(s)`)
         );
       }
 
@@ -324,7 +399,8 @@ process.stdin.on('end', async () => {
             `Fixed ${errorsEncountered.length} error(s) by editing ${filesEdited.join(', ')}`,
             ...errorsEncountered.slice(0, 3).map(e => `Error: ${e.slice(0, 100)}`),
           ],
-          [...baseTags, 'type:bugfix', ...fileTagsFor(filesEdited)]
+          [...baseTags, 'type:bugfix', ...fileTagsFor(filesEdited)],
+          truncateTitle(`${titlePrefix}: fixed ${errorsEncountered.length} error(s)`)
         );
       }
 
@@ -337,7 +413,8 @@ process.stdin.on('end', async () => {
             `Significant session: ${toolCallCount} tool calls, ${filesEdited.length} files edited`,
             ...bashCommands.slice(0, 3).map(c => `Command: ${c}`),
           ],
-          [...baseTags, 'type:heavy-session']
+          [...baseTags, 'type:heavy-session'],
+          truncateTitle(`${titlePrefix}: significant session (${toolCallCount} tool calls)`)
         );
       }
 
@@ -411,7 +488,9 @@ process.stdin.on('end', async () => {
               // undocumented internal — get it wrong and every entity scores
               // a hit instead of a miss. Structural removal is copy-count
               // and encoding independent.
-              const sessionText = stripHookEchoes(readFileSync(transcriptPath, 'utf8')).toLowerCase();
+              // Reuse the raw text parseTranscript already read — a second
+              // readFileSync doubles the Stop hook's I/O on 47MB transcripts.
+              const sessionText = stripHookEchoes(transcriptRawText).toLowerCase();
 
               // Hit/miss decision lives in `isRecallHit` (exported, unit-tested).
 
@@ -422,14 +501,25 @@ process.stdin.on('end', async () => {
                 'UPDATE entities SET recall_misses = COALESCE(recall_misses, 0) + 1 WHERE id = ?'
               );
 
+              // The injected block shows an entity's TITLE, not its name
+              // (A1 — a machine key like `commit-a1b2c3d` cost tokens and
+              // taught the model nothing). Matching on the name alone would
+              // therefore score a miss against a string the session was never
+              // shown, and a miss is not inert: it lowers the entity's impact
+              // factor in core ranking. Match either.
+              const titleStmt = db.prepare('SELECT title FROM entities WHERE id = ?');
               for (let i = 0; i < entityIds.length; i++) {
                 const name = (entityNames[i] || '').toLowerCase();
                 // Skip names that carry no recall signal: too short, or a
                 // machine identifier (auto-capture entities) that can never
                 // substring-match prose. Scoring those would be a guaranteed
                 // unearned miss — see isMeasurableRecallName.
-                if (!isMeasurableRecallName(name)) continue;
-                if (isRecallHit(sessionText, name)) {
+                let title = null;
+                try { title = titleStmt.get(entityIds[i])?.title ?? null; } catch { /* pre-title schema */ }
+                // A row is measurable if EITHER string could plausibly appear
+                // in prose; a machine-named row with a human title now can.
+                if (!isMeasurableRecallName(name) && !isMeasurableRecallName(title)) continue;
+                if (isRecallHit(sessionText, name) || isRecallHit(sessionText, title)) {
                   updateHit.run(entityIds[i]);
                 } else {
                   updateMiss.run(entityIds[i]);
@@ -446,6 +536,14 @@ process.stdin.on('end', async () => {
         // missing-column failure is visible without crashing the hook.
         try { process.stderr.write(`[memesh session-summary] recall-effectiveness write: ${err?.message || err}\n`); } catch {}
       }
+
+      // Heartbeat AFTER capture, so the stamp certifies "the capture loop
+      // completed", not "a database handle existed". A throw above skips it,
+      // and so does a captureEntity null return (writeFailed) — a run whose
+      // write did not land must not read as alive. (The recall-effectiveness
+      // block catches its own errors — session memories were already stored
+      // by then, so the run still counts.)
+      if (!writeFailed) recordHookRun(db, 'session-summary');
     } finally {
       db.close();
     }
@@ -502,12 +600,12 @@ process.stdin.on('end', async () => {
     }
   } catch (err) {
     // Never crash Claude Code — leave a trace for debugging.
-    // Suppress the expected "skip-session-capture" sentinel (raised when
-    // better-sqlite3 is unavailable in a marketplace-cache install). All
-    // other errors are real bugs and deserve a trace.
-    if (!String(err?.message || '').startsWith('skip-session-capture:')) {
-      try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
-    }
+    //
+    // Every error is traced now. There used to be a suppression branch for a
+    // `skip-session-capture:` sentinel, thrown when sqlite-vec was missing —
+    // an extension this hook never used. The thrower is gone, so the branch
+    // could only ever hide a real error from here on.
+    try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
   }
 
   // Spawn auto-update if policy + cache permit. Runs after all session work
@@ -603,15 +701,15 @@ function dreamHistoryPath() {
   // is in pure string comparisons, which we don't do here. The trace
   // below shows the resolved value verbatim so a Windows diagnosis run
   // can confirm what actually arrived.
-  const fromEnv = process.env.MEMESH_DIR;
-  const fromDbPath = !fromEnv ? getMemeshDirFromDbPath() : null;
-  const fromHome = (!fromEnv && !fromDbPath)
-    ? join(os.homedir() || (os.userInfo()?.homedir ?? '.'), '.memesh')
-    : null;
-  const dir = fromEnv || fromDbPath || fromHome;
+  // The helper IS the precedence (MEMESH_DB_PATH > MEMESH_DIR > home).
+  // A hand-rolled version here inverted it (MEMESH_DIR won over
+  // MEMESH_DB_PATH), so with both set, dream history landed in a different
+  // directory than every sibling state file — plus a dead home-fallback
+  // branch, since the helper always returns a string.
+  const dir = getMemeshDirFromDbPath();
   dreamTrigTrace('resolve', {
-    src: fromEnv ? 'env' : (fromDbPath ? 'db-path' : 'home'),
-    MEMESH_DIR: fromEnv,
+    src: process.env.MEMESH_DB_PATH ? 'db-path' : (process.env.MEMESH_DIR ? 'env' : 'home'),
+    MEMESH_DIR: process.env.MEMESH_DIR,
     MEMESH_DB_PATH: process.env.MEMESH_DB_PATH,
     dir,
     platform: process.platform,
@@ -643,18 +741,18 @@ function writeDreamHistory(history) {
 
 /**
  * Count episodic entities for the given project over the configured
- * window. Read-only — uses the hook's _shared openHookDb helper which
- * is already on the import path.
+ * window. Only issues a SELECT, but the handle is openHookDb's ordinary
+ * read-write one (it runs the schema/migration chain) — there is no
+ * read-only variant on the hook side, and this call site must not stamp
+ * the heartbeat (recordHookRun is per-hook-exit, never per-open).
  */
 function countEpisodicEntities(projectName) {
   let handle;
   try {
     handle = openHookDb();
-    // openHookDb returns null if better-sqlite3 isn't loadable;
-    // otherwise { db, dbPath }. Don't try to call db.prepare() on
-    // the wrapper itself (the previous version did and silently
-    // skipped the gate, defeating the trigger's whole purpose).
-    if (!handle?.db) return 0;
+    // { db, dbPath } — don't call db.prepare() on the wrapper itself (an
+    // earlier version did, and silently skipped the gate, defeating the
+    // trigger's whole purpose).
     const db = handle.db;
     const since = new Date(Date.now() - DREAM_WINDOW_DAYS * 86400000).toISOString();
     const types = DREAM_EPISODIC_TYPES.map(() => '?').join(',');
@@ -754,12 +852,17 @@ export function stripHookEchoes(rawTranscript) {
  * which silently failed on JSON-encoded transcripts and scored every entity a
  * hit — see the callsite comment.)
  *
- * Self-contained for its unit tests: lowercases both sides and ignores names
- * shorter than 4 chars (too generic to match reliably).
+ * Ignores names shorter than 4 chars (too generic to match reliably).
+ *
+ * CONTRACT: `sessionText` must already be lowercased. The haystack is a
+ * multi-megabyte transcript and this runs twice per injected entity (name +
+ * title) — re-lowercasing it inside the function copied the whole transcript
+ * on every call, hundreds of MB of transient allocation in the Stop hook.
+ * The caller lowercases once; only the needle is normalized here.
  */
 export function isRecallHit(sessionText, name) {
   if (!name || name.length < 4) return false;
-  return String(sessionText ?? '').toLowerCase().includes(String(name).toLowerCase());
+  return String(sessionText ?? '').includes(String(name).toLowerCase());
 }
 
 /**

package/scripts/hooks/user-prompt-intent.js

@@ -81,7 +81,7 @@ export function buildHint() {
     '1. Decide WHAT to remember from the conversation context. Be specific — pick observations',
     '   that will be useful in *future* sessions, not session-local state.',
     '',
-    '2. Decide the SCOPE (this drives namespace + tags):',
+    '2. Decide the SCOPE for a NEW memory (this drives namespace + tags):',
     '   • Machine-level / cross-project / preferences  → memesh namespace=personal',
     '   • Project-internal decision / pattern / lesson → memesh + project tag (e.g. tag:project:memesh)',
     '   • Universal / public best practice             → memesh namespace=global (rare)',
@@ -91,7 +91,8 @@ export function buildHint() {
     '   • type: one of (decision, pattern, lesson_learned, bug, process, preference, etc.)',
     '   • observations: array of specific facts / steps / rationale',
     '   • tags: relevant tags (programming language, framework, domain)',
-    '   • namespace: personal (default) | team | global',
+    '   • namespace: personal | team | global — OMIT for a memory that already exists.',
+    '     Supplying it MOVES that memory out of the scope it is in.',
     '',
     '4. Confirm to the user with: entity name + memesh ID returned by the tool.',
     '</memesh-remember-intent>',