claude-mem-lite 3.91.0 → 3.92.0

package/mem-cli.mjs

@@ -21,18 +21,17 @@ import { fetchObsDetail, fetchPromptDetail, fetchEventDetail, OBS_FIELDS, SESSIO
 import { collectBrowseTiers, getActiveMemorySessionId, BROWSE_TIERS, BROWSE_TIER_LABELS } from './lib/browse-core.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { ensureRegistryDb, collectRegistryStats, listResourcesRanked, formatRegistryListLine } from './registry.mjs';
-import { IMPORT_STRING_FIELDS, importResource, removeResource, reindexResources } from './lib/registry-core.mjs';
+import { IMPORT_STRING_FIELDS, importResource, removeResource, reindexResources, enrichResourceRow, enrichImportedResources, enrichNamedResource, REGISTRY_CONFINE_ENV } from './lib/registry-core.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { computeFunnel, formatFunnel, computeSweep, formatSweep, DEFAULT_SWEEP_FLOORS, DEFAULT_SWEEP_MARGINS } from './registry-recommend.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import {
-  cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
-  recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans,
-  purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
-  hardDeleteCandidateCount,
+  runMaintainOps, findDuplicates, maintenanceStats,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD, resolveDefaultMaintainOps,
 } from './lib/maintain-core.mjs';
-import { snapshotDb, listSnapshots, backupBudgetBytes } from './lib/db-backup.mjs';
+// snapshotDb left with maintain-core: the pre-maintain snapshot is part of the op ORDER
+// (it must see the pre-existing pending rows), so it moved into runMaintainOps (P1-5).
+import { listSnapshots, backupBudgetBytes } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.mjs';
 import { OBS_TYPE_SET } from './lib/obs-types.mjs';
 import { computeStatsFeed } from './lib/stats-core.mjs';
@@ -55,7 +54,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { isNativeBindingError, healAndReexec } from './lib/binding-probe.mjs';
 import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import { parseArgs, out, outVerbatim, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, resolvePositionalAlias, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue, obsFieldLabel, formatPendingPurgeLine } from './cli/common.mjs';
-import { saveObservation, formatSupersedeSkipped, formatSupersededNote } from './lib/save-observation.mjs';
+import { saveObservation, saveWithClosures, formatSupersedeSkipped, formatSupersededNote } from './lib/save-observation.mjs';
 import { normalizeScope, insertObservationVector, applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
@@ -81,7 +80,7 @@ const SURFACE_LABELS = {
 import { aggregateMetrics, readMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred, formatDropReasonHint,
-  resolveDeferredIds, closeDeferredItems,
+  resolveDeferredIds,
   getDeferredByIds, formatDeferredDetail,
   searchDeferredWork, formatDeferredSearchTrailer,
   formatDeferListRow, countStaleOpen, formatDeferStaleHint,
@@ -970,36 +969,21 @@ function cmdSave(db, args) {
     }
   }
 
-  let result;
-  let closesIds = null;
+  let result, closesIds;
   try {
-    result = db.transaction(() => {
-      const r = saveObservation(db, {
-        content: text,
-        title: flags.title,
-        type,
-        importance: rawImp,
-        project,
-        files: saveFiles,
-        lesson_learned: rawLesson,
-        supersedes: supersedesIds || undefined,
-      });
-      // 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) {
-        // D#195: the close verb accepts a 'dropped' row and converts it to
-        // 'done'. `defer drop` used on an item that was actually fixed was
-        // otherwise a one-way gate, permanently losing the obs link. Kept in
-        // sync with the same policy in server.mjs mem_save.
-        closesIds = resolveDeferredIds(db, project, closesTokens, { allowStatuses: ['open', 'dropped'] });
-        closeDeferredItems(db, closesIds, r.id);
-      }
-      return r;
-    })();
+    // The transaction body — dedup short-circuit BEFORE the resolver, and D#195's
+    // allowStatuses — is lib/save-observation.mjs's (audit 2026-09-02 P1-6). Both faces
+    // used to write it out and each carried a "kept in sync with the other" comment.
+    ({ result, closesIds } = saveWithClosures(db, {
+      content: text,
+      title: flags.title,
+      type,
+      importance: rawImp,
+      project,
+      files: saveFiles,
+      lesson_learned: rawLesson,
+      supersedes: supersedesIds || undefined,
+    }, { closesTokens, project }));
   } catch (e) {
     if (closesTokens) {
       fail(`[mem] save with --closes-deferred failed: ${e.message}`);
@@ -2084,10 +2068,6 @@ function cmdMaintain(db, args) {
   }
   const staleAge = Date.now() - STALE_AGE_MS;
   const mctx = { projectFilter, baseParams, staleAge, opCap: OP_CAP };
-  const results = [];
-
-  // T2-P1-B: surface the OP_CAP hit so users know to re-run, matching MCP mem_maintain.
-  const capHint = (changes) => (changes >= OP_CAP ? ' (cap reached, re-run for more)' : '');
 
   // Parse + validate --retain-days BEFORE the transaction so an invalid value rejects the
   // whole command atomically. The old code validated inside db.transaction() with a bare
@@ -2108,134 +2088,40 @@ function cmdMaintain(db, args) {
   // purge_stale is the only DELETE here — require --confirm so a mis-typed run can't wipe rows.
   const confirmed = flags.confirm === true || flags.confirm === 'true';
 
-  // Snapshot the DB before the irreversible cleanup/purge hard-deletes — only when rows will
-  // actually be removed, and OUTSIDE the transaction below (VACUUM cannot run inside one).
-  // Best-effort; snapshotDb never throws.
-  const willPurge = ops.includes('purge_stale') && confirmed;
-  if (hardDeleteCandidateCount(db, mctx, { cleanup: ops.includes('cleanup'), purge: willPurge }) > 0) {
-    snapshotDb(db, { tag: 'pre-maintain' });
-  }
-
-  db.transaction(() => {
-    // PURGE FIRST — matches the auto-maintain hook order (hook.mjs:766). Running decay BEFORE
-    // purge in one transaction marked a stale row pending-purge AND deleted it in the SAME call
-    // (zero grace), and the pre-txn snapshot guard counts only PRE-EXISTING pending rows so it
-    // skipped the backup → permanent, unrecoverable loss of notable imp-2/3 memories (audit
-    // HIGH-1). Purging first deletes only rows a PRIOR run marked (which the guard saw + backed
-    // up); rows decay marks below wait for the next maintain run, regaining the grace cycle.
-    if (ops.includes('purge_stale')) {
-      if (!confirmed) {
-        const previewRow = purgeStalePreview(db, mctx, retainCutoff);
-        const pushLines = [`purge_stale preview (no --confirm):`,
-          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
-        if (previewRow.candidates > 0) {
-          pushLines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
-          pushLines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
-        }
-        pushLines.push(`  To delete, re-run with --confirm.`);
-        results.push(pushLines.join('\n'));
-      } else {
-        const purged = purgeStale(db, mctx, retainCutoff);
-        results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)${capHint(purged)}`);
-      }
-    }
-
-    if (ops.includes('cleanup')) {
-      const deleted = cleanupBroken(db, mctx);
-      results.push(`Cleaned up ${deleted} broken observations${capHint(deleted)}`);
-      // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf): resurface
-      // unreachable children. Non-destructive — un-hide only, no delete.
-      const orphans = recoverOrphanedChildren(db, mctx);
-      if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
-      // Heal lesson rows citation-decay buried at importance 0 (pre floor=1). 0→1 on
-      // lesson-bearing rows only; idempotent no-op once none remain.
-      const lessonsHealed = recoverBuriedLessons(db, mctx);
-      if (lessonsHealed > 0) results.push(`Healed ${lessonsHealed} lesson rows buried at importance 0`);
-      // Heal deferred_work rows whose closing obs / source prompt was hard-deleted while FK was
-      // OFF (dangling ref foreign_key_check flags). Applies the ON DELETE SET NULL the FK would.
-      const deferredHealed = sweepDeferredWorkOrphans(db, mctx);
-      if (deferredHealed > 0) results.push(`Healed ${deferredHealed} deferred-work rows with dangling references`);
-    }
-
-    if (ops.includes('decay')) {
-      // injection_count>0 protected (maintain-core; shared with MCP + hook auto-maintain).
-      const { decayed, idleMarked } = decayAndMarkIdle(db, mctx);
-      const decayCap = (decayed >= OP_CAP || idleMarked >= OP_CAP) ? ' (cap reached, re-run for more)' : '';
-      results.push(`Decayed ${decayed} stale observations, marked ${idleMarked} idle as pending-purge${decayCap}`);
-    }
-
-    if (ops.includes('boost')) {
-      const boosted = boostAccessed(db, mctx);
-      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
-    }
-
-    // AFTER boost, matching server.mjs and hook.mjs. This block used to sit BEFORE
-    // it, and the order was load-bearing in the wrong direction: boostAccessed lifts
-    // any access_count>3 row with importance<3, so demoting a pinned row to 1 and
-    // then boosting handed it straight back at 2 — the demotion silently undone
-    // inside a single maintain run. DEFAULT_MAINTAIN_OPS pins the order; this block
-    // has to physically follow the boost block for that order to be real.
-    if (ops.includes('demote_pinned')) {
-      // Repair the citation-decay blind spot: decay protects injection_count>0, so a
-      // heavily-injected-but-uncited memory stays pinned at max importance forever.
-      // demotePinned (maintain-core) floors it in one pass: no lesson_learned -> 1,
-      // lesson-bearing -> 2 (v3.76.1 dual floor). Floor, not purge.
-      const demoted = demotePinned(db, mctx);
-      results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=${PINNED_INJ_THRESHOLD}, cited=0; no lesson → importance 1, lesson → 2)${capHint(demoted)}`);
-    }
-
-    if (ops.includes('dedup') && flags['merge-ids']) {
-      // Parse "keepId:removeId1:removeId2,keepId2:removeId3"; surface malformed segments
-      // (non-numeric / single-element) instead of silently dropping them. The merge SQL
-      // itself lives in maintain-core mergeDuplicates (shared with MCP).
-      const invalidSegments = [];
-      const groups = [];
-      for (const seg of flags['merge-ids'].split(',').map(s => s.trim()).filter(Boolean)) {
-        const parts = seg.split(':').map(s => s.trim());
-        const nums = parts.map(p => Number(p));
-        if (parts.length < 2 || nums.some(n => !Number.isFinite(n) || n <= 0)) { invalidSegments.push(seg); continue; }
-        groups.push(nums);
+  // Parse "keepId:removeId1:removeId2,keepId2:removeId3"; surface malformed segments
+  // (non-numeric / single-element) instead of silently dropping them. The merge SQL and the
+  // op ORDER both live in maintain-core (shared with MCP, audit 2026-09-02 P1-5) — this is
+  // the one genuinely CLI-shaped part, because the MCP tool receives groups already typed.
+  const invalidMergeSegments = [];
+  const mergeGroups = [];
+  if (flags['merge-ids']) {
+    for (const seg of String(flags['merge-ids']).split(',').map(x => x.trim()).filter(Boolean)) {
+      const parts = seg.split(':').map(x => x.trim());
+      const nums = parts.map(x => Number(x));
+      if (parts.length < 2 || nums.some(n => !Number.isFinite(n) || n <= 0)) { invalidMergeSegments.push(seg); continue; }
+      mergeGroups.push(nums);
+    }
+  }
+
+  const results = runMaintainOps(db, mctx, ops, {
+    retainDays,
+    retainCutoff,
+    confirmed,
+    mergeGroups,
+    mergeIdsProvided: Boolean(flags['merge-ids']),
+    invalidMergeSegments,
+    mergeIdsFlagName: '--merge-ids',
+    renderPurgePreview: (previewRow) => {
+      const lines = ['purge_stale preview (no --confirm):',
+        `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
+      if (previewRow.candidates > 0) {
+        lines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+        lines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
       }
-      const totalMerged = mergeDuplicates(db, groups);
-      if (invalidSegments.length) {
-        results.push(`Warning: ignored ${invalidSegments.length} malformed --merge-ids segment(s): ${invalidSegments.join(', ')} (expected keepId:removeId[:removeId...] with positive integers)`);
-      }
-      results.push(`Merged ${totalMerged} duplicate observations`);
-    }
-
-    // T2-P1-B parity with MCP: warn when merge-ids is provided but dedup wasn't requested.
-    if (!ops.includes('dedup') && flags['merge-ids']) {
-      results.push('Warning: --merge-ids provided but "dedup" not in operations — merge-ids ignored');
-    }
-
-  })();
-
-  // FTS optimize
-  db.exec("INSERT INTO observations_fts(observations_fts) VALUES('optimize')");
-  results.push('FTS5 index optimized');
-
-  // rebuild_vectors: outside main transaction (maintain-core, shared with MCP).
-  if (ops.includes('rebuild_vectors')) {
-    try {
-      const r = rebuildVectors(db);
-      results.push(r.ok
-        ? `Vectors: rebuilt vocabulary (${r.terms} terms), updated ${r.updated}/${r.total} vectors`
-        : `Vectors: ${r.reason}`);
-    } catch (e) {
-      results.push(`Vectors: rebuild failed — ${e.message}`);
-    }
-  }
-
-  // vacuum: reclaim freelist pages left by DELETEs. Whole-DB, outside any transaction.
-  // maintain-core, shared with MCP. Reports freelist before/after as the §7 reclaim metric.
-  if (ops.includes('vacuum')) {
-    try {
-      const v = vacuum(db);
-      results.push(`VACUUM: reclaimed ~${v.reclaimedMB}MB (freelist ${v.freeBefore} → ${v.freeAfter} pages)`);
-    } catch (e) {
-      results.push(`VACUUM failed — ${e.message}`);
-    }
-  }
+      lines.push('  To delete, re-run with --confirm.');
+      return lines.join('\n');
+    },
+  });
 
   out(`[mem] ${results.join('\n[mem] ')}`);
 }
@@ -2844,7 +2730,7 @@ Commands:
     --merge-ids K:R,... For dedup: keepId:removeId pairs (e.g. 10:11,20:21:22)
     --project P         Filter by project
     --retain-days N     For purge_stale: keep last N days (default 30)
-                        demote_pinned: floors importance for inj>=8 & cited=0 — to 1 with no
+                        demote_pinned: floors importance for inj>=${PINNED_INJ_THRESHOLD} & cited=0 — to 1 with no
                         lesson_learned, to 2 with one (clears pinned noise; a lesson-bearing
                         row keeps eligibility on every importance>=2 injection face).
                         In the default set since v3.76.0; runs AFTER boost, which would
@@ -2993,17 +2879,9 @@ async function cmdImport(argv) {
     if (flags.enrich) {
       out('[mem] Running LLM enrichment...');
       const { enrichResource } = await import('./registry-enricher.mjs');
-      let enriched = 0;
-      for (const r of results) {
-        const row = rdb.prepare('SELECT local_path FROM resources WHERE id = ?').get(r.id);
-        if (!row?.local_path) continue;
-        try {
-          const content = readFileSync(row.local_path, 'utf8');
-          const ok = await enrichResource(rdb, r.name, r.type, content);
-          if (ok) enriched++;
-        } catch {}
-      }
+      const { ok: enriched, denied } = await enrichImportedResources(rdb, results, { confineTo: DB_DIR, enrichResource });
       out(`[mem] Enriched ${enriched}/${results.length} resources.`);
+      if (denied) out(`[mem] Refused ${denied}: local_path outside the managed directory (${REGISTRY_CONFINE_ENV}=off to override).`);
     }
   } catch (e) {
     fail(`[mem] Import failed: ${e.message}`);
@@ -3121,24 +2999,28 @@ async function cmdEnrich(argv) {
       const rows = rdb.prepare("SELECT name, type, local_path FROM resources WHERE status = 'active' AND (enrichment_status IS NULL OR enrichment_status = 'failed')").all();
       if (rows.length === 0) { out('[mem] All resources already enriched.'); return; }
       out(`[mem] Enriching ${rows.length} resources...`);
-      let ok = 0, failCount = 0;
+      let ok = 0, failCount = 0, denied = 0;
       for (const r of rows) {
-        if (!r.local_path) { failCount++; continue; }
-        try {
-          const content = readFileSync(r.local_path, 'utf8');
-          const success = await enrichResource(rdb, r.name, r.type, content);
-          if (success) ok++; else failCount++;
-          if (!flags.batch) await new Promise(resolve => setTimeout(resolve, 500));
-        } catch { failCount++; }
+        const { status, error } = await enrichResourceRow(rdb, r, { confineTo: DB_DIR, enrichResource });
+        if (status === 'enriched') ok++;
+        else if (status === 'denied') denied++;
+        else failCount++;
+        // Pace exactly where the pre-refactor loop did: after an enrichResource call that
+        // RETURNED. A missing path, an unreadable file, a gate refusal and a throw out of
+        // enrichResource all skipped the sleep before, and still do — `error` present on a
+        // 'failed' row is what distinguishes "returned false" from "threw".
+        const apiReturned = status === 'enriched' || (status === 'failed' && !error);
+        if (apiReturned && !flags.batch) await new Promise(resolve => setTimeout(resolve, 500));
       }
       out(`[mem] Done: ${ok} enriched, ${failCount} failed.`);
+      if (denied) out(`[mem] Refused ${denied}: local_path outside the managed directory (${REGISTRY_CONFINE_ENV}=off to override).`);
     } else if (name) {
-      const row = rdb.prepare("SELECT name, type, local_path FROM resources WHERE name = ? AND status = 'active'").get(name);
-      if (!row) { fail(`[mem] Resource not found: ${name}`); return; }
-      if (!row.local_path) { fail(`[mem] No local_path for ${name}`); return; }
-      const content = readFileSync(row.local_path, 'utf8');
-      const success = await enrichResource(rdb, row.name, row.type, content);
-      out(success ? `[mem] Enriched: ${name}` : `[mem] Enrichment failed for ${name}`);
+      const { status, error } = await enrichNamedResource(rdb, name, { confineTo: DB_DIR, enrichResource });
+      if (status === 'not-found') { fail(`[mem] Resource not found: ${name}`); return; }
+      if (status === 'no-path') { fail(`[mem] No local_path for ${name}`); return; }
+      if (status === 'denied') { fail(`[mem] Access denied: local_path outside the managed directory (${REGISTRY_CONFINE_ENV}=off to override).`); return; }
+      if (status === 'unreadable') { fail(`[mem] Enrich error: ${error?.message || 'cannot read local_path'}`); return; }
+      out(status === 'enriched' ? `[mem] Enriched: ${name}` : `[mem] Enrichment failed for ${name}`);
     } else {
       fail('[mem] Usage: claude-mem-lite enrich <name> OR claude-mem-lite enrich --all [--batch]');
     }

package/memdir.mjs

@@ -9,7 +9,8 @@
 //
 // See docs/plans/2026-04-16-invited-memory-pattern.md for rationale.
 
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync, readdirSync } from 'fs';
+import { readFileSync, existsSync, unlinkSync, mkdirSync, readdirSync } from 'fs';
+import { atomicWriteFileSync as atomicWrite } from './lib/atomic-write.mjs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
@@ -100,11 +101,10 @@ function canonicalBody(contentLine) {
 
 function sha256(s) { return createHash('sha256').update(s).digest('hex'); }
 
-function atomicWrite(path, content) {
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, content);
-  renameSync(tmp, path);
-}
+// Third byte-identical copy of the same temp+rename, all three missing the same lstat
+// (audit 2026-09-02 P0-5). MEMORY.md under a memory dir is a prime symlink candidate —
+// users point it at a dotfiles repo so the same index follows them between machines —
+// and renaming onto the link NAME severs it silently. See lib/atomic-write.mjs.
 
 function readState(memdir, slug) {
   const p = stateFile(memdir, slug);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.91.0",
+  "version": "3.92.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.91.0",
+      "version": "3.92.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",
@@ -18,10 +18,12 @@
       "devDependencies": {
         "@eslint/js": "^10.0.1",
         "@vitest/coverage-v8": "^4.0.18",
+        "acorn": "8.16.0",
         "eslint": "^10.0.0",
         "fast-check": "^4.5.3",
         "knip": "^6.12.1",
         "picomatch": "^4.0.4",
+        "prettier": "3.6.2",
         "vitest": "^4.0.18"
       },
       "engines": {
@@ -3796,6 +3798,22 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/prettier": {
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.91.0",
+  "version": "3.92.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -16,7 +16,11 @@
   },
   "scripts": {
     "lint": "eslint .",
+    "format": "prettier --write \"**/*.{mjs,js}\"",
+    "format:check": "prettier --check \"**/*.{mjs,js}\"",
     "dead-code": "knip",
+    "audit:metrics": "node scripts/audit-metrics.mjs --md",
+    "audit:baseline": "node scripts/audit-metrics.mjs --run-tests --md",
     "test": "vitest run",
     "test:smoke": "vitest run tests/smoke.test.mjs",
     "test:coverage": "vitest run --coverage",
@@ -65,6 +69,8 @@
     "lib/edge-attribution.mjs",
     "lib/file-edge-match.mjs",
     "lib/cite-back-hint.mjs",
+    "lib/cite-recall-path.mjs",
+    "lib/frontmatter.mjs",
     "lib/cooldown-path.mjs",
     "lib/tmp-fixture-sweep.mjs",
     "lib/summary-extractor.mjs",
@@ -201,10 +207,12 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",
+    "acorn": "8.16.0",
     "eslint": "^10.0.0",
     "fast-check": "^4.5.3",
     "knip": "^6.12.1",
     "picomatch": "^4.0.4",
+    "prettier": "3.6.2",
     "vitest": "^4.0.18"
   }
 }

package/registry-importer.mjs

@@ -5,6 +5,7 @@
 import { parseGitHubUrl, buildTreeUrl, buildContentUrl, buildRepoUrl, buildHeaders } from './registry-github.mjs';
 import { upsertResource } from './registry.mjs';
 import { debugLog, isPathConfined } from './utils.mjs';
+import { parseFrontmatter } from './lib/frontmatter.mjs';
 import { createHash } from 'crypto';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
@@ -98,40 +99,9 @@ export function discoverFromTree(treeData, pathFilter) {
  * @param {string} content Full file content
  * @returns {{ frontmatter: Record<string, any>, body: string }}
  */
-export function parseFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return { frontmatter: {}, body: content };
-
-  const raw = match[1];
-  const body = content.slice(match[0].length).trim();
-  const fm = {};
-  let currentKey = null, currentValue = '', inMultiline = false;
-
-  for (const line of raw.split('\n')) {
-    if (inMultiline && (line.startsWith('  ') || line.startsWith('\t') || line.trim() === '')) {
-      currentValue += ' ' + line.trim();
-      continue;
-    }
-    if (inMultiline && currentKey) { fm[currentKey] = currentValue.trim(); inMultiline = false; }
-
-    const kv = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
-    if (kv) {
-      currentKey = kv[1];
-      let val = kv[2].trim();
-      if (val === '|' || val === '>') { inMultiline = true; currentValue = ''; continue; }
-      if (val.startsWith('[') && val.endsWith(']')) {
-        try { fm[currentKey] = JSON.parse(val); } catch { fm[currentKey] = val; }
-        continue;
-      }
-      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))
-        val = val.slice(1, -1);
-      if (currentKey === 'description' && val) { inMultiline = true; currentValue = val; continue; }
-      fm[currentKey] = val;
-    }
-  }
-  if (inMultiline && currentKey) fm[currentKey] = currentValue.trim();
-  return { frontmatter: fm, body };
-}
+// The parser itself is lib/frontmatter.mjs's (audit 2026-09-02 P1-16); re-exported here
+// because callers and tests import it from this module.
+export { parseFrontmatter };
 
 // ─── Keyword Extraction ─────────────────────────────────────────────────────
 

package/registry.mjs

@@ -443,7 +443,8 @@ export function ensureRegistryDb(dbPath) {
   return db;
 }
 
-// ─── Exported Schema (for test-helpers.mjs) ─────────────────────────────────
+// ─── Exported Schema (test-helpers.mjs, and scripts/index-managed.mjs since P1-16, which
+// rebuilds resources_fts from scratch and used to carry its own copy of both blocks) ──
 
 export { RESOURCES_SCHEMA, FTS5_SCHEMA, TRIGGERS_SCHEMA, INVOCATIONS_SCHEMA, PREINSTALLED_SCHEMA };
 

package/scripts/post-tool-recall.js

@@ -10,8 +10,13 @@
 // presentIdents excluded it); that class is carried by the pre-edit
 // BIND_DIRECTIVE, not here. See the spec's component-2 limits.
 //
-// Safety: readonly, no DB, exit 0 always. cooldownPathFor mirrors
-// pre-tool-recall.js (inlined per the #8447 fast-path convention).
+// Safety: readonly, no DB, exit 0 always. The cooldown path rule comes from
+// lib/cooldown-path.mjs — it used to be inlined here "per the #8447 fast-path
+// convention", but that exemption stopped applying to THIS script the moment it grew
+// the four lib imports below (audit 2026-09-02 P1-1: the fourth copy; the previous
+// round collapsed only three of four). A writer/reader disagreement on this name does
+// not error — it reads a file nobody wrote, silently zeroing the bind-mode
+// dropped-identifier check.
 
 import { existsSync, readFileSync } from 'fs';
 import { basename, join } from 'path';
@@ -22,6 +27,7 @@ import { recordHookError } from '../lib/hook-telemetry.mjs';
 // emit added later merges instead of producing two JSON documents, which the host
 // parses as neither (lib/hook-stdout.mjs). Import-free module over no runtime deps.
 import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
+import { cooldownPathFor as sharedCooldownPathFor } from '../lib/cooldown-path.mjs';
 
 const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
 
@@ -29,10 +35,12 @@ const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
 const LEGACY_COOLDOWN_PATH = join(RUNTIME_DIR, 'pre-recall-cooldown.json');
 
+// The no-session legacy fallback stays local: it is this script's own back-compat with
+// pre-session-id cooldown files, not part of the shared naming rule. Same split as
+// scripts/pre-tool-recall.js, which is the writer.
 function cooldownPathFor(sessionId) {
   if (!sessionId) return LEGACY_COOLDOWN_PATH;
-  const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
-  return join(RUNTIME_DIR, `pre-recall-cooldown-${safe}.json`);
+  return sharedCooldownPathFor(RUNTIME_DIR, sessionId);
 }
 
 async function main() {

package/scripts/pre-tool-recall.js

@@ -8,7 +8,7 @@ import { existsSync, readFileSync, mkdirSync } from 'fs';
 import { basename, join } from 'path';
 import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { atomicWriteFileSync } from '../lib/atomic-write.mjs';
-import { injectedIdsFileName, injectedIdKey, EVENT_ID_PREFIX } from '../lib/injected-ids.mjs';
+import { injectedIdsFileName, injectedIdKey, EVENT_ID_PREFIX, readInjectedMarker, mergeInjectedMarker } from '../lib/injected-ids.mjs';
 import { liveObsFilterSql } from '../lib/inject-search-core.mjs';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
@@ -253,45 +253,21 @@ function crossHookInjectedFile(project, sessionId) {
 // read and merge now carry the CC session id: a payload written by a DIFFERENT
 // session is ignored (read) / replaced (merge), mirroring the v3.35.2 episode
 // session-key fix. Legacy payloads without `session` keep the old behavior.
+// Predicate + payload shape live in lib/injected-ids.mjs (audit 2026-09-02 P1-2) — this
+// script held two of the five hand-typed copies. The window stays this script's own
+// constant; only the gate and the write are shared.
 function readCrossHookInjected(project, sessionId) {
-  try {
-    const raw = readFileSync(crossHookInjectedFile(project, sessionId), 'utf8');
-    const { ids, ts, session } = JSON.parse(raw);
-    if (session && sessionId && session !== sessionId) return new Set();
-    if (!ts || Date.now() - ts > CROSS_HOOK_DEDUP_MS) return new Set();
-    if (!Array.isArray(ids)) return new Set();
-    return new Set(ids.map(String));
-  } catch { return new Set(); }
+  const { ids } = readInjectedMarker(crossHookInjectedFile(project, sessionId),
+    { sessionId, maxAgeMs: CROSS_HOOK_DEDUP_MS });
+  return new Set(ids.map(String));
 }
 
 function mergeCrossHookInjected(project, newIds, sessionId) {
   if (!newIds || newIds.length === 0) return;
   try {
     mkdirSync(RUNTIME_DIR, { recursive: true });
-    const file = crossHookInjectedFile(project, sessionId);
-    let prev = { ids: [], ts: 0, count: 0 };
-    try {
-      const raw = readFileSync(file, 'utf8');
-      const parsed = JSON.parse(raw);
-      // Within the staleness window AND same session (or legacy): union.
-      // Outside / other session: replace.
-      if (parsed.ts && Date.now() - parsed.ts < CROSS_HOOK_DEDUP_MS
-          && !(parsed.session && sessionId && parsed.session !== sessionId)) {
-        prev = parsed;
-      }
-    } catch { /* fresh file */ }
-    const ids = [...new Set([
-      ...(Array.isArray(prev.ids) ? prev.ids.map(String) : []),
-      ...newIds.map(String),
-    ])];
-    // Atomic (tmp+rename, M-6): a plain write torn by a concurrent hook left the
-    // shared marker as invalid JSON, silently disabling cross-hook dedup.
-    atomicWriteFileSync(file, JSON.stringify({
-      ids,
-      ts: Date.now(),
-      count: (prev.count || 0) + 1,
-      ...(sessionId ? { session: sessionId } : {}),
-    }));
+    mergeInjectedMarker(crossHookInjectedFile(project, sessionId), newIds,
+      { sessionId, maxAgeMs: CROSS_HOOK_DEDUP_MS, mode: 'union' });
   } catch { /* silent — dedup is best-effort */ }
 }