claude-mem-lite 6.8.2 → 6.8.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.8.2",
+      "version": "6.8.3",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "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": "6.8.2",
+  "version": "6.8.3",
   "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

@@ -425,6 +425,13 @@ function unadoptAll(args) {
       log(`[unadopt --all] ${dir} → cleaned partial residue (detail doc/state, no block)`);
       partial++;
     }
+    // OUTSIDE the branch, because residue is orthogonal to what happened to the block: a
+    // project can have its block removed AND still carry an unpaired sentinel. An orphan is
+    // the one kind of residue the sweep cannot finish — its block has no end marker, so its
+    // extent is unknowable — and the two lines above would otherwise imply the project is
+    // clean. Inside the else-branch it was also unreachable for the 'removed' case, which is
+    // how the print survived a mutation with the whole suite green (pre-ship review P2-2).
+    if (r.residue) log(`  ⚠ ${r.residue}`);
   }
 
   // 2. Legacy memory-dir cleanup across every memdir (foreign-content guarded).
@@ -481,4 +488,8 @@ export function cmdUnadopt(args = []) {
   const mig = migrateLegacyMemoryDir(cwd, PLUGIN_SLUG, { force });
   const migNote = mig.action === 'removed' ? ' (+cleaned legacy memdir)' : '';
   log(`[unadopt] ${cwd} → ${r.action}${migNote}`);
+  // 'partial' is the outcome that used to print as 'absent': the sidecar files are gone but
+  // an unpaired sentinel still holds steering text in the user's CLAUDE.md, and only they can
+  // decide where that text ends. Silence here is what let it survive every sweep.
+  if (r.residue) log(`  ⚠ ${r.residue}`);
 }

package/claudemd.mjs

@@ -59,8 +59,50 @@ function escapeRe(s) {
 // are `\r?\n` (not bare `\n`) so a CLAUDE.md re-saved with Windows CRLF endings
 // still matches — otherwise the block read as "absent" and a fresh LF copy got
 // appended every SessionStart, growing the file without bound (review C1/H2).
+// The body may not contain ANOTHER sentinel of the same slug. `[\s\S]*?` could, and that is
+// not a tidiness point — it is how a match stopped being one block. Drop the `:end` line by
+// hand (a merge resolution, an editor, another tool) and the next adopt appends a second
+// block below whatever the user has written since; the adopt after THAT matched from the
+// orphaned begin, lazily, to the only `:end` in the file — which now sits past the user's
+// text and past the second begin — so `raw.replace(m[0], section)` deleted all of it.
+// Measured 2026-09-13: a "## Deployment runbook" section appended after adoption was gone
+// after two further adopts, silently, with both runs reporting success.
+//
+// The tempered token below cannot span a sentinel, so the engine backtracks to the
+// WELL-FORMED pair and the orphan is simply left alone — which is the right answer for a
+// file we do not own: where the orphaned body ends is genuinely unknowable, so removeManaged
+// reports it (action 'partial') rather than guessing a span to delete.
+//
+// Safe by construction for legitimate blocks: the shipped body carries the slug twice and
+// never as a sentinel (measured: 1304 bytes — 1296 UTF-16 units, the body has em dashes —
+// with zero `:begin` / `:end` occurrences), and the
+// separators stay `\r?\n` for the CRLF reason below.
 function blockBody(esc) {
-  return `<!-- ${esc}:begin (v\\d+) -->\\r?\\n([\\s\\S]*?)\\r?\\n<!-- ${esc}:end -->`;
+  const sentinel = `<!-- ${esc}:(?:begin|end)`;
+  return `<!-- ${esc}:begin (v\\d+) -->\\r?\\n((?:(?!${sentinel})[\\s\\S])*?)\\r?\\n<!-- ${esc}:end -->`;
+}
+
+// Any sentinel LINE of our slug, paired or not. The pair regex above is deliberately blind to
+// an unpaired one; this is what lets residue reporting see what it cannot safely remove.
+function sentinelLineRegexG(slug) {
+  return new RegExp(`<!-- ${escapeRe(slug)}:(?:begin|end)\\b[^>]*-->`, 'g');
+}
+
+/**
+ * Sentinel lines of this slug left in `raw` that no well-formed block accounts for.
+ * Zero on a healthy file (every sentinel belongs to a matched pair) and on a clean one.
+ * @param {string} raw
+ * @param {string} slug
+ * @returns {number}
+ */
+function orphanSentinelCount(raw, slug) {
+  const total = (raw.match(sentinelLineRegexG(slug)) || []).length;
+  let paired = 0;
+  raw.replace(blockRegexG(slug), (whole) => {
+    paired += (whole.match(sentinelLineRegexG(slug)) || []).length;
+    return whole;
+  });
+  return total - paired;
 }
 function blockRegex(slug) {
   return new RegExp(blockBody(escapeRe(slug)));
@@ -137,13 +179,24 @@ export function isAdopted(cwd, slug) {
  * removed it. removeManaged cleans all three pieces, so sweep on any of them.
  */
 export function hasResidue(cwd, slug) {
-  return (
-    readBlock(cwd, slug).body !== null ||
-    existsSync(detailDocPath(cwd, slug)) ||
-    existsSync(stateFilePath(cwd, slug))
-  );
+  const blk = readBlock(cwd, slug);
+  return blk.body !== null || existsSync(detailDocPath(cwd, slug)) || existsSync(stateFilePath(cwd, slug));
 }
 
+// An unpaired sentinel is deliberately NOT in the list above (pre-ship review P2-3). A first
+// cut added it, reasoning that the sweep should see what the pair regex cannot. But
+// orphanSentinelCount counts sentinel-shaped TEXT, and a project the plugin never touched can
+// mention the marker in prose — documenting it, pasting half an example, a changelog line.
+// That one mention let `unadopt --all` into a stranger's project, where removeManaged
+// unconditionally deletes the detail doc and state sidecar and rmdir's an empty `.claude/`,
+// then printed "remove those lines by hand" at the user's own paragraph — and never
+// converged, because the mention is still there on the next sweep.
+//
+// The three entries above are all things the PLUGIN WROTE; a sentinel in prose is not. And
+// the sweep gains nothing by entering: removeManaged cannot clean an orphan anyway, by
+// design. The orphan is reported by removeManaged when unadopt genuinely runs — which is the
+// real failure case, where the doc and sidecar are still present and do bring it in.
+
 /**
  * Whether the installed block/doc has drifted from the shipped content — i.e.
  * a version bump or a template edit means we should refresh. Returns true when
@@ -232,11 +285,25 @@ export function writeManaged(cwd, { slug, version, block, doc }) {
  * Remove our managed block from CLAUDE.md (preserving all other content) and
  * delete the detail doc + state sidecar. Best-effort removes an emptied
  * .claude/ directory.
- * @returns {{action: 'removed'|'absent'}}
+ *
+ * THREE outcomes, not two — the same rule lib/db-unusable.mjs states about backups: "there
+ * is nothing to do" and "I could not finish" must not print in the same voice, because a
+ * green-sounding line ends the reader's search. `absent` used to cover both: with one
+ * sentinel line missing, the pair regex matched nothing, so this returned 'absent' — while
+ * having already deleted the detail doc and the state sidecar and left ~1.3 KB of managed
+ * steering text in the user's CLAUDE.md, which it is then loaded from on every session.
+ * `partial` is that case, and `residue` names what is left so the caller can say so.
+ *
+ * Deliberately does NOT delete an orphaned sentinel's body: where it ends is unknowable
+ * (that is the defect, not a detail), and guessing a span in a file we do not own is how the
+ * adopt side came to delete a user's runbook. Report, do not repair.
+ *
+ * @returns {{action: 'removed'|'partial'|'absent', residue?: string}}
  */
 export function removeManaged(cwd, slug) {
   const p = claudeMdPath(cwd);
   let action = 'absent';
+  let orphans = 0;
   if (existsSync(p)) {
     let raw = readFileSync(p, 'utf8');
     // H2: loop so ALL same-slug blocks are removed, not just the first (a
@@ -283,8 +350,17 @@ export function removeManaged(cwd, slug) {
         atomicWrite(p, raw);
       }
     }
+    // Counted on what is left AFTER the loop, so a healthy file (every sentinel consumed by
+    // a matched pair) reports zero and only a genuinely unpaired line survives the count.
+    orphans = orphanSentinelCount(raw, slug);
   }
+  // Captured BEFORE the deletions below, because they are what it asks about: is there any
+  // evidence the plugin ever wrote in this project? An unpaired sentinel is NOT such
+  // evidence — it is text, and a project that merely documents the marker in prose has one
+  // (pre-ship review P2-3). Reporting residue there means telling a stranger to delete their
+  // own paragraph, on a project this tool has never touched.
   const dp = detailDocPath(cwd, slug);
+  const wasOurs = action === 'removed' || existsSync(dp) || existsSync(stateFilePath(cwd, slug));
   if (existsSync(dp))
     try {
       unlinkSync(dp);
@@ -300,6 +376,18 @@ export function removeManaged(cwd, slug) {
   } catch {
     /* best-effort */
   }
+  // `action` answers ONE question — what happened to the block — and `residue` is an
+  // independent fact that rides alongside it. A first cut let an orphan override 'removed'
+  // too, on the reasoning that both are "unfinished". Pre-ship review P2-1: unadoptAll's
+  // else-branch prints "cleaned partial residue (detail doc/state, no block)" and counts
+  // `partial++`, so a sweep that DID remove a block reported "no block" and tallied zero
+  // removals. Two facts, two fields.
+  const residue =
+    orphans > 0 && wasOurs
+      ? `${orphans} unpaired \`${slug}\` sentinel line(s) remain in ${claudeMdPath(cwd)} — the block they opened has no matching end marker, so its extent cannot be determined safely. Remove those lines and the text they wrap by hand.`
+      : null;
+  if (action === 'removed') return residue ? { action, residue } : { action };
+  if (residue) return { action: 'partial', residue };
   return { action };
 }
 

package/lib/db-unusable.mjs

@@ -67,6 +67,49 @@ export function isFtsCorruptionError(err) {
   return /SQLITE_CORRUPT_VTAB/i.test(`${err?.code || ''}`);
 }
 
+/**
+ * What to do about a damaged FTS5 INDEX — the query-time half of isFtsCorruptionError.
+ *
+ * R10 P3-9 wired the classifier into `ensureDbWithWalRecovery`, which rebuilds and retries.
+ * That covers OPEN time. A structure record damaged inside the index opens fine — nothing
+ * reads it until the first MATCH — so the fault surfaces at QUERY time, and there the two
+ * faces that carry it to a reader (the CLI catch-all, the MCP safeHandler) passed SQLite's
+ * own sentence through with no next step. `recent` / `recall` / `browse` / `context` never
+ * touch FTS and keep answering, which makes that dead end easy to misread as "search found
+ * nothing" rather than "search is broken".
+ *
+ * ONE STRING FOR BOTH CHANNELS, unlike the file-level family below. The split there exists
+ * because that remedy OVERWRITES the database and must not be handed ready-to-run to an
+ * agent holding Bash. This one re-derives every index from its own content table: the rows
+ * are never read from the index, so a rebuild is lossless and idempotent, and `doctor`
+ * already runs it unprompted. Naming "intact" is load-bearing — the reading this line
+ * exists to prevent is "my memories are corrupt".
+ *
+ * SCOPE, measured rather than assumed: a damaged index does not always reach the caller as
+ * SQLITE_CORRUPT_VTAB. `observations_fts_data` holds three rows on a one-observation store —
+ * id=1 (averages), id=10 (the STRUCTURE record) and one leaf page — and which row the damage
+ * lands on decides the code. Over 100 trials each:
+ *
+ *   UPDATE … SET block = randomblob(32) WHERE id > 1   (structure + leaf)  98 VTAB, 2 NOMEM
+ *   UPDATE … SET block = randomblob(32) WHERE id > 10  (leaf only)        100 VTAB, 0 NOMEM
+ *   DELETE … WHERE id > 10                             (leaf only)        100 VTAB, 0 NOMEM
+ *
+ * So NOMEM comes from a mangled STRUCTURE record, where SQLite reads a corrupt varint and asks
+ * for an absurd allocation — not from leaf damage. (A first draft of this paragraph said
+ * "leaf pages", which would send anyone re-measuring `WHERE id > 10` to 0/N and make the
+ * boundary below look vacuous. Caught by the pre-ship claims audit.) That case gets no
+ * remedy, on purpose:
+ * isFtsCorruptionError is what isDbCorruptionError and isDbUnusableError consult, so
+ * admitting SQLITE_NOMEM would answer a real out-of-memory with a full FTS rebuild, and
+ * would tell a user their index is damaged when it may be their RAM. The code cannot
+ * discriminate the two, so this covers the fault it can name.
+ * `tests/fts-corruption-query-time-remedy.test.mjs` pins that boundary.
+ */
+export const FTS_CORRUPTION_REMEDY =
+  'The FTS5 search index is damaged; the stored observations are intact. ' +
+  'Rebuild it losslessly with `claude-mem-lite fts-check rebuild` ' +
+  '(`claude-mem-lite doctor` rebuilds it too, and re-checks everything else).';
+
 /**
  * True when `err` means "this file exists and SQLite cannot use it as a database".
  *

package/mem-cli.mjs

@@ -5,6 +5,7 @@
 import { homedir } from 'os';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, CODE_DIR } from './schema.mjs';
 import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
+import { isFtsCorruptionError, FTS_CORRUPTION_REMEDY } from './lib/db-unusable.mjs';
 import { truncate, typeIcon, inferProject, scrubSecrets, COMPRESSED_PENDING_PURGE } from './utils.mjs';
 import { resolveProject } from './project-utils.mjs';
 // READ commands resolve the project DB-aware: a subdirectory whose own name holds no rows
@@ -3847,6 +3848,12 @@ export async function run(argv) {
     // agent runs the CLI, the model's context — got a raw Node stack trace. Print the
     // message, keep the stack behind CLAUDE_MEM_DEBUG for whoever is actually debugging.
     process.stderr.write(`[mem] ${cmd || 'command'} failed: ${(e && e.message) || e}\n`);
+    // A damaged FTS5 index reaches here as SQLITE_CORRUPT_VTAB from the first MATCH.
+    // `fts-check` and `doctor` touch the index too — and both already explain themselves —
+    // so `search` is the one command that DEAD-ENDS on SQLite's sentence, while `recent` /
+    // `recall` / `browse` / `context` / `stats` never read the index and keep working.
+    // The remedy is lossless (see FTS_CORRUPTION_REMEDY); the exit code stays 1.
+    if (isFtsCorruptionError(e)) process.stderr.write(`[mem] ${FTS_CORRUPTION_REMEDY}\n`);
     if (process.env.CLAUDE_MEM_DEBUG) process.stderr.write(`${(e && e.stack) || ''}\n`);
     process.exitCode = 1;
   } finally {

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.8.2",
+  "version": "6.8.3",
   "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/server.mjs

@@ -118,6 +118,7 @@ import { saveWithClosures, formatSupersedeSkipped, formatSupersededNote } from '
 import { applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL, buildExportWhere } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
+import { isFtsCorruptionError, FTS_CORRUPTION_REMEDY } from './lib/db-unusable.mjs';
 import { fetchRecent } from './lib/recent-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
@@ -374,7 +375,17 @@ function safeHandler(fn, { verbatim = false } = {}) {
       const result = await fn(args, extra);
       return verbatim ? result : defangResult(result, { skillBlocks: true });
     } catch (err) {
-      return defangResult({ content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true });
+      // A damaged FTS5 index arrives here as SQLITE_CORRUPT_VTAB from the first MATCH.
+      // Without this the model got SQLite's own sentence and nothing else, on a fault it
+      // could have had fixed in one command — and mem_recent / mem_recall / mem_browse
+      // keep answering, so the dead end reads as "nothing matched". Both channels carry the
+      // same string here, deliberately: unlike the file-level remedy this one is lossless
+      // (see FTS_CORRUPTION_REMEDY in lib/db-unusable.mjs).
+      const hint = isFtsCorruptionError(err) ? `\n${FTS_CORRUPTION_REMEDY}` : '';
+      return defangResult({
+        content: [{ type: 'text', text: `Error: ${err.message}${hint}` }],
+        isError: true,
+      });
     }
   };
 }