claude-mem-lite 6.9.0 → 6.9.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.9.0",
+      "version": "6.9.1",
       "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.9.0",
+  "version": "6.9.1",
   "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/cli.mjs

@@ -136,6 +136,46 @@ const INSTALL_COMMANDS = new Set([
   'release',
 ]);
 
+// A reader that leaves is not an error. `claude-mem-lite search x | head -1`,
+// `| grep -q`, or quitting `less` closes the read end while we are still writing;
+// Node then emits 'error' on the stdout Socket, and with no listener that is an
+// UNHANDLED error event — a ~20-line stack ending in `outVerbatim` where the user
+// expected the shell prompt.
+//
+// WHICH COMMANDS, measured rather than generalised (20 trials each, `| head -1`,
+// pre-fix): `search`, `export`, `recent`, `stats`, `doctor`, `timeline`,
+// `citation-stats` 20/20; `browse` 19/20; `help`, `status`, `context`, `get`,
+// `memdir-audit` 0/20. So NOT "every stdout-bearing command" — what decides it is
+// whether a write is still pending when the reader goes, which depends on how many
+// lines the consumer takes and how the output is batched — NOT on the 64 KB pipe
+// buffer, which an earlier draft of this comment blamed: pre-ship review found
+// `stats` crashing at `head -20` on an output far under it. That output's size is
+// corpus dependent, so no byte count is quoted here. This is also why the crash
+// survived so long — it is invisible to exactly the pipe depths a smoke test picks.
+//
+// Lives HERE, at the published `bin`, and not at `cli/common.mjs`'s `out()`: the
+// crash reproduces on `doctor` too, whose writes are `console.log` inside
+// install.mjs, so a chokepoint fix would cover the CLI half and leave the installer
+// half loud. One process-level listener covers both routes below.
+//
+// SWALLOW, DO NOT EXIT. The first cut called `process.exit(0)` here, on the
+// reasoning that a CLI whose consumer has gone should stop rather than serialise a
+// whole-DB `export` into a dead pipe. Pre-ship review measured what that costs:
+// `doctor | head -1` under `pipefail` exited 0 on 10/10 runs while the same doctor
+// exits 1 unpiped, because `runDoctor` assigns `process.exitCode = 1` AFTER its last
+// print (install.mjs, "Diagnostic-tool exit-code contract") and the forced exit lands
+// first. That silently turns a failing `claude-mem-lite doctor || alert` — the
+// wrapper that contract names — into a passing one. `process.exitCode ?? 0` does not
+// rescue it: the verdict does not exist yet at kill time. Returning instead reads
+// exit 1 on 10/10 and keeps the crash fixed (doctor 0/10, search 0/10 EPIPE stacks).
+// Correctness over the saved work: the process finishes into a pipe nobody reads,
+// which is wasted effort but never a wrong answer. Non-EPIPE is rethrown — this is a
+// classifier, not a blanket swallow, the same charter `explainBrokenInstall` follows.
+process.stdout.on('error', (err) => {
+  if (err && err.code === 'EPIPE') return;
+  throw err;
+});
+
 const cmd = process.argv[2];
 
 // `version` and `-V` are aliases, not extra syntax: the bare subcommand is what a user

package/install.mjs

@@ -44,6 +44,15 @@ const MEM_RUNTIME_DIR = resolveRuntimeDir(MEM_DATA_DIR);
 const DB_PATH = join(MEM_DATA_DIR, 'claude-mem-lite.db');
 const OLD_DATA_DIR = join(homedir(), '.claude-mem');
 
+// The two directories `createCliSymlink` can land the `claude-mem-lite` command in, in the
+// order it tries them. Uninstall already swept exactly this pair as an inline literal, and
+// `status` now has to ask the same question ("is the command installed somewhere, just not
+// on PATH?"), so the list is named once rather than typed a third time. `createCliSymlink`
+// itself is deliberately NOT rewritten to iterate it: its shape is primary-then-fallback
+// with different remedies per branch, and flattening that into a loop is a refactor wearing
+// a constant's clothes.
+const CLI_BIN_DIRS = [join(homedir(), '.local', 'bin'), '/usr/local/bin'];
+
 // Detect ephemeral context (npx) — files won't persist after exit
 const IS_NPX =
   process.env.npm_command === 'exec' || PROJECT_DIR.includes('_npx') || PROJECT_DIR.includes('.npm/_');
@@ -1271,7 +1280,7 @@ async function uninstall() {
   if (!removedAny) warn('MCP server not found or already removed');
 
   // 1b. Remove CLI symlink
-  for (const binDir of [join(homedir(), '.local', 'bin'), '/usr/local/bin']) {
+  for (const binDir of CLI_BIN_DIRS) {
     const cliLink = join(binDir, 'claude-mem-lite');
     // No try/catch: clearLinkPath swallows a permissions failure and returns false, so the
     // wrapper this used to have was unreachable once the existsSync gate moved inside it.
@@ -1654,14 +1663,70 @@ async function status() {
     push('warn', 'database', 'Database: not found', { exists: false });
   }
 
-  // CLI
+  // CLI.
+  //
+  // The probe resolves a BARE name, so a failure conflates three different worlds and the
+  // old single remedy ("run install again to create symlink") was correct in only one of
+  // them. On the common one — `createCliSymlink` put a working link in ~/.local/bin, a
+  // directory a non-login shell frequently does not have on PATH — the advice sends the
+  // user to re-run an installer that will create the very symlink that already exists,
+  // report ✓, and leave `status` saying the same thing. Advice that cannot converge is
+  // worse than the silence it replaced.
+  //
+  // Split on `err.code`: ENOENT is "the name did not resolve" and is the only world the
+  // symlink question applies to. Anything else means the command WAS found and then failed
+  // or timed out (a broken native binding is the live example), where naming PATH is a
+  // second wrong answer — report what actually happened instead.
+  // `linked` is a NEW field on this check, and `--json` republishes every extra key
+  // (`const { level, key, message, ...extra }` below), so it is part of that face's output,
+  // not an internal detail. Nothing in this repo reads it; external consumers of
+  // `status --json` now see `linked: <path>|null`.
   try {
     execFileSync('claude-mem-lite', ['--help'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
     push('ok', 'cli', 'CLI: claude-mem-lite command available', { available: true });
-  } catch {
-    push('warn', 'cli', 'CLI: command not on PATH — run install again to create symlink', {
-      available: false,
-    });
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') {
+      // `e.message` already CARRIES the child's stderr — with stdio:'pipe' Node formats it
+      // as "Command failed: <cmd>\n<stderr>", so the live example (a broken native binding,
+      // whose `nativeBindingRepairHint` line is on stderr) reaches the user unaided.
+      // Measured, because pre-ship review asserted the opposite and a redundant `e.stderr`
+      // suffix was written and then withdrawn: printing both duplicates the text.
+      // Note `e.code` is UNDEFINED for a non-zero exit — only a spawn failure sets ENOENT —
+      // so `!== 'ENOENT'` is what routes this branch, not a truthiness check on the code.
+      push('warn', 'cli', `CLI: on PATH but "claude-mem-lite --help" failed — ${e.message}`, {
+        available: false,
+        linked: null,
+      });
+    } else {
+      // Two properties of `existsSync` matter here and they pull in opposite directions:
+      //   - it FOLLOWS the link, so a DANGLING one reads as absent. That is the answer we
+      //     want: a link pointing at a deleted install is the installer's problem, not
+      //     PATH's, and falls through to the reinstall remedy.
+      //   - it is also true for a DIRECTORY of that name, which would make us print
+      //     "installed at … add it to PATH" about something that can never be executed —
+      //     the exact non-converging advice this block exists to stop. Hence isFile().
+      const isLinkedCli = (d) => {
+        try {
+          return statSync(join(d, 'claude-mem-lite')).isFile();
+        } catch {
+          return false; // ENOENT (absent or dangling), EACCES on the dir, anything else
+        }
+      };
+      const binDir = CLI_BIN_DIRS.find(isLinkedCli);
+      if (binDir) {
+        push(
+          'warn',
+          'cli',
+          `CLI: installed at ${join(binDir, 'claude-mem-lite')} but ${binDir} is not on PATH — add it: export PATH="${binDir}:$PATH"`,
+          { available: false, linked: join(binDir, 'claude-mem-lite') },
+        );
+      } else {
+        push('warn', 'cli', 'CLI: command not on PATH — run install again to create symlink', {
+          available: false,
+          linked: null,
+        });
+      }
+    }
   }
 
   // Old system

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.9.0",
+  "version": "6.9.1",
   "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/search-scoring.mjs

@@ -12,6 +12,18 @@ import { CLI_INVOKE } from './cli-path.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
+// The pinned-but-uncited threshold, from the module that OWNS the rule (`demotePinned` and
+// its forecast both read it there). Imported rather than restated: a second hand-typed copy
+// of this number is exactly what produced the `inj>=8` report-string drift in server.mjs.
+// (The v3.76.0 scan-vs-execute drift was a different constant — two copies of the FLOOR,
+// `importance > 1`; do not cite it for this one.) The edge is cheap: `lib/maintain-core.mjs`
+// has five direct imports — `utils.mjs`, `lib/dedup-constants.mjs`,
+// `lib/inject-search-core.mjs`, `lib/time-constants.mjs` and `lib/db-backup.mjs` — three of
+// which this module already imports directly, and the 16-file closure resolves to nothing
+// but node builtins (`fs`, `path`, `child_process`, `node:os`, `node:path`) — no
+// third-party package, so no native dependency, and no edge back to this file (the three
+// "search-scoring" strings in that graph are all comments).
+import { PINNED_INJ_THRESHOLD } from './lib/maintain-core.mjs';
 // ─── MCP Server Instructions Builder ───────────────────────────────────────
 // Phase A (v2.31.3+): when quiet=true, drops WHEN-TO-USE proactive-trigger and
 // Decision-rules sections; keeps the irreducible CLI/MCP tool list. Intended
@@ -303,6 +315,57 @@ export function expandQueryByConcepts(db, ftsQuery, project) {
  * Boost importance to 2 for observations that have been accessed multiple times
  * (access_count >= 2) but still have default importance (1).
  * Called after incrementing access_count in mem_get.
+ *
+ * A PROMOTER OUTSIDE THE MAINTENANCE RUN. `lib/maintain-core.mjs`'s DEFAULT_MAINTAIN_OPS
+ * docblock records `boostAccessed` and `demotePinned` as opponents, and names TWO separate
+ * defects it closed — keep them apart: the automatic path promoted and never demoted
+ * because `demote_pinned` was in nobody's default set and hook.mjs did not import it, while
+ * the two faces that DID wire the op ran it in opposite orders. The 148/148 figure quoted
+ * there is rows sitting back at importance>=3 that were BOOST-ELIGIBLE, not rows this op
+ * would have moved — CHANGELOG.md narrows the reachable-by-demotePinned count to 7.
+ *
+ * Both of those fixes act INSIDE a maintenance run. This function fires from
+ * `fetchObsDetail`, so it is a promoter neither a default-set nor an ordering fix can reach:
+ * every `get` / `mem_get` was another chance to hand the row straight back — the same
+ * sentence that docblock uses for the bug it closed.
+ *
+ * Reproduced end-to-end before this clause: `maintain execute --ops demote_pinned` floors a
+ * pinned-but-uncited row 2 -> 1, and ONE subsequent `get` returned it to 2. So an op in the
+ * default maintain set (`lib/maintain-core.mjs` DEFAULT_MAINTAIN_OPS) had an effect any read
+ * reverted, on its own target population.
+ *
+ * Population, stated rather than implied (doctrine rule 3): on the maintainer's DB sampled
+ * 2026-09-14T20:14:16Z, 67 live rows, 3 pinned-but-uncited, and 0 of those had reached
+ * access_count >= 2 — `injection_count` does not bump `access_count`, so the overlap needs
+ * two explicit reads and was unrealised there. The mechanism is deterministic; the observed
+ * incidence on that corpus is zero, and this is a snapshot of one corpus, not a property.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT FIX. `importance = 1` is also what an explicit
+ * `claude-mem-lite update N --importance 1` writes, and that demotion is reverted by the
+ * next read exactly the same way — worse, INSPECTING the row is what pushes access_count to
+ * 2 in the first place. Separating "1 because nobody set it" from "1 because a human said
+ * so" needs a marker this schema does not have, and `demoted_at` is not it — for a reason
+ * the first draft of this paragraph got wrong, so it is stated precisely: nothing keys on
+ * `demoted_at IS NULL` (the sole non-test reader, `mem-cli.mjs`'s decay-queue report, keys
+ * on IS NOT NULL), so a write here would not evict anything — it would ADD the row to that
+ * report, and `applyCitationDecay` CLEARS the column on the row's first citation, silently
+ * discarding a human's demotion. Wrong owner, wrong lifetime. Left as a design decision
+ * rather than patched around.
+ *
+ * THE EXCLUSION IS demotePinned's FLOOR, NOT ITS TRIGGER. `PINNED_FLOOR_SQL` in
+ * lib/maintain-core.mjs is `CASE WHEN <no lesson> THEN 1 ELSE 2 END`, so a LESSON-BEARING
+ * pinned row is floored at 2 and boosting it 1 -> 2 lands it exactly on that floor. The
+ * first cut of this clause copied the trigger (`inj >= N AND cited = 0`) without the floor
+ * and stranded those rows at 1, below the bound maintain-core declares for them — and 16 of
+ * the 17 rows that op would have moved on the maintainer's DB were lesson-bearing. The
+ * predicate below must keep selecting exactly the rows demotePinned would floor to 1.
+ *
+ * The no-lesson clause is COPIED rather than imported: `NO_LESSON_SQL` and `PINNED_FLOOR_SQL`
+ * are module-private in maintain-core by an explicit decision recorded there ("exporting by
+ * habit is how the knip baseline drifts"), and five verbatim copies already live in that
+ * file. The prose stays out here in the docblock rather than inside the SQL string, because
+ * a backtick in a template literal ends it — that cost one parse error on this very edit.
+ *
  * @param {object} db better-sqlite3 database handle
  * @param {number[]} ids Array of observation IDs to check
  */
@@ -315,6 +378,12 @@ export function autoBoostIfNeeded(db, ids) {
     WHERE id IN (${placeholders})
       AND COALESCE(importance, 1) = 1
       AND COALESCE(access_count, 0) >= 2
+      -- Exactly the rows demotePinned would floor to 1 (see the docblock above).
+      AND NOT (
+        COALESCE(injection_count, 0) >= ${PINNED_INJ_THRESHOLD}
+        AND COALESCE(cited_count, 0) = 0
+        AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
+      )
   `,
   ).run(...ids);
 }