claude-mem-lite 2.30.1 → 2.31.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.30.1",
+      "version": "2.31.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.30.1",
+  "version": "2.31.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

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', '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', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'release']);
 
 const cmd = process.argv[2];
@@ -13,6 +13,11 @@ if (cmd === '--version' || cmd === '-v') {
 } else if (cmd === '--help' || cmd === '-h') {
   const { run } = await import('./mem-cli.mjs');
   await run(['help']);
+} else if (cmd === 'doctor' && process.argv.slice(3).includes('--benchmark')) {
+  // doctor --benchmark is a baseline-capture tool, routed through mem-cli (DB layer);
+  // plain `doctor` continues to run the install health-check below.
+  const { run } = await import('./mem-cli.mjs');
+  await run(process.argv.slice(2));
 } else if (CLI_COMMANDS.has(cmd)) {
   const { run } = await import('./mem-cli.mjs');
   await run(process.argv.slice(2));

package/hook-handoff.mjs

@@ -6,6 +6,11 @@ import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm, LOW_SI
 import {
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT, HANDOFF_MATCH_THRESHOLD, CONTINUE_KEYWORDS,
 } from './hook-shared.mjs';
+// T10d: import the whole module (not a named export) so tests can spy on
+// gitStateModule.readGitState via vi.spyOn. Named-import bindings are
+// immutable in ESM and cannot be mocked after the fact.
+import * as gitStateModule from './lib/git-state.mjs';
+import * as taskReaderModule from './lib/task-reader.mjs';
 
 /**
  * Build and save a handoff snapshot to session_handoffs table.
@@ -51,6 +56,24 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
       .filter(d => { if (seenDescs.has(d)) return false; seenDescs.add(d); return true; });
     if (pendingDescs.length > 0) unfinished = pendingDescs.join('; ');
   }
+
+  // T10d: TaskList-sourced Unfinished. When no episode pending entries exist,
+  // prefer the structured signal from ~/.claude/tasks/<list>/*.json over the
+  // narrative-only fallback — a user-maintained task list is a stronger signal
+  // than a session with no recent tool activity. When the episode already has
+  // pending entries, those stay (they're fresher than the task file).
+  if (!unfinished) {
+    try {
+      const tasks = taskReaderModule.readProjectTasks({ projectPath: process.cwd() });
+      if (tasks.length > 0) {
+        unfinished = tasks
+          .slice(0, 5)
+          .map(t => `[${t.status}] ${t.title}`)
+          .join('\n');
+      }
+    } catch { /* task reader is best-effort; never block handoff */ }
+  }
+
   // Enrich unfinished with full session edit history from observation narratives.
   // Since handoff is UPSERT (max 2 rows per project), storing more data is free.
   // Always use \n---\n separator so extractUnfinishedSummary can distinguish
@@ -89,11 +112,18 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   const allText = [workingOn, ...completed.map(c => c.title).filter(Boolean), unfinished].join(' ');
   const keywords = extractMatchKeywords(allText, [...fileSet]);
 
+  // T10d: capture HEAD sha so detectContinuationIntent can anchor on it later.
+  // Best-effort — failures (non-git dir, missing binary, timeout) yield null.
+  let gitShaAtHandoff = null;
+  try {
+    gitShaAtHandoff = gitStateModule.readGitState({ cwd: process.cwd() }).headSha || null;
+  } catch { /* swallow — handoff must still persist */ }
+
   // UPSERT keyed on (project, type, session_id) — parallel sessions coexist.
   // Same session re-writing its own handoff (e.g. repeated /clear) updates in place.
   db.prepare(`
-    INSERT INTO session_handoffs (project, type, session_id, working_on, completed, unfinished, key_files, key_decisions, match_keywords, created_at_epoch)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO session_handoffs (project, type, session_id, working_on, completed, unfinished, key_files, key_decisions, match_keywords, created_at_epoch, git_sha_at_handoff)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(project, type, session_id) DO UPDATE SET
       working_on = excluded.working_on,
       completed = excluded.completed,
@@ -101,7 +131,8 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
       key_files = excluded.key_files,
       key_decisions = excluded.key_decisions,
       match_keywords = excluded.match_keywords,
-      created_at_epoch = excluded.created_at_epoch
+      created_at_epoch = excluded.created_at_epoch,
+      git_sha_at_handoff = excluded.git_sha_at_handoff
   `).run(
     project, type, sessionId,
     truncate(workingOn, 1000),
@@ -110,7 +141,8 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     JSON.stringify([...fileSet].slice(0, 20)),
     decisions.map(d => d.title).join('\n'),
     keywords,
-    Date.now()
+    Date.now(),
+    gitShaAtHandoff,
   );
 }
 
@@ -137,6 +169,26 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
   if (!promptText || typeof promptText !== 'string') return false;
   if (promptText.trim().length < 2) return false;
 
+  // T10d Stage -1: Git-commit anchor — if ANY handoff (any age) has a
+  // git_sha_at_handoff matching current HEAD, the working tree hasn't moved
+  // since that handoff, so assume continuation regardless of time / prompt.
+  //
+  // Trade-off: after weeks of no commits this fires aggressively. Users can
+  // reset by making a commit or by typing a long unrelated prompt (this
+  // anchor runs BEFORE the Stage 0 long-prompt guard, so that escape hatch
+  // does not apply here). This is an MVP choice — see plan 10d concern.
+  try {
+    const currentSha = gitStateModule.readGitState({ cwd: process.cwd() }).headSha;
+    if (currentSha) {
+      const anchor = db.prepare(`
+        SELECT 1 FROM session_handoffs
+        WHERE project = ? AND git_sha_at_handoff = ?
+        ORDER BY created_at_epoch DESC LIMIT 1
+      `).get(project, currentSha);
+      if (anchor) return true;
+    }
+  } catch { /* git/DB failure must not break the rest of the pipeline */ }
+
   // Stage 0: Non-expired 'clear' handoff — assume continuation unless long unrelated prompt.
   // Session scoping: with currentCcSessionId, only your OWN clear handoff qualifies.
   const clearHandoff = currentCcSessionId

package/hook-llm.mjs

@@ -15,6 +15,11 @@ import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
   sessionFile, getSessionId, openDb, callLLM, sleep,
 } from './hook-shared.mjs';
+import { EVENT_TYPES, saveEvent } from './lib/activity.mjs';
+
+// T9: memdir-incompatible types live in the `events` table, not `observations`.
+// Set lookup is O(1) — authoritative source is lib/activity.mjs::EVENT_TYPES.
+const EVENT_TYPE_SET = new Set(EVENT_TYPES);
 
 // ─── Save Observation to DB ─────────────────────────────────────────────────
 
@@ -172,6 +177,96 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
   }
 }
 
+// ─── obs → summary shape mapping ────────────────────────────────────────────
+// handleLLMEpisode's internal `obs` uses camelCase/legacy names (lessonLearned,
+// files, filesRead). persistHaikuSummary takes the plan's stable snake_case
+// shape. Keep the mapping here so the dispatcher's public signature stays
+// clean for external callers that already use the plan shape.
+function obsToSummary(obs) {
+  return {
+    type: obs.type,
+    title: obs.title,
+    subtitle: obs.subtitle,
+    narrative: obs.narrative,
+    concepts: obs.concepts,
+    facts: obs.facts,
+    files_modified: obs.files,
+    files_read: obs.filesRead,
+    importance: obs.importance,
+    lesson_learned: obs.lessonLearned,
+    search_aliases: obs.searchAliases,
+  };
+}
+
+// ─── T9: Haiku Summary Dispatcher (events vs observations routing) ──────────
+//
+// Routes memdir-incompatible types (the 8 values in EVENT_TYPES) to the
+// activity `events` table, and keeps legacy/memdir-aligned types (e.g.
+// `change`, which is the only non-event type hook-llm currently emits) on
+// the existing observations path.
+//
+// Input shape (matches the v2.31 MVP plan's stable interface):
+//   summary: { type, title, lesson_learned?, narrative?, importance?, files_modified? }
+//   ctx:     { project, session_id, preSavedObsId? }
+//
+// Returns { table: 'events'|'observations', id: number|null }. Callers inspect
+// `table` to decide whether follow-up observations-only logic (linking, vector
+// refresh) applies.
+//
+// NOTE: The foreground pre-save in hook.mjs:110/336 intentionally still writes
+// to `observations` for immediate visibility. When the background worker
+// processes the episode (handleLLMEpisode), it passes the pre-saved id in
+// `ctx.preSavedObsId`; this dispatcher then deletes the pre-saved observations
+// row and inserts a fresh event for event-typed summaries (upgrade-delete
+// semantics). Observations-typed summaries reuse the pre-saved row directly
+// (caller handles the UPDATE, since it needs the enriched FTS fields).
+export function persistHaikuSummary(db, summary, ctx) {
+  if (EVENT_TYPE_SET.has(summary.type)) {
+    // Upgrade-delete: the foreground pre-save landed in `observations` with a
+    // rule-inferred type; now that Haiku has classified it as an event type,
+    // we must remove the stale observations row before inserting the event.
+    // Atomic via better-sqlite3 transaction: either both succeed or neither.
+    const insertEvent = () => saveEvent(db, {
+      project: ctx.project,
+      event_type: summary.type,
+      title: summary.title,
+      body: summary.lesson_learned || summary.narrative || null,
+      file_paths: (Array.isArray(summary.files_modified) && summary.files_modified.length > 0)
+        ? summary.files_modified
+        : null,
+      importance: summary.importance ?? 1,
+      created_at_epoch: Date.now(),
+    });
+
+    if (ctx.preSavedObsId) {
+      const id = db.transaction(() => {
+        db.prepare(`DELETE FROM observations WHERE id = ?`).run(ctx.preSavedObsId);
+        return insertEvent();
+      })();
+      return { table: 'events', id };
+    }
+
+    return { table: 'events', id: insertEvent() };
+  }
+
+  // Fallthrough: memdir-compatible / legacy types use the observations path.
+  // Map the Haiku/plan field names to saveObservation's expected shape.
+  const id = saveObservation({
+    type: summary.type,
+    title: summary.title,
+    subtitle: summary.subtitle || '',
+    narrative: summary.narrative || '',
+    concepts: summary.concepts || [],
+    facts: summary.facts || [],
+    files: summary.files_modified || [],
+    filesRead: summary.files_read || [],
+    importance: summary.importance ?? 1,
+    lessonLearned: summary.lesson_learned || null,
+    searchAliases: summary.search_aliases || null,
+  }, ctx.project, ctx.session_id, db);
+  return { table: 'observations', id };
+}
+
 // ─── Related Observation Linking ─────────────────────────────────────────────
 
 function linkRelatedObservations(db, savedId, obs, episode) {
@@ -504,46 +599,72 @@ search_aliases: 2-6 alternative search terms someone might use to find this memo
 
   try {
     let savedId;
+    let savedTable;
 
     if (episode.savedId && obs) {
-      // Upgrade pre-saved observation with LLM-enriched data
-      const { conceptsText, factsText, textField } = buildFtsTextField(obs);
-      const minhashSig = computeMinHash((obs.title || '') + ' ' + (obs.narrative || ''));
-      db.prepare(`
-        UPDATE observations SET type=?, title=?, subtitle=?, narrative=?, concepts=?, facts=?,
-          text=?, importance=?, files_read=?, minhash_sig=?, lesson_learned=?, search_aliases=?
-        WHERE id = ?
-      `).run(
-        obs.type, truncate(obs.title, 120), obs.subtitle || '',
-        truncate(obs.narrative || '', 500),
-        conceptsText, factsText, textField,
-        obs.importance,
-        JSON.stringify(obs.filesRead || []),
-        minhashSig,
-        obs.lessonLearned || null,
-        obs.searchAliases || null,
-        episode.savedId
-      );
-      savedId = episode.savedId;
-      debugLog('DEBUG', 'llm-episode', `upgraded pre-saved obs #${savedId}`);
-
-      // Update TF-IDF vector with enriched content
-      try {
-        const vocab = getVocabulary(db);
-        if (vocab) {
-          const vecText = [obs.title || '', obs.narrative || '', conceptsText].filter(Boolean).join(' ');
-          const vec = computeVector(vecText, vocab);
-          if (vec) {
-            db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-              .run(savedId, Buffer.from(vec.buffer), vocab.version, Date.now());
+      if (EVENT_TYPE_SET.has(obs.type)) {
+        // Upgrade-delete: pre-saved observation's rule-inferred type was later
+        // classified by Haiku as an event type. Delete the stale observations
+        // row and insert into events instead. Dispatcher handles the atomic
+        // swap via transaction.
+        const result = persistHaikuSummary(db, obsToSummary(obs), {
+          project: episode.project,
+          session_id: episode.sessionId,
+          preSavedObsId: episode.savedId,
+        });
+        savedId = result.id;
+        savedTable = result.table;
+        debugLog('DEBUG', 'llm-episode', `upgrade-delete: obs #${episode.savedId} → event #${savedId}`);
+      } else {
+        // Non-event type (e.g. `change`) — upgrade pre-saved observations row in place
+        // so the enriched FTS text field + minhash + vector are refreshed atomically.
+        const { conceptsText, factsText, textField } = buildFtsTextField(obs);
+        const minhashSig = computeMinHash((obs.title || '') + ' ' + (obs.narrative || ''));
+        db.prepare(`
+          UPDATE observations SET type=?, title=?, subtitle=?, narrative=?, concepts=?, facts=?,
+            text=?, importance=?, files_read=?, minhash_sig=?, lesson_learned=?, search_aliases=?
+          WHERE id = ?
+        `).run(
+          obs.type, truncate(obs.title, 120), obs.subtitle || '',
+          truncate(obs.narrative || '', 500),
+          conceptsText, factsText, textField,
+          obs.importance,
+          JSON.stringify(obs.filesRead || []),
+          minhashSig,
+          obs.lessonLearned || null,
+          obs.searchAliases || null,
+          episode.savedId
+        );
+        savedId = episode.savedId;
+        savedTable = 'observations';
+        debugLog('DEBUG', 'llm-episode', `upgraded pre-saved obs #${savedId}`);
+
+        // Update TF-IDF vector with enriched content
+        try {
+          const vocab = getVocabulary(db);
+          if (vocab) {
+            const vecText = [obs.title || '', obs.narrative || '', conceptsText].filter(Boolean).join(' ');
+            const vec = computeVector(vecText, vocab);
+            if (vec) {
+              db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
+                .run(savedId, Buffer.from(vec.buffer), vocab.version, Date.now());
+            }
           }
-        }
-      } catch (e) { debugCatch(e, 'handleLLMEpisode-vector'); }
+        } catch (e) { debugCatch(e, 'handleLLMEpisode-vector'); }
+      }
     } else {
-      savedId = saveObservation(obs, episode.project, episode.sessionId, db);
+      // Clean insert (no pre-save) — dispatcher routes by type.
+      const result = persistHaikuSummary(db, obsToSummary(obs), {
+        project: episode.project,
+        session_id: episode.sessionId,
+      });
+      savedId = result.id;
+      savedTable = result.table;
     }
 
-    if (savedId) {
+    // Related-observation linking only applies to rows in `observations` —
+    // the `events` table has its own lifecycle (supersede/accessed_count).
+    if (savedId && savedTable === 'observations') {
       try {
         linkRelatedObservations(db, savedId, obs, episode);
       } catch (e) { debugCatch(e, 'relatedObsLinking'); }

package/hook.mjs

@@ -716,6 +716,23 @@ async function handleSessionStart() {
       } catch (e) { debugCatch(e, 'session-start-exit-fast-summary'); }
     }
 
+    // T10c: Startup dashboard — aggregate git/tasks/plans/handoff/events into a
+    // structured JSON hookSpecificOutput block. Emitted BEFORE the plain-text
+    // <claude-mem-context> so both surfaces coexist. Empty string → skip.
+    try {
+      const { buildDashboard } = await import('./lib/startup-dashboard.mjs');
+      const dashboardText = buildDashboard({ db, project, projectPath: process.cwd() });
+      if (dashboardText) {
+        process.stdout.write(JSON.stringify({
+          suppressOutput: true,
+          hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext: dashboardText,
+          },
+        }) + '\n');
+      }
+    } catch (e) { debugCatch(e, 'session-start-dashboard'); }
+
     // Build the full context body via shared helper (also used by `mem-cli context`).
     // Queries session_summaries, key observations, clear handoff, and the
     // token-budgeted observation pool directly from the DB.

package/install.mjs

@@ -211,6 +211,17 @@ async function install() {
     'install-metadata.mjs', 'mem-cli.mjs', 'tier.mjs', 'tfidf.mjs',
     'nlp.mjs', 'synonyms.mjs', 'scoring-sql.mjs', 'stop-words.mjs', 'project-utils.mjs',
     'secret-scrub.mjs', 'format-utils.mjs', 'hash-utils.mjs', 'bash-utils.mjs',
+    // v2.31 T9: hook-llm now statically imports lib/activity.mjs (events routing).
+    // SOURCE_FILES entries with a subdir prefix require install.mjs to mkdir the
+    // parent before symlink/copy — handled in the IS_DEV and else-branch loops.
+    'lib/activity.mjs',
+    // v2.31 T10: startup dashboard aggregator + handoff task/git anchoring.
+    // task-reader + plan-reader + git-state are read by lib/startup-dashboard.mjs
+    // on SessionStart (hook.mjs) and by hook-handoff.mjs on /exit + /clear.
+    'lib/task-reader.mjs',
+    'lib/plan-reader.mjs',
+    'lib/git-state.mjs',
+    'lib/startup-dashboard.mjs',
   ];
 
   if (IS_DEV) {
@@ -220,6 +231,9 @@ async function install() {
       const target = join(PROJECT_DIR, f);
       const link = join(DATA_DIR, f);
       if (existsSync(target)) {
+        // Ensure parent dir exists for subdir entries (e.g. 'lib/activity.mjs')
+        const linkParent = dirname(link);
+        if (!existsSync(linkParent)) mkdirSync(linkParent, { recursive: true });
         // Remove existing file/symlink before creating
         if (existsSync(link)) try { unlinkSync(link); } catch {}
         symlinkSync(target, link);
@@ -252,7 +266,13 @@ async function install() {
     if (!existsSync(scriptsDir)) mkdirSync(scriptsDir, { recursive: true });
     for (const f of SOURCE_FILES) {
       const src = join(PROJECT_DIR, f);
-      if (existsSync(src)) copyFileSync(src, join(DATA_DIR, f));
+      const dst = join(DATA_DIR, f);
+      if (existsSync(src)) {
+        // Ensure parent dir exists for subdir entries (e.g. 'lib/activity.mjs')
+        const dstParent = dirname(dst);
+        if (!existsSync(dstParent)) mkdirSync(dstParent, { recursive: true });
+        copyFileSync(src, dst);
+      }
     }
     // Copy scripts
     const postToolSrc = join(PROJECT_DIR, 'scripts', 'post-tool-use.sh');

package/mem-cli.mjs

@@ -2048,6 +2048,16 @@ Commands:
     remove              Remove resource --name N --resource-type T
     reindex             Rebuild FTS5 index
 
+  activity <action>     Non-memdir event log (v2.31) — bugfix/lesson/bug/discovery/etc.
+    save --type T "<title>" [--body "<text>"] [--files f1,f2] [--file path] [--importance 1-3] [--project P]
+    search "<query>"    Search events [--type T] [--limit N] [--project P]
+    recent [N]          Most recent events [--type T] [--project P]
+    show <id>           Show full event row by id
+
+    Valid types: bugfix, lesson, bug, discovery, refactor, feature, observation, decision
+    --files (plural, comma-split) preferred; --file (singular) kept for back-compat.
+    Use /lesson or /bug slash commands for faster capture (T8).
+
 DB: ${DB_PATH}`);
 }
 
@@ -2193,6 +2203,122 @@ async function cmdOptimize(db, args) {
   if (results.smartCompress) out(`  Smart-compress: ${results.smartCompress.compressed || 0} compressed of ${results.smartCompress.processed || 0} clusters`);
 }
 
+async function cmdDoctor(db, args) {
+  if (args.includes('--benchmark')) {
+    const { runBenchmark } = await import('./lib/doctor-benchmark.mjs');
+    const project = inferProject();
+    const result = runBenchmark(db, { project });
+    out(JSON.stringify(result, null, 2));
+    return;
+  }
+  out('[mem] doctor: supported flags: --benchmark');
+  process.exitCode = 1;
+}
+
+// ─── Activity (T7 v2.31) ─────────────────────────────────────────────────────
+// Separate namespace from observations. Handlers are thin wrappers over
+// lib/activity.mjs pure functions; imported lazily to match the doctor pattern.
+
+function formatActivityResults(rows) {
+  if (!rows || rows.length === 0) return '(no events)';
+  return rows.map(r => `#${r.id} [${r.event_type}] ${r.title}`).join('\n');
+}
+
+async function cmdActivity(db, args) {
+  const sub = args[0];
+  if (!sub) {
+    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show> ...');
+    return;
+  }
+
+  const { positional, flags } = parseArgs(args.slice(1));
+  const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES } = await import('./lib/activity.mjs');
+  const VALID_EVENT_TYPES = new Set(EVENT_TYPES);
+  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+
+  if (sub === 'save') {
+    const type = flags.type || 'observation';
+    if (!VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity save: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const title = flags.title || positional.join(' ').trim();
+    if (!title) {
+      fail('[mem] activity save: --title or positional text required');
+      return;
+    }
+    const body = flags.body || null;
+    // Accept both --file (singular, backward compat) and --files (plural,
+    // comma-split, preferred — matches cmdSave). Merge both sources.
+    const filesFromPlural = flags.files && typeof flags.files === 'string'
+      ? flags.files.split(',').map(s => s.trim()).filter(Boolean)
+      : [];
+    const filesFromSingular = flags.file && typeof flags.file === 'string' ? [flags.file] : [];
+    const file_paths_merged = [...filesFromSingular, ...filesFromPlural];
+    const file_paths = file_paths_merged.length > 0 ? file_paths_merged : null;
+    const rawImp = flags.importance !== undefined ? parseInt(flags.importance, 10) : 2;
+    if (flags.importance !== undefined && (isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
+      fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
+      return;
+    }
+    const id = saveEvent(db, {
+      project,
+      event_type: type,
+      title,
+      body,
+      importance: rawImp,
+      file_paths,
+    });
+    out(JSON.stringify({ ok: true, id }));
+    return;
+  }
+
+  if (sub === 'search') {
+    const q = positional.join(' ');
+    if (!q) {
+      fail('[mem] activity search: query required');
+      return;
+    }
+    const type = flags.type || null;
+    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity search: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const limit = flags.limit !== undefined ? parseInt(flags.limit, 10) : 10;
+    const rows = searchEvents(db, q, { project, type, limit });
+    out(formatActivityResults(rows));
+    return;
+  }
+
+  if (sub === 'recent') {
+    // Accept either `activity recent 5` or `activity recent --limit 5`.
+    const posLimit = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
+    const flagLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
+    const limit = Number.isFinite(posLimit) ? posLimit : (Number.isFinite(flagLimit) ? flagLimit : 20);
+    const type = flags.type || null;
+    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity recent: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const rows = recentEvents(db, { project, type, limit });
+    out(formatActivityResults(rows));
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
+    if (!Number.isFinite(id)) {
+      fail('[mem] activity show: numeric id required');
+      return;
+    }
+    const row = getEvent(db, id);
+    out(row ? JSON.stringify(row, null, 2) : 'Not found');
+    return;
+  }
+
+  fail(`[mem] Unknown activity subcommand: ${sub}`);
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 export async function run(argv) {
@@ -2241,6 +2367,8 @@ export async function run(argv) {
       case 'registry':  cmdRegistry(db, cmdArgs); break;
       case 'import':    await cmdImport(cmdArgs); break;
       case 'enrich':    await cmdEnrich(cmdArgs); break;
+      case 'doctor':    await cmdDoctor(db, cmdArgs); break;
+      case 'activity':  await cmdActivity(db, cmdArgs); break;
       default:
         out(`[mem] Unknown command: ${cmd}`);
         out('[mem] Run "claude-mem-lite help" for usage');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {