claude-mem-lite 2.91.0 → 2.93.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.91.0",
+      "version": "2.93.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.91.0",
+  "version": "2.93.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/adopt-cli.mjs

@@ -15,7 +15,7 @@ import { join } from 'path';
 import {
   memdirPath, writePluginSection, removePluginSection,
   writePluginDoc, removePluginDoc,
-  isAdopted, readMemoryIndex,
+  isAdopted, hasPluginState, readMemoryIndex,
   UserEditedError, BudgetExceededError,
 } from './memdir.mjs';
 import {
@@ -325,6 +325,7 @@ export function cmdUnadopt(args = []) {
 
   const all = hasFlag(args, '--all');
   const dryRun = hasFlag(args, '--dry-run');
+  const force = hasFlag(args, '--force');
   const targets = all
     ? listAllMemdirs().map((m) => m.memdir)
     : [memdirPath(detectCwd())];
@@ -334,23 +335,32 @@ export function cmdUnadopt(args = []) {
     return;
   }
 
-  let removed = 0, absent = 0;
+  let removed = 0, absent = 0, skipped = 0;
   for (const memdir of targets) {
     if (dryRun) {
-      const adopted = isAdopted(memdir, PLUGIN_SLUG);
-      const action = adopted ? 'would-remove' : 'absent';
+      // Mirror the live foreign-content guard: a sentinel with no state sidecar would be
+      // skipped (not removed) unless --force, so dry-run must report it the same way.
+      const action = !isAdopted(memdir, PLUGIN_SLUG) ? 'absent'
+        : (hasPluginState(memdir, PLUGIN_SLUG) || force) ? 'would-remove'
+          : 'would-skip-foreign';
       log(`[unadopt --dry-run] ${memdir} → ${action}`);
-      if (adopted) removed++; else absent++;
+      if (action === 'would-remove') removed++;
+      else if (action === 'would-skip-foreign') skipped++;
+      else absent++;
       continue;
     }
-    const r = removePluginSection(memdir, PLUGIN_SLUG);
-    removePluginDoc(memdir, PLUGIN_SLUG);
-    if (r.action === 'removed') removed++;
+    const r = removePluginSection(memdir, PLUGIN_SLUG, { force });
+    if (r.action === 'removed') { removePluginDoc(memdir, PLUGIN_SLUG); removed++; }
+    else if (r.action === 'skipped-foreign') skipped++;
     else absent++;
     log(`[unadopt] ${memdir} → ${r.action}`);
   }
 
+  if (skipped > 0) {
+    log('[unadopt] skipped-foreign = a sentinel block with no plugin state file (not proven plugin-written).');
+    log('[unadopt] pass --force to remove it anyway.');
+  }
   log('');
   const verb = dryRun ? 'would remove' : 'removed';
-  log(`[unadopt${dryRun ? ' --dry-run' : ''}] ${targets.length} target(s): ${removed} ${verb}, ${absent} absent`);
+  log(`[unadopt${dryRun ? ' --dry-run' : ''}] ${targets.length} target(s): ${removed} ${verb}, ${skipped} skipped-foreign, ${absent} absent`);
 }

package/bash-utils.mjs

@@ -3,6 +3,38 @@
 
 import { basename } from 'path';
 
+// Read/search commands whose output legitimately contains "error"-like keywords without
+// being a failure. Matched against the PRIMARY command (see isReadOnlyCommand).
+const SEARCH_VERBS = new Set([
+  'grep', 'rg', 'ag', 'ack', 'cat', 'head', 'tail', 'less', 'more', 'find', 'locate', 'wc', 'file', 'which', 'type',
+]);
+// Command prefixes that wrap the real command (env-assignments handled separately).
+const CMD_WRAPPERS = new Set(['sudo', 'doas', 'env', 'time', 'command', 'nice', 'nohup', 'stdbuf', 'xargs']);
+// git read subcommands whose output contains commit/log/match text, not failures.
+const GIT_READ_SUBCMDS = new Set(['grep', 'log', 'show', 'diff', 'blame', 'ls-files', 'cat-file', 'whatchanged', 'shortlog', 'reflog', 'status']);
+
+// True when the command's PRIMARY operation (left of the first pipe, past any
+// env-assignments / wrapper like `sudo`/`env`/`time`) is a read/search — including
+// `git grep`/`git log`. Anchoring on the primary command (not "search verb appears
+// anywhere") is what lets `npm run build 2>&1 | tail` stay an error while `sudo grep`,
+// `git grep`, `cat f | head` are correctly exempt.
+function isReadOnlyCommand(cmd) {
+  const primary = cmd.split('|')[0];
+  const toks = primary.trim().split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < toks.length && (/^\w+=/.test(toks[i]) || CMD_WRAPPERS.has(toks[i]))) i++;
+  const first = toks[i];
+  if (!first) return false;
+  if (SEARCH_VERBS.has(first)) return true;
+  return first === 'git' && GIT_READ_SUBCMDS.has(toks[i + 1]);
+}
+
+// Paths excluded from observation capture (ephemeral / virtual filesystems) — applied
+// uniformly to both command-parsed paths and direct file_path/path/filePath fields.
+function isExcludedPath(p) {
+  return p.startsWith('/dev/') || p.startsWith('/proc/') || p.startsWith('/tmp/');
+}
+
 /**
  * Detect significance signals in a Bash command and its response.
  * Checks for errors, test runs, builds, git operations, and deployments.
@@ -12,9 +44,12 @@ import { basename } from 'path';
  */
 export function detectBashSignificance(input, response) {
   const cmd = (input.command || '').toLowerCase();
-  // Skip error keyword matching when the command is a read/search operation
-  // (grep output naturally contains matched keywords like "error")
-  const isSearchCmd = /\b(grep|rg|ag|ack|cat|head|tail|less|more|find|locate|wc|file|which|type)\b/i.test(cmd);
+  // Skip error keyword matching only when the PRIMARY command is a read/search op (its
+  // output naturally contains "error"-like keywords that aren't failures). Anchored on the
+  // primary command — NOT "search verb appears anywhere" — so `npm run build 2>&1 | tail`
+  // stays a real failure while `sudo grep`, `git grep`, `git log --grep`, `cat f | head`
+  // remain exempt and `run-cat-tests` doesn't trip a substring match.
+  const isSearchCmd = isReadOnlyCommand(cmd);
   const looksLikeError = !isSearchCmd
     && /\berror\b|\bERR!|fail(ed|ure)?|exception|panic|traceback|errno|enoent|command not found/i.test(response)
     && response.length > 15;
@@ -38,7 +73,9 @@ export function detectBashSignificance(input, response) {
   const isTest = /\b(npm\s+test|npm\s+run\s+test|yarn\s+test|pnpm\s+test|pnpm\s+run\s+test|bun\s+test|go\s+test|cargo\s+test)\b/i.test(cmd)
     || /\b(jest|pytest|vitest|mocha|cypress|playwright)\b/i.test(cmd);
   const isBuild = /\b(build|compile|tsc|webpack|vite|rollup|esbuild|make|cargo)\b/i.test(cmd);
-  const isGit = /\bgit\s+(commit|merge|rebase|cherry-pick|push)\b/i.test(cmd);
+  // Allow intervening global git options (`-C <path>`, `-c k=v`, `--no-pager`, …) between
+  // `git` and the subcommand — `git -C /repo push` is the standard multi-repo/scripted form.
+  const isGit = /\bgit\s+(?:(?:-[cC]\s+\S+|--?[\w-]+(?:=\S+)?)\s+)*(commit|merge|rebase|cherry-pick|push)\b/i.test(cmd);
   const isDeploy = /\b(deploy|docker|kubectl|terraform)\b/i.test(cmd);
   return {
     isError, isTest, isBuild, isGit, isDeploy,
@@ -92,6 +129,9 @@ export function extractErrorKeywords(cmd, response) {
  */
 export function extractFilePaths(input) {
   const paths = [];
+  // Direct fields (Edit/Write file_path) are kept unconditionally — an explicit edit to a
+  // /tmp path is real work the user chose to make, unlike a /tmp path that merely appears as
+  // a transient argument inside a Bash command (excluded as noise in the command branch below).
   if (input.file_path) paths.push(input.file_path);
   if (input.path) paths.push(input.path);
   if (input.filePath) paths.push(input.filePath);
@@ -101,7 +141,7 @@ export function extractFilePaths(input) {
     if (match) {
       for (const m of match) {
         const p = m.trim();
-        if (!p.startsWith('/dev/') && !p.startsWith('/proc/') && !p.startsWith('/tmp/')
+        if (!isExcludedPath(p)
           // Skip single-component paths like /exit, /clear — likely slash commands, not files
           && (p.indexOf('/', 1) !== -1 || /\.\w+$/.test(p))) {
           paths.push(p);

package/cli/activity.mjs

@@ -10,8 +10,8 @@
 
 import { inferProject } from '../utils.mjs';
 import { resolveProject } from '../project-utils.mjs';
-import { parseArgs, out, fail } from './common.mjs';
-import { parseIntFlag } from '../lib/cli-flags.mjs';
+import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
+import { parseIntFlag, isNumericToken } from '../lib/cli-flags.mjs';
 
 function formatActivityResults(rows) {
   if (!rows || rows.length === 0) return '(no events)';
@@ -31,6 +31,9 @@ export async function cmdActivity(db, args) {
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
 
   if (sub === 'save') {
+    // Reject value-less string flags before they reach saveEvent as a boolean `true`
+    // (#8470): bare --body / --title crashed with a raw "SQLite3 can only bind ..." error.
+    if (rejectBareStringFlags(flags, ['type', 'title', 'body', 'files', 'file', 'project'])) return;
     const type = flags.type || 'observation';
     if (!VALID_EVENT_TYPES.has(type)) {
       fail(`[mem] activity save: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
@@ -51,7 +54,9 @@ export async function cmdActivity(db, args) {
     const file_paths_merged = [...filesFromSingular, ...filesFromPlural];
     const file_paths = file_paths_merged.length > 0 ? file_paths_merged : null;
     const rawImp = flags.importance !== undefined ? parseInt(flags.importance, 10) : 2;
-    if (flags.importance !== undefined && (isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
+    // isNumericToken first (mirrors cmdSave): bare parseInt coerces "3xyz"→3 and would
+    // persist a wrong importance that silently skews ranking. Float literals truncate (#8277).
+    if (flags.importance !== undefined && (!isNumericToken(flags.importance) || isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
       fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
       return;
     }
@@ -112,7 +117,10 @@ export async function cmdActivity(db, args) {
     if (row) {
       out(JSON.stringify(row, null, 2));
     } else {
-      out(`[mem] activity show: event #${id} Not found`);
+      // fail() (stderr + exit 1), matching the not-found contract of sibling commands
+      // (`get`, `activity delete`, `update`); previously stdout + exit 0, so scripts
+      // couldn't detect a missing event from the exit code.
+      fail(`[mem] activity show: event #${id} not found`);
     }
     return;
   }

package/cli/common.mjs

@@ -54,6 +54,29 @@ export function fail(text) {
   process.exitCode = 1;
 }
 
+/**
+ * Reject value-less `--flag` for string-valued flags. A bare trailing flag (or one
+ * immediately followed by another `--flag`) parses to boolean `true` (parseArgs above);
+ * that `true` then slips into code expecting a string and surfaces a raw
+ * `flags.x.split is not a function` / `SQLite3 can only bind ...` stacktrace (#8470).
+ * Returns true (and emits a clean `fail()`) when any listed key is a bare flag — the
+ * caller should `return` on true. Single source of the guard the update/registry paths
+ * previously inlined, so new string-flag commands stay consistent.
+ *
+ * @param {object} flags Parsed flags from parseArgs.
+ * @param {string[]} keys String-valued flag names to guard (without leading dashes).
+ * @returns {boolean} true if a bare flag was found and rejected.
+ */
+export function rejectBareStringFlags(flags, keys) {
+  for (const key of keys) {
+    if (flags[key] === true) {
+      fail(`[mem] --${key} requires a value (received a bare flag with no value).`);
+      return true;
+    }
+  }
+  return false;
+}
+
 // ─── Time Formatting ─────────────────────────────────────────────────────────
 
 /** "just now" / "5m ago" / "3h ago" / "2d ago" relative to now. */

package/format-utils.mjs

@@ -9,8 +9,19 @@
  */
 export function truncate(str, max = 80) {
   if (!str) return '';
+  // Defense-in-depth: a non-string (e.g. an LLM that returned title as an array/number)
+  // would throw `str.replace is not a function` and abort the caller. Coerce to '' rather
+  // than crash; the real type-guarding happens at the call site.
+  if (typeof str !== 'string') return '';
   str = str.replace(/\n/g, ' ').trim();
-  return str.length > max ? str.slice(0, max - 1) + '\u2026' : str;
+  if (str.length <= max) return str;
+  // Never split a UTF-16 surrogate pair: slicing between the high and low half emits a
+  // lone surrogate (invalid UTF-16) that then gets persisted to the DB. If the last kept
+  // code unit is a high surrogate, drop it so we cut on a code-point boundary.
+  let end = max - 1;
+  const last = str.charCodeAt(end - 1);
+  if (last >= 0xD800 && last <= 0xDBFF) end--;
+  return str.slice(0, end) + '\u2026';
 }
 
 /**

package/hook-handoff.mjs

@@ -446,13 +446,31 @@ function renderHandoffFromRow(handoff, db, project) {
 
   lines.push('</session-handoff>');
 
-  // Append session summary if available (long-gap enrichment)
+  // Append session summary if available (long-gap enrichment).
+  // session_summaries is keyed by the mem-internal memory_session_id, but in production
+  // session_handoffs.session_id holds the Claude Code UUID (the scope tag) — the two id
+  // namespaces never match, so the exact lookup returned nothing and this block was always
+  // dropped on a real resume. There is no bridge column (the CC-UUID lives on user_prompts,
+  // not on sdk_sessions/session_summaries), so: try the exact id match first (correct when
+  // ids align — legacy rows + tests), then fall back to the most-recent summary for the
+  // project, which at resume time is the summary from the session that wrote this handoff.
   try {
-    const summary = db.prepare(`
+    let summary = db.prepare(`
       SELECT completed, next_steps, remaining_items FROM session_summaries
       WHERE memory_session_id = ? AND project = ?
       ORDER BY created_at_epoch DESC LIMIT 1
     `).get(handoff.session_id, project);
+    if (!summary) {
+      // Pick the project summary CLOSEST IN TIME to this handoff, not merely the newest:
+      // a handoff and its own session's summary are written within ms of each other at
+      // session end, so nearest-timestamp recovers the right session even when a different
+      // session later wrote a newer summary for the same project (concurrent/interleaved use).
+      summary = db.prepare(`
+        SELECT completed, next_steps, remaining_items FROM session_summaries
+        WHERE project = ?
+        ORDER BY ABS(created_at_epoch - ?) ASC LIMIT 1
+      `).get(project, handoff.created_at_epoch ?? 0);
+    }
     if (summary && (summary.completed || summary.next_steps || summary.remaining_items)) {
       lines.push('');
       lines.push('<session-summary source="haiku">');

package/hook-llm.mjs

@@ -12,6 +12,7 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector } from './tfidf.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector } from './lib/observation-write.mjs';
 import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
@@ -209,48 +210,23 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       search_aliases: obs.searchAliases || null,
     });
 
-    // Atomic: observation INSERT + observation_files + vector in one transaction
+    // Atomic: observation INSERT + observation_files + vector in one transaction.
+    // Column list single-sourced in lib/observation-write (shared with manual mem_save).
     const savedId = db.transaction(() => {
-      const result = db.prepare(`
-        INSERT INTO observations (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, search_aliases, branch, created_at, created_at_epoch)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(
-        sessionId, project,
-        safe.text, obs.type, safe.title, safe.subtitle,
-        safe.narrative,
-        safe.concepts,
-        safe.facts,
-        JSON.stringify(obs.filesRead || []),
-        JSON.stringify(obs.files || []),
-        obs.importance ?? 1,
-        minhashSig,
-        safe.lesson_learned,
-        safe.search_aliases,
-        getCurrentBranch(),
-        now.toISOString(), now.getTime()
-      );
-      const id = Number(result.lastInsertRowid);
-
-      // Populate observation_files junction table
-      if (id && obs.files && obs.files.length > 0) {
-        const insertFile = db.prepare('INSERT OR IGNORE INTO observation_files (obs_id, filename) VALUES (?, ?)');
-        for (const f of obs.files) {
-          if (typeof f === 'string' && f.length > 0) insertFile.run(id, f);
-        }
-      }
+      const id = insertObservationRow(db, {
+        memory_session_id: sessionId, project, text: safe.text, type: obs.type,
+        title: safe.title, subtitle: safe.subtitle, narrative: safe.narrative,
+        concepts: safe.concepts, facts: safe.facts,
+        files_read: JSON.stringify(obs.filesRead || []),
+        files_modified: JSON.stringify(obs.files || []),
+        importance: obs.importance ?? 1, minhash_sig: minhashSig,
+        lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases,
+        branch: getCurrentBranch(), created_at: now.toISOString(), created_at_epoch: now.getTime(),
+      });
 
-      // Write TF-IDF vector (non-critical — catch inside transaction to avoid rollback)
-      try {
-        const vocab = getVocabulary(db);
-        if (vocab) {
-          const vecText = [obs.title || '', obs.narrative || '', (Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '')].filter(Boolean).join(' ');
-          const vec = computeVector(vecText, vocab);
-          if (vec) {
-            db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-              .run(id, Buffer.from(vec.buffer), vocab.version, Date.now());
-          }
-        }
-      } catch (e) { debugCatch(e, 'saveObservation-vector'); }
+      insertObservationFiles(db, id, obs.files);
+      const vecText = [obs.title || '', obs.narrative || '', (Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '')].filter(Boolean).join(' ');
+      insertObservationVector(db, id, vecText);
 
       return id;
     })();
@@ -681,7 +657,12 @@ ${actionList}`;
       releaseLLMSlot();
     }
 
-    if (parsed && parsed.title) {
+    // Require a STRING title: a truthy non-string (LLM returned title as an array/number/
+    // object) would pass a bare `parsed.title` check, then crash truncate() downstream,
+    // aborting the worker before tmpFile cleanup (leak) and leaving the obs degraded.
+    if (parsed && typeof parsed.title === 'string' && parsed.title) {
+      // Normalize narrative to a string too — same non-string crash risk in truncate().
+      if (typeof parsed.narrative !== 'string') parsed.narrative = '';
       // Discard if LLM judges observation has no learning value
       if (parsed.importance === 0 || parsed.importance === '0') {
         debugLog('DEBUG', 'llm-episode', `Discarded low-value observation: ${parsed.title}`);

package/hook-optimize.mjs

@@ -262,7 +262,7 @@ Rules:
   }
 }
 
-export function applyNormalization(db, groups) {
+export function applyNormalization(db, groups, { project = null } = {}) {
   if (!groups || groups.length === 0) return { updated: 0 };
 
   const aliasMap = new Map();
@@ -272,11 +272,17 @@ export function applyNormalization(db, groups) {
     }
   }
 
+  // Scope the mutation to `project` when normalize was scoped (v2.72.0 --project).
+  // Without this, synonym groups derived from ONE project's concepts rewrote the
+  // concepts/search_aliases of EVERY project's observations — the exact cross-project
+  // contamination the --project flag was added to prevent. NULL → all projects (legacy
+  // unscoped run), matching the search-engine `(? IS NULL OR project = ?)` idiom.
   const rows = db.prepare(`
     SELECT id, concepts, search_aliases FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND concepts IS NOT NULL AND concepts != ''
-  `).all();
+      AND (? IS NULL OR project = ?)
+  `).all(project, project);
 
   let updated = 0;
   const updateStmt = db.prepare(`
@@ -322,7 +328,7 @@ export async function executeNormalize(db, force = false, { project } = {}) {
   const groups = await identifySynonymGroups(concepts);
   if (groups.length === 0) return { processed: 0, groups: 0 };
 
-  const result = applyNormalization(db, groups);
+  const result = applyNormalization(db, groups, { project });
 
   try { writeFileSync(NORMALIZE_GATE_FILE, JSON.stringify({ epoch: Date.now() })); } catch {}
 
@@ -340,7 +346,7 @@ export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
   const cutoff = Date.now() - MERGE_TIME_WINDOW_MS;
   const projectClause = project ? 'AND project = ?' : '';
   const stmt = db.prepare(`
-    SELECT id, title, narrative, project, type, access_count, created_at_epoch, minhash_sig
+    SELECT id, title, narrative, project, type, access_count, importance, created_at_epoch, minhash_sig
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND optimized_at IS NULL
@@ -410,10 +416,19 @@ Return ONLY valid JSON:
     const parsed = await callModelJSON(prompt, 'sonnet', { timeout: 20000, maxTokens: 1000 });
     if (!parsed || !parsed.should_merge) return { merged: false };
 
-    const keeper = cluster.reduce((best, o) =>
-      (o.access_count || 0) > (best.access_count || 0) ? o : best
-    , cluster[0]);
+    // Keeper = highest importance, then highest access_count. Previously access_count
+    // alone, so a critical (importance=3) but never-accessed observation lost the keeper
+    // role to a trivial (importance=1) accessed one and was compressed away.
+    const keeper = cluster.reduce((best, o) => {
+      const oi = o.importance || 1, bi = best.importance || 1;
+      if (oi !== bi) return oi > bi ? o : best;
+      return (o.access_count || 0) > (best.access_count || 0) ? o : best;
+    }, cluster[0]);
     const others = cluster.filter(o => o.id !== keeper.id);
+    // Floor the merged importance at the cluster max — merging must never silently
+    // downgrade the ranking of the most-important member (the LLM default is 2). The keeper
+    // is selected by importance-first, so keeper.importance IS the cluster max by construction.
+    const maxClusterImportance = keeper.importance || 1;
 
     const concepts = Array.isArray(parsed.merged_concepts) ? parsed.merged_concepts.slice(0, 10) : [];
     const facts = Array.isArray(parsed.merged_facts) ? parsed.merged_facts.slice(0, 10) : [];
@@ -428,7 +443,7 @@ Return ONLY valid JSON:
     const bigramText = cjkBigrams((title || '') + ' ' + (narrative || ''));
     const textField = [conceptsText, factsText, bigramText].filter(Boolean).join(' ');
     const minhashSig = computeMinHash((title || '') + ' ' + (narrative || ''));
-    const importance = clampImportance(parsed.importance || 2);
+    const importance = Math.max(clampImportance(parsed.importance || 2), maxClusterImportance);
 
     // Scrub LLM-output cluster-merge text fields at the UPDATE boundary.
     // importance is numeric; minhash_sig is hash bytes.

package/hook-update.mjs

@@ -27,7 +27,10 @@ const STATE_DIR = DB_DIR;
 const STATE_FILE = join(STATE_DIR, 'runtime', 'update-state.json');
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;       // 24 hours
 const FETCH_TIMEOUT_MS = 3000;                         // 3s network timeout
-const RATE_LIMIT_INTERVAL_MS = 6 * 60 * 60 * 1000;   // 6h if rate-limited
+// When rate-limited we got NO release data, so re-check sooner than the normal 24h
+// cadence (GitHub's unauthenticated rate-limit window resets within the hour). 6h × ≤2
+// requests = 4 polls/day, far under the 60/hr limit, so this is a faster retry, not a hammer.
+const RATE_LIMIT_INTERVAL_MS = 6 * 60 * 60 * 1000;   // 6h retry when rate-limited
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
 // ── Main Entry ─────────────────────────────────────────────
@@ -57,7 +60,12 @@ export async function checkForUpdate(options = {}) {
 
     const latest = await fetchLatestRelease();
     if (!latest) {
-      saveState({ ...state, lastCheck: new Date().toISOString() });
+      // Re-read from disk: a 403 inside fetchWithTimeout just persisted rateLimited:true.
+      // Spreading the stale in-memory `state` (captured above with rateLimited:false) would
+      // clobber that flag back to false, so shouldCheck never honors the backoff and the
+      // rate-limit mechanism is dead. Re-reading preserves the freshly-written flag.
+      const fresh = readState();
+      saveState({ ...fresh, lastCheck: new Date().toISOString() });
       return null;
     }
 
@@ -174,7 +182,10 @@ async function fetchLatestRelease() {
     headers,
   );
   if (result === 'rate-limited') return null;
-  if (result) {
+  // Guard tag_name: a 200-OK with a malformed body ({} / {tag_name:null}) would throw
+  // `Cannot read properties of undefined (reading 'replace')`. Caught upstream, but it
+  // poisons lastError and blocks the tags fallback below — fall through instead.
+  if (result && typeof result.tag_name === 'string') {
     return {
       version: result.tag_name.replace(/^v/, ''),
       tarballUrl: result.tarball_url,
@@ -188,7 +199,7 @@ async function fetchLatestRelease() {
     headers,
   );
   if (tags === 'rate-limited') return null;
-  if (Array.isArray(tags) && tags.length > 0) {
+  if (Array.isArray(tags) && tags.length > 0 && typeof tags[0]?.name === 'string') {
     const tag = tags[0];
     return {
       version: tag.name.replace(/^v/, ''),
@@ -208,7 +219,7 @@ async function fetchWithTimeout(url, headers) {
     if (res.status === 403) {
       const state = readState();
       saveState({ ...state, rateLimited: true });
-      debugLog('DEBUG', 'hook-update', 'GitHub API rate limited, extending interval');
+      debugLog('DEBUG', 'hook-update', 'GitHub API rate limited; will retry on the 6h rate-limit cadence');
       return 'rate-limited';
     }
     if (!res.ok) return null;

package/hook.mjs

@@ -202,13 +202,20 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
         // bugfix-shape nudge above and may co-fire.
         const citeBack = loadCiteBackForEpisode(episode, RUNTIME_DIR);
         if (citeBack) lines.push(citeBack);
+        // Trailing newline is REQUIRED: when this receipt flushes at SessionStart
+        // (leftover episode after /clear or /compact), the startup dashboard writes a
+        // second hookSpecificOutput object right after. Without the '\n' the two land
+        // back-to-back as `}{` on one line and Claude Code's line-based JSON parser
+        // drops both — losing the episode-flush / cite-back context exactly at the
+        // session boundary. Every other hookSpecificOutput write appends '\n'; this
+        // was the lone exception.
         process.stdout.write(JSON.stringify({
           suppressOutput: true,
           hookSpecificOutput: {
             hookEventName,
             additionalContext: lines.join('\n'),
           },
-        }));
+        }) + '\n');
       } catch { /* never block on receipt */ }
     }
   } else {

package/lib/citation-tracker.mjs

@@ -492,6 +492,18 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
            decay_seen_count = decay_seen_count + 1
      WHERE id = ?
   `);
+  // Suppressed (non-adopting) projects never demote, so uncited_streak would grow
+  // UNBOUNDED — and citeFactorClause penalizes -0.25*streak (floor 0.4), pinning every
+  // memory at the ranking floor with no recovery path. Cap at UNCITED_STREAK_THRESHOLD-1
+  // to hold the [0, threshold-1] steady state the scoring header asserts (in an adopting
+  // project the streak resets to 0 on demote, so the STORED value never exceeds 2).
+  const updateStreakCapped = db.prepare(`
+    UPDATE observations
+       SET uncited_streak = MIN(uncited_streak + 1, ?),
+           last_decided_session_id = ?,
+           decay_seen_count = decay_seen_count + 1
+     WHERE id = ?
+  `);
   const updateDemote = db.prepare(`
     UPDATE observations
        SET importance = MAX(?, importance - 1),
@@ -520,6 +532,9 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         if (nextStreak >= UNCITED_STREAK_THRESHOLD && !suppressDemotion) {
           updateDemote.run(IMPORTANCE_FLOOR, sessionId, Date.now(), id);
           demoted++;
+        } else if (suppressDemotion) {
+          // Never-demoting project: cap the streak so cite_factor can't sink to floor.
+          updateStreakCapped.run(UNCITED_STREAK_THRESHOLD - 1, sessionId, id);
         } else {
           updateStreakOnly.run(sessionId, id);
         }