@pcircle/memesh 4.6.1 → 4.7.1

package/scripts/hooks/_shared.js

@@ -26,15 +26,18 @@ import { fileURLToPath, pathToFileURL } from 'url';
 // Re-exported here so all 6 hooks keep importing these names from `_shared.js`
 // unchanged.
 import {
+  homeDir,
   memeshDir,
   getDbPath,
   getMemeshDirFromDbPath,
   getProjectName,
+  redactSecrets,
   slugFromRemoteUrl,
 } from './_generated/core-paths.js';
 import { autoCaptureDecision } from './_generated/capture-flag.js';
 export { assembleTopologyBlock, buildReferenceContext, extractCitedMemoryIds, DEFAULT_TOPOLOGY_BUDGET, SNIPPET_FETCH_CHARS, TOPOLOGY_CANDIDATE_CAP } from './_generated/work-topology.js';
 export { matchingGuards, guardFromMetadata } from './_generated/guards.js';
+export { writeCitationRule, citationRulePath, CITATION_RULE_BODY } from './_generated/citation-rule.js';
 import { guardFromMetadata as guardFromMetadataLocal } from './_generated/guards.js';
 
 /**
@@ -101,7 +104,16 @@ export function recordGuardFires(dbPath, lessonIds) {
     } finally {
       db.close();
     }
-  } catch { /* counting must never block the user's work */ }
+  } catch (err) {
+    // Never block the user's work — but say so. A read-only database file, a
+    // lost lock, or a schema drift silently stopped the fire counter, and
+    // guard ROI is judged on exactly this number: a guard that fires often
+    // and a guard whose counter never landed look identical in review. One
+    // line on stderr is what guard-check already does for its own failures.
+    try {
+      process.stderr.write(`[memesh guard-fires] not counted: ${err?.message || err}\n`);
+    } catch { /* stderr gone */ }
+  }
 }
 import { isAutoInjectable } from './_generated/work-topology.js';
 export { parseTaskState, taskStateLines, taskStateName } from './_generated/task-state.js';
@@ -114,7 +126,7 @@ import {
   tokenizeQuery,
 } from './_generated/fts-index.js';
 
-export { memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, slugFromRemoteUrl };
+export { homeDir, memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, redactSecrets, slugFromRemoteUrl };
 
 const require = createRequire(import.meta.url);
 
@@ -332,6 +344,10 @@ import {
 // nothing. node:sqlite is part of the runtime: there is no binary to
 // miss, so the failure mode and its whole recovery apparatus are gone.
 
+/** See the pragma in `openHookDb` for why this is not the 30s the shared
+ *  database class uses. */
+const HOOK_BUSY_TIMEOUT_MS = 2000;
+
 export function openHookDb(env = process.env, opts = {}) {
 
   // Path helpers read process.env directly (no-arg). The `env` parameter
@@ -349,6 +365,23 @@ export function openHookDb(env = process.env, opts = {}) {
   const db = new MemeshDatabase(dbPath, { allowExtension: true });
   db.pragma('journal_mode = WAL');
   db.pragma('foreign_keys = ON');
+  // A hook waits for a held write lock for less time than Claude Code will
+  // wait for the hook.
+  //
+  // `MemeshDatabase` sets `busy_timeout = 30000`, and that number is right
+  // for the processes it was chosen for: a 30k-vector `swapVectorGeneration`
+  // holds the write lock for ~9s, and the CLI, the MCP server and the HTTP
+  // server should WAIT for it rather than fail. A hook cannot. Its budget in
+  // `hooks/hooks.json` is 3s (UserPromptSubmit) to 10s (Stop, PreCompact),
+  // so a 30s wait has exactly one possible ending: the harness kills the
+  // hook. The capture is lost either way — the difference is that the user
+  // also gets a hook-timeout error, which is the failure mode that makes
+  // memesh something to switch off.
+  //
+  // 2s fits inside every budget with room for the hook's own work. On
+  // contention the capture is skipped quietly, this run's `hook_runs` stamp
+  // is not written, and `memesh doctor` reports the gap honestly.
+  db.pragma(`busy_timeout = ${HOOK_BUSY_TIMEOUT_MS}`);
   // Bringing the schema current is a WRITE, and "cannot migrate" must not
   // mean "cannot open": a database file that is read-only but behind on
   // schema (a pre-upgrade backup, a permissions accident) dies on the
@@ -535,6 +568,23 @@ export { truncateTitle } from './_generated/title.js';
  * @returns {{ id: number, isNew: boolean } | null} null if the row could not be resolved
  */
 export function captureEntity(db, { name, type, observations = [], tags = [], title, metadata }) {
+  // One transaction, because this function performs six writes that only
+  // mean anything together: the entity row, its observations, its tags, and
+  // the contentless-FTS delete + insert that make them findable.
+  //
+  // Without it, a throw anywhere in the middle — a lock lost to the CLI, a
+  // full disk, an FTS corruption — committed the prefix and dropped the
+  // rest, and the two most likely resting places are both invisible:
+  // observations inserted with no FTS row (a memory that exists and can
+  // never be recalled), or the old FTS row deleted and the new one not
+  // written (a memory that just stopped being findable). Neither is
+  // retried, because the callers dedupe on the entity NAME existing —
+  // `INSERT OR IGNORE` reports "already there" on the next run and the
+  // half-written state is permanent.
+  return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata }))();
+}
+
+function captureEntityInner(db, { name, type, observations, tags, title, metadata }) {
   // source_host provenance: these hooks only ever run under Claude Code (they
   // are wired into ~/.claude/settings.json), so a hook-captured entity is by
   // definition a claude-code capture. Stamped only on the INSERT — an OR
@@ -573,8 +623,11 @@ export function captureEntity(db, { name, type, observations = [], tags = [], ti
     // it's corrupted — replace with {} and log the healing.
     if (!meta && metaRow?.metadata) {
       try {
+        // The id, not the name. The id is what a maintainer needs to look
+        // the row up; the name is user-authored content, and this line goes
+        // to a stderr stream the user may paste anywhere.
         process.stderr.write(
-          `MeMesh: healed corrupted metadata for entity ${id} (${name}). ` +
+          `MeMesh: healed corrupted metadata for entity ${id}. ` +
           `Original value was unparseable; replaced with {}.\n`,
         );
       } catch { /* stderr gone */ }
@@ -745,9 +798,25 @@ export function decideAutoUpdateHook(currentVersion, cache, policy) {
   const policyAllows = (POLICY_RANK[policy] ?? 0) >= BUMP_RANK[bump];
   if (policyAllows) return { run: true, latest, bump, deprecationOverride: false };
 
+  // The deprecation override does NOT apply when the policy is `off`.
+  //
+  // Look at what the override could ever do: it fires only for a `patch`
+  // bump, and any policy above `off` already permits a patch. So its ONLY
+  // effect was to defeat `off` — the one setting whose whole meaning is
+  // "never install anything without me asking".
+  //
+  // And its trigger is `currentVersionDeprecation`, a string the PUBLISHER
+  // writes into the npm registry. Anyone able to publish the package could
+  // therefore make every user who had turned auto-update OFF run a detached
+  // `npm install -g`, unattended, from a Stop hook. That is not a security
+  // override; it is a remote switch on a user's explicit refusal.
+  //
+  // A deprecated version still gets said out loud: `memesh doctor` escalates
+  // the update-status row to FAIL for it (there is a test named for that),
+  // and the session banner reports it. The user decides.
   const deprecated = typeof cache.currentVersionDeprecation === 'string'
     && cache.currentVersionDeprecation.length > 0;
-  if (deprecated && bump === 'patch') {
+  if (deprecated && bump === 'patch' && policy !== 'off') {
     return { run: true, latest, bump, deprecationOverride: true };
   }
 

package/scripts/hooks/pre-compact.js

@@ -4,13 +4,20 @@ import { basename } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
 
-// Timeout guard: always exit within 10 seconds
-const TIMEOUT_MS = 10000;
-const timeoutHandle = setTimeout(() => {
-  try { process.stderr.write('[memesh pre-compact] Timed out after 10s\n'); } catch {}
-  process.exit(0);
-}, TIMEOUT_MS);
-timeoutHandle.unref();
+// There is no in-process timeout guard, and its absence is deliberate.
+//
+// This file used to arm `setTimeout(() => process.exit(0), 10_000).unref()`.
+// It could not fire. Everything after `stdin`'s `end` event is one
+// synchronous block — no `await`, no callback — so the event loop never gets
+// a turn between the handler starting and the process exiting, and a JS
+// timer cannot interrupt a blocking SQLite call. The one window where it
+// COULD have run is while stdin is still open, which is not where a hook
+// hangs.
+//
+// The timeout that does work is external: `hooks/hooks.json` declares
+// `"timeout": 10` for PreCompact, and the harness enforces it on the
+// process. `openHookDb` additionally caps the SQLite lock wait at 2s so
+// contention ends in a skipped capture rather than in that kill.
 
 let input = '';
 process.stdin.setEncoding('utf8');

package/scripts/hooks/session-start.js

@@ -27,7 +27,9 @@ import {
   resolvePluginRoot,
   resolveSessionLimit,
   taskStateLines,
+  homeDir,
   taskStateName,
+  writeCitationRule,
   writePrivateJson,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
@@ -542,6 +544,36 @@ process.stdin.on('end', async () => {
     const data = JSON.parse(input);
     const projectName = getProjectName(data.cwd);
 
+    // Self-heal the citation contract.
+    //
+    // `install-hooks` writes it too, but a PLUGIN install never runs that
+    // command — and plugin is how most users arrive. Without this, the
+    // contract would reach only npm installs, which is the same shape as the
+    // bug it exists to fix: a mechanism that is correct on a path nobody
+    // takes. Idempotent (a byte-identical file is left alone), refuses to
+    // touch a file memesh did not write, and never blocks the session: a
+    // failure here traces and the hook carries on.
+    try {
+      // Scope comes from the install marker, NOT hardcoded to 'user'. A
+      // `--scope project` install keeps everything inside that project, and
+      // writing the contract to ~/.claude/rules/ anyway would leak it into
+      // every OTHER project on the machine — and survive
+      // `uninstall-hooks --scope project`, which only knows about the
+      // project path. No marker means a plugin install, which is user-level
+      // by construction.
+      let ruleScope = 'user';
+      try {
+        const markerPath = join(memeshHomeDir(), 'install-hooks.json');
+        if (existsSync(markerPath)) {
+          const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+          if (marker?.scope === 'project') ruleScope = 'project';
+        }
+      } catch { /* unreadable marker → user scope, the safe default */ }
+      writeCitationRule(ruleScope, homeDir(), data.cwd || process.cwd());
+    } catch (err) {
+      try { process.stderr.write(`[memesh session-start] citation rule: ${err?.message || err}\n`); } catch {}
+    }
+
     // Clear per-session throttle files from previous session
     try {
       if (existsSync(throttlePath)) {
@@ -916,7 +948,19 @@ process.stdin.on('end', async () => {
         // this line IS an instruction. One line is the entire write side of
         // the injection-ROI signal; the Stop hook credits recall_hits only
         // from these markers (self-reported: undercounts, never overcounts).
-        memoryContext += '\nWhen a memory above genuinely informs your work, cite it once inline as [mem:ID], using the id shown on its line.';
+        // The citation instruction used to be appended here, outside the
+        // fence, so it would read as an instruction rather than as data.
+        // It never worked: Claude Code wraps a hook's additionalContext in a
+        // system-reminder ending "you should not respond to this context
+        // unless it is highly relevant", so the whole block — instruction
+        // included — arrives as data. Measured on a real database:
+        // citation_sessions_total=4, sessions WITH a citation = 0.
+        //
+        // The contract now lives in `.claude/rules/memesh-citations.md`,
+        // which Claude Code loads as an instruction. Writing it is the
+        // self-heal below; the line here is gone rather than duplicated,
+        // because a per-session copy of an instruction that is read as data
+        // is a per-session cost with no effect.
       }
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
@@ -1038,7 +1082,22 @@ process.stdin.on('end', async () => {
       const lifecycleMod = await importFromPluginRoot(pluginRoot, 'dist/core/lifecycle.js');
       dbMod.openDatabase();
       try {
-        lifecycleMod.compressWeeklyNoise(dbMod.getDatabase());
+        // Say what it did. This archives at least 20 of the user's memories
+        // per week processed and the count was thrown away, so the one
+        // operation in memesh that removes things from view was also the
+        // only one that left no trace anywhere — not in the hook output, not
+        // in doctor, not in the dashboard. Nothing to opt into: it runs at
+        // most once a day and stays silent when it compresses nothing.
+        const noise = lifecycleMod.compressWeeklyNoise(dbMod.getDatabase());
+        if (noise && noise.compressed > 0) {
+          try {
+            process.stderr.write(
+              `[memesh] archived ${noise.compressed} low-signal memor${noise.compressed === 1 ? 'y' : 'ies'} `
+              + `into ${noise.weeksProcessed} weekly summar${noise.weeksProcessed === 1 ? 'y' : 'ies'} `
+              + `(recover with \`memesh recall --include-archived\`)\n`,
+            );
+          } catch { /* stderr gone */ }
+        }
       } finally {
         dbMod.closeDatabase();
       }

package/scripts/hooks/session-summary.js

@@ -36,6 +36,7 @@ import {
   isAutoCaptureEnabled,
   openHookDb,
   readUpdateCheckCache,
+  redactSecrets,
   recordHookRun,
   stampHookRunOnly,
   resolveAutoUpdatePolicy,
@@ -117,7 +118,14 @@ function parseTranscript(transcriptPath) {
             if (block.name === 'Bash') {
               const cmd = block.input?.command ?? '';
               if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
-                bashCommands.push(cmd.slice(0, 100));
+                // Redact BEFORE truncating. A bash command line is the single
+                // most likely place a credential appears in a transcript
+                // (`export ANTHROPIC_API_KEY=sk-...`, `curl -H "Authorization:
+                // Bearer ..."`), and this text is stored verbatim as an
+                // observation — a permanent, searchable, exportable copy.
+                // Truncating first would cut a token in half and leave the
+                // fragment unmatched by every pattern.
+                bashCommands.push(redactSecrets(cmd).slice(0, 100));
               }
             }
           }
@@ -141,7 +149,14 @@ function parseTranscript(transcriptPath) {
             const text = typeof block.content === 'string'
               ? block.content
               : JSON.stringify(block.content);
-            errorsEncountered.push(text.slice(0, 200));
+            // Same reason as the bash branch, and one more: this array is
+            // ALSO the payload `analyzeFailure` sends to the configured LLM
+            // provider. A failed request that echoes its own Authorization
+            // header — the ordinary shape of an auth error — would be stored
+            // and then transmitted off the machine. Redacted once here, at
+            // the point the text enters the process, so every downstream use
+            // inherits it.
+            errorsEncountered.push(redactSecrets(text).slice(0, 200));
           }
         }
 
@@ -511,8 +526,21 @@ process.stdin.on('end', async () => {
               const updateHit = db.prepare(
                 'UPDATE entities SET recall_hits = COALESCE(recall_hits, 0) + 1 WHERE id = ?'
               );
+              // Counted here, not recomputed below. The compliance
+              // numerator and `recall_hits` have to be the SAME
+              // measurement: `cited.size > 0` asked "did this transcript
+              // contain any [mem:N] at all", which counts a marker for an id
+              // this session never injected — one carried over from an
+              // earlier turn, or a number the agent invented — as compliance.
+              // The denominator counts sessions that received an injection,
+              // so the two halves of the rate were answering different
+              // questions.
+              let injectedAndCited = 0;
               for (const id of entityIds) {
-                if (cited.has(id)) updateHit.run(id);
+                if (cited.has(id)) {
+                  updateHit.run(id);
+                  injectedAndCited++;
+                }
               }
 
               // Accounting-mode stamp (constant value, rewritten every
@@ -527,7 +555,16 @@ process.stdin.on('end', async () => {
                  ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)`
               );
               bump.run('citation_sessions_total');
-              if (cited.size > 0) bump.run('citation_sessions_cited');
+              // Initialised unconditionally, then bumped. Writing it only on
+              // a citation made "zero sessions cited" and "this code never
+              // ran" the same absent key — and that is exactly what a real
+              // database showed on 2026-08-24: total=4, cited absent, with
+              // no way to tell a 0% compliance rate from a dead counter.
+              db.prepare(
+                `INSERT INTO memesh_metadata (key, value) VALUES ('citation_sessions_cited', '0')
+                 ON CONFLICT(key) DO NOTHING`
+              ).run();
+              if (injectedAndCited > 0) bump.run('citation_sessions_cited');
             }
           }
         }

package/scripts/upgrade-plugin.sh

@@ -94,7 +94,15 @@ CURRENT_VERSION="$(INSTALL_REGISTRY="$INSTALL_REGISTRY" node -e "
   const entries = (j.plugins && j.plugins['memesh@pcircle-memesh']) || [];
   if (entries.length === 0) { process.stdout.write('none'); process.exit(0); }
   process.stdout.write(entries[0].version || 'unknown');
-")"
+")" || {
+  # Its sibling twelve lines up has this guard; this read did not, so an
+  # unreadable or malformed installed_plugins.json made CURRENT_VERSION the
+  # empty string. That compares unequal to every target, so the script
+  # reported an upgrade from "" and carried on — on a registry it had just
+  # failed to parse.
+  echo "ERROR: could not read the installed memesh version from $INSTALL_REGISTRY" >&2
+  exit 1
+}
 
 echo "==> Currently installed: $CURRENT_VERSION"