claude-mem-lite 5.5.1 → 5.6.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.5.1",
+      "version": "5.6.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": "5.5.1",
+  "version": "5.6.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/hook.mjs

@@ -145,7 +145,7 @@ import {
   buildUnsavedBugfixHint,
   countUnsavedBugfixShape,
   buildCiteRecallNudge as libBuildCiteRecallNudge,
-  nextCiteLowStreak,
+  nextCiteStreakState,
 } from './lib/cite-back-hint.mjs';
 import { citeRecallPathFor } from './lib/cite-recall-path.mjs';
 import { detectUnpersistedDecision } from './lib/persist-reminder.mjs';
@@ -1182,7 +1182,11 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
           sessionId: ccSessionId,
           subagentInjected: sub.injected,
         });
-        const n = bumpCitationAccess(db, ids, project, relevant);
+        // sessionId is the ACCESS channel's idempotency key (R11-B-P1-1). Stop fires once
+        // per assistant turn and `ids` above is a rescan of the WHOLE transcript, so
+        // without it every later turn re-credited the same citation — 7.86x on the real
+        // corpus, straight into boostAccessed's `access_count > 3`.
+        const n = bumpCitationAccess(db, ids, project, relevant, { sessionId: ccSessionId });
         debugLog(
           'DEBUG',
           'handleStop',
@@ -1407,11 +1411,19 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
         const dest = citeRecallPathFor(RUNTIME_DIR, project);
         // Carry the consecutive-low-cite streak forward so the SessionStart
         // nag can self-silence after the project has ignored it N times.
-        let priorStreak = 0;
+        let prevPayload = null;
         try {
-          priorStreak = JSON.parse(readFileSync(dest, 'utf8')).lowStreak || 0;
+          prevPayload = JSON.parse(readFileSync(dest, 'utf8'));
         } catch {}
-        const lowStreak = nextCiteLowStreak(priorStreak, stats);
+        // R11-B-P1-2: the streak's unit is the SESSION, which is what the docblock has
+        // always said. Stop fires once per assistant TURN, so incrementing here silenced
+        // the nudge inside the first session — this machine read lowStreak 58 against 26
+        // transcripts before the fix.
+        const { lowStreak, streakBase, lastStreakSession } = nextCiteStreakState(
+          prevPayload,
+          ccSessionId,
+          stats,
+        );
         // G3: finalized-in-conversation + zero deliberate persistence →
         // decisionSignal rides the payload; next SessionStart reminds once.
         let decisionSignal = null;
@@ -1432,7 +1444,16 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
         } catch (e) {
           debugCatch(e, 'handleStop-persist-reminder');
         }
-        const payload = { ...stats, ...bugfixStats, lowStreak, decisionSignal, project, savedAt: Date.now() };
+        const payload = {
+          ...stats,
+          ...bugfixStats,
+          lowStreak,
+          streakBase,
+          lastStreakSession,
+          decisionSignal,
+          project,
+          savedAt: Date.now(),
+        };
         writeFileSync(dest, JSON.stringify(payload), { mode: 0o600 });
       } catch (e) {
         debugCatch(e, 'handleStop-cite-recall-persist');

package/lib/citation-tracker.mjs

@@ -46,9 +46,21 @@ export const OBS_ID_DIGITS = '\\d{1,7}';
  * Returned fresh per call rather than shared: a `/g` regex carries `lastIndex`, so one
  * exported instance reused by two scanners silently starts mid-string in whichever one
  * runs second.
+ *
+ * R11-B-P2-3: the lookbehind is what makes "bare" true. This product renders — and
+ * teaches the agent and the user to type back — `E#N` (events), `P#N` (user_prompts),
+ * `D#N` (deferred) and `S#N` (sessions), and every INJECTED-side extractor already drops
+ * those by construction (they fail INJECTED_ROW_RE / FYI_LINE_ID_RE / UPS_ID_RE). The
+ * CITED side did not, so `E#501` was read as observation 501. On this machine 26/26 live
+ * observation ids are also event ids AND prompt ids, so the collision needs exactly one
+ * co-occurrence to land.
+ *
+ * It does NOT catch every false positive and is not meant to: `issue #1234` and
+ * `[link](#42)` are still matched, because a digit preceded by a space or `(` is
+ * indistinguishable from a citation at this layer.
  */
 export function citationIdRe() {
-  return new RegExp(`#(${OBS_ID_DIGITS})\\b`, 'g');
+  return new RegExp(`(?<![A-Za-z0-9])#(${OBS_ID_DIGITS})\\b`, 'g');
 }
 
 /**
@@ -58,7 +70,16 @@ export function citationIdRe() {
  * `citationIdRe()` above is a NUMERATOR caliber. On the numerator side a spurious `#1`
  * costs nothing, because a cited id only counts once it intersects an injected set that
  * WAS anchored — every injected-side extractor in this module matches a row shape
- * (`INJECTED_ROW_RE`, `FYI_LINE_ID_RE`, `UPS_ID_RE`, `SUBAGENT_INJECT_ID_RE`). On the
+ * (`INJECTED_ROW_RE`, `FYI_LINE_ID_RE`, `UPS_ID_RE`, `SUBAGENT_INJECT_ID_RE`).
+ *
+ * That argument has ONE measured exception, and it is why citationIdRe now carries a
+ * lookbehind (R11-B-P2-3): `extractUserTypedIds` feeds the access allow-list through the
+ * SAME numerator regex, and nothing anchors a user's own message. So a user typing `D#9`
+ * and the assistant writing `D#9` intersect on an unanchored token — 8 of 43 credited
+ * (session, id) pairs on the real corpus were sourced only that way, 4 of them landing on
+ * live observations. Read the argument as "anchored on the injected side", not "safe".
+ *
+ * On the
  * denominator side nothing anchors it, so a prose `#1` is a false positive by
  * construction — it inflates "injected, never cited" and biases the measured rate DOWN.
  *
@@ -408,7 +429,13 @@ export function assertRelevanceCoversAllFaces(sourced) {
  *        with ids the user typed themselves. Required.
  * @returns {number} count of rows incremented
  */
-export function bumpCitationAccess(db, ids, project, relevantIds, env = process.env) {
+export function bumpCitationAccess(
+  db,
+  ids,
+  project,
+  relevantIds,
+  { env = process.env, sessionId = null } = {},
+) {
   if (!db || !ids || !project) return 0;
   // Revert path for the gate (CLAUDE_MEM_CITATION_RELEVANCE_GATE=off). It restores the
   // pre-v3.84.0 behaviour — every mention credited — including the missing-argument hole,
@@ -428,7 +455,35 @@ export function bumpCitationAccess(db, ids, project, relevantIds, env = process.
   // crediting a tombstone instead of the row that absorbed it) with no upside to restore.
   const idList = gateOff ? [...cited] : [...cited].filter((id) => allowed.has(id));
   if (idList.length === 0) return 0;
-  const stmt = db.prepare(`
+  // R11-B-P1-1: credit once per CC SESSION, not once per call. `Stop` fires on every
+  // assistant turn and rescans the entire transcript, so without this key one citation
+  // was re-credited on every later turn of the same session — measured 7.86x over the
+  // real corpus (338 credits / 43 distinct (session, id) pairs), which then crosses
+  // boostAccessed's `access_count > 3` and lifts importance unattended.
+  //
+  // The key is the same shape the decay channel uses (last_cited_session_id /
+  // last_decided_session_id) and deliberately a SEPARATE column: decay resolves a
+  // mainOnly id set behind hasMainThreadAssistantText, this channel resolves the whole
+  // transcript, so sharing one key would let either channel silence the other.
+  //
+  // sessionId null → no session scope exists to be idempotent within (non-CC
+  // invocation), so the pre-R11 unconditional bump is the only defined behaviour.
+  //
+  // Scope the guarantee honestly: the column holds the LAST crediting session, not a set,
+  // so two same-project CC sessions interleaving their turns flip the stamp between them
+  // (A credits → B credits → A's next Stop sees B's stamp and credits again) and the key
+  // degrades toward per-turn counting for that pair. That is the same bound the decay
+  // channel accepts at :1634 and lib/edge-attribution.mjs:145, and widening it would mean
+  // storing a set per row. "Once per session" is exact for the ordinary single-session
+  // case and an upper bound of "once per session PAIR interleave" otherwise.
+  const scoped = typeof sessionId === 'string' && sessionId.length > 0;
+  const stmt = scoped
+    ? db.prepare(`
+    UPDATE observations SET access_count = access_count + 1, last_accessed_at = ?,
+      last_access_session_id = ?
+    WHERE id = ? AND project = ? AND COALESCE(last_access_session_id, '') != ?
+  `)
+    : db.prepare(`
     UPDATE observations SET access_count = access_count + 1, last_accessed_at = ?
     WHERE id = ? AND project = ?
   `);
@@ -436,7 +491,10 @@ export function bumpCitationAccess(db, ids, project, relevantIds, env = process.
   let n = 0;
   for (const id of idList) {
     try {
-      const result = stmt.run(now, id, project);
+      // 0 changes is a SKIP, not a failure: either the row is not this project's, or
+      // this session already credited it. Both must leave `n` alone, because the caller
+      // logs it as "obs bumped".
+      const result = scoped ? stmt.run(now, sessionId, id, project, sessionId) : stmt.run(now, id, project);
       if (result.changes > 0) n++;
     } catch (e) {
       debugCatch(e, `bumpCitationAccess-id-${id}`);
@@ -1427,6 +1485,19 @@ export function redirectSupersededIds(db, project, ids) {
  * rows are currently boost-eligible; 25 of them are cited nowhere in the corpus, and
  * at most 3 could have crossed `access_count > 3` on citations even under an upper
  * bound that ignores the gate entirely. So the path is real and its effect is small.
+ *
+ * THAT BOUND IS RETRACTED (R11-B-P1-1, 2026-09-07). It was computed as "one citation
+ * contributes at most 1", and that premise was false: `Stop` fires once per assistant
+ * TURN and rescans the whole transcript, so before the `last_access_session_id` key one
+ * citation contributed once per REMAINING TURN of its session — 338 credits over 43
+ * distinct (session, id) pairs = 7.86x across 51 real transcripts, single-session worst
+ * case 18.75x. The "at most 3" therefore understated its own quantity by an unmeasured
+ * factor, and no replacement bound is stated here because none has been measured.
+ *
+ * The premise now holds going FORWARD only. Existing rows keep whatever inflated
+ * `access_count` they accumulated — the true count is not recoverable from the inflated
+ * one, so nothing is back-corrected. Any future reading of `access_count` as "how often
+ * this was cited" must treat pre-v5.6.0 values as an upper bound, not a count.
  * It is untouched here because `access_count` has other writers (explicit recall /
  * get / timeline) and is also an input to noisePenaltyClause, so changing it is a
  * different decision with a different blast radius.

package/lib/cite-back-hint.mjs

@@ -243,6 +243,52 @@ export function nextCiteLowStreak(priorStreak, stats, env = process.env) {
   return ratioGateFires(stats, env) ? prior + 1 : 0;
 }
 
+/**
+ * R11-B-P1-2 — advance the self-silence streak by SESSION, which is the unit the
+ * docblock above has always claimed and the code never implemented.
+ *
+ * `Stop` fires once per assistant TURN, and the writer incremented on every fire, so
+ * with a median of ~6 turns per session the default silence-after-3 was reached inside
+ * the FIRST session and never recovered. Measured on this machine before the fix:
+ * `runtime/cite-recall-dev--claude-mem-lite.json` read lowStreak 58 for a project with
+ * 26 transcripts on disk — a per-session counter cannot exceed the session count — and
+ * 2 of 3 projects had the cite-#NN nudge permanently silenced.
+ *
+ * Recomputing from the value the session STARTED at (rather than freezing after the
+ * first fire) keeps two properties: a session advances the streak by at most 1, and a
+ * citation arriving in a later turn still resets it to 0 — which matters because the
+ * whole contract is "cite NEXT time you produce user-visible text".
+ *
+ * @param {object|null} prev  parsed previous payload, or null when absent/unreadable
+ * @param {string|null} ccSessionId  current CC session id
+ * @returns {{lowStreak: number, streakBase: number, lastStreakSession: string|null}}
+ */
+export function nextCiteStreakState(prev, ccSessionId, stats, env = process.env) {
+  let streakBase = 0;
+  if (prev && typeof prev === 'object') {
+    if (prev.lastStreakSession === undefined) {
+      // Written under the pre-R11 TURN semantics. The stored number counted Stop fires,
+      // so it is not convertible to sessions — discard it once, here, rather than
+      // leaving every existing install permanently silenced by a number that never
+      // meant what it was read as.
+      streakBase = 0;
+    } else if (ccSessionId && prev.lastStreakSession === ccSessionId) {
+      streakBase = Number(prev.streakBase) || 0;
+    } else {
+      streakBase = Number(prev.lowStreak) || 0;
+    }
+  }
+  return {
+    lowStreak: nextCiteLowStreak(streakBase, stats, env),
+    streakBase,
+    // null when there is no CC session to key on: the same-session branch above then
+    // never matches, so those invocations keep the old per-fire behaviour. There is no
+    // session identity available to do better, and the field's presence is what tells a
+    // later read that this file is post-R11.
+    lastStreakSession: ccSessionId || null,
+  };
+}
+
 // Env opt-outs:
 //   • CLAUDE_MEM_NO_CITE_NUDGE=1 — disables BOTH gates (full silence)
 //   • CLAUDE_MEM_CITE_NUDGE_THRESHOLD — ratio gate threshold (default 0.6)

package/lib/export-columns.mjs

@@ -13,8 +13,10 @@
 // Full round-trippable set: content + value-signals (access/cited/uncited/injection/decay)
 // + branch + timing. `id` + `memory_session_id` are informational (restore remaps id and
 // buckets under a synthetic restore session). Session-idempotency keys (last_decided/
-// last_cited_session_id, demoted_at, optimized_at) are intentionally NOT exported — they are
-// meaningless after a row is re-bucketed under a restore session. Also intentionally NOT
+// last_cited/last_access_session_id, demoted_at, optimized_at) are intentionally NOT
+// exported — they are meaningless after a row is re-bucketed under a restore session.
+// last_access_session_id (v48) joins that set for the same reason: it answers "did THIS cc
+// session already credit this row", which no restored session can have done. Also intentionally NOT
 // exported: `related_ids` (holds observation ids, stale/dangling after restore remaps ids)
 // and `discovery_tokens` (a derived retrieval metric, rebuilt by the live system; exporting
 // it would freeze a stale value into backups).

package/lib/search-core.mjs

@@ -261,7 +261,7 @@ export function searchPromptsFts(
       ${project ? 'AND s.project = ?' : ''}
       ${epochFrom !== null ? 'AND p.created_at_epoch >= ?' : ''}
       ${epochTo !== null ? 'AND p.created_at_epoch <= ?' : ''}
-    ORDER BY p.created_at_epoch DESC
+    ORDER BY p.created_at_epoch DESC, p.id DESC
     LIMIT ? OFFSET ?
   `,
     )
@@ -977,13 +977,22 @@ export async function coreRunSearchPipeline(ctx, opts) {
       typeWheres.push('COALESCE(importance, 1) >= ?');
       typeParams.push(importance);
     }
+    // R11-A-P1-1: `branch` was the one caller-supplied filter this rebuilt WHERE did not
+    // carry, and nothing downstream compensates — applyTierFilter only reads tier, and
+    // finalizeSearchPage only counts. The leak surfaced exactly when FTS matched nothing,
+    // so the wrong-branch rows were the ONLY rows the caller saw, with `total` clamped to
+    // them so the page read like a legitimate hit.
+    if (branch) {
+      typeWheres.push('branch = ?');
+      typeParams.push(branch);
+    }
     typeParams.push(limit);
     const typeRows = db
       .prepare(
         `
       SELECT id, type, title, subtitle, project, created_at, importance, files_modified
       FROM observations WHERE ${typeWheres.join(' AND ')}
-      ORDER BY created_at_epoch DESC LIMIT ?
+      ORDER BY created_at_epoch DESC, id DESC LIMIT ?
     `,
       )
       .all(...typeParams);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "5.5.1",
+      "version": "5.6.0",
       "os": [
         "darwin",
         "linux"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.5.1",
+  "version": "5.6.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/schema.mjs

@@ -156,7 +156,18 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // every existing install at v46 a new index there would simply never be created. Same trap
 // the FTS5 migration hit — a DDL change that is not reachable from the version the DB
 // already reports is a no-op with a convincing diff.
-export const CURRENT_SCHEMA_VERSION = 47;
+// v48 (R11-B-P1-1): observations.last_access_session_id — the THIRD per-row session key
+// on this table, and it exists for the same reason as the other two. `Stop` fires once
+// per assistant TURN and rescans the whole transcript, so `bumpCitationAccess` re-credited
+// one citation on every later turn of the same session: real-corpus replay over 51
+// transcripts read 338 credits across 43 distinct (session, id) pairs = 7.86x, single
+// session worst case 18.75x. That feeds boostAccessed (access_count > 3 → importance + 1,
+// in DEFAULT_MAINTAIN_OPS, unattended daily) and suppresses noisePenaltyClause, whose
+// predicate reads `injection_count > access_count * 3`. Additive + nullable: legacy rows
+// read NULL and are credited exactly once more, on their next citation, then stamp.
+// The column holds the LAST crediting session, not a set, so two same-project sessions
+// interleaving their turns flip it between them — see the scope note in bumpCitationAccess.
+export const CURRENT_SCHEMA_VERSION = 48;
 
 // Sentinel columns for the LATEST migration set(s). The fast-path uses these
 // to self-heal half-migrated DBs — schema_version bumped but column ALTERs
@@ -177,6 +188,7 @@ export const CURRENT_SCHEMA_VERSION = 47;
 // pragma_table_info on a missing table returns zero rows (it does not throw), so
 // naming any column of the new table is a table-presence check.
 const LATEST_MIGRATION_COLUMNS = [
+  { table: 'observations', column: 'last_access_session_id' }, // v48
   { table: 'observations', column: 'decay_seen_at_first_cite' }, // v46
   { table: 'citation_surface_log', column: 'surface' }, // v45
   { table: 'observations', column: 'scope' }, // v44
@@ -397,6 +409,14 @@ const MIGRATIONS = [
   // destroy the distinction the column exists to record. Legacy rows stay NULL — they
   // are not evidence of anything and must not be read as first-cite-at-0.
   'ALTER TABLE observations ADD COLUMN decay_seen_at_first_cite INTEGER DEFAULT NULL',
+  // v48 (R11-B-P1-1): the access-channel idempotency key. Sibling of
+  // last_decided_session_id (v40, uncited/streak arm) and last_cited_session_id (v41,
+  // promote arm) — three channels fire out of one Stop hook, each needs its own key
+  // because they resolve different id sets: decay reads mainOnly, access reads the whole
+  // transcript including sidechains, and the decay pair is additionally gated on
+  // hasMainThreadAssistantText, so a session can credit access while decay never runs.
+  // Sharing a key would make one channel silence the other.
+  'ALTER TABLE observations ADD COLUMN last_access_session_id TEXT DEFAULT NULL',
 ];
 
 /**

package/search-engine.mjs

@@ -518,7 +518,8 @@ export function findFtsAnchor(
       AND (? IS NULL OR o.project = ?)
       AND ${liveObsFilterSql('o')}
     ORDER BY ${OBS_BM25}
-      * ${recencyDecaySql({ tsExpr: 'o.created_at_epoch', halfLifeSql: `${halfLifeMs}.0` })}
+      * ${recencyDecaySql({ tsExpr: 'o.created_at_epoch', halfLifeSql: `${halfLifeMs}.0` })},
+      o.id DESC
     LIMIT 1
   `;
   const stmt = db.prepare(sql);
@@ -579,7 +580,7 @@ export function searchObservationsHybrid(db, ctx) {
         `
       SELECT id, type, title, subtitle, project, created_at, created_at_epoch, files_modified, importance, lesson_learned
       FROM observations ${where}
-      ORDER BY created_at_epoch DESC
+      ORDER BY created_at_epoch DESC, id DESC
       LIMIT ? OFFSET ?
     `,
       )