claude-mem-lite 3.67.0 → 3.68.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.67.0",
+      "version": "3.68.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": "3.67.0",
+  "version": "3.68.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/haiku-client.mjs

@@ -286,6 +286,29 @@ export async function callHaikuJSON(prompt, opts) {
   return parseJsonFromLLM(result.text);
 }
 
+/**
+ * Non-blocking sibling of callHaikuJSON for callers reachable from an MCP request
+ * handler (registry enrichment: mem_registry `enrich` / `import_url`). Same
+ * provider priority; the CLI leg — primary AND post-provider-failure fallback —
+ * is the async spawn, so a keyed-provider outage cannot freeze the server event
+ * loop for BG_LLM_TIMEOUT_MS (D#138 MEDIUM-3).
+ *
+ * `resolveModel().cli`, NOT the literal 'haiku': despite the name, callHaikuJSON
+ * reaches the model through resolveModel() on ALL three legs (callHaikuAPI,
+ * callOpenRouterAPI, callHaikuCLI), so it honours the documented CLAUDE_MEM_MODEL
+ * knob. Pinning 'haiku' here would silently downgrade registry enrichment for
+ * every user who set CLAUDE_MEM_MODEL=sonnet — pre-tag review finding, v3.68.0.
+ *
+ * Defaults also mirror callHaiku (10s / 500 tokens), not callModelJSONAsync's
+ * 15s / 1000: a caller that omits opts must get the sync twin's budget.
+ * @param {string|{system?:string,user:string}} prompt
+ * @param {{timeout?:number,maxTokens?:number,temperature?:number}} [opts]
+ * @returns {Promise<object|null>} Parsed JSON or null
+ */
+export async function callHaikuJSONAsync(prompt, { timeout = 10000, maxTokens = 500, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
+  return callModelJSONAsync(prompt, resolveModel().cli, { timeout, maxTokens, temperature });
+}
+
 // ─── Model-Selectable API ────────────────────────────────────────────────────
 
 /**
@@ -328,6 +351,44 @@ export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 1500
   catch (e) { debugCatch(e, `callLLMWithModel:cli-fallback:${resolvedModel}`); return null; }
 }
 
+/**
+ * Non-blocking sibling of callLLMWithModel — returns the RAW {text} envelope
+ * without JSON-parsing it. For MCP-reachable callers whose answer is not
+ * guaranteed to be an object: rerank accepts a bare `[2,1,3]` array, which a
+ * JSON-parsing dispatcher would keep but whose contract (rerank.mjs:72) is the
+ * envelope, not the parse. Both CLI legs use the async spawn, so a keyed-provider
+ * outage cannot freeze the server event loop (D#138 MEDIUM-3).
+ *
+ * Behaviourally identical to callLLMWithModel otherwise — same `if (primary)`
+ * test, same headless-flag compat retry and budget arithmetic, same timeout
+ * salvage. Only the CLI transport differs.
+ * @param {string|{system?:string,user:string}} prompt
+ * @param {'haiku'|'sonnet'} model
+ * @param {{timeout?:number,maxTokens?:number,temperature?:number}} [opts]
+ * @returns {Promise<{text: string}|null>} Response or null on failure
+ */
+export async function callLLMWithModelAsync(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
+  if (!prompt) return null;
+  const resolvedModel = MODEL_MAP[model] ? model : 'haiku';
+  const mode = detectMode();
+
+  // CLI is terminal — no provider to fall back to.
+  if (mode === 'cli') return callModelCLIAsync(prompt, resolvedModel, { timeout });
+
+  let primary = null;
+  try {
+    primary = mode === 'api'
+      ? await callModelAPI(prompt, resolvedModel, { timeout, maxTokens, temperature })
+      : await callOpenRouterAPI(prompt, resolvedModel, { timeout, maxTokens, temperature });
+  } catch (e) {
+    debugCatch(e, `callLLMWithModelAsync:${mode}:${resolvedModel}`);
+  }
+  if (primary) return primary;
+
+  debugLog('WARN', 'haiku-client', `${mode} call failed, falling back to async claude CLI (${resolvedModel})`);
+  return callModelCLIAsync(prompt, resolvedModel, { timeout });
+}
+
 /**
  * Call LLM with model selection and parse JSON response.
  * @param {string} prompt
@@ -628,6 +689,20 @@ export async function callModelCLIAsync(prompt, model, { timeout }) {
     child.on('error', (e) => { debugCatch(e, `${model}-cli-async`); done({ result: null, stderr: '', stdout: '', code: null }); });
     child.on('close', (code) => {
       const t = stdout.trim();
+      // Parity with callModelCLI: execFileSync THROWS on a non-zero exit, so the
+      // sync leg only ever returns such output when parseJsonFromLLM accepts it
+      // (its catch-salvage). Without the same gate, a CLI that prints a
+      // diagnostic to stdout and dies — auth failure, overload banner, wrapper
+      // error — has that diagnostic returned as the model's ANSWER. rerank is the
+      // first caller to consume the raw {text}: extractRanked's last resort
+      // matches any bracketed number list in prose, so a `[1]` inside a stack
+      // frame becomes a ranking and silently reorders search results. The
+      // flag-compat probe below reads stderr/stdout/code directly, not `result`,
+      // so nulling here does not cost it its retry.
+      if (t && typeof code === 'number' && code !== 0 && parseJsonFromLLM(t) === null) {
+        done({ result: null, stderr, stdout, code });
+        return;
+      }
       done({ result: t ? { text: t } : null, stderr, stdout, code });
     });
     // EPIPE guard: the child may exit before we finish writing stdin.

package/hook-optimize.mjs

@@ -13,7 +13,7 @@ import {
   computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity, clampImportance, cjkBigrams,
   notLowSignalTitleClause, scrubSecrets,
 } from './utils.mjs';
-import { callModelJSON, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
+import { callModelJSONAsync, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, cosineSimilarity, vecTextForRow } from './tfidf.mjs';
@@ -175,7 +175,7 @@ Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
 
 JSON: {"search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if the domain word has one"]}
 Give 3-6 aliases: words a user might search for the SAME concept but that are NOT already in the title (synonyms, the spelled-out form of an acronym, the jargon term for a described symptom, a CJK translation of a key domain term).`;
-        const parsed = await callModelJSON(aliasPrompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 300 });
+        const parsed = await callModelJSONAsync(aliasPrompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 300 });
         const aliasArr = parsed && Array.isArray(parsed.search_aliases)
           ? parsed.search_aliases.filter((a) => typeof a === 'string' && a.trim().length > 0)
           : [];
@@ -204,7 +204,7 @@ importance: 0=no value, 1=routine, 2=notable non-obvious insight, 3=critical. De
 lesson_learned: State what was learned. If routine, write "none".
 search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
 
-      const parsed = await callModelJSON(prompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 500 });
+      const parsed = await callModelJSONAsync(prompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 500 });
       if (!parsed || !parsed.title) { skipped++; continue; }
 
       // Auto-hide on importance:0 targets fully-degraded NARROW rows (this branch predates
@@ -356,7 +356,7 @@ Rules:
 - Include CJK ↔ English equivalents if present
 - Skip terms that have no synonyms in the list`;
 
-    const parsed = await callModelJSON(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
+    const parsed = await callModelJSONAsync(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
     if (!parsed?.groups || !Array.isArray(parsed.groups)) return [];
     return parsed.groups.filter(g => g.canonical && Array.isArray(g.aliases) && g.aliases.length > 0);
   } catch (e) {
@@ -524,7 +524,7 @@ Return ONLY valid JSON:
 - If they should NOT be merged: {"should_merge":false}
 - If they SHOULD be merged: {"should_merge":true,"merged_title":"≤120 char comprehensive title","merged_narrative":"comprehensive ≤800 char summary preserving all key details","merged_concepts":["kw1","kw2"],"merged_facts":["specific fact 1"],"merged_lesson":"synthesized non-obvious lesson or null","importance":2}`;
 
-    const parsed = await callModelJSON(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
+    const parsed = await callModelJSONAsync(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
     if (!parsed || !parsed.should_merge) return { merged: false };
 
     // Keeper = highest importance, then highest access_count. Previously access_count
@@ -758,7 +758,7 @@ ${obsDescriptions}
 
 JSON: {"title":"descriptive summary ≤120 chars","narrative":"comprehensive summary ≤800 chars preserving key decisions and lessons","concepts":["kw1","kw2"],"facts":["all specific facts preserved"],"lesson_learned":"most important synthesized lesson or 'none'","search_aliases":["alt search 1","alt search 2"]}`;
 
-    const parsed = await callModelJSON(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
+    const parsed = await callModelJSONAsync(prompt, 'sonnet', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 1000 });
     if (!parsed || !parsed.title) return { compressed: false };
 
     // Scrub BEFORE truncate (see re-enrich note): boundary cut on scrubbed text.

package/hook-semaphore.mjs

@@ -34,9 +34,32 @@ export const LLM_SEM_STALE_MS = BG_LLM_TIMEOUT_MS * 2 + 30000; // 120s
 
 export const sleepMs = (ms) => new Promise(r => setTimeout(r, ms));
 
+// Does THIS process currently hold the (single, pid-named) slot?
+//
+// The slot file is one per process, and until the MCP LLM legs went async in
+// v3.68.0 two acquires could not overlap inside one: execFileSync held the event
+// loop, so a second tools/call was not even read from stdio while the first was
+// in its LLM call. The EEXIST branch below encodes that era's assumption — "we
+// are inside acquire and therefore do NOT hold a slot, so it is always stale" —
+// and unlinks unconditionally. With two concurrent mem_optimize handlers that
+// unlink would delete a LIVE sibling's slot: the cross-process count stops
+// seeing it (so more than LLM_SEM_MAX `claude -p` children run at once), and the
+// first holder's release then unlinks the second holder's file. This bookkeeping
+// makes the EEXIST branch's claim true again by keeping same-process acquires out
+// of it — they wait for the holder instead.
+//
+// A TIMESTAMP, not a boolean, and the difference is load-bearing: a boolean has no
+// self-heal, so one caller that acquired and never released would deadlock every
+// later LLM call in a long-lived MCP server for the life of the process — strictly
+// worse than the race it fixes. Past LLM_SEM_STALE_MS the local record is treated
+// as broken bookkeeping and we fall through to the file-side logic, which is the
+// same age escape hatch the reaper applies to other processes' slots. 0 = not held.
+let localHeldAt = 0;
+
 /**
  * Acquire a file-based semaphore slot for LLM calls.
  * Uses acquire-then-verify: atomically creates a slot file, then checks total count.
+ * At most one slot per process; a concurrent same-process caller queues behind it.
  * @returns {Promise<boolean>} true if slot acquired, false on timeout
  */
 export async function acquireLLMSlot() {
@@ -44,6 +67,12 @@ export async function acquireLLMSlot() {
   const slotFile = join(RUNTIME_DIR, `llm-sem-${process.pid}`);
 
   while (Date.now() < deadline) {
+    // A sibling call in this process holds the slot — queue, do not race. The
+    // file cannot be re-created without destroying the holder's.
+    if (localHeldAt && Date.now() - localHeldAt < LLM_SEM_STALE_MS) {
+      await sleepMs(200 + Math.random() * 800);
+      continue;
+    }
     // Acquire-then-verify: atomically create our slot first, then check total count
     let created;
     try {
@@ -59,8 +88,9 @@ export async function acquireLLMSlot() {
     } catch {
       // Our own pid-named slot file already exists: a leftover from a prior acquire
       // that never released (crash between acquire and releaseLLMSlot, or PID reuse).
-      // We are inside acquire and therefore do NOT currently hold a slot, so it is
-      // always stale — remove it and retry. The await is essential: a bare `continue`
+      // `localHeldAt` was checked above, so this process either holds nothing right
+      // now or its record is past the stale threshold — either way the file is not
+      // a live sibling's. Remove it and retry. The await is essential: a bare `continue`
       // here re-hits the same EEXIST every iteration, a synchronous tight loop that
       // pins a core until the 30s deadline (the age-based cleanup below is unreachable
       // on this path — it only runs after a successful create).
@@ -106,7 +136,7 @@ export async function acquireLLMSlot() {
       }
     } catch {}
 
-    if (active <= LLM_SEM_MAX) return true; // Slot acquired
+    if (active <= LLM_SEM_MAX) { localHeldAt = Date.now(); return true; } // Slot acquired
 
     // Too many concurrent — release our slot and back off
     try { unlinkSync(slotFile); } catch {}
@@ -119,5 +149,6 @@ export async function acquireLLMSlot() {
  * Release the file-based semaphore slot for the current process.
  */
 export function releaseLLMSlot() {
+  localHeldAt = 0;
   try { unlinkSync(join(RUNTIME_DIR, `llm-sem-${process.pid}`)); } catch {}
 }

package/hook.mjs

@@ -1749,12 +1749,20 @@ async function handleUserPrompt() {
         }
       } catch { /* file may not exist — that's fine */ }
 
-      // Phase-2 task-imperative (default OFF — CLAUDE_MEM_TASK_IMPERATIVE): the single
-      // highest-value lesson relevant to THIS prompt, delivered at the prompt position under
-      // an imperative template. Excluded from the <memory-context> list so it is never
-      // injected twice. Channel-isolation measure (efficacy arm U, 2026-06-29): task-prompt
-      // 6-8/8 vs PreToolUse hook 0/8. Flipping the default ON is a separate L3 decision
-      // gated on the live cite-recall canary.
+      // Phase-2 task-imperative (EXPERIMENTAL, default OFF — CLAUDE_MEM_TASK_IMPERATIVE):
+      // the single highest-value lesson relevant to THIS prompt, delivered at the prompt
+      // position under an imperative template. Excluded from the <memory-context> list so it
+      // is never injected twice. Channel-isolation measure (efficacy arm U, 2026-06-29):
+      // task-prompt 6-8/8 vs PreToolUse hook 0/8.
+      //
+      // The default flip is ABANDONED (D#137, 2026-08-16). rankImperativeCandidates requires
+      // identifier overlap between the prompt and the lesson body/title, and over the last 400
+      // real prompts that gate opened 76 times = 19.0% (CJK prompts 57/352 = 16.2%, ASCII
+      // 19/48 = 39.6%). With 88% of prompts on this install in Chinese, the emitter fires
+      // roughly once every six prompts — the canary can never accumulate n, because the
+      // ceiling is the gate's DESIGN (precision-first symbol anchoring), not a defect.
+      // Reviving the flip needs a CJK-viable anchor proven in A/B without a precision loss;
+      // until then this stays experimental and off.
       const taskImperativeOn = process.env.CLAUDE_MEM_TASK_IMPERATIVE === 'on'
         || process.env.CLAUDE_MEM_TASK_IMPERATIVE === '1';
       // Exclude only ids path-A (user-prompt-search.js) already injected — NOT the

package/lib/citation-tracker.mjs

@@ -1016,13 +1016,20 @@ export function recordCitationSurfaces(db, project, sessionId, surfaceSets, cite
  * the window, highest injection volume first (the face spending the most budget
  * is the one worth aiming a lever at).
  *
+ * `unavailable` is set — and ONLY set — when the read could not run (no handle,
+ * missing table, unreadable DB). An empty window leaves it undefined. Without
+ * this split both render as `surfaces: []`, which is exactly how a table that was
+ * never created reads as "no data yet" for as long as the surface stays unmetered
+ * (#10650): the reader swallows `no such table` into the debug log, and the only
+ * caller-visible signal is a shape identical to the benign case.
+ *
  * @param {import('better-sqlite3').Database} db
  * @param {{days?: number, project?: string|null}} [opts]
- * @returns {{window_days: number, surfaces: Array<{surface: string, injected: number, cited: number, rate: number, sessions: number}>}}
+ * @returns {{window_days: number, surfaces: Array<{surface: string, injected: number, cited: number, rate: number, sessions: number}>, unavailable?: string}}
  */
 export function computeSurfaceFunnel(db, { days = 7, project = null } = {}) {
   const empty = { window_days: days, surfaces: [] };
-  if (!db) return empty;
+  if (!db) return { ...empty, unavailable: 'no database handle' };
   try {
     const windowStart = Date.now() - days * DAY_MS;
     const params = project ? [windowStart, project] : [windowStart];
@@ -1043,7 +1050,10 @@ export function computeSurfaceFunnel(db, { days = 7, project = null } = {}) {
       window_days: days,
       surfaces: rows.map(r => ({ ...r, rate: r.injected > 0 ? r.cited / r.injected : 0 })),
     };
-  } catch (e) { debugCatch(e, 'computeSurfaceFunnel'); return empty; }
+  } catch (e) {
+    debugCatch(e, 'computeSurfaceFunnel');
+    return { ...empty, unavailable: e?.message || 'query failed' };
+  }
 }
 
 /**

package/mem-cli.mjs

@@ -2595,12 +2595,15 @@ function cmdCitationStats(db, args) {
   // whether effectiveness is rising; this says WHICH face to aim a lever at.
   out(`Cite rate by injection face (last ${days}d):`);
   out('  a per-face VIEW, not a partition — do NOT reconcile against the funnel above: faces overlap (an obs carried by two counts in both) and the funnel also counts cite-back signals that belong to no face:');
-  if (surfaceFunnel.surfaces.length === 0) {
-    // Deliberately does NOT claim "no data yet": the reader swallows a query
-    // error, so an absent or unreadable citation_surface_log renders exactly
-    // like an empty one. Say what is true (nothing came back) and name the
-    // check, rather than assert the benign cause (pre-tag review b4).
-    out('  (nothing returned for this window — rows accrue at Stop; if this stays empty after a few sessions, check the table exists: claude-mem-lite fts-check)');
+  if (surfaceFunnel.unavailable) {
+    // The read FAILED — a missing/unreadable citation_surface_log. Pre-b4 this
+    // rendered identically to an empty window, so the #10650 shape (table never
+    // created, `no such table` swallowed into the debug log) read as "no data
+    // yet" for as long as the surface stayed unmetered.
+    out(`  (UNAVAILABLE — the per-face table could not be read: ${surfaceFunnel.unavailable})`);
+    out('  this is a failure, not an empty window: run `claude-mem-lite fts-check` to repair the schema');
+  } else if (surfaceFunnel.surfaces.length === 0) {
+    out('  (no rows in this window yet — rows accrue at Stop, one per injection face per session)');
   } else {
     for (const s of surfaceFunnel.surfaces) {
       const pct = (s.rate * 100).toFixed(1) + '%';

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.67.0",
+  "version": "3.68.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.67.0",
+      "version": "3.68.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.67.0",
+  "version": "3.68.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/registry-enricher.mjs

@@ -2,7 +2,10 @@
 // Sends resource content to Haiku for semantic metadata generation
 // Graceful degradation: failure preserves existing data
 
-import { callHaikuJSON, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
+// Async dispatcher: enrichResource is reached from the MCP handlers for
+// mem_registry `enrich` and `import_url`, where a blocking CLI leg would freeze
+// the server event loop for the whole BG_LLM_TIMEOUT_MS budget (D#138 MEDIUM-3).
+import { callHaikuJSONAsync, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 import { truncate, debugCatch } from './utils.mjs';
 
 /**
@@ -84,7 +87,7 @@ export async function enrichResource(db, name, type, content) {
 
   try {
     const prompt = buildEnrichPrompt(name, content, existing);
-    const result = await callHaikuJSON(prompt, { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 500 });
+    const result = await callHaikuJSONAsync(prompt, { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 500 });
 
     if (!result || !result.capability_summary) {
       db.prepare("UPDATE resources SET enrichment_status = 'failed' WHERE name = ? AND type = ?").run(name, type);

package/rerank.mjs

@@ -69,10 +69,13 @@ export async function llmRerankOrder(query, cand /* [{sid,text}] */, llm) {
 }
 
 // Default provider — lazy import so stub-injected callers never load the client.
-// Uses callLLMWithModel (returns {text}) rather than callModelJSONAsync (which
+// Uses the {text}-envelope dispatcher rather than callModelJSONAsync (which
 // JSON-parses internally and nulls on any non-{...} output) so extractRanked can
-// recover bare-array answers the strict JSON parse drops.
+// recover bare-array answers the strict JSON parse drops. The Async variant is
+// load-bearing: rerank runs inside the mem_search MCP handler (deep + rerank), so
+// the blocking callLLMWithModel froze the server event loop whenever a keyed
+// provider was down and the call degraded to the CLI (D#138 MEDIUM-3).
 export async function defaultRerankLLM(prompt) {
-  const { callLLMWithModel } = await import('./haiku-client.mjs');
-  return callLLMWithModel(prompt, 'haiku', { timeout: 20000, maxTokens: 300 });
+  const { callLLMWithModelAsync } = await import('./haiku-client.mjs');
+  return callLLMWithModelAsync(prompt, 'haiku', { timeout: 20000, maxTokens: 300 });
 }