claude-mem-lite 3.48.0 → 3.50.0

package/server.mjs

@@ -12,7 +12,6 @@ import { reRankWithContext, autoBoostIfNeeded, runIdleCleanup, buildServerInstru
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
@@ -26,6 +25,8 @@ import { snapshotDb } from './lib/db-backup.mjs';
 import { deleteObservations } from './lib/delete-core.mjs';
 import { effectiveQuiet, RUNTIME_DIR } from './hook-shared.mjs';
 import { TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
+import { computeStatsFeed } from './lib/stats-core.mjs';
+import { buildLessonNudge } from './lib/save-nudge.mjs';
 import { formatObsFieldValue } from './cli/common.mjs';
 import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema, memDeferSchema, memDeferListSchema, memDeferDropSchema, tools as TOOL_DEFS } from './tool-schemas.mjs';
 
@@ -42,16 +43,17 @@ import { join, sep } from 'path';
 import { homedir } from 'os';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
-import { probeOtherSources as probeIdSources, bucketIdTokens } from './lib/id-routing.mjs';
+import { probeOtherSources as probeIdSources, bucketIdTokens, splitDeferredTokens } from './lib/id-routing.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
 import { rebuildObservationDerived } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
-import { computeNoiseGauge } from './lib/stats-quality.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
   resolveDeferredIds, closeDeferredItems,
+  getDeferredByIds, formatDeferredDetail,
+  searchDeferredWork, formatDeferredSearchTrailer,
 } from './lib/deferred-work.mjs';
 import { _resetVocabCache } from './tfidf.mjs';
 import { createRequire } from 'module';
@@ -283,11 +285,30 @@ async function runSearchPipeline(db, args, { llm, rerankLlm } = {}) {
   const deepMode = resolveDeepMode(args.deep, { surface: 'mcp' });
   const rerank = args.rerank === true && deepMode === 'deep';
 
+  // P2: deferred trailer — open deferred items matching the query, appended to
+  // the text blob AFTER (and never counted in) the main results/total. Parity
+  // with CLI cmdSearch's emitDeferredTrailer; unfiltered first-page searches
+  // only. Structured fields (results/total) stay untouched — the trailer is a
+  // text affordance, not a result source.
+  const wantDeferredTrailer = !args.type && !args.obs_type && !args.branch && !args.tier && !args.importance && offset === 0;
+  const appendDeferredTrailer = (result) => {
+    if (!wantDeferredTrailer) return result;
+    try {
+      const rows = searchDeferredWork(db, args.query || '', args.project || currentProject);
+      const lines = formatDeferredSearchTrailer(rows, 'mem_get ids=["D#<id>"]');
+      if (lines.length > 0 && result.content?.[0]?.type === 'text') {
+        result.content[0].text += `\n\n${lines.join('\n')}`;
+      }
+    } catch { /* trailer is best-effort; never break search */ }
+    return result;
+  };
+
   // Early return when query was provided but sanitized to nothing (all FTS5
   // keywords/special chars). Skipped for deep/auto (the LLM rewrite may still
   // produce variants) and for filter-only listings (date/obs_type/importance).
+  // A pure "D#92" query lands here — the trailer still reaches the item.
   if (args.query && !ftsQuery && !epochFrom && !epochTo && !args.obs_type && !args.importance && deepMode === 'normal') {
-    return { ...formatSearchOutput([], args, ftsQuery, 0), escalated: false, results: [], total: 0, variants: null };
+    return { ...appendDeferredTrailer(formatSearchOutput([], args, ftsQuery, 0)), escalated: false, results: [], total: 0, variants: null };
   }
 
   // Source scoping. deep is observations-only (deepSearch fuses hybrid-obs lists). branch/tier are
@@ -349,6 +370,7 @@ async function runSearchPipeline(db, args, { llm, rerankLlm } = {}) {
   if (r.reranked && output.content?.[0]?.type === 'text') {
     output.content[0].text += '\n\n[deep search: LLM-reranked the top candidates by relevance]';
   }
+  appendDeferredTrailer(output);
 
   // Expose structured fields for tests + the MCP content blob.
   return { ...output, results: r.page, total: r.total, escalated: r.escalated, variants: r.variants, reranked: r.reranked };
@@ -505,14 +527,18 @@ server.registerTool(
     inputSchema: memGetSchema,
   },
   safeHandler(async (args) => {
+    // D#N deferred tokens are peeled off BEFORE bucketing/source-forcing —
+    // get-only read surface into deferred_work (parity with CLI cmdGet; the
+    // fetch+render live in lib/deferred-work.mjs so the twins cannot drift).
+    const { deferredIds, rest } = splitDeferredTokens(args.ids);
     // Bucket by per-token prefix (or force all to `args.source` when explicit).
     // coerceMixedIdTokens has already stringified + regex-validated each token.
-    const { bySrc, invalid } = bucketIdTokens(args.ids, { explicit: args.source || null, defaultSource: 'obs' });
+    const { bySrc, invalid } = bucketIdTokens(rest, { explicit: args.source || null, defaultSource: 'obs' });
     if (invalid.length > 0) {
       // Should not happen — schema regex already rejected bad tokens — but guard defensively.
-      return { content: [{ type: 'text', text: `Invalid ID token(s): ${invalid.join(', ')}. Expected N, #N, P#N, S#N, or E#N.` }] };
+      return { content: [{ type: 'text', text: `Invalid ID token(s): ${invalid.join(', ')}. Expected N, #N, P#N, S#N, E#N, or D#N.` }] };
     }
-    const totalRequested = bySrc.obs.length + bySrc.session.length + bySrc.prompt.length + bySrc.event.length;
+    const totalRequested = bySrc.obs.length + bySrc.session.length + bySrc.prompt.length + bySrc.event.length + deferredIds.length;
     if (totalRequested === 0) {
       return { content: [{ type: 'text', text: 'No valid IDs provided.' }] };
     }
@@ -615,7 +641,26 @@ server.registerTool(
       }
     }
 
-    const totalFound = foundBySource.obs.size + foundBySource.session.size + foundBySource.prompt.size + foundBySource.event.size;
+    // Deferred sections — prepended below (explicit D# requests are rare; the
+    // FULL untruncated detail is the point of this surface).
+    let deferredSections = [];
+    let deferredFound = 0;
+    let deferredMissing = [];
+    if (deferredIds.length > 0) {
+      const dRows = getDeferredByIds(db, deferredIds);
+      const found = new Set(dRows.map(r => r.id));
+      deferredMissing = deferredIds.filter(id => !found.has(id));
+      deferredSections = dRows.map(formatDeferredDetail);
+      deferredFound = dRows.length;
+    }
+
+    const totalFound = foundBySource.obs.size + foundBySource.session.size + foundBySource.prompt.size + foundBySource.event.size + deferredFound;
+
+    if (totalFound === 0 && deferredIds.length > 0 && bySrc.obs.length + bySrc.session.length + bySrc.prompt.length + bySrc.event.length === 0) {
+      // Deferred-only request, nothing found — the source-probe below is about
+      // obs/session/prompt/event and would render an empty source list.
+      return { content: [{ type: 'text', text: `Deferred item(s) not found: ${deferredMissing.map(i => `D#${i}`).join(', ')}. List open items: mem_defer_list.` }] };
+    }
 
     if (totalFound === 0) {
       // Probe other sources so callers can retry with the right prefix/source override.
@@ -629,7 +674,8 @@ server.registerTool(
       if (probe.event.length > 0)   hints.push(`E#${probe.event.join(', E#')} (event — use source='event' or E#N)`);
       const hint = hints.length > 0 ? ` Try: ${hints.join('; ')}.` : '';
       const queriedList = [...queried].join(', ');
-      const msg = `No records found in source(s) [${queriedList}] for the given ID(s).${hint}`;
+      const deferredNote = deferredMissing.length > 0 ? ` Deferred item(s) not found: ${deferredMissing.map(i => `D#${i}`).join(', ')}.` : '';
+      const msg = `No records found in source(s) [${queriedList}] for the given ID(s).${deferredNote}${hint}`;
       return { content: [{ type: 'text', text: fieldsNote ? `${msg}\n\n${fieldsNote}` : msg }] };
     }
 
@@ -641,10 +687,11 @@ server.registerTool(
     missingHints.push(...miss(bySrc.session, foundBySource.session, 'S#'));
     missingHints.push(...miss(bySrc.prompt, foundBySource.prompt, 'P#'));
     missingHints.push(...miss(bySrc.event, foundBySource.event, 'E#'));
+    missingHints.push(...deferredMissing.map(id => `D#${id}`));
 
     const parts = [];
     if (fieldsNote) parts.push(fieldsNote);
-    parts.push(...sections);
+    parts.push(...deferredSections, ...sections);
     if (missingHints.length > 0) {
       parts.push(`Note: ID(s) ${missingHints.join(', ')} not found.`);
     }
@@ -750,7 +797,8 @@ server.registerTool(
     const supersededNote = result.supersededIds && result.supersededIds.length > 0
       ? ` Superseded: ${result.supersededIds.map(i => `#${i}`).join(', ')}.`
       : '';
-    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}` }] };
+    const nudge = buildLessonNudge({ type: result.type, id: result.id, lessonCaptured: result.lessonCaptured, surface: 'mcp' });
+    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}${nudge}` }] };
   })
 );
 
@@ -801,6 +849,8 @@ server.registerTool(
       const pTag = r.priority === 3 ? '🔴' : r.priority === 1 ? '⚪' : '🟡';
       lines.push(`${r.ordinal}. ${pTag} [P${r.priority}] ${r.title} (D#${r.id})`);
     }
+    // Affordance for the detail field — list stays title-only by design.
+    lines.push(`Full detail: mem_get ids=["D#<id>"]`);
     return { content: [{ type: 'text', text: lines.join('\n') }] };
   })
 );
@@ -848,97 +898,11 @@ server.registerTool(
       return { content: [{ type: 'text', text: formatQualityReport(data) }] };
     }
 
-    const cutoff = Date.now() - days * 86400000;
-    const projectFilter = args.project ? 'AND project = ?' : '';
-    const baseParams = args.project ? [args.project] : [];
-
-    // Total counts
-    const obsTotal = db.prepare(`SELECT COUNT(*) as c FROM observations WHERE 1=1 ${projectFilter}`).get(...baseParams);
-    const sessTotal = db.prepare(`SELECT COUNT(*) as c FROM session_summaries WHERE 1=1 ${projectFilter}`).get(...baseParams);
-    const promptTotal = args.project
-      ? db.prepare(`SELECT COUNT(*) as c FROM user_prompts p JOIN sdk_sessions s ON p.content_session_id = s.content_session_id WHERE s.project = ?`).get(args.project)
-      : db.prepare(`SELECT COUNT(*) as c FROM user_prompts`).get();
-
-    // Recent counts
-    const obsRecent = db.prepare(`SELECT COUNT(*) as c FROM observations WHERE created_at_epoch >= ? ${projectFilter}`).get(cutoff, ...baseParams);
-    const sessRecent = db.prepare(`SELECT COUNT(*) as c FROM session_summaries WHERE created_at_epoch >= ? ${projectFilter}`).get(cutoff, ...baseParams);
-
-    // Type distribution (recent)
-    const types = db.prepare(`
-      SELECT type, COUNT(*) as c FROM observations
-      WHERE created_at_epoch >= ? ${projectFilter}
-      GROUP BY type ORDER BY c DESC
-    `).all(cutoff, ...baseParams);
-
-    // Projects (global view — skipped when filtering by single project)
-    const projects = args.project ? [] : db.prepare(`
-      SELECT project, COUNT(*) as c FROM observations
-      GROUP BY project ORDER BY c DESC
-      LIMIT 20
-    `).all();
-
-    // Daily activity (last 7 days)
-    const daily = db.prepare(`
-      SELECT date(created_at) as day, COUNT(*) as c FROM observations
-      WHERE created_at_epoch >= ? ${projectFilter}
-      GROUP BY day ORDER BY day DESC
-      LIMIT 7
-    `).all(Date.now() - 7 * 86400000, ...baseParams);
-
-    // Health metrics
-    const tokenEst = db.prepare(`
-      SELECT SUM(LENGTH(COALESCE(title,'')) + LENGTH(COALESCE(narrative,'')) + LENGTH(COALESCE(text,''))) / 4 as t
-      FROM observations WHERE 1=1 ${projectFilter}
-    `).get(...baseParams);
-
-    const avgImp = db.prepare(`
-      SELECT AVG(COALESCE(importance,1)) as v FROM observations WHERE 1=1 ${projectFilter}
-    `).get(...baseParams);
-
-    const thirtyDaysAgo = Date.now() - 30 * 86400000;
-    // v3.23 noise-gauge de-blinding (mirrors mem-cli cmdStats): `<= 1` makes the
-    // imp=0 dormant population visible (decay floor + LLM low-signal filter push
-    // ~half the live corpus to 0); injection_count=0 mirrors decay's NEVER-INJECTED
-    // guard so injected-but-decayed pinned noise isn't miscounted as "never used".
-    const lowVal = db.prepare(`
-      SELECT COUNT(*) as c FROM observations
-      WHERE COALESCE(importance,1) <= 1 AND COALESCE(access_count,0) = 0
-        AND COALESCE(injection_count,0) = 0
-        AND COALESCE(compressed_into, 0) = 0
-        AND created_at_epoch < ? ${projectFilter}
-    `).get(thirtyDaysAgo, ...baseParams);
-
-    // Low-signal-title population (template / tool-log titles the read-side filter
-    // already excludes). The imp=1 "Low-value" metric can't see these, so the
-    // gauge under-reports real noise without it. See lib/low-signal-patterns.mjs.
-    const lowSignalTitle = db.prepare(`
-      SELECT COUNT(*) as c FROM observations
-      WHERE NOT ${buildNotLowSignalSql()}
-        AND COALESCE(compressed_into, 0) = 0 ${projectFilter}
-    `).get(...baseParams);
-    // F7: both noise numerators exclude compressed rows → divide by the LIVE count, not
-    // obsTotal (all rows), so a compress-heavy store isn't reported cleaner than it is.
-    const liveTotal = db.prepare(
-      `SELECT COUNT(*) as c FROM observations WHERE COALESCE(compressed_into, 0) = 0 ${projectFilter}`
-    ).get(...baseParams);
-    const { noiseRatio, lowSignalRatio } = computeNoiseGauge({ liveTotal: liveTotal.c, lowValCount: lowVal.c, lowSignalCount: lowSignalTitle.c });
-    const compressedCount = db.prepare(`
-      SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}
-    `).get(...baseParams);
-    const supersededOnlyCount = db.prepare(`
-      SELECT COUNT(*) as c FROM observations WHERE superseded_at IS NOT NULL AND compressed_into IS NULL ${projectFilter}
-    `).get(...baseParams);
-
-    // Tier distribution
-    const tierCtx = { now: Date.now(), currentProject: args.project || inferProject(), currentSessionId: '' };
-    const tdParams = tierSqlParams(tierCtx);
-    const tierDist = db.prepare(`
-      SELECT tier, COUNT(*) as c FROM (
-        SELECT ${TIER_CASE_SQL} as tier FROM observations
-        WHERE COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL ${projectFilter}
-      ) GROUP BY tier ORDER BY tier
-    `).all(...tdParams, ...baseParams);
-    const tierMap = Object.fromEntries(tierDist.map(r => [r.tier, r.c]));
+    const {
+      obsTotal, sessTotal, promptTotal, obsRecent, sessRecent,
+      types, projects, daily, tokenEst, avgImp, lowVal, lowSignalTitle,
+      noiseRatio, lowSignalRatio, compressedCount, supersededOnlyCount, tierMap,
+    } = computeStatsFeed(db, { project: args.project || null, days });
 
     const lines = [
       `Memory Statistics${args.project ? ` (project: ${args.project})` : ''}:`,

package/source-files.mjs

@@ -162,6 +162,19 @@ export const SOURCE_FILES = [
   // (cmdDelete) — extracted to kill the byte-duplicated twin. Missing it from the
   // manifest would leave both delete surfaces unsigned/broken on auto-update.
   'lib/delete-core.mjs',
+  // Shared primary stats feed (audit 2026-07-17 MED-4) — statically imported by
+  // server.mjs (mem_stats) and mem-cli.mjs (cmdStats); killed the ~80-line
+  // byte-duplicated twin. Missing it breaks both stats surfaces on auto-update.
+  'lib/stats-core.mjs',
+  // Observation `type` vocabulary single source (audit 2026-07-17 MED-3) —
+  // statically imported by tool-schemas.mjs, mem-cli.mjs, hook-llm.mjs,
+  // hook-optimize.mjs, lib/activity.mjs. Missing it breaks every save/validate
+  // path on auto-update.
+  'lib/obs-types.mjs',
+  // Save-time lesson nudge (audit 2026-07-17 P4) — statically imported by server.mjs
+  // (mem_save) and mem-cli.mjs (cmdSave). Missing it breaks both save surfaces on
+  // auto-update.
+  'lib/save-nudge.mjs',
   // P10 dedup/merge threshold constants — single source of truth for the Jaccard
   // dedup/merge cutoffs. Statically imported by hook.mjs, hook-llm.mjs,
   // hook-optimize.mjs, mem-cli.mjs, server.mjs, and the save/maintain cores;

package/tool-schemas.mjs

@@ -3,8 +3,9 @@
 
 import { z } from 'zod';
 import { CLI_INVOKE } from './cli-path.mjs';
+import { OBS_TYPES } from './lib/obs-types.mjs';
 
-export const OBS_TYPE_ENUM = z.enum(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+export const OBS_TYPE_ENUM = z.enum([...OBS_TYPES]);
 
 // LLM-friendly coercion: accept string numbers and normalize to proper types
 const coerceInt = z.preprocess(
@@ -51,7 +52,7 @@ const coerceStringArray = z.preprocess(
   z.array(z.string())
 );
 
-// Coerce mixed ID tokens (#N / P#N / S#N / bare N) for mem_get. Accepts:
+// Coerce mixed ID tokens (#N / P#N / S#N / D#N / bare N) for mem_get. Accepts:
 //   - native arrays: [1, "P#2", "#3"]
 //   - single number: 1
 //   - single/comma string: "1,P#2,S#3"
@@ -75,7 +76,10 @@ const coerceMixedIdTokens = z.preprocess(
     }
     return v;
   },
-  z.array(z.string().regex(/^[EePpSs]?#?\d+$/, 'Expected N, #N, P#N, S#N, or E#N')).min(1).max(20)
+  // D#N (deferred_work) requires the `#` — bare "D92" is prose, not a token.
+  // Round-trip rule: `defer list` renders "(D#92)", so mem_get must accept it
+  // back (tests/schema-roundtrip.test.mjs). Delete/timeline keep rejecting D#.
+  z.array(z.string().regex(/^(?:[Dd]#|[EePpSs]?#?)\d+$/, 'Expected N, #N, P#N, S#N, E#N, or D#N')).min(1).max(20)
 );
 
 export const memSearchSchema = {
@@ -136,8 +140,8 @@ export const memGetSchema = {
   // Accepts mixed tokens so pasted search results work verbatim: [1], [1, "P#2"], "1,P#2,S#3",
   // or the JSON-stringified form ["1","P#2"]. Each token's prefix routes to its source bucket
   // in server.mjs via lib/id-routing.bucketIdTokens. An explicit `source` override still wins.
-  ids: coerceMixedIdTokens.describe('Mixed observation/prompt/session/event IDs — accepts N, #N, P#N, S#N, E#N; comma-strings and JSON arrays also coerced'),
-  source: z.enum(['obs', 'session', 'prompt', 'event']).optional().describe('Force all IDs to this source (overrides per-token prefixes). Omit to let P#/S#/E#/# prefixes route individually.'),
+  ids: coerceMixedIdTokens.describe('Mixed observation/prompt/session/event/deferred IDs — accepts N, #N, P#N, S#N, E#N, D#N; comma-strings and JSON arrays also coerced. D#N reads a deferred_work item with FULL detail (defer list is title-only)'),
+  source: z.enum(['obs', 'session', 'prompt', 'event']).optional().describe('Force all IDs to this source (overrides per-token prefixes). Omit to let P#/S#/E#/# prefixes route individually. D#N tokens are exempt — they always read deferred_work.'),
   fields: coerceStringArray.optional().describe('Specific fields to return (default: all; validated against obs schema — session/prompt sources ignore this filter)'),
 };