claude-mem-lite 5.3.0 → 5.4.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.3.0",
+      "version": "5.4.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.3.0",
+  "version": "5.4.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/README.md

@@ -120,7 +120,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Schema auto-migration** -- Idempotent `ALTER TABLE` migrations run on every startup, safely adding new columns and indexes without data loss
 - **LLM concurrency control** -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
 - **stdin overflow protection** -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
-- **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm does not currently fire** (tracked as R10-P1-1). The measurement, first: on the maintainer's own install `session_handoffs` holds 4 `exit` rows and **0** `clear` rows — the `clear` snapshot has never once been written. The mechanism, as a hypothesis: SessionStart treats a session file left on disk as the marker of a previous session that ended without `Stop` (`hook.mjs:2393-2405`, whose own comment reads "Normal `/exit` deletes the file, so this only triggers for `/clear`, `/compact`, or crash recovery"), and that file is exactly what `Stop` deletes (`hook.mjs:1542`) — which would make the branch unreachable if `Stop` runs at the end of every assistant turn rather than once per session. **That last clause is NOT verified**, and it is the whole question: the fix differs depending on whether Claude Code rotates its session id across `/clear`, so a real `/clear` stdin capture comes before any code change
+- **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm fires since v5.4.0** (R10-P1-1); before that it had never once written a row — `session_handoffs` on the maintainer's install held 4 `exit` rows and **0** `clear` rows. Two host facts settled it, both measured rather than assumed. (1) `Stop` runs at the end of every assistant *turn*, not once per session, and it deleted the session file that SessionStart reads to learn which session just ended — so the branch was unreachable, and mem sessions were minted per turn (58 prompts over 16 host sessions produced 56 mem sessions and 56 summary rows, 2026-09-07). (2) Claude Code **rotates its session id across `/clear`**: of 21 real transcripts, 12 carry a `/clear` command record, and in 12/12 that record's timestamp precedes its own file's first record by ~0.1s — the command is issued in the old session and replayed into a new file under a new id. So `Stop` no longer deletes the file, SessionStart asks the host's `source` (`startup`/`clear`/`compact`/`resume`) instead of guessing from the file, and the handoff's prompt lookup falls back to the unscoped set when the new session's id matches none. Revert path: `CLAUDE_MEM_LEGACY_STOP_UNLINK=1`
 - **Git-SHA continuation anchor** (v2.31.0) -- Handoff rows include `git_sha_at_handoff`; any handoff matching the current `HEAD` counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
 - **Startup dashboard** (v2.31.0) -- SessionStart hook aggregates `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + most-recent exit handoff + recent event count into a single structured block injected via `hookSpecificOutput.additionalContext`
 - **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)
@@ -431,9 +431,10 @@ FTS5 indexes: `observations_fts` (title, subtitle, narrative, text, facts, conce
 
 ```
 SessionStart
-  -> Generate session ID
-     (the /clear|/compact handoff branch here is currently unreachable — R10-P1-1,
-      see Cross-session handoff above)
+  -> Read the host's `source` (startup | clear | compact | resume) from stdin
+  -> On clear/compact: read the outgoing session from the session file, save its
+     'clear' handoff, emit the Working State block  (R10-P1-1, fixed v5.4.0)
+  -> Generate session ID (overwrites the session file)
   -> Mark stale sessions (>24h active) as abandoned
   -> Clean orphaned/stale lock files
   -> Query recent observations (24h)
@@ -462,8 +463,9 @@ Stop
   -> Flush final episode buffer
   -> Save handoff snapshot (type 'exit')
   -> Mark session completed
-  -> Delete the session file  <- what makes the SessionStart /clear branch unreachable
   -> Spawn LLM summary worker (poll-based wait)
+  -> Keep the session file  <- Stop fires per TURN; deleting it here re-minted a mem
+     session every turn and left the SessionStart /clear branch unreachable (v5.4.0)
 ```
 
 
@@ -828,6 +830,7 @@ what is already stored — only whether new work runs.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CLAUDE_MEM_SKIP_SUMMARY` | Skip the background LLM session summary at **both** of its spawn sites — `Stop`, and the SessionStart `/clear`-handoff path. Until v5.3.0 only the `Stop` one honoured it. | _(runs)_ |
+| `CLAUDE_MEM_LEGACY_STOP_UNLINK` | Restore the pre-v5.4.0 behaviour where `Stop` deletes the session file. Documented revert path for the session-lifecycle change, not a supported configuration: it re-mints a mem session per turn and makes the `/clear` handoff unreachable again. Only reach for it on a host that fires `Stop` once per session rather than once per turn. | _(file kept)_ |
 | `CLAUDE_MEM_SKIP_EPISODE_LLM` | Skip LLM extraction on episode flush — observations are still batched, just not summarized. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_SAVE_ENRICH` | Skip the background Haiku call that backfills `lesson_learned` / search aliases after a save. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_COMPRESS` | Skip auto-compression of old observations. | _(runs)_ |

package/hook-handoff.mjs

@@ -56,25 +56,35 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // scopeSessionId is absent or == sessionId (legacy/test/no-stdin), fall back to the
   // unfiltered query (identical to pre-D#26 behavior).
   const ccScope = scopeSessionId && scopeSessionId !== sessionId ? scopeSessionId : null;
-  const prompts = ccScope
-    ? db
-        .prepare(
-          `
+  const unscopedPrompts = () =>
+    db
+      .prepare(
+        `
         SELECT prompt_text FROM user_prompts
-        WHERE content_session_id = ? AND (cc_session_id = ? OR cc_session_id IS NULL)
+        WHERE content_session_id = ?
         ORDER BY prompt_number ASC LIMIT 5
       `,
-        )
-        .all(sessionId, ccScope)
-    : db
+      )
+      .all(sessionId);
+  let prompts = ccScope
+    ? db
         .prepare(
           `
         SELECT prompt_text FROM user_prompts
-        WHERE content_session_id = ?
+        WHERE content_session_id = ? AND (cc_session_id = ? OR cc_session_id IS NULL)
         ORDER BY prompt_number ASC LIMIT 5
       `,
         )
-        .all(sessionId);
+        .all(sessionId, ccScope)
+    : unscopedPrompts();
+  // R10-P1-1: on the /clear path the scope is the NEW session's CC id while the prompts
+  // being handed off belong to the OLD one, and the host rotates that id across /clear
+  // (measured 12/12 on real transcripts, 2026-09-07) — so the scoped query returns 0 and
+  // the whole handoff was silently skipped. Fall back to the unscoped set when, and only
+  // when, the scoped one is EMPTY: D#26 exists to stop two live sessions being MERGED into
+  // one working_on, and there is nothing to merge with when this session contributed no
+  // prompts. The alternative at that point is not a cleaner row, it is no row at all.
+  if (ccScope && prompts.length === 0) prompts = unscopedPrompts();
   if (prompts.length === 0) return; // Empty session — nothing to hand off
 
   // Filter prompts whose only content is workflow/control language ("继续",

package/hook.mjs

@@ -1537,10 +1537,32 @@ async function handleStop() {
   // recreate at 432ms and watched a 300ms grace lose.
   if (!process.env.CLAUDE_MEM_SKIP_SUMMARY) spawnBackground('llm-summary', sessionId, project);
 
-  // Clean session file AFTER spawning background
-  try {
-    unlinkSync(sessionFile());
-  } catch {}
+  // The session file deliberately SURVIVES Stop (R10-P1-1). It used to be unlinked here,
+  // on the model "Stop = /exit = the session is over". The host does not work that way:
+  // Stop fires at the end of EVERY assistant turn, so the unlink minted a fresh mem
+  // session on the next event and cost two things at once —
+  //
+  //   • `sdk_sessions` / `session_summaries` counted turns, not sessions. Measured on the
+  //     maintainer's live DB 2026-09-07: 58 prompts over 16 host sessions produced 56
+  //     distinct mem sessions and 56 summary rows, 0 of which carried the LLM-only fields.
+  //   • handleSessionStart's mid-restart probe reads this file to learn which session just
+  //     ended. With it deleted every turn the probe never fired, so the /clear handoff
+  //     branch was unreachable in production — 0 `clear` rows against 21 real sessions.
+  //
+  // Lifetime is bounded by SESSION_EXPIRY_MS (12h) in getSessionId(), and every
+  // SessionStart overwrites it via createSessionId(), so "one mem session per host
+  // session" holds without anything having to delete it.
+  //
+  // CLAUDE_MEM_LEGACY_STOP_UNLINK=1 restores the pre-v5.4.0 unlink. It exists because the
+  // measurements above are from ONE host build; a host that fires Stop once per session
+  // instead of once per turn would be better served by the old shape, and a user who hits
+  // that has no other lever. It is not a supported configuration — it re-breaks the /clear
+  // handoff by design.
+  if (process.env.CLAUDE_MEM_LEGACY_STOP_UNLINK === '1') {
+    try {
+      unlinkSync(sessionFile());
+    } catch {}
+  }
 }
 
 // ─── SessionStart Handler + CLAUDE.md Persistence (Tier 1 A, E) ─────────────
@@ -2336,13 +2358,20 @@ async function handleSessionStart() {
 
   // Read CC real session_id from hook stdin — used to scope handoff rows so parallel
   // sessions for the same project don't clobber each other (see docs/bug.txt).
+  // `source` (startup | clear | compact | resume) is read here too: since Stop stopped
+  // deleting the session file, the file's survival no longer tells us WHY this session
+  // started, and the host's own word is the only non-guess (R10-P1-1).
   let ccSessionId = null;
+  let startSource = null;
   try {
     const raw = await readStdin();
     const hookData = JSON.parse(raw.text);
     if (typeof hookData?.session_id === 'string' && hookData.session_id.length > 0) {
       ccSessionId = hookData.session_id;
     }
+    if (typeof hookData?.source === 'string' && hookData.source.length > 0) {
+      startSource = hookData.source;
+    }
   } catch {
     /* stdin unavailable — legacy behavior */
   }
@@ -2390,19 +2419,32 @@ async function handleSessionStart() {
     }
   }
 
-  // Detect mid-session restart (/clear or /compact): if a recent session file exists,
-  // the previous session ended without Stop hook firing. Read BEFORE createSessionId()
-  // overwrites the session file. Normal /exit deletes the file, so this only triggers
-  // for /clear, /compact, or crash recovery.
+  // Detect mid-session restart (/clear or /compact) and carry the ending session forward.
+  // Read BEFORE createSessionId() overwrites the session file.
+  //
+  // The discriminator is the host's `source`, NOT the session file's survival. The old
+  // comment here read "normal /exit deletes the file, so this only triggers for /clear,
+  // /compact, or crash recovery" — but the deleter was Stop, which fires every turn, so
+  // the file was always gone and this branch never triggered (R10-P1-1). Now that Stop
+  // keeps the file, the file is always THERE, and asking it "why did this session start"
+  // would answer /clear for a plain launch too. Only the host knows.
+  //
+  // `startup` and `resume` mean the previous session ended on its own terms and already
+  // wrote its per-turn `exit` handoff, which UserPromptSubmit reads back — no clear
+  // snapshot is owed. A null source (no stdin: tests, legacy hosts) keeps the old
+  // file-presence behavior so nothing that used to reach this branch stops reaching it.
+  const isMidSessionRestart = startSource !== 'startup' && startSource !== 'resume';
   let prevSessionId = null;
   let prevProject = null;
-  try {
-    const data = JSON.parse(readFileSync(sessionFile(), 'utf8'));
-    if (Date.now() - data.startedAt < SESSION_EXPIRY_MS) {
-      prevSessionId = data.id;
-      prevProject = data.project;
-    }
-  } catch {} // No session file = fresh startup, nothing to recover
+  if (isMidSessionRestart) {
+    try {
+      const data = JSON.parse(readFileSync(sessionFile(), 'utf8'));
+      if (Date.now() - data.startedAt < SESSION_EXPIRY_MS) {
+        prevSessionId = data.id;
+        prevProject = data.project;
+      }
+    } catch {} // No session file = fresh startup, nothing to recover
+  }
 
   // Tier 1 A: Create unique session ID
   const sessionId = createSessionId();

package/install.mjs

@@ -509,7 +509,7 @@ function registerMcpServer() {
   }
 }
 
-function dedupePluginCacheAndHooks({ managedHooks } = {}) {
+export function dedupePluginCacheAndHooks({ managedHooks, isDev = false } = {}) {
   // 3b. Deduplicate: if marketplace plugin also registers MCP + hooks,
   // clear them to prevent double execution. install.mjs hooks (in settings.json)
   // point to ~/.claude-mem-lite/ (latest code in dev mode via symlinks),
@@ -593,17 +593,47 @@ function dedupePluginCacheAndHooks({ managedHooks } = {}) {
       const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_KEY, 'claude-mem-lite');
       if (existsSync(cacheBase)) {
         const launchSyncFiles = ['launch.mjs', 'launch-preflight.mjs'];
+        // Read, not remembered: the cache dir names ARE versions, so the comparison has to
+        // be against what this installer actually is. A stale constant here would re-open
+        // R10-P2-11 on the next release without changing a line of this block.
+        let selfVersion = null;
+        try {
+          selfVersion = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).version;
+        } catch {
+          /* no readable package.json — treat every version as non-matching (sync nothing) */
+        }
         let clearedHooks = 0;
         for (const ver of readdirSync(cacheBase)) {
           const verDir = join(cacheBase, ver);
 
-          // Sync launch.mjs + its preflight companion (issue #15)
-          if (existsSync(join(verDir, 'scripts'))) {
+          // Sync launch.mjs + its preflight companion (issue #15).
+          //
+          // R10-P2-11: this used to run for EVERY cached version. Issue #15 is a dev-mode
+          // routing fix — the point is that a dev tree's launch.mjs reaches the cache the
+          // MCP server starts from — but nothing gated it, so a plain `install` (and the
+          // repair that SessionStart spawns in the background) pushed the installer's entry
+          // point into every OLD version dir, where it runs against that version's own
+          // `lib/`. Entry point and library are versioned together: HEAD's launch.mjs:72-73
+          // destructures `nativeBindingRepairHint` from ../lib/binding-probe.mjs, which
+          // v3.95.0 does not export, so :110 throws inside a catch and the user's repair
+          // hint disappears — a silent downgrade of the one message that tells them how to
+          // fix a dead binding. Reproduced in tests/sandbox/phaseB-npm.mjs §B9 (the old
+          // dir came back 9802B with `nativeBindingRepairHint` in it), which is the
+          // reproduction R10 §8 required before touching install().
+          //
+          // Dev mode still syncs everything: that is the fix's whole purpose, and a dev
+          // tree has no old versions to protect. Otherwise only the version dir that
+          // matches this installer — same release, so same expectations of `lib/`.
+          const versionMatches = isDev || ver === selfVersion;
+          if (versionMatches && existsSync(join(verDir, 'scripts'))) {
             for (const f of launchSyncFiles) {
               const src = join(PROJECT_DIR, 'scripts', f);
               if (existsSync(src)) {
                 try {
-                  copyFileSync(src, join(verDir, 'scripts', f));
+                  // Atomic for the same reason the two hooks.json writes above are: a
+                  // torn launch.mjs is the MCP server's entry point, and the reader is
+                  // Claude Code starting it, not us.
+                  atomicWriteFileSync(join(verDir, 'scripts', f), readFileSync(src));
                 } catch {
                   /* keep going */
                 }
@@ -959,7 +989,7 @@ async function install() {
   // re-read settings.json) is what keeps a future reorder from silently turning the
   // dedup off — the dependency is data, not sequence.
   const managedHooks = configureHooks();
-  dedupePluginCacheAndHooks({ managedHooks });
+  dedupePluginCacheAndHooks({ managedHooks, isDev: IS_DEV });
   backupLegacyClaudeMemData();
   verifyDatabase();
   await dogfoodAutoAdopt();

package/lib/maintain-core.mjs

@@ -394,6 +394,21 @@ export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP })
       -- lesson). Parity with the "lessons never auto-GC" guards in
       -- decayAndMarkIdle / selectCompressionCandidates / findSmartCompressCandidates.
       AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
+      -- D#4. The one HARD DELETE in this family, and until now the only site whose
+      -- exemption from liveObsFilterSql was a LIKELIHOOD argument rather than an
+      -- inertness proof: these rows have no title, narrative or lesson, so they are
+      -- absent from every injection surface, so an id that was never injected is not one
+      -- a #NN cites. Narrow, but reachable -- a hand-typed #NN, or a numeric
+      -- "save --supersedes" chain later blanked by a degenerate cluster-merge -- and what
+      -- the delete takes with it is the superseded_by that
+      -- citation-tracker.redirectSupersededIds (:1363) follows to credit a corrected
+      -- memory's #NN to its successor.
+      --
+      -- Deliberately NOT the full liveObsFilterSql. A retired row whose superseded_by is
+      -- null hands that redirect nothing: it falls through to out.add(id) (:1379-1381),
+      -- the same answer a missing row produces. Filtering on superseded_at instead would
+      -- strand every empty retired row here forever for no gain.
+      AND superseded_by IS NULL
       ${projectFilter} LIMIT ${opCap}
   `,
     )

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.3.0",
+  "version": "5.4.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/scripts/hook-launcher.mjs

@@ -124,12 +124,23 @@ if (!entryArg) {
 
 const entryAbs = entryArg.startsWith('/') ? entryArg : join(INSTALL_DIR, entryArg);
 
-// Swap barrier. An auto-update / repair renames files into the install dir one at
-// a time — atomic per file, not per file SET — so a hook process that starts
-// mid-swap can resolve its entry from the old version and an import from the new
-// one. hook-update.mjs marks that window; skip the fire instead of importing a
-// mixed module graph. Hooks are best-effort and the swap lasts ~a second, so the
-// next fire runs against a settled install.
+// Swap barrier. An auto-update renames files into the install dir one at a time —
+// atomic per file, not per file SET — so a hook process that starts mid-swap can
+// resolve its entry from the old version and an import from the new one.
+// hook-update.mjs marks that window; skip the fire instead of importing a mixed
+// module graph. Hooks are best-effort and the swap lasts ~a second, so the next
+// fire runs against a settled install.
+//
+// This covers the AUTO-UPDATE path only, and the distinction is not pedantic:
+// `hook-update.mjs:719` is the sole writer of this marker in the whole tree (name set,
+// 2026-09-07), so the barrier is never armed for `install.mjs install` — which copies the
+// same file set in place with copyFileSync (`install.mjs:341-350`) and is what
+// `install.mjs repair` ends up executing (`:2388`, after verifying the release). A repair
+// spawned in the background at SessionStart therefore overwrites this tree while hooks
+// keep firing into it. That is R10 P2-12, still open: the mechanism is settled, the runtime
+// symptom is not reproduced, and R10 §8 asks for a repro in tests/sandbox/phaseB-npm.mjs
+// before install()'s main path is touched. An earlier draft of this comment said "auto-update
+// / repair", which reads as though the repair path were already covered — it is not.
 //
 // Stale-guarded on BOTH pid and ts: an updater killed mid-swap leaves the marker
 // behind, and a marker that outlives its writer must never mute hooks permanently.