claude-mem-lite 2.30.1 → 2.31.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.30.1",
+      "version": "2.31.1",
       "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.1",
   "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

@@ -32,6 +32,7 @@ import { searchRelevantMemories } from './hook-memory.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
+import { clearPluginCacheHooks, hasInstallManagedHooks } from './plugin-cache-guard.mjs';
 import { SKIP_TOOLS, SKIP_PREFIXES } from './skip-tools.mjs';
 import { getVocabulary } from './tfidf.mjs';
 
@@ -397,6 +398,21 @@ async function handleStop() {
 // ─── SessionStart Handler + CLAUDE.md Persistence (Tier 1 A, E) ─────────────
 
 async function handleSessionStart() {
+  // Plugin cache self-heal: Claude Code auto-updates the marketplace plugin can
+  // re-populate cache/<ver>/hooks/hooks.json, reintroducing duplicate hook
+  // registration alongside install.mjs-managed settings.json entries. Silently
+  // clear — gated by hasInstallManagedHooks to avoid breaking plugin-only users.
+  try {
+    if (hasInstallManagedHooks()) {
+      const cleared = clearPluginCacheHooks({
+        reason: 'Auto-healed by hook.mjs session-start — install.mjs-managed hooks active in settings.json',
+      });
+      if (cleared.length > 0) {
+        debugLog('DEBUG', 'session-start', `auto-healed stale plugin cache hooks.json in version(s): ${cleared.join(', ')}`);
+      }
+    }
+  } catch (e) { debugCatch(e, 'session-start-cache-heal'); }
+
   // Read CC real session_id from hook stdin — used to scope handoff rows so parallel
   // sessions for the same project don't clobber each other (see docs/bug.txt).
   let ccSessionId = null;
@@ -716,6 +732,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

@@ -26,6 +26,7 @@ const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
 import { RESOURCE_METADATA } from './install-metadata.mjs';
+import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 
 /**
  * Derive invocation_name from resource name when metadata doesn't provide one.
@@ -205,12 +206,24 @@ async function install() {
     'cli.mjs', 'server.mjs', 'server-internals.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',
+    'plugin-cache-guard.mjs',
     'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'package-lock.json', 'skill.md',
     'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
     'registry-retriever.mjs', 'resource-discovery.mjs',
     '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 +233,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 +268,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');
@@ -381,18 +403,43 @@ async function install() {
       }
     } catch (e) { warn(`Marketplace hooks dedup: ${e.message}`); }
 
-    // Sync launch.mjs to plugin cache — ensures MCP server loads dev code via symlink detection
+    // Sync launch.mjs to plugin cache — ensures MCP server loads dev code via symlink detection.
+    // ALSO clear cached hooks.json in every version dir — Claude Code runtime reads hooks from
+    // ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json, NOT from the marketplace source.
+    // Clearing only the marketplace source (above) leaves stale cache copies that double-register
+    // hooks alongside install.mjs-written settings.json entries.
     try {
       const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_KEY, 'claude-mem-lite');
       if (existsSync(cacheBase)) {
         const srcLaunch = join(PROJECT_DIR, 'scripts', 'launch.mjs');
+        let clearedHooks = 0;
         for (const ver of readdirSync(cacheBase)) {
-          const dest = join(cacheBase, ver, 'scripts', 'launch.mjs');
-          if (existsSync(join(cacheBase, ver, 'scripts'))) {
-            copyFileSync(srcLaunch, dest);
+          const verDir = join(cacheBase, ver);
+
+          // Sync launch.mjs
+          if (existsSync(join(verDir, 'scripts'))) {
+            try { copyFileSync(srcLaunch, join(verDir, 'scripts', 'launch.mjs')); } catch {}
+          }
+
+          // Clear cached hooks.json (runtime reads here, not marketplace source)
+          const cachedHooksPath = join(verDir, 'hooks', 'hooks.json');
+          if (existsSync(cachedHooksPath)) {
+            try {
+              const h = JSON.parse(readFileSync(cachedHooksPath, 'utf8'));
+              if (h.hooks && Object.keys(h.hooks).length > 0) {
+                writeFileSync(cachedHooksPath, JSON.stringify({
+                  description: h.description || 'claude-mem-lite hooks',
+                  _note: `Hooks managed by install.mjs in settings.json — cache hooks.json cleared to prevent duplicate registration (cache ver: ${ver})`,
+                  hooks: {}
+                }, null, 2) + '\n');
+                clearedHooks++;
+              }
+            } catch { /* silent — never block install on one bad cache entry */ }
           }
         }
-        ok('Plugin cache: launch.mjs synced (dev mode MCP routing)');
+        const parts = ['launch.mjs synced (dev mode MCP routing)'];
+        if (clearedHooks > 0) parts.push(`${clearedHooks} stale hooks.json cleared`);
+        ok(`Plugin cache: ${parts.join('; ')}`);
       }
     } catch (e) { warn(`Plugin cache sync: ${e.message}`); }
   }
@@ -942,6 +989,18 @@ async function status() {
     fail('Hooks: not configured');
   }
 
+  // Plugin cache pollution: populated hooks.json in cache AND install.mjs-managed
+  // settings.json hooks → runtime registers both → duplicate firing.
+  const polluted = scanPluginCacheHookPollution();
+  if (polluted.length > 0 && hasHooks) {
+    fail(`Plugin cache: stale hooks.json in version(s) ${polluted.join(', ')} — duplicate firing alongside settings.json (run 'install' to auto-clear)`);
+  } else if (polluted.length > 0) {
+    // plugin-only mode (no settings.json hooks) — cache hooks.json is the sole source, expected
+    ok(`Plugin cache: ${polluted.length} version(s) with hooks.json (plugin-only mode)`);
+  } else if (pluginEnabled || hasHooks) {
+    ok('Plugin cache: no stale hooks.json (no duplicate firing)');
+  }
+
   // Database
   if (existsSync(DB_PATH)) {
     try {