claude-mem-lite 3.63.0 → 3.64.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.63.0",
+      "version": "3.64.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.63.0",
+  "version": "3.64.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-memory.mjs

@@ -3,6 +3,7 @@
 
 import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
 import { citeFactorJs } from './scoring-sql.mjs';
+import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
 import { extractIdents } from './lib/lesson-idents.mjs';
@@ -218,8 +219,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         AND o.project = ?
         AND o.importance >= 1
         AND o.created_at_epoch > ?
-        AND COALESCE(o.compressed_into, 0) = 0
-        AND o.superseded_at IS NULL
+        AND ${liveObsFilterSql('o')}
         AND ${notLowSignalTitleClause('o')}
       ORDER BY ${OBS_BM25}
       LIMIT 10
@@ -266,8 +266,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
           AND o.type IN ('decision', 'discovery')
           AND o.importance >= 2
           AND o.created_at_epoch > ?
-          AND COALESCE(o.compressed_into, 0) = 0
-          AND o.superseded_at IS NULL
+          AND ${liveObsFilterSql('o')}
           AND ${notLowSignalTitleClause('o')}
         ORDER BY ${OBS_BM25}
         LIMIT 5
@@ -316,7 +315,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // Adaptive threshold: scales with corpus size to filter noise.
     // Each result must individually exceed the threshold (not just the top one).
     const obsCount = db.prepare(
-      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL',
+      `SELECT COUNT(*) as c FROM observations WHERE project = ? AND ${liveObsFilterSql('')}`,
     ).get(project)?.c || 0;
     const { TINY, SMALL, MEDIUM, LARGE } = BM25_THRESHOLD;
     const threshold = obsCount < 5 ? TINY : obsCount < 100 ? SMALL : obsCount < 500 ? MEDIUM : LARGE;
@@ -389,8 +388,7 @@ export function recallForFile(db, filePath, project) {
       JOIN observation_files of2 ON of2.obs_id = o.id
       WHERE o.project = ?
         AND o.importance >= 2
-        AND COALESCE(o.compressed_into, 0) = 0
-        AND o.superseded_at IS NULL
+        AND ${liveObsFilterSql('o')}
         AND o.created_at_epoch > ?
         AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
       ORDER BY o.created_at_epoch DESC
@@ -431,8 +429,7 @@ export function rankImperativeCandidates(db, userPrompt, project, excludeIds = [
       SELECT id, title, lesson_learned, importance
       FROM observations
       WHERE project = ?
-        AND COALESCE(compressed_into, 0) = 0
-        AND superseded_at IS NULL
+        AND ${liveObsFilterSql('')}
         AND COALESCE(importance, 1) >= 2
         AND lesson_learned IS NOT NULL
         AND TRIM(lesson_learned) != ''

package/hook.mjs

@@ -68,6 +68,8 @@ import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
+import { injectedIdsFileName } from './lib/injected-ids.mjs';
+import { liveObsFilterSql, recencyDecaySql } from './lib/inject-search-core.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
@@ -491,15 +493,12 @@ function triggerErrorRecall(db, toolInput, response) {
         -- only for symmetry: the block's own footer is a mem_get(ids=...) pointer, and a
         -- COMPRESSED_PENDING_PURGE row is queued for deletion by maintain purge_stale,
         -- so that pointer would resolve to nothing.
-        AND COALESCE(o.compressed_into, 0) = 0
-        AND o.superseded_at IS NULL
+        AND ${liveObsFilterSql('o')}
         AND ${notLowSignalTitleClause('o')}
-      -- MAX(0, …) clamps recency age to >= 0 (parity with search-engine FULL_SCORE):
-      -- a far-future created_at (reachable via restore/import-jsonl, which accept
-      -- arbitrary epochs) made the exponent large-positive → EXP overflow → that row
-      -- pinned #1 for every error until its "future" passed (audit 2026-08-14 M-1).
+      -- Decay via the shared core (P2-11): the M-1 MAX(0,…) age clamp lives there.
+      -- Fixed 14d half-life (error recency matters more than obs type here).
       ORDER BY ${OBS_BM25}
-        * (1.0 + EXP(-0.693 * MAX(0, ? - o.created_at_epoch) / 1209600000.0))
+        * ${recencyDecaySql({ tsExpr: 'o.created_at_epoch', halfLifeSql: '1209600000.0' })}
       LIMIT 3
     `).all(ftsQuery, project, nowR);
 
@@ -857,16 +856,21 @@ function buildCiteRecallNudge(project) {
   return libBuildCiteRecallNudge(project, RUNTIME_DIR);
 }
 
-// GC pre-recall cooldown files older than 24h. Pulled out of pre-tool-recall.js
-// (where it ran on every Edit, costing 15-30 disk stats per call on long-lived
-// projects) and consolidated here — once per SessionStart is enough to keep
-// RUNTIME_DIR from growing unbounded across stale sessions.
+// GC stale per-session runtime files older than 24h: pre-recall cooldowns AND
+// (D#120) the per-session injected-ids markers — both grow one file per session.
+// Pulled out of pre-tool-recall.js (where it ran on every Edit, costing 15-30
+// disk stats per call on long-lived projects) and consolidated here — once per
+// SessionStart is enough to keep RUNTIME_DIR from growing unbounded.
 const PRE_RECALL_COOLDOWN_STALE_MS = 24 * 60 * 60 * 1000;
 function gcStalePreRecallCooldowns() {
   try {
     const now = Date.now();
     for (const name of readdirSync(RUNTIME_DIR)) {
-      if (!name.startsWith('pre-recall-cooldown-') || !name.endsWith('.json')) continue;
+      // D#120: the injected-ids marker is also per-session now — same growth
+      // shape as the cooldown files, same 24h GC (dedup window is 5 min).
+      const isCooldown = name.startsWith('pre-recall-cooldown-') && name.endsWith('.json');
+      const isInjectedMarker = name.startsWith('.claude-mem-injected-');
+      if (!isCooldown && !isInjectedMarker) continue;
       try {
         const p = join(RUNTIME_DIR, name);
         const st = statSync(p);
@@ -1036,10 +1040,8 @@ function runSessionStartAutoMaintain(db) {
         JOIN observations b ON a.title = b.title AND a.project = b.project
           AND a.id < b.id
           AND ABS(a.created_at_epoch - b.created_at_epoch) < 3600000
-          AND COALESCE(a.compressed_into, 0) = 0
-          AND COALESCE(b.compressed_into, 0) = 0
-          AND a.superseded_at IS NULL
-          AND b.superseded_at IS NULL
+          AND ${liveObsFilterSql('a')}
+          AND ${liveObsFilterSql('b')}
         LIMIT 20
       `).all();
       if (dupPairs.length > 0) {
@@ -1062,8 +1064,7 @@ function runSessionStartAutoMaintain(db) {
         const recent = db.prepare(`
           SELECT id, title, importance, created_at_epoch, narrative, text
           FROM observations
-          WHERE COALESCE(compressed_into, 0) = 0
-            AND superseded_at IS NULL
+          WHERE ${liveObsFilterSql('')}
             AND created_at_epoch > ?
             AND title IS NOT NULL AND title != ''
           ORDER BY created_at_epoch DESC LIMIT ${SCAN_LIMIT}
@@ -1661,12 +1662,14 @@ async function handleUserPrompt() {
 
       // Read IDs already injected by user-prompt-search.js to avoid duplicate injection
       try {
-        const injectedFile = join(RUNTIME_DIR, `.claude-mem-injected-${project}`);
+        // D#120: the marker file is session-keyed (no ccSessionId → legacy
+        // project-keyed name), so a concurrent session's write can no longer
+        // replace this session's payload between the UPS write and this read.
+        const injectedFile = join(RUNTIME_DIR, injectedIdsFileName(project, ccSessionId));
         const raw = readFileSync(injectedFile, 'utf8');
         const { ids, ts, session } = JSON.parse(raw);
         // Only use if written within last 10 seconds (same prompt cycle) AND by this
-        // CC session — the file is project-keyed, so a concurrent session's write
-        // would otherwise dedup-suppress OUR injection (M-6, audit 2026-08-14).
+        // CC session (M-6 payload gate, still load-bearing for legacy files).
         // Legacy payloads without `session` keep the old time-window-only behavior.
         if (ts && Date.now() - ts < 10000 && Array.isArray(ids)
             && !(session && ccSessionId && session !== ccSessionId)) {

package/lib/browse-core.mjs

@@ -0,0 +1,67 @@
+// lib/browse-core.mjs — shared data collection for the CLI `browse` / MCP
+// `mem_browse` twin (P2-12, audit 2026-08-14). The tier count + row queries were
+// duplicated and had already drifted (the CLI SELECT carried `importance`, the
+// MCP one had dropped it). Collection lives here with the superset column shape;
+// each face keeps its own rendering (text dashboard vs --json vs MCP text).
+
+import { TIER_CASE_SQL, tierSqlParams } from '../tier.mjs';
+import { liveObsFilterSql } from './inject-search-core.mjs';
+
+export const BROWSE_TIERS = ['working', 'active', 'archive'];
+export const BROWSE_TIER_LABELS = { working: '🔴 Working Memory', active: '🟡 Active Memory', archive: '🔵 Archive' };
+
+/** Newest active memory_session_id for the project ('' when none) — the tier
+ *  classifier's "current session" input, needed identically by both faces. */
+export function getActiveMemorySessionId(db, project) {
+  const row = db.prepare(
+    "SELECT memory_session_id FROM sdk_sessions WHERE project = ? AND status = 'active' ORDER BY started_at_epoch DESC LIMIT 1"
+  ).get(project);
+  return row?.memory_session_id ?? '';
+}
+
+/**
+ * Collect per-tier counts + rows for the memory dashboard.
+ * Archive keeps its count but skips row fetch in the unfiltered view (both faces'
+ * documented behavior — the archive tail is reachable via `browse --tier archive`).
+ * @returns {{showTiers: string[], tierData: object, tierCounts: object, grandTotal: number}}
+ */
+export function collectBrowseTiers(db, { project, tierFilter, limit, now, currentSessionId }) {
+  const ctx = { now, currentProject: project, currentSessionId };
+  const params = tierSqlParams(ctx);
+  const showTiers = tierFilter ? [tierFilter] : BROWSE_TIERS;
+
+  const tierData = {};
+  const tierCounts = {};
+  let grandTotal = 0;
+
+  for (const tier of showTiers) {
+    const countRow = db.prepare(`
+      SELECT COUNT(*) as c FROM (
+        SELECT ${TIER_CASE_SQL} as tier FROM observations
+        WHERE project = ? AND ${liveObsFilterSql('')}
+      ) WHERE tier = ?
+    `).get(...params, project, tier);
+    const count = countRow?.c ?? 0;
+    tierCounts[tier] = count;
+    grandTotal += count;
+
+    const skipRows = tier === 'archive' && !tierFilter;
+    if (count === 0 || skipRows) {
+      tierData[tier] = { count, rows: [] };
+      continue;
+    }
+
+    const rows = db.prepare(`
+      SELECT * FROM (
+        SELECT id, type, title, importance, created_at, created_at_epoch, ${TIER_CASE_SQL} as tier
+        FROM observations
+        WHERE project = ? AND ${liveObsFilterSql('')}
+      ) WHERE tier = ?
+      ORDER BY created_at_epoch DESC
+      LIMIT ?
+    `).all(...params, project, tier, limit);
+    tierData[tier] = { count, rows };
+  }
+
+  return { showTiers, tierData, tierCounts, grandTotal };
+}

package/lib/delete-core.mjs

@@ -7,7 +7,7 @@
 // merged/compressed-child recovery, and the delete transaction.
 import { snapshotDb } from './db-backup.mjs';
 import { recoverChildrenOf } from './maintain-core.mjs';
-import { debugCatch } from '../utils.mjs';
+import { debugCatch, truncate } from '../utils.mjs';
 
 /**
  * Hard-delete the given observation ids with full orchestration. The CALLER owns
@@ -70,3 +70,20 @@ export function deleteObservations(db, ids, { snapshotTag = 'pre-delete' } = {})
   const result = deleteTx();
   return { deleted: result.changes, recoveredChildren: result.recovered, snapshotPath };
 }
+
+/**
+ * Shared delete-preview body (P2-12): fetch the doomed rows and format the
+ * per-row lines both faces print between their own header ("Preview: N …")
+ * and footer (--confirm vs confirm=true remedy). The SELECT and the row shape
+ * were duplicated in mem-cli.mjs + server.mjs and are the exact place a
+ * preview/execute drift would hide.
+ * @param {import('better-sqlite3').Database} db
+ * @param {number[]} ids
+ * @returns {{rows: Array<{id:number,type:string,title:string,project:string}>, lines: string[]}}
+ */
+export function previewDeleteRows(db, ids) {
+  const ph = ids.map(() => '?').join(',');
+  const rows = db.prepare(`SELECT id, type, title, project FROM observations WHERE id IN (${ph})`).all(...ids);
+  const lines = rows.map((r) => `  #${r.id} [${r.type}] ${truncate(r.title || '(untitled)', 80)} | ${r.project}`);
+  return { rows, lines };
+}

package/lib/get-core.mjs

@@ -0,0 +1,33 @@
+// lib/get-core.mjs — shared core for the CLI `get` / MCP `mem_get` twin (P2-12,
+// audit 2026-08-14). The 23-element OBS_FIELDS array was duplicated verbatim in
+// mem-cli.mjs and server.mjs (the 16-vs-24-column export data-loss incident's
+// precursor shape), and the session detail field sets had ALREADY diverged
+// (MCP 13 fields vs CLI 6 — a `remaining_items` FTS hit was a dead end in the
+// CLI detail view). Field sets + the access-bump fetch live here; each face
+// keeps its own header/label rendering conventions.
+
+import { autoBoostIfNeeded } from '../search-scoring.mjs';
+
+/** Every observation column `get --fields` accepts, in render order. */
+export const OBS_FIELDS = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
+
+/** Session-summary detail render set — the FULL set (both faces). The CLI's old
+ *  6-field subset made notes/remaining_items/files_* searchable-but-unrenderable. */
+export const SESSION_DETAIL_FIELDS = ['id', 'request', 'investigated', 'learned', 'completed', 'next_steps', 'remaining_items', 'files_read', 'files_edited', 'notes', 'project', 'created_at', 'memory_session_id', 'prompt_number'];
+
+/**
+ * Fetch observation detail rows: bump access_count/last_accessed_at (reading a
+ * detail IS an access signal — feeds noisePenalty's ratio guard), run the
+ * auto-boost heuristic, and return rows oldest-first.
+ * @param {import('better-sqlite3').Database} db
+ * @param {number[]} ids
+ * @returns {object[]} full observation rows (SELECT *), created order
+ */
+export function fetchObsDetail(db, ids) {
+  const ph = ids.map(() => '?').join(',');
+  try {
+    db.prepare(`UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${ph})`).run(Date.now(), ...ids);
+    autoBoostIfNeeded(db, ids);
+  } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
+  return db.prepare(`SELECT * FROM observations WHERE id IN (${ph}) ORDER BY created_at_epoch ASC`).all(...ids);
+}

package/lib/inject-search-core.mjs

@@ -0,0 +1,84 @@
+// lib/inject-search-core.mjs — the injection-side shared core (P2-11, audit
+// 2026-08-14). Shared home for the three SQL atoms that kept drifting across
+// hand-copied twins on the INJECTION-side retrieval surfaces (the five consumer
+// files the ledger test enforces — NOT yet the whole read surface: recall-core /
+// recent-core / timeline-core / hook-context / hook-handoff / hook-optimize /
+// deep-search / stats and the sessions/events decay arms in lib/search-core
+// still inline their own copies; extending them is the deferred second cut):
+//
+//   * live-row filter        — the compressed+superseded pair whose omission was
+//                              the superseded-invariant's recurring reopening
+//                              (7th occurrence fixed in v3.63 H-1, write-side)
+//   * clamped recency decay  — the MAX(0,…) age clamp (audit M-1: a far-future
+//                              created_at from restore/import-jsonl EXP-overflowed
+//                              and pinned that row #1; the fix reached
+//                              search-engine but not the UPS/error-recall twins)
+//   * injection relevance    — the full multiplicative chain incl. cite/noise
+//                              behavior factors (audit M-3: wired on every auto
+//                              surface, missing from the explicit-surface score)
+//
+// Consumers: scripts/user-prompt-search.js, scripts/pre-tool-recall.js,
+// hook-memory.mjs, hook.mjs (error-recall), search-engine.mjs. Each surface keeps
+// its own deliberate pipeline composition (BM25-sort + JS scoring vs SQL full
+// chain vs file-keyed sort — see #8786: per-surface asymmetries stay explicit);
+// only the ATOMS are shared. tests/inject-search-core.test.mjs holds the ledger:
+// the five consumer files must compose these builders, never re-inline copies.
+//
+// Lives under lib/ (not scripts/) so hook.mjs can statically import it without
+// colliding with the installExtractedRelease scripts-dir rename (same constraint
+// as lib/mem-override.mjs). Dependency-light by design: pre-tool-recall's
+// standalone fast-path (#8447) already imports scoring-sql.mjs.
+
+import {
+  OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE,
+  noisePenaltyClause, citeFactorClause,
+} from '../scoring-sql.mjs';
+
+/**
+ * Live-row filter: rows a model-facing retrieval surface may return. Excludes
+ * compression tombstones (positive keeper ids AND -2 pending-purge) and
+ * superseded rows (a retracted lesson must never outrank its correction).
+ * @param {string} [alias='o'] table alias; '' for unqualified single-table queries
+ * @returns {string} SQL boolean expression (no leading AND)
+ */
+export function liveObsFilterSql(alias = 'o') {
+  const a = alias ? `${alias}.` : '';
+  return `COALESCE(${a}compressed_into, 0) = 0 AND ${a}superseded_at IS NULL`;
+}
+
+/**
+ * Clamped recency-decay factor: (1 + EXP(-ln2 · age / halfLife)), age >= 0.
+ * The MAX(0,…) clamp is the M-1 fix — restore/import-jsonl accept arbitrary
+ * epochs, and an unclamped future timestamp makes the exponent large-positive →
+ * EXP overflows to +Infinity → that row sorts #1 for every query (and its score
+ * serializes as null). A future row reads as age 0 = max finite recency instead.
+ * Binds one `?` placeholder: the caller passes `now` (epoch ms) at that position.
+ * @param {object} opts
+ * @param {string} opts.tsExpr - SQL expression for the row's reference timestamp
+ *   (e.g. 'o.created_at_epoch', or the created/last-accessed MAX search-engine uses)
+ * @param {string} [opts.halfLifeSql=TYPE_DECAY_CASE] - SQL expression for the
+ *   half-life in ms (constant or per-type CASE; TYPE_DECAY_CASE assumes alias 'o')
+ * @returns {string} SQL numeric expression (parenthesized)
+ */
+export function recencyDecaySql({ tsExpr, halfLifeSql = TYPE_DECAY_CASE }) {
+  return `(1.0 + EXP(-0.693 * MAX(0, ? - ${tsExpr}) / ${halfLifeSql}))`;
+}
+
+/**
+ * Injection relevance: the full multiplicative chain the prompt-time injection
+ * surface (UPS searchByFts) ranks by — BM25 × clamped type-decay × type-quality
+ * × importance × noise penalty × cite factor. Alias is fixed to 'o' because
+ * TYPE_DECAY_CASE / TYPE_QUALITY_CASE bake that alias in.
+ * Binds one `?` placeholder (the decay `now`), first in parameter order.
+ * @param {string} [alias='o'] must be 'o'
+ * @returns {string} SQL numeric expression
+ */
+export function injectionRelevanceSql(alias = 'o') {
+  if (alias !== 'o') throw new Error('injectionRelevanceSql: alias must be "o" (TYPE_*_CASE bake it in)');
+  return `${OBS_BM25}
+             * ${recencyDecaySql({ tsExpr: 'o.created_at_epoch' })}
+             * ${TYPE_QUALITY_CASE}
+             * (0.5 + 0.5 * COALESCE(o.importance, 1))
+             * ${noisePenaltyClause('o')}
+             * ${citeFactorClause('o')}`;
+}

package/lib/injected-ids.mjs

@@ -0,0 +1,29 @@
+// lib/injected-ids.mjs — file-name derivation for the cross-hook injected-ids
+// dedup marker. Single source of truth for user-prompt-search.js (writer),
+// pre-tool-recall.js (read/merge), and hook.mjs (path-A reader): all three must
+// derive the same name or cross-hook dedup silently goes blind.
+//
+// D#120: M-6 session-keyed the marker's PAYLOAD but kept ONE file per project,
+// so two concurrent CC windows full-replaced each other's marker — no dedup
+// between them and `count` reset on every alternation (MAX_SESSION_INJECTIONS
+// unreachable). One file per SESSION instead, mirroring
+// pre-recall-cooldown-<session>.json in the same runtime dir. GC: session-start
+// sweep in hook.mjs (24h mtime, same policy as the cooldown files).
+//
+// Lives under lib/ (not scripts/) so hook.mjs can statically import it without
+// colliding with the scripts/ directory rename in installExtractedRelease —
+// same constraint as lib/mem-override.mjs.
+
+/**
+ * Runtime-dir FILE NAME for the injected-ids marker (no directory component).
+ * No sessionId → legacy project-keyed name (env-less harnesses, old callers).
+ * @param {string} project - inferProject() value (already filename-safe)
+ * @param {string} [sessionId] - CC session id
+ * @returns {string}
+ */
+export function injectedIdsFileName(project, sessionId) {
+  const base = `.claude-mem-injected-${project}`;
+  if (!sessionId) return base;
+  const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+  return `${base}-${safe}`;
+}

package/lib/observation-write.mjs

@@ -9,7 +9,7 @@
 // + vector writes in one db.transaction so a failure can't leave a partial row).
 
 import { getVocabulary, computeVector, vectorsEnabled } from '../tfidf.mjs';
-import { debugCatch, cjkBigrams } from '../utils.mjs';
+import { debugCatch, cjkBigrams, scrubSecrets } from '../utils.mjs';
 
 // Canonical column order — must mirror the observations schema (schema.mjs).
 const OBS_COLUMNS = [
@@ -84,7 +84,9 @@ export function insertObservationVector(db, obsId, vecText) {
  * block — the same drift class #8614/#8639 closed for compress/maintain. Caller
  * owns the transaction (vector write is internally non-critical).
  */
-export function rebuildObservationDerived(db, obsId) {
+// P2-12: internal-only since applyObsUpdate became the single update choke point
+// (both faces previously imported this directly; un-exported per knip discipline).
+function rebuildObservationDerived(db, obsId) {
   const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts, lesson_learned, search_aliases FROM observations WHERE id = ?').get(obsId);
   if (!row) return;
   const base = [row.title, row.subtitle, row.narrative, row.concepts, row.facts, row.lesson_learned, row.search_aliases].filter(Boolean).join(' ');
@@ -93,3 +95,37 @@ export function rebuildObservationDerived(db, obsId) {
   db.prepare('UPDATE observations SET text = ? WHERE id = ?').run(textField, obsId);
   insertObservationVector(db, obsId, textField);
 }
+
+// P2-12 (audit 2026-08-14): shared update mutation for the CLI `update` / MCP
+// `mem_update` twin. Both faces previously built the SET list + ran the
+// transaction + rebuild inline (byte-equivalent copies); each keeps its own
+// validation front-end (CLI flag guards / MCP zod) and passes only the fields
+// it accepted. String values are secret-scrubbed here — the single choke point,
+// so a new face can't forget it (concepts had already slipped through once).
+const UPDATABLE_OBS_COLS = ['title', 'narrative', 'type', 'importance', 'lesson_learned', 'concepts'];
+
+/**
+ * Apply a validated field patch to one observation: UPDATE + derived-column
+ * rebuild (FTS text + vector) in one transaction.
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} id - observation id (caller has verified existence)
+ * @param {object} fields - subset of {title, narrative, type, importance, lesson_learned, concepts}
+ * @returns {string[]} column names actually updated ([] = nothing to do, no write)
+ */
+export function applyObsUpdate(db, id, fields) {
+  const updates = [];
+  const params = [];
+  for (const col of UPDATABLE_OBS_COLS) {
+    if (fields[col] !== undefined) {
+      updates.push(`${col} = ?`);
+      params.push(typeof fields[col] === 'string' ? scrubSecrets(fields[col]) : fields[col]);
+    }
+  }
+  if (updates.length === 0) return [];
+  params.push(id);
+  db.transaction(() => {
+    db.prepare(`UPDATE observations SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+    rebuildObservationDerived(db, id);
+  })();
+  return updates.map((u) => u.split(' =')[0]);
+}

package/lib/search-core.mjs

@@ -258,7 +258,16 @@ export function searchEventsFts(db, { ftsQuery, project = null, projectBoost = n
 // obs/event/session BM25 live on comparable scales (weighted bm25 × decay ×
 // project-boost), so the ratio is meaningful there; small-scale sources (prompts,
 // bm25 ≈ -1) can only be penalized by this comparison, never inflated — the safe
-// direction. Bands (ratio = |lone| / globalMaxAbs, first match wins):
+// direction.
+// D#121 (2026-08-16): obs FULL_SCORE additionally carries citeFactor (0.4–3.0) ×
+// noisePenalty (0.2–1.0) — behavior state events/sessions never have. A heavily-
+// cited obs can therefore widen globalMaxAbs and demote a lone event's band: this
+// is ACCEPTED direction (cite is genuine relevance evidence), and it is BOUNDED —
+// citeFactor caps at 3.0, so a lone hit that was the raw max keeps ratio >= 1/3
+// and never sinks below the -0.5 neutral mid; noise only shrinks obs (can only
+// IMPROVE the lone hit's band). Real-SQL pins: benchmark/events-pipeline-probes.mjs
+// (cite-widening-bounded-3x / decisive-lone-event-survives-max-cite / noise-shrink).
+// Bands (ratio = |lone| / globalMaxAbs, first match wins):
 //   ratio ≥ 1   → -1.05  the lone hit IS the strongest raw match anywhere: rank it
 //                        strictly ahead of every normalized -1 (ties in raw
 //                        strength resolve toward the lone hit — the [-1, 0] band