claude-mem-lite 2.69.0 → 2.70.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.69.0",
+      "version": "2.70.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.69.0",
+  "version": "2.70.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -209,14 +209,14 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 
 ### MCP Tools (used automatically by Claude)
 
-As of v2.34.0, the server registers 17 tools in total but only the 6 **core**
+As of v2.70.0, the server registers 20 tools in total but only the 9 **core**
 tools appear in `tools/list`. The 11 **hidden** tools remain callable at the
 protocol layer (`tools/call` by exact name still routes normally); they're
 omitted from the list response so Claude Code sessions don't load 11 extra
 tool schemas at startup. Hidden tools are the maintenance / admin / browser
 surface — reach them through the CLI column in the second table.
 
-**Core (6, exposed to Claude Code)**
+**Core (9, exposed to Claude Code)**
 
 | Tool | Description |
 |------|-------------|
@@ -225,7 +225,10 @@ surface — reach them through the CLI column in the second table.
 | `mem_recall` | Recall observations related to a file. Use before editing to surface past bugfixes and context. |
 | `mem_timeline` | Browse observations chronologically around an anchor point. |
 | `mem_get` | Retrieve full details for specific observation IDs (includes importance and related_ids). |
-| `mem_save` | Manually save a memory/observation. |
+| `mem_save` | Manually save a memory/observation. Accepts `closes_deferred` array for transactional closure of deferred work. |
+| `mem_defer` | Mark work for a future session (v2.70+). First-class carry-forward signal, surfaced in SessionStart `### Deferred Work` block. |
+| `mem_defer_list` | List open deferred items for the current project. |
+| `mem_defer_drop` | Drop a deferred item without fixing it; requires a `reason` for the audit trail. |
 
 **Hidden-but-callable (11, CLI-routed)**
 

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'defer', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'release']);
 
 const cmd = process.argv[2];

package/hook-context.mjs

@@ -407,26 +407,30 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
     handoffLines.push('');
   }
 
-  // 5b. Deferred Work — project-level importance≥3 obs that survived prior
-  // session boundaries. Independent of the per-session handoff: even when the
-  // most recent /clear or /exit handoff has stale or meta-only `working_on`,
-  // genuine carry-forward decisions stay surfaced. Capped at 3 to keep the
-  // banner skim-able. Quiet-hooks does NOT suppress: the whole point is
-  // visibility for cross-session continuity.
-  const deferredObs = db.prepare(`
-    SELECT id, type, title FROM observations
-    WHERE project = ? AND COALESCE(compressed_into, 0) = 0
-      AND superseded_at IS NULL
-      AND COALESCE(importance, 1) >= 3
-      AND ${notLowSignalTitleClause('')}
-    ORDER BY created_at_epoch DESC LIMIT 3
+  // 5b. Deferred Work — backed by deferred_work table (v2.70.0).
+  // Replaces the prior importance≥3 obs proxy. Items shown by per-project
+  // ordinal so user can refer to "处理1" / "handle item 1" naturally; D#<id>
+  // is the stable handle for tool-layer references (closes_deferred=[N]).
+  // Quiet-hooks does NOT suppress: cross-session continuity is the whole point.
+  const deferredItems = db.prepare(`
+    SELECT id, title, priority,
+           ROW_NUMBER() OVER (
+             ORDER BY priority DESC, created_at_epoch ASC
+           ) AS ordinal
+    FROM deferred_work
+    WHERE project = ? AND status = 'open'
+    ORDER BY priority DESC, created_at_epoch ASC
+    LIMIT 5
   `).all(project);
 
   const deferredLines = [];
-  if (deferredObs.length > 0) {
+  if (deferredItems.length > 0) {
     deferredLines.push('### Deferred Work');
-    for (const o of deferredObs) {
-      deferredLines.push(`- ${typeIcon(o.type)} [${o.type}] ${truncate(o.title, 140)} (#${o.id})`);
+    for (const d of deferredItems) {
+      const pTag = d.priority === 3 ? '🔴' : d.priority === 1 ? '⚪' : '🟡';
+      deferredLines.push(
+        `${d.ordinal}. ${pTag} [P${d.priority}] ${truncate(d.title, 120)} (D#${d.id})`
+      );
     }
     deferredLines.push('');
   }

package/hook.mjs

@@ -51,6 +51,7 @@ import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection,
 import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
+import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -1073,6 +1074,13 @@ async function handleSessionStart() {
     // CLAUDE.md by pre-v2.30 installs. Idempotent no-op afterwards.
     cleanupClaudeMdLegacyBlock();
 
+    // v2.70.0 one-shot upgrade banner: notify users on first SessionStart per
+    // project that the `### Deferred Work` block now reads from the
+    // deferred_work table (was: high-importance observations in v2.69.x).
+    // Idempotent via marker file; subsequent SessionStarts are silent.
+    try { emitV270UpgradeBanner({ project, runtimeDir: RUNTIME_DIR }); }
+    catch (e) { debugCatch(e, 'session-start-v270-banner'); }
+
     // Pre-load TF-IDF vocabulary cache for this session (from DB, ~1ms)
     try { getVocabulary(db); } catch (e) { debugCatch(e, 'session-start-vocab'); }
 

package/lib/deferred-work.mjs

@@ -0,0 +1,171 @@
+// claude-mem-lite — deferred_work data layer
+// Pure-data CRUD + ordinal resolver + transactional closure helper.
+// Decoupled from observations table: different lifecycle, different scoring.
+
+/**
+ * Insert a new open deferred_work row.
+ * @param {Database} db Opened DB
+ * @param {object} args
+ * @param {string} args.project Required project name
+ * @param {string} args.title Required one-line subject
+ * @param {number} [args.priority=2] 1=low, 2=normal, 3=urgent
+ * @param {string} [args.detail] Optional longer description
+ * @param {string[]} [args.files] Optional file paths
+ * @param {string} [args.source_session_id] Mem session id
+ * @param {number} [args.source_prompt_id] user_prompts.id
+ * @returns {{id: number}} Inserted row id
+ */
+export function insertDeferred(db, args) {
+  const { project, title, priority = 2, detail = null, files = null,
+          source_session_id = null, source_prompt_id = null } = args;
+  // source_session_id / source_prompt_id: forward-compat for v2.71+ defer-detector
+  // hook (anchor a deferred item to the originating prompt). v1 inserts NULL.
+  if (!project || typeof project !== 'string') throw new Error('project required');
+  if (!title || typeof title !== 'string') throw new Error('title required');
+  if (![1, 2, 3].includes(priority)) throw new Error('priority must be 1, 2, or 3');
+  const stmt = db.prepare(`
+    INSERT INTO deferred_work
+      (project, title, detail, priority, status, created_at_epoch,
+       source_session_id, source_prompt_id, files)
+    VALUES (?, ?, ?, ?, 'open', ?, ?, ?, ?)
+  `);
+  const r = stmt.run(
+    project, title, detail, priority, Date.now(),
+    source_session_id, source_prompt_id,
+    files ? JSON.stringify(files) : null,
+  );
+  return { id: Number(r.lastInsertRowid) };
+}
+
+/**
+ * List open items in a project with computed per-project ordinal.
+ * Ordinal is dynamic — recomputed each call by ROW_NUMBER over open rows
+ * sorted (priority DESC, created_at_epoch ASC). When item-1 closes, item-2
+ * becomes the new item-1.
+ * @param {Database} db
+ * @param {string} project
+ * @param {number} [limit=10]
+ * @returns {Array<{id, project, title, detail, priority, status, created_at_epoch, ordinal}>}
+ */
+export function listOpenWithOrdinal(db, project, limit = 10) {
+  return db.prepare(`
+    SELECT id, project, title, detail, priority, status, created_at_epoch,
+           ROW_NUMBER() OVER (ORDER BY priority DESC, created_at_epoch ASC) AS ordinal
+    FROM deferred_work
+    WHERE project = ? AND status = 'open'
+    ORDER BY priority DESC, created_at_epoch ASC
+    LIMIT ?
+  `).all(project, limit);
+}
+
+/**
+ * Set status='dropped' with a non-empty reason. No-op when status is not 'open'.
+ * @returns {{changed: number}} 1 if updated, 0 if not found or not open.
+ */
+export function dropDeferred(db, id, reason) {
+  if (typeof reason !== 'string' || reason.trim().length === 0) {
+    throw new Error('drop reason required (non-empty string)');
+  }
+  const r = db.prepare(`
+    UPDATE deferred_work
+    SET status='dropped', closed_at_epoch=?, drop_reason=?
+    WHERE id=? AND status='open'
+  `).run(Date.now(), reason.trim(), id);
+  return { changed: r.changes };
+}
+
+/**
+ * Resolve mixed ordinal (int) + raw-id ("D#<n>") tokens to real deferred_work
+ * ids, validated against caller project + status='open'.
+ *
+ * - bare integer N → ordinal-within-project (uses same ROW_NUMBER as listOpenWithOrdinal)
+ * - "D#<n>" string → raw deferred_work.id; must belong to caller project AND be open
+ *
+ * @param {Database} db
+ * @param {string} project Caller project (FK guard)
+ * @param {Array<number|string>} tokens Mixed input
+ * @returns {number[]} Real deferred_work ids in input order
+ * @throws {Error} On unresolvable input — error message names the offending token
+ */
+export function resolveDeferredIds(db, project, tokens) {
+  if (!Array.isArray(tokens)) throw new Error('tokens must be an array');
+  // Pre-load open list once for ordinal resolution (ROW_NUMBER snapshot stable
+  // within this call so [1, 2] resolves consistently).
+  const open = db.prepare(`
+    SELECT id, ROW_NUMBER() OVER (ORDER BY priority DESC, created_at_epoch ASC) AS ordinal
+    FROM deferred_work
+    WHERE project = ? AND status = 'open'
+  `).all(project);
+  const ordinalToId = new Map(open.map(r => [r.ordinal, r.id]));
+
+  const getRow = db.prepare(`SELECT id, project, status FROM deferred_work WHERE id = ?`);
+  const seen = new Set();
+  const resolved = [];
+
+  for (const t of tokens) {
+    let id;
+    if (Number.isInteger(t)) {
+      id = ordinalToId.get(t);
+      if (id === undefined) {
+        throw new Error(`ordinal ${t} has no corresponding open deferred item in project "${project}" (open count: ${open.length})`);
+      }
+    } else if (typeof t === 'string') {
+      const m = /^D#(\d+)$/.exec(t.trim());
+      if (!m) throw new Error(`invalid token "${t}" — expected D#N or integer ordinal`);
+      id = parseInt(m[1], 10);
+      const row = getRow.get(id);
+      if (!row) throw new Error(`D#${id} not found`);
+      if (row.project !== project) {
+        throw new Error(`D#${id} belongs to project "${row.project}", not "${project}"`);
+      }
+      if (row.status !== 'open') {
+        throw new Error(`D#${id} status is "${row.status}", cannot close (only 'open' items)`);
+      }
+    } else {
+      throw new Error(`invalid token type ${typeof t} — expected D#N or integer ordinal`);
+    }
+    if (seen.has(id)) throw new Error(`duplicate token resolves to id ${id}`);
+    seen.add(id);
+    resolved.push(id);
+  }
+  return resolved;
+}
+
+/**
+ * Close a set of deferred items by id, all-or-nothing.
+ *
+ * Wraps the UPDATE loop in an internal transaction so that any per-row failure
+ * rolls back prior rows. better-sqlite3's `.transaction()` composes with an
+ * outer caller-managed transaction via SAVEPOINT — Task 5's wider closure flow
+ * (obs INSERT + closeDeferredItems) wraps both calls in one outer transaction
+ * to guarantee atomicity across the obs row and the deferred-work UPDATEs.
+ *
+ * @param {Database} db
+ * @param {number[]} ids Already-resolved real ids (use resolveDeferredIds first)
+ * @param {number} closingObsId observations.id that proves closure
+ * @throws {Error} If any id is not currently open (lookup-based safety net)
+ */
+export function closeDeferredItems(db, ids, closingObsId) {
+  if (!Array.isArray(ids) || ids.length === 0) return;
+  if (!Number.isInteger(closingObsId) || closingObsId <= 0) {
+    throw new Error('closingObsId must be a positive integer');
+  }
+  // Defense-in-depth: even if caller already validated via resolveDeferredIds,
+  // re-check status here (caller may have done resolution earlier in the same
+  // transaction without holding a lock).
+  const stmt = db.prepare(`
+    UPDATE deferred_work
+    SET status='done', closed_at_epoch=?, closed_by_obs_id=?
+    WHERE id=? AND status='open'
+  `);
+  const now = Date.now();
+  const tx = db.transaction((idList) => {
+    for (const id of idList) {
+      const r = stmt.run(now, closingObsId, id);
+      if (r.changes !== 1) {
+        throw new Error(`closeDeferredItems: id ${id} was not in 'open' status (changes=${r.changes})`);
+      }
+    }
+  });
+  tx(ids);
+}

package/lib/git-state.mjs

@@ -6,10 +6,25 @@ import { execFileSync } from 'child_process';
 
 const GIT_TIMEOUT_MS = 1500;
 
+// Strip inherited GIT_* env so child `git` operates on the requested `cwd`
+// rather than a parent process's repo. Required when readGitState is called
+// from contexts where GIT_DIR/GIT_INDEX_FILE/GIT_WORK_TREE/GIT_PREFIX leak in:
+// pre-commit hooks running tests, hooks invoked under `git commit`, etc.
+// Without this, headSha and `changed` reflect the parent's repo, not cwd's.
+function buildCleanEnv() {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_INDEX_FILE;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_PREFIX;
+  return env;
+}
+
 function run(cmd, args, { cwd } = {}) {
   try {
     return execFileSync(cmd, args, {
       cwd,
+      env: buildCleanEnv(),
       encoding: 'utf8',
       timeout: GIT_TIMEOUT_MS,
       // Suppress git's own stderr noise (e.g. "fatal: not a git repository").

package/lib/upgrade-banner.mjs

@@ -0,0 +1,31 @@
+// One-shot v2.70.0 upgrade banner.
+// Split out of hook.mjs because hook.mjs has module-level side effects
+// (notably `if (!event) process.exit(0)` at top level) that abort vitest
+// workers if imported directly from a test. See test
+// tests/hook-upgrade-banner.test.mjs.
+
+import { writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * One-shot stderr banner on first SessionStart after v2.70.0 upgrade.
+ * Notifies users that the `### Deferred Work` block now reads from the
+ * deferred_work table (not high-importance observations as in v2.69.x).
+ * Idempotent via a marker file in `runtimeDir`; subsequent calls in the
+ * same project are silent.
+ *
+ * @param {object} args
+ * @param {string} args.project Project name (used in banner + marker filename).
+ * @param {string} args.runtimeDir RUNTIME_DIR (test override; production passes hook-shared.RUNTIME_DIR).
+ */
+export function emitV270UpgradeBanner({ project, runtimeDir }) {
+  const marker = join(runtimeDir, `.deferred-block-migrated-${project}`);
+  if (existsSync(marker)) return;
+  process.stderr.write(
+    `[mem] v2.70.0 upgrade notice (project "${project}"): Deferred Work block now ` +
+    `backed by deferred_work table. To keep an obs visible there, run ` +
+    `\`claude-mem-lite defer add "<title>" --priority 3\`. ` +
+    `Pin to 2.69.x to revert.\n`
+  );
+  try { writeFileSync(marker, String(Date.now())); } catch { /* best-effort marker */ }
+}

package/mem-cli.mjs

@@ -28,6 +28,10 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 // move each cmdXxx into its own cli/<cmd>.mjs; mem-cli.mjs becomes pure dispatch.
 import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
+import {
+  insertDeferred, listOpenWithOrdinal, dropDeferred,
+  resolveDeferredIds, closeDeferredItems,
+} from './lib/deferred-work.mjs';
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
@@ -884,7 +888,7 @@ function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
   if (!text) {
-    fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T]');
+    fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T] [--closes-deferred 1,D#42]');
     return;
   }
 
@@ -914,15 +918,60 @@ function cmdSave(db, args) {
     return;
   }
 
-  const result = saveObservation(db, {
-    content: text,
-    title: flags.title,
-    type,
-    importance: rawImp,
-    project,
-    files: saveFiles,
-    lesson_learned: rawLesson,
-  });
+  // --closes-deferred parsing: accepts comma-separated mixed tokens
+  // ("1,D#42,3") with bare integers treated as ordinals and "D#N" as raw ids.
+  // We pre-parse tokens here (cheap, syntax-only) but defer resolveDeferredIds
+  // INTO the transaction, AFTER the dedup check. Resolving outside the
+  // transaction would throw on the duplicate-replay path: the previously-
+  // closed deferred row is no longer 'open', so ordinal/id resolution would
+  // crash even though the duplicate short-circuit makes closure a no-op.
+  // Resolving inside the dedup-gated branch keeps "save the same content
+  // twice" idempotent (mirrors server.mjs:934 dedup-skip-closure intent).
+  let closesTokens = null;
+  if (flags['closes-deferred'] !== undefined && flags['closes-deferred'] !== false) {
+    const raw = String(flags['closes-deferred']);
+    closesTokens = raw.split(',').map(t => t.trim()).filter(Boolean).map(t => {
+      return /^\d+$/.test(t) ? parseInt(t, 10) : t;
+    });
+    if (closesTokens.length === 0) {
+      fail('[mem] --closes-deferred requires at least one token (integer ordinal or D#N)');
+      return;
+    }
+  }
+
+  let result;
+  let closesIds = null;
+  try {
+    result = db.transaction(() => {
+      const r = saveObservation(db, {
+        content: text,
+        title: flags.title,
+        type,
+        importance: rawImp,
+        project,
+        files: saveFiles,
+        lesson_learned: rawLesson,
+      });
+      // Skip closure on dedup short-circuit — the obs row already exists, so
+      // the deferred item should NOT be re-closed by a duplicate save call.
+      // Resolving deferred ids only on the non-duplicate path keeps repeated
+      // save commands (with the same --closes-deferred) idempotent even after
+      // the deferred row has transitioned out of 'open'.
+      if (r.kind === 'duplicate') return r;
+      if (closesTokens) {
+        closesIds = resolveDeferredIds(db, project, closesTokens);
+        closeDeferredItems(db, closesIds, r.id);
+      }
+      return r;
+    })();
+  } catch (e) {
+    if (closesTokens) {
+      fail(`[mem] save with --closes-deferred failed: ${e.message}`);
+    } else {
+      fail(`[mem] save failed: ${e.message}`);
+    }
+    return;
+  }
 
   if (result.kind === 'duplicate') {
     out(`[mem] Skipped: similar to existing #${result.existingId}. Use "claude-mem-lite get ${result.existingId}" to review.`);
@@ -930,7 +979,108 @@ function cmdSave(db, args) {
   }
 
   const lessonNote = result.lessonCaptured ? ' 💡lesson captured' : '';
-  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}`);
+  const closedNote = closesIds && closesIds.length > 0
+    ? ` Closed: ${closesIds.map(i => `D#${i}`).join(', ')}.`
+    : '';
+  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}`);
+}
+
+// ─── cmdDefer (sub-dispatch: add | list | drop) ──────────────────────────────
+
+function cmdDefer(db, args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case 'add':  cmdDeferAdd(db, rest); break;
+    case 'list': cmdDeferList(db, rest); break;
+    case 'drop': cmdDeferDrop(db, rest); break;
+    default:
+      fail('[mem] Usage: claude-mem-lite defer <add|list|drop> ...');
+      fail('[mem]   defer add "<title>" [--priority 1|2|3] [--detail T] [--files f1,f2] [--project P]');
+      fail('[mem]   defer list [--project P] [--limit N]');
+      fail('[mem]   defer drop <id-or-D#N> --reason "<reason>" [--project P]');
+  }
+}
+
+function cmdDeferAdd(db, args) {
+  const { positional, flags } = parseArgs(args);
+  const title = positional.join(' ').trim();
+  if (!title) {
+    fail('[mem] Usage: claude-mem-lite defer add "<title>" [--priority 1|2|3] [--detail T] [--files f1,f2] [--project P]');
+    return;
+  }
+  const priority = flags.priority !== undefined ? parseInt(flags.priority, 10) : 2;
+  if (![1, 2, 3].includes(priority)) {
+    fail(`[mem] Invalid --priority "${flags.priority}". Must be 1 (low), 2 (normal), or 3 (urgent).`);
+    return;
+  }
+  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const detail = typeof flags.detail === 'string' ? flags.detail : null;
+  const files = flags.files
+    ? flags.files.split(',').map(f => f.trim()).filter(Boolean)
+    : null;
+
+  let r;
+  try {
+    r = insertDeferred(db, { project, title, priority, detail, files });
+  } catch (e) {
+    fail(`[mem] defer add failed: ${e.message}`);
+    return;
+  }
+  // Compute the freshly-inserted row's ordinal for an immediately-actionable
+  // response ("ok, deferred this as item N"). Mirrors server.mjs:980.
+  const open = listOpenWithOrdinal(db, project, 50);
+  const ord = open.find(o => o.id === r.id)?.ordinal ?? '?';
+  out(`[mem] Deferred as D#${r.id} (item ${ord}) in project "${project}".`);
+}
+
+function cmdDeferList(db, args) {
+  const { flags } = parseArgs(args);
+  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const limit = parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: 100 });
+  const list = listOpenWithOrdinal(db, project, limit);
+  if (list.length === 0) {
+    out(`[mem] No open deferred items in project "${project}".`);
+    return;
+  }
+  out(`[mem] Open deferred items (project "${project}"):`);
+  for (const r of list) {
+    const pTag = r.priority === 3 ? '🔴' : r.priority === 1 ? '⚪' : '🟡';
+    out(`  ${r.ordinal}. ${pTag} [P${r.priority}] ${r.title} (D#${r.id})`);
+  }
+}
+
+function cmdDeferDrop(db, args) {
+  const { positional, flags } = parseArgs(args);
+  if (positional.length === 0) {
+    fail('[mem] Usage: claude-mem-lite defer drop <id-or-D#N> --reason "<reason>" [--project P]');
+    return;
+  }
+  const reason = flags.reason;
+  if (!reason || typeof reason !== 'string' || reason.trim().length === 0) {
+    fail('[mem] defer drop requires --reason "<non-empty string>"');
+    return;
+  }
+  const rawTok = positional[0];
+  // Accept both bare integer (ordinal) and "D#N" string. Mirrors the MCP
+  // mem_defer_drop input contract (server.mjs:1025) by using the same
+  // single-element resolveDeferredIds call.
+  const token = /^\d+$/.test(rawTok) ? parseInt(rawTok, 10) : rawTok;
+  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+
+  let realId;
+  try {
+    [realId] = resolveDeferredIds(db, project, [token]);
+  } catch (e) {
+    fail(`[mem] defer drop: ${e.message}`);
+    return;
+  }
+  const r = dropDeferred(db, realId, reason);
+  if (r.changed === 0) {
+    out(`[mem] D#${realId} was not in 'open' status — drop is a no-op.`);
+    return;
+  }
+  out(`[mem] Dropped D#${realId} in project "${project}". Reason: ${reason.trim()}`);
 }
 
 // N-1: Quality-focused stats for R-2 A/B baseline.
@@ -2178,6 +2328,19 @@ Commands:
     --project P         Project name
     --files f1,f2       Comma-separated file paths
     --lesson T          Lesson learned (≤500 chars; alias: --lesson-learned)
+    --closes-deferred 1,D#42  Close deferred items in same transaction
+
+  defer <action>        First-class deferred work (v2.70+)
+    add "<title>"       Mark deferred work for next session
+      --priority N      1-3 (default 2)
+      --detail T        Constraint + why deferred
+      --files f1,f2     Comma-separated file paths
+      --project P       Project name
+    list                List open deferred items
+      --limit N         Max results (default 10)
+      --project P       Filter by project
+    drop <D#N|ordinal>  Drop a deferred item (no fix needed)
+      --reason "..."    Required audit trail
 
   delete <id1,id2,...>  Delete observations by ID
     --confirm           Execute deletion (preview by default)
@@ -2506,6 +2669,7 @@ export async function run(argv) {
       case 'get':       cmdGet(db, cmdArgs); break;
       case 'timeline':  cmdTimeline(db, cmdArgs); break;
       case 'save':      cmdSave(db, cmdArgs); break;
+      case 'defer':     cmdDefer(db, cmdArgs); break;
       case 'delete':    cmdDelete(db, cmdArgs); break;
       case 'update':    cmdUpdate(db, cmdArgs); break;
       case 'export':    cmdExport(db, cmdArgs); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.69.0",
+  "version": "2.70.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -62,6 +62,8 @@
     "lib/metrics.mjs",
     "lib/mem-override.mjs",
     "lib/save-observation.mjs",
+    "lib/deferred-work.mjs",
+    "lib/upgrade-banner.mjs",
     "cli/common.mjs",
     "cli/fts-check.mjs",
     "cli/doctor.mjs",

package/schema.mjs

@@ -40,7 +40,12 @@ export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 // DROP+CREATE so DBs that picked up the strict v29 trigger get the UUID-
 // gated body. Required because `CREATE TRIGGER IF NOT EXISTS` is a no-op
 // when the trigger already exists, even with a different body.
-export const CURRENT_SCHEMA_VERSION = 30;
+// v31 (v2.70.0): deferred_work table — first-class carry-forward surface.
+// Decoupled from observations: different decay semantics (no time decay; older
+// items rank HIGHER as tech debt accumulates), different lifecycle (mutable
+// status open→done|dropped vs immutable obs). Closure tied to obs via
+// closed_by_obs_id FK with ON DELETE SET NULL (audit trail preserved).
+export const CURRENT_SCHEMA_VERSION = 31;
 
 const CORE_SCHEMA = `
   CREATE TABLE IF NOT EXISTS sdk_sessions (
@@ -541,6 +546,33 @@ export function initSchema(db) {
     )
   `);
 
+  // ─── v31 (v2.70.0): deferred_work — carry-forward TODOs ─────────────────────
+  // Independent table because decay semantics are inverted (older = higher
+  // priority signal) and lifecycle is mutable (status flips). Project-scoped
+  // queries; no FTS5 (per-project N expected ≪ 100). Idempotent migration.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS deferred_work (
+      id                INTEGER PRIMARY KEY AUTOINCREMENT,
+      project           TEXT    NOT NULL,
+      title             TEXT    NOT NULL,
+      detail            TEXT,
+      priority          INTEGER NOT NULL DEFAULT 2,
+      status            TEXT    NOT NULL DEFAULT 'open' CHECK(status IN ('open','done','dropped')),
+      created_at_epoch  INTEGER NOT NULL,
+      closed_at_epoch   INTEGER,
+      closed_by_obs_id  INTEGER REFERENCES observations(id) ON DELETE SET NULL,
+      drop_reason       TEXT,
+      source_session_id TEXT,
+      source_prompt_id  INTEGER REFERENCES user_prompts(id) ON DELETE SET NULL,
+      files             TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_deferred_open
+      ON deferred_work(project, priority DESC, created_at_epoch ASC)
+      WHERE status = 'open';
+    CREATE INDEX IF NOT EXISTS idx_deferred_closed_by
+      ON deferred_work(closed_by_obs_id) WHERE closed_by_obs_id IS NOT NULL;
+  `);
+
   // Record schema version for fast-path on subsequent calls
   db.exec('CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)');
   db.transaction(() => {

package/server.mjs

@@ -13,7 +13,7 @@ import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, b
 import { searchObservationsHybrid, findFtsAnchor } from './search-engine.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 +30,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 +911,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}` }] };
   })
 );
 
@@ -2038,11 +2141,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 +2162,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 +2187,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

@@ -63,6 +63,13 @@ 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',
 ];
 
 /**

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,
+  },
 ];