@pcircle/memesh 4.9.4 → 4.10.1

package/scripts/hooks/session-summary.js

@@ -6,7 +6,7 @@
 //
 import { createRequire } from 'module';
 import { basename, join } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeSync } from 'fs';
 import { pathToFileURL } from 'url';
 import {
   AUTO_CAPTURE_TAG,
@@ -20,13 +20,17 @@ import {
   openHookDb,
   readUpdateCheckCache,
   redactSecrets,
+  hookErrorReason,
+  recordHookOutcome,
   recordHookRun,
   stampHookRunOnly,
   resolveAutoUpdatePolicy,
   resolvePluginRoot,
+  SKIP_REASONS,
   spawnAutoUpdate,
   truncateTitle,
 } from './_shared.js';
+import { runStopNotes } from './_stop-notes.js';
 
 const require = createRequire(import.meta.url);
 
@@ -211,13 +215,22 @@ function parseTranscript(transcriptPath) {
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
+// See post-commit.js for why every exit path leaves a record (#327).
+let payload = null;
+let pendingSystemMessage = null;
+/** Set by runStopNotes; called by exit0() with whether the nudge went out. */
+let settleNudge = null;
+function record(outcome, reason, entity) {
+  recordHookOutcome(process.env, { hook: 'session-summary', outcome, reason, entity, payload });
+}
+
 process.stdin.on('end', async () => {
   let sessionId = 'unknown';
   try {
-    if (!input.trim()) return exit0();
-
-    // Opt-out check (env > config > default-on)
-    if (!isAutoCaptureEnabled(process.env)) return exit0();
+    if (!input.trim()) {
+      record('skipped', SKIP_REASONS.emptyStdin);
+      return exit0();
+    }
 
     let inputData;
     try {
@@ -230,12 +243,37 @@ process.stdin.on('end', async () => {
         const preview = (input || '').slice(0, 80).replace(/\n/g, ' ');
         process.stderr.write(`[memesh session-summary] malformed stdin JSON (len=${input.length}): ${parseErr?.message || parseErr}; preview="${preview}"\n`);
       } catch {}
+      record('error', 'malformed stdin JSON');
       return exit0();
     }
 
+    payload = inputData;
     sessionId = inputData.session_id || 'unknown';
     const transcriptPath = inputData.transcript_path;
 
+    // Opt-out check (env > config > default-on). Read before the note work
+    // below because ingestion WRITES memories and must honour it; the nudge
+    // writes nothing and runs either way (#324). It used to sit above the
+    // JSON parse, which is why the payload is parsed first now.
+    const captureEnabled = isAutoCaptureEnabled(process.env);
+
+    // #324: ingest the project's note directory and decide the
+    // "decided things, stored nothing" nudge. Records its own outcomes under
+    // `note-ingest` / `remember-nudge`, never throws, and only ever yields
+    // one line for exit0() to print.
+    const stopNotes = await runStopNotes(inputData, {
+      captureEnabled,
+      project: inputData.cwd ? getProjectName(inputData.cwd) : undefined,
+      metaUrl: import.meta.url,
+    });
+    pendingSystemMessage = stopNotes.message;
+    settleNudge = stopNotes.settle;
+
+    if (!captureEnabled) {
+      record('skipped', SKIP_REASONS.autoCaptureOff);
+      return exit0();
+    }
+
     // `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
@@ -249,6 +287,7 @@ process.stdin.on('end', async () => {
     // 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 {}
+      record('skipped', SKIP_REASONS.cwdAbsent);
       return exit0();
     }
     const cwd = inputData.cwd;
@@ -279,7 +318,11 @@ process.stdin.on('end', async () => {
     // (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(); }
+    if (!wasAgenticLoop) {
+      stampHookRunOnly(process.env, 'session-summary');
+      record('skipped', SKIP_REASONS.notAgenticLoop);
+      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`
@@ -291,6 +334,7 @@ process.stdin.on('end', async () => {
     // breadcrumb so a schema flip doesn't ship undetected again.
     if (!transcriptPath) {
       try { process.stderr.write(`[memesh session-summary] transcript_path absent in payload (keys: ${Object.keys(inputData).join(',')}); skipping capture\n`); } catch {}
+      record('skipped', SKIP_REASONS.transcriptPathAbsent);
       return exit0();
     }
     if (!existsSync(transcriptPath)) {
@@ -299,6 +343,7 @@ process.stdin.on('end', async () => {
       // 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');
+      record('skipped', SKIP_REASONS.transcriptGone);
       return exit0();
     }
 
@@ -310,11 +355,18 @@ process.stdin.on('end', async () => {
     // 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();
+    if (readFailed) {
+      record('error', 'the transcript could not be read');
+      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(); }
+    if (toolCallCount < 3) {
+      stampHookRunOnly(process.env, 'session-summary');
+      record('skipped', SKIP_REASONS.tooLittleActivity);
+      return exit0();
+    }
 
     const projectName = getProjectName(cwd);
 
@@ -324,35 +376,23 @@ process.stdin.on('end', async () => {
     //
     const { db } = openHookDb(process.env, { fts: true });
     let writeFailed = false;
+    let firstFailedEntity = null;
+    // True once any of the three rules below actually calls storeMemory.
+    // Between the toolCallCount < 3 guard above and Rule 3's >= 20 bar, a
+    // session that ran real commands but edited no file matches none of
+    // them — storeMemory never runs, writeFailed stays false, and without
+    // this flag the outcome below fell through to record('wrote') anyway:
+    // a claimed write with zero entities actually touched.
+    let anyRuleMatched = false;
+    // True only once captureEntity actually lands a write. A matched rule
+    // whose entity is `forget`-archived sets anyRuleMatched but not this —
+    // the archived branch below returns before either flag changes, so a
+    // Stop where every matched rule's target was archived falls through to
+    // the `!anyWrote` branch instead of a false 'wrote' (same bug shape as
+    // the noRuleMatched fix above, one level deeper).
+    let anyWrote = false;
+    let lastWrittenEntity = null;
     try {
-      // Duplicate detection: if we already captured this session, bail.
-      //
-      // Use the FULL session_id rather than the first 8 chars: real
-      // Claude Code UUIDs collide on 8 chars only with cosmically small
-      // probability, but artificial test IDs (verify-fix-001 vs -002)
-      // 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.
-      // Guard on ANY of this session's three entities, not only `-files`.
-      // A Bash-only session created no `-files` row, so the guard never
-      // tripped and `-summary` was re-appended on every Stop — measured: 56
-      // observations, 16 unique, three commands stored fourteen times each.
-      const alreadyCaptured = db.prepare(
-        "SELECT id FROM entities WHERE name IN (?, ?, ?) LIMIT 1",
-      ).get(`session-${sessionId}-files`, `session-${sessionId}-fixes`, `session-${sessionId}-summary`);
-      if (alreadyCaptured) {
-        recordHookRun(db, 'session-summary');
-        // A duplicate capture is still a completed Stop lifecycle. Update
-        // consent is session-scoped and must not be skipped merely because
-        // the same transcript was observed twice (a common host retry).
-        await runAutoUpdateAtStop(sessionId);
-        return exit0();
-      }
-
       // Build and store session memories
       const baseTags = [AUTO_CAPTURE_TAG, `session:${sessionId}`, `project:${projectName}`];
 
@@ -378,12 +418,51 @@ 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.
+      //
+      // Known tradeoff, not a bug: the three Rule blocks below each call this
+      // function independently, and captureEntity() commits its own
+      // transaction per call. A failure partway through Rule 2 or 3 can leave
+      // an earlier entity (e.g. -files) replaced while a later one is not,
+      // even though the overall Stop is recorded as 'error'. Wrapping all
+      // three in one outer db.transaction() would close that gap (nested
+      // calls become SAVEPOINTs — see MemeshDatabase.transaction() in
+      // src/storage/sqlite.ts) but was deliberately not done here: it widens
+      // the write-lock hold on every Stop (this hook's busy_timeout is
+      // shorter than the harness timeout on purpose), to guard a failure mode
+      // that self-heals — the next Stop rebuilds each entity fresh from the
+      // transcript, since these are snapshots, not accumulations.
       function storeMemory(name, type, observations, tags, title) {
+        anyRuleMatched = true;
+        // `replace`: these three entities are a SNAPSHOT of one session, and
+        // Stop fires at the end of every turn. Appending stored the same
+        // sentences on every turn; skipping after the first froze a two-day
+        // session at its first turn (#322). A snapshot is restated, not added
+        // to.
+        const result = captureEntity(db, { name, type, observations, tags, title, replace: true });
+        if (result?.archived) {
+          // The user `forget`-archived this exact entity. Not a failure —
+          // captureEntity's contract left it untouched on purpose — so it
+          // must not set writeFailed (that would misreport an honoured
+          // `forget` as a broken hook). Traced, not silent (#3d): the next
+          // Stop will try again and say the same thing until the user either
+          // reactivates the entity or the session ends.
+          try { process.stderr.write(`MeMesh: session-summary left "${name}" alone — archived by forget.\n`); } catch {}
+          return;
+        }
         // 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;
+        if (!result) {
+          writeFailed = true;
+          // First failure, not last: with three independent per-entity
+          // transactions, the first is the root cause — later calls run
+          // regardless and naming one of them would point at a symptom.
+          if (firstFailedEntity === null) firstFailedEntity = name;
+          return;
+        }
+        anyWrote = true;
+        lastWrittenEntity = name;
       }
 
       // No free-form human text exists for these three entities the way a
@@ -393,7 +472,8 @@ process.stdin.on('end', async () => {
       const titleDate = new Date().toISOString().slice(0, 10);
       const titlePrefix = `${titleDate} ${projectName}`;
 
-      // Rule 1: File editing session summary
+      // Rule 1: File editing session summary — name uses the FULL
+      // session_id (tests/core/extractor.test.ts pins why).
       if (filesEdited.length > 0) {
         storeMemory(
           `session-${sessionId}-files`,
@@ -421,7 +501,15 @@ process.stdin.on('end', async () => {
         );
       }
 
-      // Rule 3: Heavy session summary (20+ tool calls = significant work)
+      // Rule 3: Heavy session summary (20+ tool calls = significant work).
+      // This literal is the one place that actually decides the bar; two
+      // doc strings describe it in prose without importing it (this file is
+      // plain JS with no shared constant module, and capture-liveness.ts is
+      // a deliberate zero-import leaf) — src/core/capture-liveness.ts's
+      // SKIP_REASONS.noRuleMatched and src/core/session-insight.ts's own
+      // (HEAVY_SESSION_TOOL_CALLS-derived) copy. A future change to this
+      // number needs both updated by hand, or doctor's text will drift from
+      // what actually happened.
       if (toolCallCount >= 20) {
         storeMemory(
           `session-${sessionId}-summary`,
@@ -548,9 +636,42 @@ process.stdin.on('end', async () => {
               // session so it survives DB restores from either era) plus
               // the compliance denominators: sessions that HAD an injection
               // vs sessions whose transcript carried any citation marker.
+              //
+              // The counters are scoped to the generation named in the stamp.
+              // When a graph that counted under an EARLIER generation meets
+              // this one, they are cleared rather than added to: the
+              // numerator changed meaning (v1 asked "did the transcript
+              // contain any marker", v2 asks "was an id we injected cited"),
+              // so a sum across both is one ratio wearing the newer label and
+              // no key separates the eras. Readers — analytics.ts and
+              // scripts/audit/measure-signals.mjs — read the bare keys and
+              // therefore keep working unchanged; what they report is now
+              // this generation only. A graph that never counted has no
+              // stamp, so nothing resets on a new install.
+              const ACCOUNTING_MODE = 'citation-v2 since 2026-09-12';
+              const priorMode = db.prepare(
+                "SELECT value FROM memesh_metadata WHERE key = 'recall_accounting_mode'"
+              ).get()?.value;
+              if (priorMode && priorMode !== ACCOUNTING_MODE) {
+                // Traced, not silently dropped: the numbers being discarded
+                // are the only record of the previous era, and a reset that
+                // leaves no result record is the silent-skip shape.
+                const prior = (key) => db.prepare('SELECT value FROM memesh_metadata WHERE key = ?').get(key)?.value ?? 'absent';
+                const priorTotal = prior('citation_sessions_total');
+                const priorCited = prior('citation_sessions_cited');
+                db.prepare(
+                  "DELETE FROM memesh_metadata WHERE key IN ('citation_sessions_total', 'citation_sessions_cited')"
+                ).run();
+                try {
+                  process.stderr.write(
+                    `[memesh session-summary] citation accounting generation changed (${priorMode} -> ${ACCOUNTING_MODE}); ` +
+                      `counters reset from total=${priorTotal} cited=${priorCited} — the two eras count different things and are not comparable.\n`,
+                  );
+                } catch {}
+              }
               db.prepare(
                 'INSERT OR REPLACE INTO memesh_metadata (key, value) VALUES (?, ?)'
-              ).run('recall_accounting_mode', 'citation-v1 since 2026-08-16');
+              ).run('recall_accounting_mode', ACCOUNTING_MODE);
               const bump = db.prepare(
                 `INSERT INTO memesh_metadata (key, value) VALUES (?, '1')
                  ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)`
@@ -584,7 +705,39 @@ process.stdin.on('end', async () => {
       // 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');
+      if (writeFailed) {
+        // Name the entity whose captureEntity call actually returned null —
+        // not a fixed guess. With three independent per-entity writes, a
+        // hardcoded name here would point at the wrong one whenever the
+        // failure was in Rule 1 or 2.
+        record('error', 'captureEntity did not land the write', firstFailedEntity ?? undefined);
+      } else if (!anyRuleMatched) {
+        // Correctly deciding there was nothing to capture is still a
+        // completed run — same stance as the tooLittleActivity skip above,
+        // which stamps too. What it must NOT do is claim 'wrote': that was
+        // this hook's shape for every real-work-but-no-file-edit session
+        // until this branch existed.
+        recordHookRun(db, 'session-summary');
+        // No entity named: by definition no rule matched, so `-files`,
+        // `-fixes` and `-summary` are all equally untouched this Stop —
+        // naming one of them would misreport which entity this record is
+        // about.
+        record('skipped', SKIP_REASONS.noRuleMatched);
+      } else if (!anyWrote) {
+        // A rule DID match, but every entity it targeted was `forget`-
+        // archived — the same false-'wrote' shape as the branch above, one
+        // level deeper (a matched rule that produced no write). Its own
+        // reason, not noRuleMatched: a rule fired, saying otherwise would
+        // hide that.
+        recordHookRun(db, 'session-summary');
+        record('skipped', SKIP_REASONS.allMatchedEntitiesArchived);
+      } else {
+        recordHookRun(db, 'session-summary');
+        // Name the entity that actually landed the write (the last one, if
+        // more than one rule wrote) — not a fixed guess at which of the
+        // three this Stop touched.
+        record('wrote', undefined, lastWrittenEntity ?? undefined);
+      }
     } finally {
       db.close();
     }
@@ -596,6 +749,7 @@ process.stdin.on('end', async () => {
     // failures from this hook; with that branch gone, real capture errors stay
     // visible without crashing the host session.
     try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
+    record('error', hookErrorReason(err));
   }
 
   // Update only after all session work so installed files cannot change while
@@ -619,6 +773,28 @@ process.stdin.on('end', async () => {
 });
 
 function exit0() {
+  // The one thing this hook may print (#324): the nudge. `systemMessage` is
+  // the only Stop output Claude Code shows the user (Stop has no
+  // hookSpecificOutput variant — tests/helpers/hook-output-contract.ts).
+  // Codex's acceptance of it on Stop is NOT verified against a live Codex in
+  // this repository; tests/hooks/cross-host-output-contract.test.ts pins the
+  // exact envelope so a rejection report maps to one line. `suppressOutput`,
+  // which Codex did reject, stays gone. writeSync, not console.log: stdout is a
+  // pipe, and an async pipe write can be cut off by process.exit on macOS.
+  //
+  // The nudge's outcome is decided HERE, by whether the write succeeded —
+  // not by runStopNotes, which cannot know. A host that closed stdout gets
+  // an `error` record and keeps its transcript offset, so the next Stop
+  // judges the same window again instead of losing it to a line nobody read.
+  let delivered = true;
+  if (pendingSystemMessage) {
+    try {
+      writeSync(1, `${JSON.stringify({ systemMessage: pendingSystemMessage })}\n`);
+    } catch {
+      delivered = false; // host closed stdout; the record says so.
+    }
+  }
+  try { settleNudge?.(delivered); } catch { /* diagnostics never take the hook down */ }
   process.exit(0);
 }
 /**

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

@@ -21,11 +21,19 @@
 import { pathToFileURL } from 'url';
 import {
   findAutoUpdateConsent,
+  importFromPluginRoot,
   isAutoCaptureEnabled,
+  hookErrorReason,
+  SKIP_REASONS,
+  recordHookOutcome,
+  markUpdatePromptAnswered,
+  memeshDir,
   parseAutoUpdateConsent,
   readUpdateCheckCache,
+  readUpdatePromptClaim,
   resolvePluginRoot,
   writeAutoUpdateConsent,
+  writeSnooze,
 } from './_shared.js';
 import { join } from 'path';
 import { existsSync, readFileSync } from 'fs';
@@ -56,24 +64,64 @@ function currentInstalledVersion() {
   } catch { return null; }
 }
 
-function recordUpdateConsent(sessionId, prompt) {
+/**
+ * Record the owner's answer to this session's first-use update notice.
+ *
+ * Returns 'approved' | 'declined' | 'never' | null. The answer counts only
+ * when THIS session was actually shown the notice (a prompt claim exists for
+ * session/current/latest), so a stray "no" in unrelated conversation is not
+ * a decision about updates.
+ *
+ *   approved — npm-global only (the one channel with a hook-owned installer);
+ *              other channels were told their manual action and cannot be
+ *              approved into an install.
+ *   declined — "Not now": escalating snooze for this target version, on
+ *              every channel. A distinct newer target is offered again.
+ *   never    — "Never ask again": config.updateCheck = false; also snoozed so
+ *              a host that already read the old config stays quiet.
+ */
+async function recordUpdateConsent(sessionId, prompt) {
   const current = currentInstalledVersion();
   if (!current || !sessionId) return null;
-  const channel = currentInstallChannel();
-  // Only npm-global has a hook-owned installer. Other channels receive an
-  // actionable notice at SessionStart and must not turn an "Upgrade" word
-  // into a misleading approval marker for a different installation path.
-  if (channel !== 'npm-global') return null;
   const cache = readUpdateCheckCache(current);
   const latest = cache?.latestVersion;
   if (typeof latest !== 'string' || !latest) return null;
-  const pending = findAutoUpdateConsent(sessionId, current, latest, channel);
-  if (!pending || !['pending'].includes(pending.decision)) return null;
   const decision = parseAutoUpdateConsent(prompt);
   if (!decision) return null;
-  return writeAutoUpdateConsent(
-    sessionId, current, latest, pending.channel ?? 'unknown', decision,
-  ) ? decision : null;
+  const channel = currentInstallChannel();
+  const pending = channel === 'npm-global'
+    ? findAutoUpdateConsent(sessionId, current, latest, channel)
+    : null;
+  const claim = readUpdatePromptClaim(sessionId, current, latest);
+  // The notice must have been shown to THIS session and not answered yet.
+  // Once answered, later "no"/"later" in ordinary conversation is not a
+  // decision about updates (it used to escalate the snooze every time).
+  const open = (claim && claim.decision !== 'answered') || pending?.decision === 'pending';
+  if (!open) return null;
+
+  if (decision === 'approved') {
+    if (!pending || pending.decision !== 'pending') return null;
+    if (!writeAutoUpdateConsent(sessionId, current, latest, pending.channel ?? channel, 'approved')) return null;
+    markUpdatePromptAnswered(sessionId, current, latest, 'approved');
+    return 'approved';
+  }
+  // declined | never
+  try { writeSnooze(memeshDir(), latest); } catch { /* best-effort */ }
+  if (pending?.decision === 'pending') {
+    writeAutoUpdateConsent(sessionId, current, latest, pending.channel ?? channel, 'declined');
+  }
+  let recorded = decision;
+  if (decision === 'never') {
+    try {
+      const configMod = await importFromPluginRoot(resolvePluginRoot(import.meta.url), 'dist/core/config.js');
+      configMod.updateConfig({ updateCheck: false });
+    } catch (err) {
+      logError('user-prompt-intent', `could not persist updateCheck=false: ${err?.message || err}`);
+      recorded = 'declined';
+    }
+  }
+  markUpdatePromptAnswered(sessionId, current, latest, recorded);
+  return recorded;
 }
 
 // Patterns compiled at module load — invalid regex MUST fail loudly. Do
@@ -171,10 +219,20 @@ function logError(scope, msg) {
 // every platform, so the comparison is portable.
 const isMainModule = import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isMainModule) {
+  // See post-commit.js for why every exit path leaves a record (#327). This
+  // hook's only effect is the additionalContext it injects, so its outcome is
+  // `notified`, not `wrote`: doctor's `writes` answers "is memory capture
+  // still alive", and an injected hint is not a memory. Both branches that
+  // reach it — a remember intent and an update-consent decision — inject and
+  // store nothing, so there is no writing branch here to keep.
+  let payload = null;
+  const record = (outcome, reason, entity) =>
+    recordHookOutcome(process.env, { hook: 'user-prompt-intent', outcome, reason, entity, payload });
+
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
+  process.stdin.on('end', async () => {
     try {
       // Distinguish empty stdin (legitimate degenerate event) from malformed
       // input (protocol drift). Both stay non-blocking, but only malformed
@@ -186,6 +244,7 @@ if (isMainModule) {
           data = JSON.parse(trimmed);
         } catch (parseErr) {
           logError('user-prompt-intent', `malformed stdin JSON (len=${input.length}): ${parseErr.message}`);
+          record('error', 'malformed stdin JSON');
           return process.exit(0);
         }
       }
@@ -194,26 +253,37 @@ if (isMainModule) {
       // Claude Code's transcript format changed once before (2026-05-07), so
       // we accept either name to survive a similar rename. If both are absent
       // or non-string, detectRememberIntent's type guard returns false safely.
+      payload = data;
       const prompt = data.prompt ?? data.user_prompt ?? '';
-      const updateDecision = recordUpdateConsent(data.session_id, prompt);
+      const updateDecision = await recordUpdateConsent(data.session_id, prompt);
       const rememberIntent = detectRememberIntent(prompt);
-      if (!rememberIntent && !updateDecision) return process.exit(0);
+      if (!rememberIntent && !updateDecision) {
+        record('skipped', SKIP_REASONS.noPromptIntent);
+        return process.exit(0);
+      }
       // Update consent is a user-authorized control decision, not memory
       // capture; it must still be recorded when auto-capture is disabled.
-      if (!isAutoCaptureEnabled(process.env) && !updateDecision) return process.exit(0);
+      if (!isAutoCaptureEnabled(process.env) && !updateDecision) {
+        record('skipped', SKIP_REASONS.autoCaptureOff);
+        return process.exit(0);
+      }
 
       const contexts = [];
-      if (updateDecision) {
-        contexts.push(updateDecision === 'approved'
-          ? 'The user explicitly approved the MeMesh upgrade. The Stop hook may now update the consented installation.'
-          : 'The user declined the MeMesh upgrade for this session. Do not install it or ask again in this session.');
+      if (updateDecision === 'approved') {
+        contexts.push('The user explicitly approved the MeMesh upgrade. The Stop hook may now update the consented installation.');
+      } else if (updateDecision === 'declined') {
+        contexts.push('The user declined the MeMesh upgrade. It is snoozed for this target version (24h, then 48h, then 7 days on repeated declines); do not install it or mention it again unless a newer version appears.');
+      } else if (updateDecision === 'never') {
+        contexts.push('The user asked never to be asked about MeMesh updates again. updateCheck is now off; do not mention updates. `memesh config set updateCheck true` turns checks back on.');
       }
       if (rememberIntent) contexts.push(buildHint());
       const out = { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: contexts.join('\n\n') } };
       process.stdout.write(JSON.stringify(out));
+      record('notified', undefined, `hint:${updateDecision ?? 'remember-intent'}`);
       process.exit(0);
     } catch (err) {
       logError('user-prompt-intent', err?.message || err);
+      record('error', hookErrorReason(err));
       process.exit(0);
     }
   });

package/skills/memesh/SKILL.md

@@ -28,14 +28,14 @@ All examples below use CLI. MCP tools accept the same parameters as JSON objects
 | Tool | Purpose |
 |---|---|
 | `work_package` | Prepare one bounded untrusted `digest` (calendar cluster) or `transcript` package from the newest Claude Code session under the client's single matching MCP workspace root; submit exactly one strict result or defer. Submit only stages pending human review and retains bounded redacted source turns for comparison; agents cannot apply or reject. No hidden reasoning, raw transcript, transcript path, API key, LLM, embedding, or vector data is exposed or used; hashes identify freshness and workspace scope rather than authentication. |
-| `remember` | Store knowledge as an entity with observations, tags, and relations |
+| `remember` | Store knowledge as an entity with observations, tags, and relations; `note` (free text) derives title/observations/name; `replace: true` rewrites a named memory, keeping history |
 | `recall` | Search stored knowledge; empty query lists recent memories |
 | `forget` | Archive an entity or remove one exact observation |
 | `export` | Export memories as portable JSON |
 | `import` | Import a JSON export with the required skip, append, or overwrite strategy |
 | `learn` | Record a structured lesson with error, fix, root cause, and prevention |
 | `task_state` | Read or update user-stated goal, next step, blocker, and finished work |
-| `briefing` | Assemble the current project's work topology |
+| `briefing` | Assemble the current project's work topology, closing with a capped index of its durable memories |
 | `user_patterns` | Analyze work schedule, tool preferences, and focus areas |
 | `improvement` | Propose an evidence-linked product improvement or read its status; only a human may accept or reject it |
 | `message` | Discover live agents in one project, then contact one exact recipient with a bounded, untrusted payload. Native size and availability failures are distinct; acceptance, discovery, polling, and fetching do not acknowledge |
@@ -101,6 +101,8 @@ Call the `briefing` MCP tool or run `memesh briefing`. It returns the assembled
 work topology: where the work was left off (goal / next / blocked / done),
 decisions and direction, lessons not to repeat, what is known, recent activity.
 One call is cheaper than re-exploring the repo to reconstruct the same picture.
+`memesh briefing --index` returns only the index of durable memories — what is
+known here, one line each, without the ranked sections.
 Generic briefing and SessionStart context do not report unread durable messages:
 they have no recipient identity. If you already know the exact logical
 recipient, pass `recipient` with `project` (MCP) or use
@@ -154,7 +156,7 @@ With the Claude Code plugin, the first eight rows happen **without any action fr
 | **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages) and reminds Claude to use memesh |
 | **PostToolUse (Bash)** | After `git commit` | Auto-tracks the commit with diff stats as a memory entity |
 | **PostToolUse (ExitPlanMode/AskUserQuestion)** | A plan is approved or you answer a question | Reminds Claude to `remember` the decision if it's worth keeping — once per tool per session |
-| **Stop** | Session ends | Auto-captures session knowledge and applies the configured update policy |
+| **Stop** | Session ends | Auto-captures session knowledge, ingests the project's Claude Code memory directory (frontmatter notes → `source:note-file` memories), shows one line when the turn made a decision-shaped move and stored no memory, and applies the configured update policy. The two writes (session capture, note-directory ingestion) stop when auto-capture is off (`memesh config set autoCapture false` / `MEMESH_AUTO_CAPTURE=false`); the advisory line still runs |
 | **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 | **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |
 | **SessionStart/SessionEnd (Codex)** | An ordinary Codex CLI plugin session starts, resumes, or ends | Launches the detached exact-thread companion, replaces its generation on resume, and retires it after the bounded idle queue window; a matching owner-private config may override its project/principal |
@@ -174,7 +176,8 @@ and retiring outdated info.
 | Situation | Action |
 |-----------|--------|
 | User states what they're working on / what's next / what's blocking | `memesh task --goal "…"` / `--next "…"` / `--blocked "…"` |
-| Design decision made | `memesh remember --name "auth-choice" --type decision --obs "Use OAuth 2.0 with PKCE" --tags "project:myapp"` |
+| Design decision made | `memesh remember "Use OAuth 2.0 with PKCE for the API" --type decision --tags "project:myapp"` (or `remember({ note })` over MCP) |
+| A stored memory is wrong | `memesh remember --name "auth-choice" --obs "the corrected fact" --replace` — the memory keeps its type and the old version moves to `metadata.replaced_history` (add `--type` only to reclassify it) |
 | Bug fixed | `memesh learn --error "what broke" --fix "what fixed it" --root-cause "why" --severity major` |
 | Starting work on a feature | `memesh recall "feature-name" --json` |
 | User asks "what did we decide?" | `memesh recall "topic" --tag "project:myapp"` |
@@ -211,7 +214,13 @@ memesh remember \
 Use a **stable name** (`db-choice`, not `db-choice-2026-08-16`): reusing the
 name appends to the same entity instead of scattering duplicates. `--title` is
 the human-readable headline; the name stays the machine key. If this replaces
-an older decision, add `--supersedes "old-db-choice"`.
+an older decision, add `--supersedes "old-db-choice"`. To correct it instead
+of adding to it, repeat the call with `--replace`.
+
+Quicker when the text is all you have: `memesh remember "SQLite for local-first
+storage"` (MCP: `remember({ note: "…" })`). The first line becomes the title,
+each following paragraph an observation, and the name is derived from the text,
+so repeating the same text does not create a duplicate.
 Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
 ### You need context on a specific topic
@@ -245,9 +254,12 @@ memesh reindex --fts                         # rebuild the local keyword index
 
 ## Memory hygiene
 
-1. **Stable names append.** Remembering under an existing name adds
-   observations and dedupes tags — it never replaces the entity. Reuse the
-   name to grow one memory; do not mint `-v2` / dated variants of it.
+1. **Stable names append — unless you ask to replace.** Remembering under an
+   existing name adds observations and dedupes tags by default. Pass
+   `replace: true` (CLI: `--replace`) to rewrite the entity's observations,
+   tags and title instead — the previous version moves to
+   `metadata.replaced_history`, not lost. Reuse the name to grow or correct
+   one memory; do not mint `-v2` / dated variants of it.
 2. **`supersedes` retires the loser.** When a new memory replaces an old one,
    record it with `--supersedes <old-name>` (MCP: a relation of type
    `supersedes`). The old entity is archived — recoverable, out of recall.