claude-mem-lite 3.46.0 → 3.47.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.46.0",
+      "version": "3.47.0",
       "source": "./",
       "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)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.46.0",
+  "version": "3.47.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).",
   "author": {
     "name": "sdsrss"

package/hook-llm.mjs

@@ -12,7 +12,7 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, vecTextForRow } from './tfidf.mjs';
-import { insertObservationRow, insertObservationFiles, insertObservationVector } from './lib/observation-write.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector, normalizeScope } from './lib/observation-write.mjs';
 import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
@@ -266,6 +266,10 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
         importance: obs.importance ?? 1, minhash_sig: minhashSig,
         lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases,
         branch: getCurrentBranch(), created_at: now.toISOString(), created_at_epoch: now.getTime(),
+        // P3 (D#78): re-validate at the write boundary — saveObservation is also
+        // reached by immediate-save / manual callers whose scope never saw the
+        // handleLLMEpisode whitelist.
+        scope: normalizeScope(obs.scope),
       });
 
       insertObservationFiles(db, id, obs.files);
@@ -298,6 +302,7 @@ function obsToSummary(obs) {
     importance: obs.importance,
     lesson_learned: obs.lessonLearned,
     search_aliases: obs.searchAliases,
+    scope: obs.scope,
   };
 }
 
@@ -366,6 +371,7 @@ export function persistHaikuSummary(db, summary, ctx) {
     importance: summary.importance ?? 1,
     lessonLearned: summary.lesson_learned || null,
     searchAliases: summary.search_aliases || null,
+    scope: summary.scope ?? null,
   }, ctx.project, ctx.session_id, db);
   return { table: 'observations', id };
 }
@@ -731,6 +737,7 @@ type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y b
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
 lesson_learned: The non-obvious insight a future session would benefit from. Examples: "FTS5 porter stemmer doesn't tokenize CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". Look hard before giving up — most coding episodes contain at least one micro-lesson (an undocumented flag, a surprising default, a debugging shortcut, an unexpected interaction). If literally no insight worth teaching (e.g. version bump, whitespace fix, file rename), output JSON null. Do NOT invent a lesson, do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
+scope: where does the lesson APPLY (not where it was learned)? file = specific to the touched file(s)' own code. module = a directory/subsystem of this project. project = a project-wide convention, architecture, or workflow. environment = a tooling/OS/CI/network/registry/service quirk (proxy, npm, git, GitHub, shell, runner, editor) that would hold in ANY project — even though some project files were touched when it surfaced. When lesson_learned is null, still classify the episode's dominant subject.
 search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
 
   let prompt;
@@ -738,7 +745,7 @@ search_aliases: 2-6 alternative search terms someone might use to find this memo
     const e = episode.entries[0];
     const system = `Extract a structured observation from this code change. Return ONLY valid JSON, no markdown fences.
 
-JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"concise ≤80 char description","narrative":"what changed, why, and outcome (2-3 sentences)","concepts":["kw1","kw2"],"facts":["fact1","fact2"],"importance":1,"lesson_learned":"non-obvious insight a future session needs, or null","search_aliases":["alt query 1","alt query 2"]}
+JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"concise ≤80 char description","narrative":"what changed, why, and outcome (2-3 sentences)","concepts":["kw1","kw2"],"facts":["fact1","fact2"],"importance":1,"lesson_learned":"non-obvious insight a future session needs, or null","scope":"file|module|project|environment","search_aliases":["alt query 1","alt query 2"]}
 ${SHARED_OBS_SCHEMA_TAIL}`;
     const user = `Tool: ${e.tool}
 File: ${episodeFiles.join(', ') || 'unknown'}
@@ -752,7 +759,7 @@ Error: ${e.isError ? 'yes' : 'no'}`;
 
     const system = `Summarize this coding episode as ONE coherent observation. Return ONLY valid JSON, no markdown fences.
 
-JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"coherent ≤80 char summary","narrative":"what was done, why, and outcome (3-5 sentences)","concepts":["keyword1","keyword2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight a future session needs, or null","search_aliases":["alt query 1","alt query 2"]}
+JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"coherent ≤80 char summary","narrative":"what was done, why, and outcome (3-5 sentences)","concepts":["keyword1","keyword2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight a future session needs, or null","scope":"file|module|project|environment","search_aliases":["alt query 1","alt query 2"]}
 ${SHARED_OBS_SCHEMA_TAIL}`;
     const user = `Project: ${episode.project}
 Files: ${fileList}
@@ -919,6 +926,8 @@ ${actionList}`;
           : Math.max(Math.min(ruleImportance, 2), clampImportance(parsed.importance)),
         lessonLearned,
         searchAliases,
+        // P3 (D#78): lesson applicability scope — whitelist-validated, invalid → null.
+        scope: normalizeScope(parsed.scope),
       };
 
       // v2.56.0 #1: paired-gate DROP. Haiku-titled `change` obs with null lesson
@@ -1000,7 +1009,8 @@ ${actionList}`;
         db.prepare(`
           UPDATE observations SET type=?, title=?, subtitle=?,
             narrative=COALESCE(NULLIF(?, ''), narrative), concepts=?, facts=?,
-            text=?, importance=?, files_read=?, minhash_sig=?, lesson_learned=?, search_aliases=?
+            text=?, importance=?, files_read=?, minhash_sig=?, lesson_learned=?, search_aliases=?,
+            scope=COALESCE(?, scope)
           WHERE id = ?
         `).run(
           obs.type, safe.title, safe.subtitle,
@@ -1011,6 +1021,7 @@ ${actionList}`;
           minhashSig,
           safe.lesson_learned,
           safe.search_aliases,
+          normalizeScope(obs.scope),
           episode.savedId
         );
         savedId = episode.savedId;

package/hook.mjs

@@ -58,6 +58,7 @@ import {
   recordCitationFunnel,
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
+import { resolveEdgeAttribution, readPreRecallFileEdges } from './lib/edge-attribution.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
 import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from './hook-memory.mjs';
 import { formatTaskImperative } from './lib/task-imperative.mjs';
@@ -650,6 +651,27 @@ async function handleStop() {
                 // obs resolved this run (denominator), promoted = obs cited this run
                 // (numerator). Idempotent (touched is 0 on re-fire) + best-effort.
                 recordCitationFunnel(db, project, sessionId, r.touched, r.promoted);
+                // P1 (D#78): per-edge attribution. The session cooldown file
+                // (keyed by CC session id) records which FILE each obs was
+                // injected for; resolve those (obs,file) edges as hit/miss with
+                // the same citedMain set. Lives inside the same text-floor gate
+                // so a tool-only Stop can't lock edges as missed. Best-effort.
+                // Keying on ccSessionId (NOT the rotating memory sessionId)
+                // matches the cooldown file's lifetime — a memory-session
+                // rotation mid-CC-session must not re-resolve old injections as
+                // fresh misses. mainInjectedIds mirrors the mainOnly discipline
+                // above: sidechain-only injections in the cooldown never accrue
+                // misses (review D#78).
+                try {
+                  if (ccSessionId) {
+                    const edges = readPreRecallFileEdges(RUNTIME_DIR, ccSessionId);
+                    if (edges.length > 0) {
+                      const er = resolveEdgeAttribution(db, project, edges, citedMain, ccSessionId,
+                        { mainInjectedIds: injected });
+                      debugLog('DEBUG', 'handleStop', `edge-attribution: edges=${er.touchedEdges} hits=${er.hits} misses=${er.misses}`);
+                    }
+                  }
+                } catch (e) { debugCatch(e, 'handleStop-edge-attribution'); }
               }
             }
           } catch (e) { debugCatch(e, 'handleStop-citation-decay'); }

package/lib/edge-attribution.mjs

@@ -0,0 +1,158 @@
+// P1 (D#78): per-(obs, file) edge attribution for pre-tool-recall injections.
+//
+// pre-tool-recall triggers purely on file-edge matches (observation_files),
+// but 89% of lessons never mention their attached file — the edges record
+// "touched during the episode", not "about this file". A mis-bound edge (the
+// environment-gotcha-on-unrelated-file class from D#65) therefore re-fires on
+// every future session. This module gives each edge its own hit/miss record so
+// P2 can stop firing edges with a consecutive-miss streak, WITHOUT touching
+// the per-obs decay counters on observations (#8641: separate policies — an
+// edge going quiet must not bury the lesson on other injection surfaces).
+//
+// Wiring: pre-tool-recall.js records { filePath → obsIds } in the session
+// cooldown file; hook.mjs handleStop reads it back (readPreRecallFileEdges),
+// unions the same citedMain set the per-obs decay uses, and calls
+// resolveEdgeAttribution inside the same text-floor-gated block.
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { debugCatch } from '../utils.mjs';
+import { fileMatchClause, fileMatchParams } from './file-edge-match.mjs';
+
+// Mirrors pre-tool-recall.js cooldownPathFor sanitization — the two MUST agree
+// or Stop-side resolution reads a different file than the hook wrote.
+function cooldownFileFor(runtimeDir, ccSessionId) {
+  const safe = String(ccSessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+  return join(runtimeDir, `pre-recall-cooldown-${safe}.json`);
+}
+
+/**
+ * Read the session cooldown file and return the file→obsIds edge list for
+ * attribution. Entries without a non-empty obsIds array (legacy bare-number
+ * entries, no-lesson files, event-only injections) are skipped.
+ *
+ * @param {string} runtimeDir
+ * @param {string|null|undefined} ccSessionId Claude Code session id (cooldown file key)
+ * @returns {Array<{filePath: string, obsIds: number[]}>}
+ */
+export function readPreRecallFileEdges(runtimeDir, ccSessionId) {
+  if (!runtimeDir || !ccSessionId) return [];
+  const file = cooldownFileFor(runtimeDir, ccSessionId);
+  if (!existsSync(file)) return [];
+  let data;
+  try { data = JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
+  if (!data || typeof data !== 'object') return [];
+  const edges = [];
+  for (const [filePath, entry] of Object.entries(data)) {
+    if (!entry || typeof entry !== 'object' || !Array.isArray(entry.obsIds)) continue;
+    const obsIds = entry.obsIds
+      .map(Number)
+      .filter((n) => Number.isInteger(n) && n > 0 && n < 1e7);
+    if (obsIds.length === 0) continue;
+    edges.push({ filePath, obsIds });
+  }
+  return edges;
+}
+
+/**
+ * Resolve one session's pre-tool file-edge injections as hit (cited) or miss
+ * (uncited), updating the per-edge counters on observation_files.
+ *
+ * Edge matching uses the SAME predicate as pre-tool-recall's trigger query —
+ * lib/file-edge-match.mjs is the shared source — so attribution lands exactly
+ * on the edges that caused (or would cause) the injection.
+ *
+ * Semantics mirror applyCitationDecay's split idempotency keys:
+ * - miss: guarded on last_resolved_session_id — never double-streaks a session.
+ * - hit:  guarded on last_cited_session_id — a citation landing in a LATER
+ *   turn of the same session still resets the streak (undoes that session's
+ *   miss) without re-counting inject_count.
+ * - MEM_DISABLE_CITATION_DECAY=1 disables all writes (same kill switch as the
+ *   per-obs loop — edge attribution is part of the decay feedback family).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @param {Array<{filePath: string, obsIds: number[]}>} fileEdges
+ * @param {Set<number>|Iterable<number>} citedIds
+ * @param {string} sessionId — the CLAUDE CODE session id (the cooldown file's
+ *   own key), NOT the memory session id: memory sessions rotate on /clear /
+ *   resume / 12h expiry while the cooldown file lives for the whole CC
+ *   session, so a rotating key would re-resolve the same injection as a fresh
+ *   miss after every rotation (review D#78 — 2 rotations ≈ a full K=3 streak
+ *   from ONE real injection).
+ * @param {{mainInjectedIds?: Set<number>}} [opts] — when mainInjectedIds is
+ *   given, only obsIds present in it (or in citedIds) are resolved. The
+ *   cooldown file has no sidechain marker, so subagent-triggered injections
+ *   land in it too; gating on the main-thread injected set mirrors the
+ *   per-obs loop's mainOnly discipline (hook.mjs:625) — an obs injected only
+ *   inside a subagent must not accrue misses it can never repay.
+ * @returns {{hits: number, misses: number, touchedEdges: number}}
+ */
+export function resolveEdgeAttribution(db, project, fileEdges, citedIds, sessionId, opts = {}) {
+  const empty = { hits: 0, misses: 0, touchedEdges: 0 };
+  if (process.env.MEM_DISABLE_CITATION_DECAY === '1') return empty;
+  if (!db || !project || !sessionId) return empty;
+  if (!Array.isArray(fileEdges) || fileEdges.length === 0) return empty;
+  const cited = citedIds instanceof Set ? citedIds : new Set(citedIds || []);
+  const mainInjected = opts.mainInjectedIds instanceof Set ? opts.mainInjectedIds : null;
+
+  const selectEdges = db.prepare(`
+    SELECT of2.rowid AS edge_rowid,
+           of2.miss_streak,
+           of2.last_resolved_session_id,
+           of2.last_cited_session_id
+      FROM observation_files of2
+      JOIN observations o ON o.id = of2.obs_id
+     WHERE of2.obs_id = ?
+       AND o.project = ?
+       AND ${fileMatchClause('of2')}
+  `);
+  const updateHit = db.prepare(`
+    UPDATE observation_files
+       SET miss_streak = 0,
+           inject_count = inject_count + ?,
+           last_cited_session_id = ?,
+           last_resolved_session_id = ?
+     WHERE rowid = ?
+  `);
+  const updateMiss = db.prepare(`
+    UPDATE observation_files
+       SET miss_streak = miss_streak + 1,
+           inject_count = inject_count + 1,
+           last_resolved_session_id = ?
+     WHERE rowid = ?
+  `);
+
+  let hits = 0, misses = 0, touchedEdges = 0;
+  const txn = db.transaction(() => {
+    for (const { filePath, obsIds } of fileEdges) {
+      if (!filePath || !Array.isArray(obsIds)) continue;
+      const fileParams = fileMatchParams(filePath);
+      for (const obsId of obsIds) {
+        // Sidechain gate: skip obs the main thread never saw injected or cited
+        // (see opts.mainInjectedIds in the JSDoc above).
+        if (mainInjected && !mainInjected.has(obsId) && !cited.has(obsId)) continue;
+        let rows;
+        try {
+          rows = selectEdges.all(obsId, project, ...fileParams);
+        } catch (e) { debugCatch(e, `resolveEdgeAttribution-select-${obsId}`); continue; }
+        for (const row of rows) {
+          if (cited.has(obsId)) {
+            if (row.last_cited_session_id === sessionId) continue; // already credited
+            // First resolution this session counts the injection; a cross-turn
+            // late cite (already resolved as miss) only flips the verdict.
+            const first = row.last_resolved_session_id !== sessionId;
+            updateHit.run(first ? 1 : 0, sessionId, sessionId, row.edge_rowid);
+            hits++; touchedEdges++;
+          } else {
+            if (row.last_resolved_session_id === sessionId) continue; // idempotent
+            updateMiss.run(sessionId, row.edge_rowid);
+            misses++; touchedEdges++;
+          }
+        }
+      }
+    }
+  });
+  try { txn(); } catch (e) { debugCatch(e, 'resolveEdgeAttribution-txn'); return empty; }
+  return { hits, misses, touchedEdges };
+}

package/lib/export-columns.mjs

@@ -18,6 +18,7 @@
 export const EXPORT_COLUMNS = [
   'id', 'memory_session_id', 'project', 'type', 'title', 'subtitle', 'narrative', 'text',
   'concepts', 'facts', 'files_read', 'files_modified', 'lesson_learned', 'search_aliases',
+  'scope',
   'importance', 'branch', 'access_count', 'cited_count', 'uncited_streak', 'injection_count',
   'decay_seen_count', 'last_accessed_at', 'created_at', 'created_at_epoch',
 ];

package/lib/file-edge-match.mjs

@@ -0,0 +1,44 @@
+// Single source of truth for the (obs,file) trigger-edge match predicate.
+//
+// Two consumers MUST stay in byte-identical agreement or injection and
+// attribution diverge (a lesson injected via an edge the resolver can't find
+// never resolves, and vice versa): scripts/pre-tool-recall.js (injection
+// trigger) and lib/edge-attribution.mjs (Stop-side hit/miss resolution).
+// Review 2026-07-14 found the pair enforced only by comments — this module
+// makes the parity mechanical.
+//
+// Semantics (P0 D#78, plus the review's case/backslash recall fix):
+// observation_files.filename is heterogeneous (bare basename, relative path,
+// absolute path, either separator, historical case variants). An edited file
+// matches an edge when the stored value is:
+//   1. the exact full path            (= COLLATE NOCASE — old LIKE was
+//   2. the exact bare basename         ASCII-case-insensitive; '=' alone is
+//                                      BINARY and silently dropped 'Utils.mjs')
+//   3. a path ending in '/<basename>' (LIKE, path boundary — blocks the
+//   4. a path ending in '\<basename>'  bash-utils.mjs-vs-utils.mjs suffix
+//                                      collision while keeping both separators)
+// LIKE wildcards in the basename are escaped (sqlite gotcha #9); LIKE itself
+// is ASCII-case-insensitive, matching arm 1/2's NOCASE.
+//
+// Dependency-free on purpose: pre-tool-recall.js is a ~30ms cold-start script.
+
+import { basename } from 'path';
+
+/**
+ * SQL boolean expression for the four-arm match. Placeholder order matches
+ * fileMatchParams. @param {string} [alias=''] table alias (e.g. 'of2').
+ */
+export function fileMatchClause(alias = '') {
+  const p = alias ? `${alias}.` : '';
+  return `(${p}filename = ? COLLATE NOCASE OR ${p}filename = ? COLLATE NOCASE ` +
+    `OR ${p}filename LIKE ? ESCAPE '\\' OR ${p}filename LIKE ? ESCAPE '\\')`;
+}
+
+/** Bind values for fileMatchClause, in placeholder order. */
+export function fileMatchParams(filePath) {
+  const fname = basename(filePath);
+  const escaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
+  // `%\\` before the basename: under ESCAPE '\', a literal backslash is
+  // written '\\' — so the JS string carries two backslash characters.
+  return [filePath, fname, `%/${escaped}`, `%\\\\${escaped}`];
+}

package/lib/observation-write.mjs

@@ -16,8 +16,18 @@ const OBS_COLUMNS = [
   'memory_session_id', 'project', 'text', 'type', 'title', 'subtitle',
   'narrative', 'concepts', 'facts', 'files_read', 'files_modified',
   'importance', 'minhash_sig', 'lesson_learned', 'search_aliases', 'branch',
-  'created_at', 'created_at_epoch',
+  'created_at', 'created_at_epoch', 'scope',
 ];
+
+// P3 (D#78): lesson applicability scope. Hard whitelist — Haiku output is
+// untrusted; anything outside the enum (including case variants) becomes NULL,
+// which every scope-aware read path treats as "unclassified, do not filter".
+const VALID_SCOPES = new Set(['file', 'module', 'project', 'environment']);
+
+/** Validate an LLM-emitted scope value against the enum; invalid → null. */
+export function normalizeScope(value) {
+  return typeof value === 'string' && VALID_SCOPES.has(value) ? value : null;
+}
 // Defaults for columns a caller omits. NULL-default columns (subtitle,
 // search_aliases) match the schema DEFAULT, so omitting == the old short INSERT.
 // concepts/facts/files_read default to the empty literals the manual path used.

package/mem-cli.mjs

@@ -39,7 +39,7 @@ 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, rejectBareStringFlags, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
-import { rebuildObservationDerived } from './lib/observation-write.mjs';
+import { rebuildObservationDerived, normalizeScope } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
 import { computeNoiseGauge } from './lib/stats-quality.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
@@ -1808,6 +1808,7 @@ function cmdRestore(db, argv) {
   const signalUpdate = db.prepare(`UPDATE observations SET
       text = COALESCE(?, text),
       subtitle = ?, concepts = ?, facts = ?, search_aliases = ?, files_read = ?, branch = COALESCE(?, branch),
+      scope = ?,
       access_count = ?, cited_count = ?, uncited_streak = ?, injection_count = ?,
       decay_seen_count = ?, last_accessed_at = ?
     WHERE id = ?`);
@@ -1854,6 +1855,9 @@ function cmdRestore(db, argv) {
         scrubSecrets(r.subtitle || ''), scrubSecrets(r.concepts || ''), scrubSecrets(r.facts || ''),
         r.search_aliases === null || r.search_aliases === undefined ? null : scrubSecrets(r.search_aliases),
         r.files_read || '[]', r.branch ?? null,
+        // v44 scope round-trip (review D#78): whitelist-validated; old backups
+        // without the column restore as NULL — same as pre-v44 behavior.
+        normalizeScope(r.scope),
         num(r.access_count), num(r.cited_count), num(r.uncited_streak), num(r.injection_count),
         num(r.decay_seen_count), r.last_accessed_at ?? null,
         res.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.46.0",
+  "version": "3.47.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",
@@ -61,6 +61,8 @@
     "lib/low-signal-patterns.mjs",
     "lib/private-strip.mjs",
     "lib/citation-tracker.mjs",
+    "lib/edge-attribution.mjs",
+    "lib/file-edge-match.mjs",
     "lib/cite-back-hint.mjs",
     "lib/tmp-fixture-sweep.mjs",
     "lib/summary-extractor.mjs",

package/schema.mjs

@@ -112,20 +112,44 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // silently drop event writes. NO new column, so LATEST_MIGRATION_COLUMN is unchanged — the
 // forced pass alone carries it (same pattern as v35/v36/v38/v39/v40); existing DBs run it
 // because version 41 != 42 falls through the fast-path.
-export const CURRENT_SCHEMA_VERSION = 42;
-
-// Sentinel column for the LATEST migration set. The fast-path uses this to
-// self-heal half-migrated DBs — schema_version bumped but column ALTERs rolled
-// back (observed once in dev during v2.74.0). Update both the column AND
-// (if needed) the table when adding a new migration batch.
-const LATEST_MIGRATION_COLUMN = { table: 'observations', column: 'last_cited_session_id' };
+// v43 (D#78 edge attribution): adds 4 columns to observation_files so each
+// (obs, file) trigger edge carries its own injection/citation record —
+// inject_count, miss_streak, last_resolved_session_id, last_cited_session_id.
+// Per-EDGE policy, deliberately separate from the per-obs decay counters on
+// observations (#8641: the two encode different policies — an edge that stops
+// firing must not bury the lesson on other surfaces). The ALTERs live NEXT TO
+// the observation_files CREATE (initSchema body), NOT in MIGRATIONS[] — that
+// array runs before the table exists on fresh DBs.
+// v44 (D#78 P3 scope label): observations.scope (file|module|project|
+// environment, NULL for legacy/manual rows) — where a lesson APPLIES,
+// decoupled from which files the episode touched. SEPARATE version from v43
+// on purpose: dev-mode hooks migrate the live DB between working-tree edits,
+// and a two-table batch under ONE version left a real DB at "43 with edge
+// columns, without scope" that the single sentinel could not detect (observed
+// 2026-07-14 on this machine's own DB). One version per migration batch keeps
+// the version number itself the detector. LATEST_MIGRATION_COLUMN advances to
+// observations.scope.
+export const CURRENT_SCHEMA_VERSION = 44;
+
+// Sentinel columns for the LATEST migration set(s). The fast-path uses these
+// to self-heal half-migrated DBs — schema_version bumped but column ALTERs
+// rolled back (observed once in dev during v2.74.0). Update the list when
+// adding a new migration batch. Plural since v44 (review D#78): v43 and v44
+// touch DIFFERENT tables, and a restore-from-old-backup can resurrect one
+// table's pre-migration shape while the version row and the other table stay
+// current — a single sentinel can't see that hole, so every recent batch
+// keeps a representative column here until it is ancient enough to retire.
+const LATEST_MIGRATION_COLUMNS = [
+  { table: 'observations', column: 'scope' },                      // v44
+  { table: 'observation_files', column: 'last_cited_session_id' }, // v43
+];
 
 function hasLatestMigrationColumn(db) {
   try {
-    const row = db.prepare(
+    const stmt = db.prepare(
       `SELECT 1 AS present FROM pragma_table_info(?) WHERE name = ?`
-    ).get(LATEST_MIGRATION_COLUMN.table, LATEST_MIGRATION_COLUMN.column);
-    return Boolean(row);
+    );
+    return LATEST_MIGRATION_COLUMNS.every(({ table, column }) => Boolean(stmt.get(table, column)));
   } catch {
     return false; // table itself missing → caller falls through to CORE_SCHEMA
   }
@@ -286,6 +310,12 @@ const MIGRATIONS = [
   // legacy rows read NULL and behave exactly as before until their first same-session
   // late cite.
   'ALTER TABLE observations ADD COLUMN last_cited_session_id TEXT DEFAULT NULL',
+  // v44 (D#78 P3): lesson applicability scope — file | module | project |
+  // environment, validated by lib/observation-write normalizeScope; NULL for
+  // legacy rows / manual saves / events. CLAUDE_MEM_SCOPE_FILTER=1 (opt-in)
+  // makes pre-tool-recall skip environment-scoped rows on file-triggered
+  // injection; NULL always passes the filter.
+  'ALTER TABLE observations ADD COLUMN scope TEXT DEFAULT NULL',
 ];
 
 /**
@@ -574,10 +604,28 @@ export function initSchema(db) {
     CREATE TABLE IF NOT EXISTS observation_files (
       obs_id INTEGER NOT NULL REFERENCES observations(id) ON DELETE CASCADE,
       filename TEXT NOT NULL,
+      inject_count INTEGER NOT NULL DEFAULT 0,
+      miss_streak INTEGER NOT NULL DEFAULT 0,
+      last_resolved_session_id TEXT DEFAULT NULL,
+      last_cited_session_id TEXT DEFAULT NULL,
       UNIQUE(obs_id, filename)
     )
   `);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obsfiles_filename ON observation_files(filename)`);
+  // v43 (D#78): per-edge attribution columns for DBs whose observation_files
+  // predates them — CREATE IF NOT EXISTS above is a no-op on those (gotcha #1),
+  // so each column gets its own idempotent ALTER (swallow duplicate-column only,
+  // same discipline as MIGRATIONS[]). Fresh DBs hit the duplicate branch.
+  for (const sql of [
+    'ALTER TABLE observation_files ADD COLUMN inject_count INTEGER NOT NULL DEFAULT 0',
+    'ALTER TABLE observation_files ADD COLUMN miss_streak INTEGER NOT NULL DEFAULT 0',
+    'ALTER TABLE observation_files ADD COLUMN last_resolved_session_id TEXT DEFAULT NULL',
+    'ALTER TABLE observation_files ADD COLUMN last_cited_session_id TEXT DEFAULT NULL',
+  ]) {
+    try { db.exec(sql); } catch (e) {
+      if (!e.message?.includes('duplicate column name')) throw e;
+    }
+  }
 
   // Data migration: populate observation_files from existing observations.files_modified JSON
   // Only runs once: when observation_files is empty but observations has rows with files_modified

package/scripts/pre-tool-recall.js

@@ -10,6 +10,7 @@ import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
+import { fileMatchClause, fileMatchParams } from '../lib/file-edge-match.mjs';
 import { fileIntelFor } from '../lib/file-intel.mjs';
 import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
 import { recordMetric } from '../lib/metrics.mjs';
@@ -58,6 +59,23 @@ const STALE_MS = 10 * 60 * 1000;   // 10 minutes cleanup threshold for legacy fi
 // small reads carry no noise. Env names mirror schema.mjs CLAUDE_MEM_* convention (#8447).
 const FILE_INTEL_OFF = ['0', 'off', 'false', 'no'].includes(
   String(process.env.CLAUDE_MEM_FILE_INTEL || '').toLowerCase());
+// P2 (D#78): edge-level decay ENFORCEMENT — opt-in (default OFF, shadow-first).
+// When on, a (obs,file) edge whose miss_streak reached K consecutive uncited
+// injections stops firing on this surface; the lesson stays reachable via
+// search / UPS / error-recall. P1 counting (Stop-side attribution) is always
+// on regardless of this flag. Flip only after real-DB cite-rate evidence.
+const EDGE_DECAY_ON = ['1', 'on', 'true', 'yes'].includes(
+  String(process.env.CLAUDE_MEM_EDGE_DECAY || '').toLowerCase());
+// NaN-checked, not `|| 3`: an explicit K=0 is falsy and would silently become
+// the default instead of clamping to the declared minimum of 1 (review D#78).
+const EDGE_DECAY_K_RAW = parseInt(process.env.CLAUDE_MEM_EDGE_DECAY_K, 10);
+const EDGE_DECAY_K = Math.max(1, Number.isNaN(EDGE_DECAY_K_RAW) ? 3 : EDGE_DECAY_K_RAW);
+// P3 (D#78): scope filter — opt-in (default OFF, shadow-first). When on,
+// environment-scoped observations (tooling/CI/network gotchas that apply in
+// ANY project) stop firing on FILE-triggered recall; they stay reachable via
+// search / UPS / error-recall. NULL scope (legacy / manual rows) always passes.
+const SCOPE_FILTER_ON = ['1', 'on', 'true', 'yes'].includes(
+  String(process.env.CLAUDE_MEM_SCOPE_FILTER || '').toLowerCase());
 const FILE_INTEL_MIN_TOKENS = Math.max(1,
   parseInt(process.env.CLAUDE_MEM_FILE_INTEL_MIN_TOKENS, 10) || 800);
 // Feature ② (repeated-read guard): when the agent does a FULL re-read of a file
@@ -323,9 +341,14 @@ try {
   try {
     const project = inferProject();
     const fname = basename(filePath);
-    // Escape LIKE wildcards
+    // Escape LIKE wildcards (still needed below for the events file_paths arms)
     const escaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
-    const likePattern = `%${escaped}`;
+    // P0 (D#78): path-boundary match — editing utils.mjs must NOT pull lessons
+    // stored under bash-utils.mjs (the old '%<basename>' suffix LIKE did).
+    // Clause + params come from lib/file-edge-match.mjs, byte-shared with the
+    // Stop-side edge attribution so trigger and resolver can never drift.
+    const fileMatch = fileMatchClause('of2');
+    const fileParams = fileMatchParams(filePath);
     // 60-day lookback to avoid surfacing ancient observations
     const cutoff = Date.now() - 60 * 86400000;
 
@@ -358,6 +381,30 @@ try {
     // merely-most-recent one. Single-match files unchanged (obsLimit=1 Read /
     // 2 Edit). Composes with v2.83.0 A1 to extend the citation-decay feedback
     // loop to the 85%-recall PreToolUse:Read/Edit path.
+    // P2 (D#78): decayed-edge filter. This readonly fast-path never migrates,
+    // so a pre-v43 DB has no miss_streak column and the filter would throw at
+    // prepare time — probe pragma_table_info and fall back to unfiltered
+    // (pre-v43 edges carry no counts anyway, so nothing would be filtered).
+    let edgeDecayFilter = '';
+    if (EDGE_DECAY_ON) {
+      try {
+        const hasCol = db.prepare(
+          `SELECT 1 FROM pragma_table_info('observation_files') WHERE name = 'miss_streak'`
+        ).get();
+        if (hasCol) edgeDecayFilter = `AND of2.miss_streak < ${EDGE_DECAY_K}`;
+      } catch { /* probe failure → unfiltered */ }
+    }
+    // P3 (D#78): environment-scope filter — same probe discipline (readonly
+    // fast-path may hit a pre-v43 DB where observations.scope doesn't exist).
+    let scopeFilter = '';
+    if (SCOPE_FILTER_ON) {
+      try {
+        const hasScope = db.prepare(
+          `SELECT 1 FROM pragma_table_info('observations') WHERE name = 'scope'`
+        ).get();
+        if (hasScope) scopeFilter = `AND (o.scope IS NULL OR o.scope != 'environment')`;
+      } catch { /* probe failure → unfiltered */ }
+    }
     const rows = db.prepare(`
       SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned
       FROM observations o
@@ -367,14 +414,16 @@ try {
         AND COALESCE(o.compressed_into, 0) = 0
         AND o.superseded_at IS NULL
         AND o.created_at_epoch > ?
-        AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
+        AND ${fileMatch}
+        ${edgeDecayFilter}
+        ${scopeFilter}
         ${typeFallback}
       ORDER BY
         CASE WHEN o.lesson_learned IS NOT NULL AND o.lesson_learned != '' THEN 0 ELSE 1 END,
         ${citeFactorClause('o')} DESC,
         o.created_at_epoch DESC
       LIMIT ${obsLimit}
-    `).all(project, cutoff, filePath, likePattern);
+    `).all(project, cutoff, ...fileParams);
 
     // T9: also query the `events` table — after T9, bugfix/lesson/decision/etc.
     // route here instead of observations, so we must read both sources to keep
@@ -382,12 +431,21 @@ try {
     // patterns match both basename and full-path entries. JSON quoting
     // (`"<name>"`) prevents partial-match false positives like "foo.mjs"
     // matching "myfoo.mjs".
-    const fnameEscaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
     const filePathEscaped = filePath.replace(/%/g, '\\%').replace(/_/g, '\\_');
     // v2.34.6: Read also tightens the events query — only rows with a non-empty
-    // body (= lesson equivalent). Edit path keeps the wider net since the agent
-    // is about to change the file and benefits from any contextual signal.
-    const eventsBodyFilter = isRead ? "AND body IS NOT NULL AND body != ''" : '';
+    // body (= lesson equivalent). Edit path keeps a wider net, but P0 (D#78)
+    // closes the parallel-path drift vs the observations query: a bodyless row
+    // is admitted only when it is a lesson-bearing type (bugfix/decision — the
+    // obs fallback's set — plus events-only 'lesson') AND its title isn't a
+    // LOW_SIGNAL auto-fallback; body-bearing rows outrank bodyless ones
+    // (mirrors the obs lesson-first sort). Known tradeoff: a deliberately
+    // bodyless manual event whose title starts with a LOW_SIGNAL prefix
+    // ('npm …', 'Error: …') no longer fires here — it stays reachable via
+    // search / UPS; /bug and /lesson write bodies, so this is a rare shape.
+    const eventsBodyFilter = isRead
+      ? "AND body IS NOT NULL AND body != ''"
+      : `AND ((body IS NOT NULL AND body != '')
+          OR (event_type IN ('bugfix', 'decision', 'lesson') AND ${buildNotLowSignalSql('')}))`;
     const eventsLimit = isRead ? 1 : 2;
     let eventRows = [];
     try {
@@ -400,9 +458,11 @@ try {
           AND created_at_epoch > ?
           AND (file_paths LIKE ? ESCAPE '\\' OR file_paths LIKE ? ESCAPE '\\')
           ${eventsBodyFilter}
-        ORDER BY created_at_epoch DESC
+        ORDER BY
+          CASE WHEN body IS NOT NULL AND body != '' THEN 0 ELSE 1 END,
+          created_at_epoch DESC
         LIMIT ${eventsLimit}
-      `).all(project, cutoff, `%"${fnameEscaped}"%`, `%"${filePathEscaped}"%`);
+      `).all(project, cutoff, `%"${escaped}"%`, `%"${filePathEscaped}"%`);
     } catch { /* events table may not exist on pre-v2.31 DBs — silent */ }
 
     // A3 (v2.83): cross-hook dedup. UPS may have already injected some of
@@ -410,10 +470,17 @@ try {
     // (and inflates context). Drop ids found in the cross-hook injected file
     // inside the staleness window; keep file-cooldown unchanged (the same
     // file might also re-warrant a different lesson next session).
+    // P1 (D#78): tag each row's source table — events share the numeric id
+    // space with observations, and the Stop-side edge attribution must never
+    // feed an event id into observation_files updates.
     const crossHookSeen = readCrossHookInjected(project);
+    const sourcedRows = [
+      ...rows.map(r => ({ ...r, src: 'obs' })),
+      ...eventRows.map(r => ({ ...r, src: 'evt' })),
+    ];
     const dedupedRows = crossHookSeen.size > 0
-      ? [...rows, ...eventRows].filter(r => !crossHookSeen.has(String(r.id)))
-      : [...rows, ...eventRows];
+      ? sourcedRows.filter(r => !crossHookSeen.has(String(r.id)))
+      : sourcedRows;
 
     // Merge: observations first (they carry richer lesson_learned), then events.
     // Edit/Write caps at 3 total; Read caps at 1 (single most-actionable hit).
@@ -537,6 +604,10 @@ try {
     cooldown[filePath] = {
       ts: now,
       lessonIds: allRows.map(r => r.id),
+      // P1 (D#78): observation-sourced ids only — consumed by the Stop-side
+      // edge attribution (lib/edge-attribution.mjs). lessonIds stays mixed for
+      // the cite-back hint contract.
+      obsIds: allRows.filter(r => r.src === 'obs').map(r => r.id),
       mode: isRead ? 'read' : 'edit',
       ...(lessonIdents ? { lessonIdents } : {}),
       ...(rereadMeta ? { reread: { mtimeMs: rereadMeta.mtimeMs, tokens: rereadMeta.tokens, full: isFullRead } } : {}),

package/source-files.mjs

@@ -49,6 +49,13 @@ export const SOURCE_FILES = [
   'lib/low-signal-patterns.mjs',
   'lib/private-strip.mjs',
   'lib/citation-tracker.mjs',
+  // v3.47 (D#78 P1): per-(obs,file) edge attribution. Imported by hook.mjs
+  // (handleStop edge resolution). Missing from manifest → tarball hook.mjs
+  // ERR_MODULE_NOT_FOUND on every Stop.
+  'lib/edge-attribution.mjs',
+  // v3.47 (D#78 P0): shared trigger-edge match predicate. Imported by BOTH
+  // scripts/pre-tool-recall.js (hook fast-path) and lib/edge-attribution.mjs.
+  'lib/file-edge-match.mjs',
   'lib/cite-back-hint.mjs',
   // v2.85: stale test-fixture sweeper. Imported by install.mjs (cleanup) + cli.mjs.
   // Missing from manifest → tarball ships install.mjs that ERR_MODULE_NOT_FOUND on cleanup.