@pcircle/memesh 4.5.1 → 4.6.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');
@@ -140,11 +140,14 @@ 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),
       });
 
       // 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

@@ -43,9 +43,6 @@ 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
     const fileKey = filePath.toLowerCase();
     let seenFiles = [];
@@ -64,6 +61,11 @@ process.stdin.on('end', () => {
 
     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);
+
     // `readOnly`, not `readonly`: node:sqlite ignores the lowercase spelling
     // and hands back a WRITABLE handle. This hook only reads.
     const db = new MemeshDatabase(dbPath, { readOnly: true });

package/scripts/hooks/session-start.js

@@ -2,7 +2,6 @@
 
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
-import { homedir } from 'os';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
 import { existsSync, readFileSync, unlinkSync, mkdirSync, accessSync, constants as fsConstants } from 'fs';
@@ -13,10 +12,22 @@ import {
   getMemeshDirFromDbPath,
   getProjectName,
   importFromPluginRoot,
+  assembleTopologyBlock,
+  DEFAULT_TOPOLOGY_BUDGET,
+  SNIPPET_FETCH_CHARS,
+  TOPOLOGY_CANDIDATE_CAP,
   isTrustedForAutoContext,
+  parseEntityMetadata,
+  // Aliased: this file already has a local `const memeshDir` (a resolved
+  // db-path-derived directory string) — the helper here is the MEMESH_DIR/
+  // home resolver the update-check cache itself uses.
+  memeshDir as memeshHomeDir,
+  parseTaskState,
   readUpdateCheckCache,
   resolvePluginRoot,
   resolveSessionLimit,
+  taskStateLines,
+  taskStateName,
   writePrivateJson,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
@@ -192,7 +203,7 @@ function isStrictlyOlder(a, b) {
   return pa.tail < pb.tail;
 }
 
-function buildUpdateAvailableBanner(currentVersion, cache, channel) {
+function buildUpdateAvailableBanner(currentVersion, cache, getChannel) {
   if (!cache || cache.currentVersion !== currentVersion) return [];
   // Deprecation banner takes precedence — when set, it owns the
   // session-start real estate. Skip the soft banner so the user sees
@@ -215,7 +226,10 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
   // this user a banner today?"
   try {
     const fs = require('fs');
-    const dir = join(homedir(), '.memesh');
+    // memeshHomeDir(), not join(homedir(), '.memesh'): the throttle marker
+    // must sit next to the update-check cache it throttles when MEMESH_DIR
+    // is set (readUpdateCheckCache resolves its path with this same helper).
+    const dir = memeshHomeDir();
     try { ensurePrivateDir(dir); } catch { /* best-effort */ }
     const versionTag = /^[0-9A-Za-z.+-]+$/.test(currentVersion) ? currentVersion : 'unknown';
     const markerPath = join(dir, `last-update-banner.${versionTag}.lock`);
@@ -234,6 +248,13 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
     } catch { /* best-effort */ }
   } catch { /* best-effort */ }
 
+  // Channel detection spawns `npm root -g` (50-200ms) — resolve it only
+  // here, after every early return above has had its chance to suppress
+  // the banner. The guards fire on ~every session; the banner at most
+  // once per 24h.
+  let channel = 'unknown';
+  try { channel = getChannel(); } catch { /* best-effort */ }
+
   const lines = [
     '',
     `ℹ️  MeMesh update available: ${cache.latestVersion} (you're on ${currentVersion}).`,
@@ -241,7 +262,7 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
   if (channel === 'npm-global') {
     lines.push(`    Run: memesh update`);
   } else if (channel === 'plugin-marketplace') {
-    lines.push(`    Run: bash <plugin-root>/scripts/upgrade-plugin.sh   (or reinstall from /plugin UI)`);
+    lines.push(`    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`);
   } else if (channel === 'source-checkout') {
     lines.push(`    Source checkout: \`git pull && npm install && npm run build\`.`);
   } else if (channel === 'npm-local') {
@@ -309,7 +330,9 @@ function spawnFreshUpdateCheck(installedVersion) {
     const cliPath = join(pluginRoot, 'dist/transports/cli/cli.js');
     if (!existsSync(cliPath)) return false;
     const fs = require('fs');
-    const dir = join(homedir(), '.memesh');
+    // memeshHomeDir(), not join(homedir(), '.memesh') — same reasoning as
+    // the banner marker above: marker and cache must share a directory.
+    const dir = memeshHomeDir();
     try { ensurePrivateDir(dir); } catch { /* best-effort */ }
     // Codex round 37: scope the throttle marker to the installed
     // version. The marker was machine-global, so a refresh started
@@ -491,8 +514,8 @@ function combineWithBanner(baseMessage) {
       if (deprecation.length > 0) {
         lines = deprecation;
       } else {
-        const channel = detectInstallChannelHook(pluginRoot);
-        lines = buildUpdateAvailableBanner(installedVersion, cache, channel);
+        lines = buildUpdateAvailableBanner(
+          installedVersion, cache, () => detectInstallChannelHook(pluginRoot));
       }
     }
   } catch {
@@ -571,6 +594,10 @@ process.stdin.on('end', async () => {
     // property of the database file that the writing side already set, and a
     // reader opens a WAL database perfectly well without asking for it.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    // Whether the noise-compression epilogue below should run at all —
+    // pre-read from this readonly handle before it closes. Defaults to
+    // true so any early exit still lets the epilogue's own throttle decide.
+    let noiseCompressDue = true;
     try {
       // Check if tables exist (db may exist but be empty)
       const tableCheck = db.prepare(
@@ -633,7 +660,12 @@ process.stdin.on('end', async () => {
       // doesn't have confidence/access_count/last_accessed_at, so the
       // SELECT can't reference them. Build the column list to match
       // what the schema actually supports.
-      const baseCols = 'e.id, e.name, e.type, e.created_at, e.metadata';
+      // `title` is an ALTER-added column (UX-1) and gets the same
+      // legacy-schema guard as the scoring columns: a database that predates
+      // it must still produce an injection, falling back to the observation
+      // snippet for its display text.
+      const hasTitle = colNames.has('title');
+      const baseCols = `e.id, e.name, e.type,${hasTitle ? ' e.title,' : ''} e.created_at, e.metadata`;
       const scoringCols = hasScoringCols
         ? `, e.confidence, e.access_count, e.last_accessed_at`
         : '';
@@ -650,7 +682,7 @@ process.stdin.on('end', async () => {
             pool_stats AS (
               SELECT COALESCE(MAX(access_count), 0) AS max_access FROM pool
             )
-            SELECT p.id, p.name, p.type, p.created_at, p.metadata
+            SELECT p.id, p.name, p.type,${hasTitle ? ' p.title,' : ''} p.created_at, p.metadata
             FROM pool p, pool_stats s
             ORDER BY
               COALESCE(p.confidence, 1.0) * 0.2833
@@ -679,7 +711,19 @@ process.stdin.on('end', async () => {
         `JOIN tags t ON t.entity_id = e.id`,
         `WHERE t.tag = ? ${statusFilter}`,
       );
-      const projectEntities = db.prepare(projectQuery).all(projectTag, sessionLimit * 3)
+      // Over-fetch WIDE, then filter. The window used to be `sessionLimit * 3`
+      // and the trust filter ran after it — so a class of entity that ranks
+      // high can consume the entire window and leave nothing. That was not
+      // hypothetical: measured on a real graph, all 30 top-ranked rows were
+      // filtered out and the "project memory" section rendered empty while 92
+      // eligible entities sat below the cut. The filter is a JS predicate with
+      // one owner (`isTrustedForAutoContext`); rather than restate it as SQL
+      // and own it twice, the window is made wide enough that the filtered
+      // class cannot fill it. CANDIDATE_CAP bounds the work for a large graph.
+      // Shared with the briefing surface via the leaf, so the two sides'
+      // candidate windows cannot drift apart.
+      const CANDIDATE_CAP = TOPOLOGY_CANDIDATE_CAP;
+      const projectEntities = db.prepare(projectQuery).all(projectTag, CANDIDATE_CAP)
         .filter(entity => isTrustedForAutoContext(entity.metadata))
         .slice(0, sessionLimit);
 
@@ -688,7 +732,7 @@ process.stdin.on('end', async () => {
       // so rewrite to e.status for consistency.
       const recentWhere = hasStatus ? "WHERE e.status = 'active'" : '';
       const recentQuery = buildScoringQuery('', recentWhere);
-      const recentEntities = db.prepare(recentQuery).all(15)
+      const recentEntities = db.prepare(recentQuery).all(CANDIDATE_CAP)
         .filter(entity => isTrustedForAutoContext(entity.metadata))
         .slice(0, 5);
 
@@ -701,7 +745,7 @@ process.stdin.on('end', async () => {
       let lessonEntities = [];
       try {
         const lessonRows = db.prepare(`
-          SELECT DISTINCT e.id, e.name, e.type, e.metadata
+          SELECT DISTINCT e.id, e.name, e.type,${hasTitle ? ' e.title,' : ''} e.metadata
           FROM entities e
           JOIN tags t ON t.entity_id = e.id
           WHERE e.type = 'lesson_learned'
@@ -754,8 +798,9 @@ process.stdin.on('end', async () => {
       // stay far under that on purpose — session start should prime the
       // model, not consume its working context. Snippets are truncated per
       // observation and the whole block is hard-capped.
-      const MAX_SNIPPET = 160;
-      const MAX_CONTEXT_CHARS = 4000;
+      // The budget itself comes from the leaf (DEFAULT_TOPOLOGY_BUDGET) at
+      // the assembleTopologyBlock call — "the same block" depends on the two
+      // surfaces agreeing, so neither side restates the numbers.
 
       const memoryLines = [];
       try {
@@ -788,33 +833,59 @@ process.stdin.on('end', async () => {
             // later ones are refinements.
             if (snippets.has(row.entity_id)) continue;
             const text = String(row.content ?? '').replace(/\s+/g, ' ').trim();
-            if (text) snippets.set(row.entity_id, text.slice(0, MAX_SNIPPET));
+            // A few line-widths, not the exact line cap: the final cut is
+            // clip()'s, on a word boundary — a hard slice at the line cap
+            // would hand it a string with nothing left to trim and ship
+            // mid-word fragments again.
+            if (text) snippets.set(row.entity_id, text.slice(0, SNIPPET_FETCH_CHARS));
           }
         }
 
-        // Groups overlap by construction: a lesson tagged to this project
-        // is in lessonEntities AND projectEntities. Render each entity once,
-        // in the highest-priority group it belongs to, so the injected block
-        // doesn't spend the model's context repeating itself.
-        const rendered = new Set();
-        const renderGroup = (label, entities) => {
-          const fresh = entities.filter(e => !rendered.has(e.id));
-          if (fresh.length === 0) return;
-          memoryLines.push(label);
-          for (const e of fresh) {
-            rendered.add(e.id);
-            const snippet = snippets.get(e.id);
-            const type = e.type || 'memory';
-            memoryLines.push(
-              snippet ? `- ${e.name} (${type}): ${snippet}` : `- ${e.name} (${type})`
-            );
-          }
-          memoryLines.push('');
-        };
+        // "Where we left off" leads the block. It is the one memory a new
+        // session needs before any other: everything below is context for
+        // work, this IS the work. It is also the only line here a human
+        // (or an agent acting for one) stated on purpose — the rest is
+        // ranked, and ranking cannot know what you meant to do next.
+        //
+        // Read from metadata, not from the observation trail: observations
+        // are the CHANGE history, and picking "the current goal" out of them
+        // means guessing which line is newest. Metadata holds one answer.
+        const taskRow = db
+          .prepare('SELECT metadata FROM entities WHERE name = ?')
+          .get(taskStateName(projectName));
+        const stateLines = taskStateLines(
+          parseTaskState(parseEntityMetadata(taskRow?.metadata)),
+          projectName,
+        );
 
-        renderGroup('Lessons learned (avoid repeating these):', topLessons);
-        renderGroup(`Project memory for "${projectName}":`, projectEntities);
-        renderGroup('Recently active across projects:', recentEntities);
+        // The pools overlap by construction (a lesson tagged to this project
+        // is in lessonEntities AND projectEntities); the shared assembler
+        // dedupes across them in claim order, so a project-scoped row is
+        // never marked foreign by the cross-project recent pool, and the
+        // topology grouping decides where each one belongs. This mapping —
+        // raw row → TopologyEntity — is the only part this hook owns; the
+        // assembly order, the spacer discipline, the budget and the
+        // task-state exclusion live in the leaf, shared with `briefing`.
+        const toEntity = (e) => {
+          const meta = parseEntityMetadata(e.metadata);
+          return {
+            name: e.name,
+            type: e.type || 'memory',
+            title: e.title ?? null,
+            snippet: snippets.get(e.id) ?? null,
+            signalScore: meta && typeof meta.signal_score === 'number' ? meta.signal_score : null,
+          };
+        };
+        memoryLines.push(...assembleTopologyBlock(
+          stateLines,
+          [
+            { entities: topLessons.map(toEntity), foreign: false },
+            { entities: projectEntities.map(toEntity), foreign: false },
+            { entities: recentEntities.map(toEntity), foreign: true },
+          ],
+          projectName,
+          DEFAULT_TOPOLOGY_BUDGET,
+        ));
       } catch (err) {
         // Snippet enrichment is best-effort. A failure here must not stop
         // the banner or the session — but trace it, because a silent break
@@ -830,22 +901,10 @@ process.stdin.on('end', async () => {
         // attacker-influenced in the general case (anything the agent has
         // ever been told can end up in an observation), so it must be
         // delimited the same way on every injection path — not hand-rolled
-        // per hook.
-        //
-        // Truncate the LINES before wrapping, so the closing fence is never
-        // cut off — a dangling fence would let the tail of the block escape
-        // its delimiter.
-        const budgeted = [];
-        let used = 0;
-        for (const line of memoryLines) {
-          if (used + line.length + 1 > MAX_CONTEXT_CHARS) {
-            budgeted.push('… (truncated)');
-            break;
-          }
-          budgeted.push(line);
-          used += line.length + 1;
-        }
-        memoryContext = buildReferenceContext(budgeted);
+        // per hook. The lines arrive already budgeted — assembleTopologyBlock
+        // 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);
       }
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
@@ -925,12 +984,8 @@ process.stdin.on('end', async () => {
         if (deprecation.length > 0) {
           bannerLines = deprecation;
         } else {
-          let channel = 'unknown';
-          try {
-            const pluginRoot = resolvePluginRoot(import.meta.url);
-            channel = detectInstallChannelHook(pluginRoot);
-          } catch { /* best-effort */ }
-          bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache, channel);
+          bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache,
+            () => detectInstallChannelHook(resolvePluginRoot(import.meta.url)));
         }
       }
       const finalMessage = bannerLines.length > 0
@@ -938,6 +993,25 @@ process.stdin.on('end', async () => {
         : summary;
 
       output(withCaptureWarning(finalMessage), memoryContext);
+
+      // Pre-read the noise-compression throttle on the handle we already
+      // hold. compressWeeklyNoise() re-checks under its own connection, but
+      // ~364/365 sessions are inside the 24h window — and the full path
+      // costs two dist module-graph imports plus a write-capable
+      // migration-chain open (WAL writer lock) that must stay off the
+      // SessionStart hot path. Missing table / any error ⇒ due (the full
+      // path owns schema creation).
+      noiseCompressDue = (() => {
+        try {
+          const row = db.prepare(
+            "SELECT value FROM memesh_metadata WHERE key = 'last_noise_compress_at'"
+          ).get();
+          if (!row) return true;
+          return Date.now() - new Date(row.value).getTime() >= 24 * 60 * 60 * 1000;
+        } catch {
+          return true;
+        }
+      })();
     } finally {
       db.close();
     }
@@ -945,6 +1019,7 @@ process.stdin.on('end', async () => {
     // Opens a separate read-write connection via the core module.
     // Throttled to once per 24h inside compressWeeklyNoise().
     try {
+      if (noiseCompressDue) {
       // F5: derive pluginRoot strictly from this file's location.
       // See `resolvePluginRoot` for the full reasoning.
       const pluginRoot = resolvePluginRoot(import.meta.url);
@@ -956,6 +1031,7 @@ process.stdin.on('end', async () => {
       } finally {
         dbMod.closeDatabase();
       }
+      }
     } catch (err) {
       // Non-critical — noise compression failed, will retry next session.
       // Trace because this catch previously hid an off-by-one regression

package/scripts/hooks/session-summary.js

@@ -24,7 +24,6 @@ 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,
@@ -41,6 +40,7 @@ import {
   resolveAutoUpdatePolicy,
   resolvePluginRoot,
   spawnAutoUpdate,
+  truncateTitle,
 } from './_shared.js';
 
 const require = createRequire(import.meta.url);
@@ -90,9 +90,15 @@ function parseTranscript(transcriptPath) {
   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);
@@ -171,7 +177,7 @@ function parseTranscript(transcriptPath) {
     }
   }
 
-  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount, readFailed };
+  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount, readFailed, rawText };
 }
 
 // Main: read stdin, extract insights, store in DB
@@ -268,8 +274,9 @@ process.stdin.on('end', async () => {
       return exit0();
     }
 
-    // Parse transcript
-    const { filesEdited, bashCommands, errorsEncountered, toolCallCount, readFailed } = 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
@@ -354,14 +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) {
+      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 })) writeFailed = true;
+        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(
@@ -371,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)`)
         );
       }
 
@@ -384,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)`)
         );
       }
 
@@ -397,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)`)
         );
       }
 
@@ -471,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).
 
@@ -482,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]);
@@ -671,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,
@@ -822,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());
 }
 
 /**