claude-mem-lite 2.69.0 → 2.71.0

package/server.mjs

@@ -11,9 +11,10 @@ import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
 import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
+import { scrubRecord } from './lib/scrub-record.mjs';
 import { effectiveQuiet } from './hook-shared.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
-import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema, tools as TOOL_DEFS } from './tool-schemas.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';
 
 // Lookup helper: all user-facing tool descriptions live in tool-schemas.mjs
 // (discouragement-style, Task 5). This keeps server.mjs from drifting.
@@ -30,6 +31,10 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { probeOtherSources as probeIdSources, parseIdToken, bucketIdTokens } from './lib/id-routing.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
+import {
+  insertDeferred, listOpenWithOrdinal, dropDeferred,
+  resolveDeferredIds, closeDeferredItems,
+} from './lib/deferred-work.mjs';
 import { getVocabulary, rebuildVocabulary, _resetVocabCache, computeVector } from './tfidf.mjs';
 import { createRequire } from 'module';
 
@@ -907,22 +912,121 @@ server.registerTool(
   safeHandler(async (args) => {
     if (args.project) args = { ...args, project: resolveProject(args.project) };
     const project = args.project || inferProject();
-    const result = saveObservation(db, {
-      content: args.content,
-      title: args.title,
-      type: args.type || 'discovery',
-      importance: args.importance,
-      project,
-      files: args.files || [],
-      lesson_learned: args.lesson_learned,
-    });
+
+    let closesIds = null;
+    let result;
+    try {
+      result = db.transaction(() => {
+        const r = saveObservation(db, {
+          content: args.content,
+          title: args.title,
+          type: args.type || 'discovery',
+          importance: args.importance,
+          project,
+          files: args.files || [],
+          lesson_learned: args.lesson_learned,
+        });
+        if (r.kind === 'duplicate') return r; // dedup short-circuits BEFORE resolver — replay is idempotent
+        // Resolve INSIDE tx + after dedup check so duplicate replays don't throw on
+        // already-closed items. Mirrors mem-cli.mjs cmdSave shape.
+        if (args.closes_deferred && args.closes_deferred.length > 0) {
+          closesIds = resolveDeferredIds(db, project, args.closes_deferred);
+          closeDeferredItems(db, closesIds, r.id);
+        }
+        return r;
+      })();
+    } catch (e) {
+      if (args.closes_deferred && args.closes_deferred.length > 0) {
+        // Re-throw with a clearer prefix so MCP error response names the
+        // contract failure — gate on caller intent (args.closes_deferred) since
+        // closesIds is closure-scoped and may not have been assigned before throw.
+        throw new Error(`mem_save with closes_deferred failed: ${e.message}`, { cause: e });
+      }
+      throw e;  // unwrapped — preserves original message + stack
+    }
 
     if (result.kind === 'duplicate') {
       return { content: [{ type: 'text', text: `Skipped: similar to existing #${result.existingId} in project "${project}". Use mem_get(ids=[${result.existingId}]) to review.` }] };
     }
 
     const lessonNote = result.lessonCaptured ? ` 💡lesson captured` : '';
-    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}` }] };
+    const closedNote = closesIds && closesIds.length > 0
+      ? ` Closed deferred: ${closesIds.map(i => `D#${i}`).join(', ')}.`
+      : '';
+    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}` }] };
+  })
+);
+
+// ─── Tool: mem_defer ────────────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_defer',
+  {
+    description: descriptionOf('mem_defer'),
+    inputSchema: memDeferSchema,
+  },
+  safeHandler(async (args) => {
+    if (args.project) args = { ...args, project: resolveProject(args.project) };
+    const project = args.project || inferProject();
+    const r = insertDeferred(db, {
+      project,
+      title: args.title,
+      priority: args.priority ?? 2,
+      detail: args.detail ?? null,
+      files: args.files ?? null,
+    });
+    // Compute the ordinal for the freshly-inserted row so the response is
+    // immediately actionable ("ok, I deferred this as item 1").
+    const open = listOpenWithOrdinal(db, project, 50);
+    const ord = open.find(o => o.id === r.id)?.ordinal ?? null;
+    return { content: [{ type: 'text', text:
+      `Deferred as D#${r.id} (item ${ord ?? '?'}) in project "${project}" — surfaces in next SessionStart banner.` }] };
+  })
+);
+
+// ─── Tool: mem_defer_list ───────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_defer_list',
+  {
+    description: descriptionOf('mem_defer_list'),
+    inputSchema: memDeferListSchema,
+  },
+  safeHandler(async (args) => {
+    if (args.project) args = { ...args, project: resolveProject(args.project) };
+    const project = args.project || inferProject();
+    const list = listOpenWithOrdinal(db, project, args.limit ?? 10);
+    if (list.length === 0) {
+      return { content: [{ type: 'text', text: `No open deferred items in project "${project}".` }] };
+    }
+    const lines = [`Open deferred items (project "${project}"):`];
+    for (const r of list) {
+      const pTag = r.priority === 3 ? '🔴' : r.priority === 1 ? '⚪' : '🟡';
+      lines.push(`${r.ordinal}. ${pTag} [P${r.priority}] ${r.title} (D#${r.id})`);
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  })
+);
+
+// ─── Tool: mem_defer_drop ───────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_defer_drop',
+  {
+    description: descriptionOf('mem_defer_drop'),
+    inputSchema: memDeferDropSchema,
+  },
+  safeHandler(async (args) => {
+    if (args.project) args = { ...args, project: resolveProject(args.project) };
+    const project = args.project || inferProject();
+    // Resolve id (accept D#N or ordinal int) via resolveDeferredIds with a
+    // single-element array — reuses the same project + status validation.
+    const [realId] = resolveDeferredIds(db, project, [args.id]);
+    const r = dropDeferred(db, realId, args.reason);
+    if (r.changed === 0) {
+      return { content: [{ type: 'text', text: `D#${realId} was not in 'open' status — drop is a no-op.` }] };
+    }
+    return { content: [{ type: 'text', text: `Dropped D#${realId} in project "${project}". Reason: ${args.reason}` }] };
   })
 );
 
@@ -1145,8 +1249,11 @@ server.registerTool(
           VALUES (?, ?, ?, ?, ?, 'active')
         `).run(sessionId, sessionId, proj, now.toISOString(), now.getTime());
 
+        // Defense-in-depth: source rows already scrubbed at original ingest,
+        // but the new compressed narrative is constructed here and re-persisted.
+        const safe = scrubRecord('observations', { text: narrative, title, narrative });
         const summaryResult = insertSummary.run(
-          sessionId, proj, narrative, dominantType, title, narrative,
+          sessionId, proj, safe.text, dominantType, safe.title, safe.narrative,
           medianDate.toISOString(), medianEpoch
         );
         const summaryId = Number(summaryResult.lastInsertRowid);
@@ -2038,11 +2145,15 @@ server.registerTool(
 );
 
 // ─── Hidden tool filter ─────────────────────────────────────────────────────
-// All 17 tools are registered (so `tools/call <name>` still resolves for
-// scripts and direct MCP clients), but only the 6 core tools appear in the
-// `tools/list` response. Hiding the 11 maintenance/admin tools keeps Claude
-// Code's startup context small while preserving the contract that the plugin
-// dogfoods (see CLAUDE.md §Mem usage contract and adopt-content.mjs).
+// All tools are registered (so `tools/call <name>` still resolves for scripts
+// and direct MCP clients), but only the core tools appear in the `tools/list`
+// response. Hiding the maintenance/admin tools keeps Claude Code's startup
+// context small while preserving the contract that the plugin dogfoods (see
+// CLAUDE.md §Mem usage contract and adopt-content.mjs).
+// Surface counts as of v2.70.0: 9 core (mem_search/recent/timeline/get/save/
+// recall + mem_defer/mem_defer_list/mem_defer_drop) + 11 hidden (maintenance/
+// admin/specialized) = 20 registered; tests/tool-schemas.test.mjs is the
+// authoritative count.
 //
 // Safe because:
 //   - Protocol-layer override: we replace the mcp.js default ListTools
@@ -2055,9 +2166,9 @@ const HIDDEN_TOOL_NAMES = new Set(
 );
 
 // Opt-out: setting CLAUDE_MEM_ALL_TOOLS=1 restores pre-v2.34.0 behavior where
-// all 17 tools are visible in `tools/list`. Users who relied on Claude Code
-// autonomously invoking the now-hidden maintenance tools can use this as an
-// immediate escape hatch while adopting the CLI entry points documented in
+// every registered tool is visible in `tools/list`. Users who relied on Claude
+// Code autonomously invoking the now-hidden maintenance tools can use this as
+// an immediate escape hatch while adopting the CLI entry points documented in
 // adopt-content.mjs / README.
 const EXPOSE_ALL_TOOLS = process.env.CLAUDE_MEM_ALL_TOOLS === '1';
 
@@ -2080,7 +2191,7 @@ if (!EXPOSE_ALL_TOOLS) {
 // harnesses stay silent.
 if (!effectiveQuiet()) {
   const status = EXPOSE_ALL_TOOLS
-    ? 'all 17 tools exposed via CLAUDE_MEM_ALL_TOOLS=1'
+    ? `all ${TOOL_DEFS.length} tools exposed via CLAUDE_MEM_ALL_TOOLS=1`
     : `tools/list narrowed to ${TOOL_DEFS.length - HIDDEN_TOOL_NAMES.size} core tools (${HIDDEN_TOOL_NAMES.size} hidden but callable by exact name; unset CLAUDE_MEM_ALL_TOOLS to keep, set =1 to restore all)`;
   process.stderr.write(`[claude-mem-lite v${PKG_VERSION}] ${status}\n`);
 }

package/source-files.mjs

@@ -9,7 +9,7 @@ export const SOURCE_FILES = [
   'cli.mjs', 'server.mjs', 'server-internals.mjs', 'search-engine.mjs', 'tool-schemas.mjs',
   'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
   'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs',
-  'hook-update.mjs', 'hook-optimize.mjs',
+  'hook-update.mjs', 'hook-optimize.mjs', 'hook-precompact.mjs',
   'plugin-cache-guard.mjs',
   'haiku-client.mjs', 'utils.mjs', 'schema.mjs',
   'package.json', 'package-lock.json', 'skill.md',
@@ -63,6 +63,22 @@ export const SOURCE_FILES = [
   // mem-cli.mjs::cmdSave and server.mjs::mem_save. Statically imported from both
   // entry points; missing it from the manifest broke MCP saves on auto-update.
   'lib/save-observation.mjs',
+  // v2.70 deferred-work: carry-forward TODO primitives. Statically imported by
+  // server.mjs (mem_defer family) and mem-cli.mjs (defer subcommand).
+  'lib/deferred-work.mjs',
+  // v2.70 one-shot upgrade banner. Split out of hook.mjs because hook.mjs has
+  // module-level `process.exit(0)` side effects that abort vitest workers on
+  // direct import. Statically imported by hook.mjs SessionStart handler.
+  'lib/upgrade-banner.mjs',
+  // Per-table scrub helper for defense-in-depth at text-write INSERT paths.
+  // Statically imported by hook-llm, hook-handoff, hook-optimize, hook,
+  // mem-cli; reached transitively from server.mjs and cli.mjs.
+  'lib/scrub-record.mjs',
+  // Cold-start backfill: parses ~/.claude/projects/<encoded>/<uuid>.jsonl
+  // transcripts into user_prompts + observations. Dynamic-imported by
+  // mem-cli.mjs::cmdImportJsonl; listed here so source-files-sync.test.mjs
+  // and the npm tarball ship it on every release.
+  'lib/import-jsonl.mjs',
 ];
 
 /**

package/tool-schemas.mjs

@@ -140,6 +140,31 @@ export const memDeleteSchema = {
   confirm: coerceBool.describe('false=preview what will be deleted, true=execute deletion'),
 };
 
+// Coerce closes_deferred input — accepts mixed array of integers (ordinals) and
+// "D#<n>" strings (raw ids). Numeric strings are coerced to numbers (so MCP
+// bridges that JSON-stringify ints don't drop them); D#-prefixed strings stay
+// strings for the resolver. Other string shapes reject early at schema layer.
+const coerceDeferredTokens = z.preprocess(
+  (v) => {
+    if (Array.isArray(v)) {
+      return v.map(x => {
+        if (typeof x === 'number') return x;
+        if (typeof x === 'string') {
+          const s = x.trim();
+          if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+          return s;
+        }
+        return x;
+      });
+    }
+    return v;
+  },
+  z.array(z.union([
+    z.number().int().positive(),
+    z.string().regex(/^D#\d+$/, 'expected D#N (raw id) or positive integer (ordinal)'),
+  ])).min(1).max(20)
+);
+
 export const memSaveSchema = {
   content: z.string().min(1).max(50000).describe('Memory content to save'),
   title: z.string().optional().describe('Short title'),
@@ -148,6 +173,7 @@ export const memSaveSchema = {
   importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('Importance level: 1=routine, 2=notable, 3=critical (default: 2 for explicit saves)'),
   files: coerceStringArray.optional().describe('File paths associated with this observation'),
   lesson_learned: z.string().max(500).optional().describe('Key lesson or takeaway (for bugfix: root cause & fix; for decision: rationale)'),
+  closes_deferred: coerceDeferredTokens.optional().describe('Close one or more deferred_work items in the same project. Mixed array: bare integer = ordinal-within-project, "D#<n>" string = raw id. Transactional with the obs insert — a single invalid id rolls back the whole save.'),
 };
 
 export const memStatsSchema = {
@@ -252,6 +278,28 @@ export const memBrowseSchema = {
   limit: coerceInt.pipe(z.number().int().min(1).max(100)).optional().describe('Max entries per tier (default 5, or 20 when filtering by tier)'),
 };
 
+export const memDeferSchema = {
+  title: z.string().min(1).max(200).describe('One-line subject of the deferred item'),
+  priority: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('1=low, 2=normal, 3=urgent (default: 2)'),
+  detail: z.string().max(2000).optional().describe('Optional longer description / constraint / why deferred'),
+  files: coerceStringArray.optional().describe('Optional file paths this deferred item concerns'),
+  project: z.string().optional().describe('Project name (default: inferred from CWD)'),
+};
+
+export const memDeferListSchema = {
+  project: z.string().optional().describe('Project name (default: inferred from CWD)'),
+  limit: coerceInt.pipe(z.number().int().min(1).max(50)).optional().describe('Max results (default 10)'),
+};
+
+export const memDeferDropSchema = {
+  id: z.union([
+    coerceInt.pipe(z.number().int().positive()),
+    z.string().regex(/^D#\d+$/, 'expected D#N or positive integer'),
+  ]).describe('Deferred item id — accepts D#N (raw id) or positive integer (ordinal-within-project)'),
+  reason: z.string().min(1).max(500).describe('Why this item is being dropped (required for audit trail)'),
+  project: z.string().optional().describe('Project name (default: inferred from CWD)'),
+};
+
 // ────────────────────────────────────────────────────────────────────────────
 // Tool descriptions — discouragement style (Task 5, v2.31)
 //
@@ -265,14 +313,16 @@ export const memBrowseSchema = {
 // 40-60% vs. encouragement-style ("use this to..."). See tests/tool-schemas.test.mjs
 // for the invariants this list must satisfy.
 //
-// Core vs hidden (v2.34.0): only 6 tools are exposed via MCP `tools/list`. The
+// Core vs hidden (v2.34.0, expanded v2.70.0): only 9 tools are exposed via MCP
+// `tools/list` (the original 6 + mem_defer/mem_defer_list/mem_defer_drop). The
 // remaining 11 stay registered — and are still callable by name at the MCP
 // protocol level (`tools/call` by exact name) — but are omitted from the list
 // response so they don't bloat every agent's startup context. The core set
 // covers the hot paths the invited-memory contract promises (recall before
-// Edit, save after bugfix, search/recent/timeline/get for retrieval). Hidden
-// tools are either maintenance (compress/maintain/optimize/fts_check),
-// admin/infra (stats/export/update/delete), or specialized browsers
+// Edit, save after bugfix, search/recent/timeline/get for retrieval, defer
+// for cross-session carry-forward). Hidden tools are either maintenance
+// (compress/maintain/optimize/fts_check), admin/infra
+// (stats/export/update/delete), or specialized browsers
 // (browse/registry/use) — all of which have CLI equivalents documented in
 // `adopt-content.mjs`.
 // ────────────────────────────────────────────────────────────────────────────
@@ -599,4 +649,57 @@ export const tools = [
     inputSchema: memBrowseSchema,
     hidden: true,
   },
+  {
+    name: 'mem_defer',
+    description:
+      'Save a future-session TODO to the project carry-forward list. Surfaces in the next SessionStart `### Deferred Work` banner with an ordinal (e.g. "1") so user can say "处理1" / "handle item 1".\n' +
+      '\n' +
+      'DO NOT use when:\n' +
+      '  - Work is in-flight this session (just do it; do not defer mid-task)\n' +
+      '  - This-PR follow-up cleanup (file in tasks/, not deferred_work)\n' +
+      '  - Already saved a bugfix obs for it (use mem_save closes_deferred instead)\n' +
+      '\n' +
+      'USE when:\n' +
+      '  - User says "下次/next session/留给下个会话/defer to next round"\n' +
+      '  - Wrap-up phase enumerates follow-up items for the next session\n' +
+      '  - Bug surfaces but root cause is out of this session\'s scope\n' +
+      '\n' +
+      'Equivalent CLI: claude-mem-lite defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
+    inputSchema: memDeferSchema,
+  },
+  {
+    name: 'mem_defer_list',
+    description:
+      'List open deferred_work items for a project, ordered by priority DESC then age. Each item carries a per-project ordinal (1, 2, 3...) for "处理1"-style reference.\n' +
+      '\n' +
+      'DO NOT use when:\n' +
+      '  - The SessionStart `### Deferred Work` block already shows the items (reuse that — same data)\n' +
+      '  - You only need one item by id (use mem_get on the obs that closed it, or look up the row directly)\n' +
+      '\n' +
+      'USE when:\n' +
+      '  - User asks "what was on the deferred list" / "what did I leave for next time"\n' +
+      '  - About to refer to "item N" and need to confirm what N points to\n' +
+      '  - Auditing carry-forward state across multiple sessions\n' +
+      '\n' +
+      'Equivalent CLI: claude-mem-lite defer list [--project X] [--limit 10]',
+    inputSchema: memDeferListSchema,
+  },
+  {
+    name: 'mem_defer_drop',
+    description:
+      'Mark a deferred_work item as dropped (no fix, no longer relevant) with a required reason. For real fixes, prefer mem_save({type:"bugfix", closes_deferred:[N]}) — establishes audit trail.\n' +
+      '\n' +
+      'DO NOT use when:\n' +
+      '  - The item was actually fixed (use mem_save closes_deferred — audit linkage)\n' +
+      '  - You want to delete the row (drops are soft — status flips, row stays)\n' +
+      '  - The reason is trivial — drop reason is the only audit trail for "why no fix"\n' +
+      '\n' +
+      'USE when:\n' +
+      '  - Originally-deferred item turns out to be a flaky test, not a real bug\n' +
+      '  - Scope changed and the work is no longer needed\n' +
+      '  - User explicitly says "drop the deferred X, never mind"\n' +
+      '\n' +
+      'Equivalent CLI: claude-mem-lite defer drop <D#N|ordinal> --reason "..."',
+    inputSchema: memDeferDropSchema,
+  },
 ];