@lh8ppl/claude-memory-kit 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   "dependencies": {
     "@lh8ppl/cmk-canonicalize": "0.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.10.0",
+    "better-sqlite3": "^12.11.1",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "js-yaml": "^4.2.0",

package/src/audit-log.mjs

@@ -33,6 +33,7 @@ export const REASON_CODES = Object.freeze({
   FACT_CREATED: 'fact-created', // writeFact: a new fact file was written (Task 123.A — the default create audit; callers emitting a richer code opt out via audit:false)
   DUPLICATE: 'duplicate', // writeFact: same path + same id
   DUPLICATE_ELSEWHERE: 'duplicate-elsewhere', // writeFact: different path + same id
+  RECURRENCE: 'recurrence', // writeFact: a duplicate write = the same canonical fact re-surfaced → recurrence_count bumped (Task 151.1, ADR-0016 — the capped-recurrence promotion signal)
   INDEX_REBUILD_FAILED: 'index-rebuild-failed', // writeFact: the fact landed on disk but the best-effort INDEX.md rebuild threw (e.g. a detached auto-extract child killed mid-rebuild). Surfaces what was previously a SILENTLY swallowed catch (D-152) so a lagging committed INDEX is diagnosable; the next reindex/cmk reindex self-heals.
   USER_REQUESTED: 'user-requested', // forget: user-initiated tombstone
   CURATED_MERGE: 'curated-merge', // mergeFacts: explicit merge of A + B → C

package/src/auto-persona.mjs

@@ -50,6 +50,7 @@ import { memoryWrite } from './memory-write.mjs';
 import { detectConflicts } from './conflict-queue.mjs';
 import { appendAuditEntry, REASON_CODES } from './audit-log.mjs';
 import { DEFAULT_COOLDOWN_MS, isCooldownActive, touchCooldownMarker } from './cooldown.mjs';
+import { PROMOTE_THRESHOLD } from './heat.mjs';
 
 // User-tier scratchpads auto-persona is allowed to promote into. A
 // classifier-named target outside this set is dropped defensively (the
@@ -80,8 +81,19 @@ export const PERSONA_CANDIDATE_RE =
 // Generous (facts are high-signal) but bounded; whole facts only (see below).
 export const PERSONA_CORPUS_BYTES = 60_000;
 
-function assembleProjectCorpus({ projectRoot, userDir }) {
+// Assemble the tier-P fact corpus AND the cite-and-sum recurrence index (151.3).
+// Returns { corpus, factIndex }:
+//   - corpus: the classifier input. Each fact is headed `### [P-XXXXXXXX] title`
+//     so the classifier has a stable HANDLE to cite in `source_fact_ids=[…]`.
+//   - factIndex: Map<id, recurrence_count> for the facts ACTUALLY in the corpus
+//     (an id dropped by the byte cap isn't citable — the LLM never saw it — so it
+//     isn't in the index either). resolveRecurrenceSum uses this to validate cited
+//     ids + sum their real recurrence_count (the gate — code counts, LLM doesn't).
+// Scratchpad bullets have no per-bullet id/recurrence_count, so they appear in the
+// corpus (still useful synthesis context) but contribute no citable index entries.
+export function assembleProjectCorpus({ projectRoot, userDir }) {
   const sources = listObservationSources({ projectRoot, userDir });
+  // {part, id, recurrenceCount}; id/recurrenceCount null for scratchpad parts.
   const parts = [];
   for (const s of sources) {
     if (s.tier !== 'P') continue;
@@ -93,10 +105,17 @@ function assembleProjectCorpus({ projectRoot, userDir }) {
     }
     if (s.kind === 'fact') {
       const { frontmatter, body } = parse(content);
-      const title = frontmatter?.title ?? frontmatter?.id ?? '';
-      parts.push(`### ${title}\n${(body ?? '').trim()}`);
+      const id = frontmatter?.id ?? null;
+      const title = frontmatter?.title ?? id ?? '';
+      // 151.1: recurrence_count is the gate signal; a fact predating the field
+      // (or with a bad value) counts as 1 — a single occurrence.
+      const rc = frontmatter?.recurrence_count;
+      const recurrenceCount = Number.isFinite(rc) && rc > 0 ? rc : 1;
+      // Lead the heading with the citable id so the classifier can echo it.
+      const head = id ? `### [${id}] ${title}` : `### ${title}`;
+      parts.push({ part: `${head}\n${(body ?? '').trim()}`, id, recurrenceCount });
     } else {
-      parts.push((content ?? '').trim());
+      parts.push({ part: (content ?? '').trim(), id: null, recurrenceCount: null });
     }
   }
   // Task 111 (F-2): BOUND the corpus. Previously this joined EVERY tier-P fact
@@ -110,9 +129,10 @@ function assembleProjectCorpus({ projectRoot, userDir }) {
   // timed-out zero. A value-ordered (trust/recency-first) accumulation is the
   // follow-up if a large corpus drops doctrine.
   const out = [];
+  const factIndex = new Map();
   let used = 0;
   let truncated = false;
-  for (const part of parts.filter(Boolean)) {
+  for (const { part, id, recurrenceCount } of parts.filter((p) => p.part)) {
     const cost = Buffer.byteLength(part, 'utf8') + 2; // +2 for the '\n\n' join
     if (used + cost > PERSONA_CORPUS_BYTES) {
       truncated = true;
@@ -120,9 +140,11 @@ function assembleProjectCorpus({ projectRoot, userDir }) {
     }
     out.push(part);
     used += cost;
+    // Index only facts that actually made it into the corpus (citable).
+    if (id) factIndex.set(id, recurrenceCount);
   }
   if (truncated) out.push('### …\n(corpus truncated — additional project facts omitted for this pass)');
-  return out.join('\n\n');
+  return { corpus: out.join('\n\n'), factIndex };
 }
 
 // Default size of the recent-transcript window handed to the SessionEnd persona
@@ -231,13 +253,32 @@ export function buildClassifierInstructions(source = 'facts') {
   const beginMarker = isTranscript
     ? '=== BEGIN RECENT CONVERSATION ==='
     : '=== BEGIN CAPTURED PROJECT FACTS ===';
+  // 151.3 (cite-and-sum, D-230): on the FACTS path each input fact is headed
+  // `### [P-XXXXXXXX] title`, so the classifier can CITE the facts it synthesized
+  // a trait from. It cites — it does NOT count. Code resolves the cited ids and
+  // sums their real recurrence_count (the gate). The transcript path has no
+  // citable ids, so it keeps the simpler line + the confidence fast-path only.
+  const outputFormat = isTranscript
+    ? 'PERSONA CANDIDATE | target=<FILE> | section=<SECTION> | confidence=<high|medium|low> | <one-line restatement>'
+    : 'PERSONA CANDIDATE | target=<FILE> | section=<SECTION> | confidence=<high|medium|low> | <one-line restatement> | source_fact_ids=[<the [P-...] ids of the facts you synthesized THIS trait from>]';
+  const citeBlock = isTranscript
+    ? []
+    : [
+        '',
+        'CITING SOURCE FACTS (required on every line):',
+        '  - Each input fact is headed `### [P-XXXXXXXX] <title>`. In source_fact_ids, list the [P-...] ids of the facts THIS trait was synthesized from — copy them EXACTLY as shown.',
+        '  - CITE the facts; do NOT count anything and do NOT invent a number. The kit sums the cited facts\' real recurrence on its own.',
+        '  - Cite ONLY ids that appear in the input. Never invent an id.',
+        '  - Example: `… | source_fact_ids=[P-AAAAAAAA, P-BBBBBBBB]`',
+      ];
   return [
     opener,
     '',
     jobLine,
     '',
     'For EACH cross-project fact, emit exactly one line, nothing else, in this EXACT format:',
-    'PERSONA CANDIDATE | target=<FILE> | section=<SECTION> | confidence=<high|medium|low> | <one-line restatement>',
+    outputFormat,
+    ...citeBlock,
     '',
     'Routing:',
     '  - target=HABITS.md  → working-style habits. sections: Iteration Cadence | Destructive Operations | Communication Style',
@@ -264,12 +305,77 @@ export function parsePersonaCandidates(outputText) {
       target: target.trim(),
       section: section.trim(),
       confidence: confidence.trim().toLowerCase(),
-      text: text.trim(),
+      ...splitSourceFactIds(text.trim()),
     });
   }
   return candidates;
 }
 
+// The cite-and-sum suffix the classifier appends to a candidate line (151.3,
+// ADR-0016 / D-230): `… | source_fact_ids=[P-AAAAAAAA, P-BBBBBBBB]`. It cites the
+// PROJECT facts the trait was synthesized from — NOT a recurrence COUNT (5/5
+// bridge-study systems reject the LLM counting; the LLM groups, code counts).
+// Optional + trailing so a line WITHOUT it still parses (back-compat: the
+// transcript path has no fact ids to cite, and an older classifier prompt omits
+// it) — such a candidate gets `sourceFactIds: []` and can only promote via the
+// explicit-imperative (confidence=high) fast-path.
+const SOURCE_FACT_IDS_RE = /\s*\|\s*source_fact_ids=\[([^\]]*)\]\s*$/;
+
+// Split a candidate's free-text tail into {text, sourceFactIds}. The ids are
+// peeled off the END (the classifier appends them last), leaving the human-
+// readable restatement as `text`. Ids are UPPER-CASED (canonical ids are always
+// uppercase `P-…`; a lowercase echo from Haiku — despite "copy EXACTLY" — would
+// otherwise miss the Map lookup) + de-noised; the real corpus-resolution
+// (rejecting hallucinations) happens in resolveRecurrenceSum.
+function splitSourceFactIds(tail) {
+  const m = SOURCE_FACT_IDS_RE.exec(tail);
+  if (!m) return { text: tail, sourceFactIds: [] };
+  const text = tail.slice(0, m.index).trim();
+  const sourceFactIds = m[1]
+    .split(',')
+    .map((s) => s.trim().toUpperCase())
+    .filter(Boolean);
+  return { text, sourceFactIds };
+}
+
+/**
+ * THE cite-and-sum gate arithmetic (151.3, ADR-0016 / D-230). Given the ids the
+ * classifier CITED and the project corpus's real `{id → recurrence_count}` index,
+ * resolve the cited ids against the corpus (DROP any the LLM hallucinated) and SUM
+ * their real recurrence_count. That deterministic sum — never an LLM count — gates
+ * promotion. Repeated cited ids are de-duplicated (a fact cited twice counts once).
+ *
+ * PURE: no I/O. The factIndex is assembled by assembleProjectCorpus.
+ *
+ * @param {object} o
+ * @param {string[]} [o.sourceFactIds]      ids the classifier cited
+ * @param {Map<string,number>} [o.factIndex] real corpus `id → recurrence_count`
+ * @returns {{sum:number, resolved:string[], rejected:string[]}}
+ */
+export function resolveRecurrenceSum({ sourceFactIds = [], factIndex } = {}) {
+  const index = factIndex instanceof Map ? factIndex : new Map();
+  const resolved = [];
+  const rejected = [];
+  const seen = new Set();
+  let sum = 0;
+  for (const rawId of sourceFactIds ?? []) {
+    const id = String(rawId).trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    if (index.has(id)) {
+      resolved.push(id);
+      const n = index.get(id);
+      // Floor again here (assembleProjectCorpus already floors): this helper is
+      // exported + pure, so a direct caller could pass a junk Map — a real fact is
+      // always worth ≥1.
+      sum += Number.isFinite(n) && n > 0 ? n : 1;
+    } else {
+      rejected.push(id); // hallucinated / not in the synthesis corpus → contributes 0
+    }
+  }
+  return { sum, resolved, rejected };
+}
+
 /**
  * Run auto-persona synthesis: classify project-tier captured facts,
  * auto-promote cross-project doctrine into the user tier (trust:medium).
@@ -315,9 +421,17 @@ export async function autoPersona(opts = {}) {
   // Task 86c (D-44): the SessionEnd path classifies the RAW TRANSCRIPT (where a
   // user's standing rule survives verbatim); the default 'facts' path classifies
   // the distilled project corpus (whole-project sweep — weekly/manual).
-  const corpus = source === 'transcript'
-    ? assembleTranscriptWindow({ projectRoot })
-    : assembleProjectCorpus({ projectRoot, userDir });
+  // 151.3: the facts path ALSO returns a factIndex (id → recurrence_count) for the
+  // cite-and-sum gate. The transcript path has no citable fact ids — its candidates
+  // promote only via the explicit-imperative (confidence=high) fast-path, which is
+  // exactly the verbatim "from now on …" signal a transcript carries (D-44).
+  let corpus;
+  let factIndex = new Map();
+  if (source === 'transcript') {
+    corpus = assembleTranscriptWindow({ projectRoot });
+  } else {
+    ({ corpus, factIndex } = assembleProjectCorpus({ projectRoot, userDir }));
+  }
   if (!corpus) {
     const reason = source === 'transcript' ? 'no-transcript' : 'no-facts';
     return { action: 'skipped', reason, promoted: [], queued: [], duration_ms: Date.now() - t0 };
@@ -353,7 +467,17 @@ export async function autoPersona(opts = {}) {
     });
   }
 
-  const candidates = parsePersonaCandidates(result?.outputText);
+  // 151.3 (cite-and-sum, D-230): resolve each candidate's cited source_fact_ids
+  // against the corpus factIndex (rejecting hallucinated ids) and attach the
+  // arithmetic recurrence SUM. THAT sum — computed in code, never by the LLM —
+  // is the promotion gate inside promoteCandidatesToUserTier (a medium/inferred
+  // trait promotes iff its cited facts recur ≥ PROMOTE_THRESHOLD). The transcript
+  // path's factIndex is empty, so its candidates carry sum 0 and promote only via
+  // the confidence=high fast-path (the verbatim stated rule a transcript holds).
+  const candidates = parsePersonaCandidates(result?.outputText).map((c) => ({
+    ...c,
+    recurrenceSum: resolveRecurrenceSum({ sourceFactIds: c.sourceFactIds, factIndex }).sum,
+  }));
   const { promoted, queued, superseded, conflicts, reviewQueuePath } = promoteCandidatesToUserTier({
     candidates,
     userDir,
@@ -531,12 +655,29 @@ export function promoteCandidatesToUserTier({ candidates, userDir, now, settings
   const conflicts = [];
   for (const c of candidates) {
     if (!VALID_TARGETS.has(c.target)) continue; // defensive: drop bad routing
-    if (c.confidence !== 'high') {
-      // Confidence gate (not a manual gate): low/medium route to the review
-      // queue. They are returned in `queued` AND written to the durable
+    // 151.3 — THE RECURRENCE GATE (ADR-0016, D-230), replacing the pure form
+    // gate. A candidate promotes if EITHER:
+    //   (a) confidence=high — an EXPLICITLY-STATED standing rule (the fast-path:
+    //       a user-attested rule promotes immediately, recurrence irrelevant); OR
+    //   (b) its cited facts' recurrence SUM ≥ PROMOTE_THRESHOLD — a DEMONSTRATED-
+    //       but-not-declared trait that has recurred enough to be durable.
+    // (b) is the Hole-A fix: pre-151.3 a demonstrated philosophy stranded here
+    // because it lacked "always/never" phrasing (D-177). The sum is arithmetic on
+    // real recurrence_count (the LLM cites; code counts). recurrenceSum is attached
+    // by autoPersona; callers that don't attach it (inline/explicit/drain) leave it
+    // undefined → those paths rely on the confidence=high clause, unchanged.
+    const recurrenceSum = c.recurrenceSum ?? 0;
+    const promotesByRecurrence = recurrenceSum >= PROMOTE_THRESHOLD;
+    // Door 4: name WHY this trait promoted, so a debugger can tell a recurrence-
+    // gated promotion (the new 151.3 path) from the explicit-imperative fast-path.
+    const promotedVia = c.confidence === 'high' ? 'confidence-high' : `recurrence-${recurrenceSum}`;
+    if (c.confidence !== 'high' && !promotesByRecurrence) {
+      // Not promotable: low/medium confidence AND under the recurrence threshold.
+      // Route to the review queue — returned in `queued` AND written to the durable
       // queue FILE below (appendPersonaReviewQueue) so they survive past the
       // response — the daily/weekly auto-drain (or a manual review) acts on them.
-      queued.push({ target: c.target, section: c.section, text: c.text, confidence: c.confidence, reason: `confidence-${c.confidence}` });
+      const reason = recurrenceSum > 0 ? `recurrence-${recurrenceSum}-below-${PROMOTE_THRESHOLD}` : `confidence-${c.confidence}`;
+      queued.push({ target: c.target, section: c.section, text: c.text, confidence: c.confidence, reason });
       continue;
     }
 
@@ -652,8 +793,10 @@ export function promoteCandidatesToUserTier({ candidates, userDir, now, settings
       id: res.id,
       reasonCode: REASON_CODES.PERSONA_PROMOTED,
       // Carry `source` so the audit trail distinguishes an explicit
-      // `cmk lessons promote` (user-explicit) from an auto-synthesis promote.
-      reasonText: `${c.target} § ${c.section} (${source})`,
+      // `cmk lessons promote` (user-explicit) from an auto-synthesis promote, and
+      // `promotedVia` so a recurrence-gated promotion (151.3) is distinguishable
+      // from the explicit-imperative fast-path.
+      reasonText: `${c.target} § ${c.section} (${source}; via ${promotedVia})`,
       paths: { after: res.path },
     });
 

package/src/config-core.mjs

@@ -96,15 +96,31 @@ function coerce(raw) {
   return raw;
 }
 
-function setDeep(obj, dottedKey, value) {
+// Exported for a direct unit test: this guard holds a security invariant
+// (prototype-pollution resistance) and is analyzed by CodeQL in isolation, so
+// it's tested at its own boundary, not only through configSet.
+export function setDeep(obj, dottedKey, value) {
   const parts = dottedKey.split('.');
   let cur = obj;
-  for (let i = 0; i < parts.length - 1; i++) {
+  for (let i = 0; i < parts.length; i++) {
     const p = parts[i];
-    if (cur[p] == null || typeof cur[p] !== 'object' || Array.isArray(cur[p])) cur[p] = {};
-    cur = cur[p];
+    // Defense-in-depth: refuse prototype-polluting segments at the assignment
+    // site, inside the walk loop. CodeQL's js/prototype-pollution-utility
+    // recognizes a sanitizer only as DIRECT `===` comparisons against the
+    // dangerous names (per its query-help example `if (key === "__proto__" ||
+    // key === "constructor") ...`), NOT a Set/helper lookup — so this is spelled
+    // out explicitly. (FORBIDDEN_KEYS keeps the same names for the entry-point
+    // guards; this in-loop form is what the static analyzer reads.)
+    if (p === '__proto__' || p === 'constructor' || p === 'prototype') {
+      throw new Error(`setDeep: forbidden key segment (${p}) — prototype-pollution guard`);
+    }
+    if (i === parts.length - 1) {
+      cur[p] = value;
+    } else {
+      if (cur[p] == null || typeof cur[p] !== 'object' || Array.isArray(cur[p])) cur[p] = {};
+      cur = cur[p];
+    }
   }
-  cur[parts[parts.length - 1]] = value;
 }
 
 /**

package/src/conflict-queue.mjs

@@ -54,6 +54,8 @@ import { hashContent } from './content-hash.mjs';
 import { nowIso, appendAuditEntry, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { generateId } from '@lh8ppl/cmk-canonicalize';
+import { applyTrustSignal } from './trust-signal.mjs';
+import { openIndexDb } from './index-db.mjs';
 
 // Trust ordering. Higher number = higher trust.
 const TRUST_LEVELS = Object.freeze({
@@ -825,6 +827,22 @@ export function mergeScratchpadBullets({
     },
   });
 
+  // Task 151.12 — merge-both SUPERSEDES both originals → DAMPEN their trust_score
+  // (the supersession passive signal; closes the merge-path gap 151.8 deferred).
+  // Best-effort overlay — never breaks the merge. One shared index-db handle for
+  // both dampens (avoid open/close per id).
+  try {
+    const sigDb = openIndexDb({ projectRoot });
+    try {
+      applyTrustSignal({ id: idA, event: 'dampen', db: sigDb });
+      applyTrustSignal({ id: idB, event: 'dampen', db: sigDb });
+    } finally {
+      sigDb.close();
+    }
+  } catch {
+    // best-effort: the trust dampen must never break the merge.
+  }
+
   return {
     action: 'merged',
     id: newId,

package/src/graduation.mjs

@@ -177,3 +177,42 @@ export function graduateForCapRelief({
   const out = lines.filter((_, i) => !removeIdx.has(i)).join('\n');
   return { text: out, graduated };
 }
+
+/**
+ * Mechanical cap relief for the USER-TIER PERSONA (Task 151.4, ADR-0016 §20.3).
+ *
+ * The persona (USER/HABITS/LESSONS.md) must NEVER graduate its high-trust bullets
+ * out to un-injected `fragments/` — that strands a promoted trait so it vanishes
+ * at cold-open (Hole B). Instead, reclaim bytes WITHOUT dropping any content:
+ *   - trim trailing whitespace per line,
+ *   - collapse any run of ≥2 blank lines down to a single blank line.
+ * No bullet is ever removed. This is a best-effort byte reclaim (the load-cap-not-
+ * write-cap invariant, D-61, already lets the file exceed the inject budget when
+ * relief isn't enough; the snapshot load-cap + sweep order (151.5) then keeps the
+ * high-trust traits injected). A genuine LLM tighter-rewrite is Task 95 (off the
+ * synchronous append hot path — an inline Haiku call here would be a composition +
+ * latency hazard). PURE: no I/O. Idempotent (re-condensing tight text is a no-op).
+ *
+ * @param {string} text  the scratchpad content
+ * @returns {string} the condensed content (same bullets, fewer bytes)
+ */
+export function condenseScratchpadForCapRelief(text) {
+  // CRLF-tolerant (Task 139): split on /\r?\n/ so a Windows-authored persona file
+  // condenses too — a plain split('\n') would leave a trailing '\r' on every line,
+  // making blank-run collapse + trailing-trim silent no-ops. Rejoin with '\n'
+  // (LF), matching how consolidate()/writeBullet() already normalize line endings.
+  const lines = String(text ?? '').split(/\r?\n/);
+  const out = [];
+  let blankRun = 0;
+  for (const line of lines) {
+    const trimmed = line.replace(/[ \t]+$/, ''); // trailing whitespace
+    if (trimmed === '') {
+      blankRun += 1;
+      if (blankRun > 1) continue; // collapse ≥2 blanks → 1
+    } else {
+      blankRun = 0;
+    }
+    out.push(trimmed);
+  }
+  return out.join('\n');
+}

package/src/heat.mjs

@@ -0,0 +1,75 @@
+// heat.mjs — the capped-recurrence promotion score (Task 151.2, ADR-0016).
+//
+// A fact earns promotion to the persona by RECURRENCE, not by phrasing. The
+// score blends how often a fact has re-surfaced (the earned signal, CAPPED) with
+// how recently (a lazy exponential decay). The cap is load-bearing: recurrence
+// is a tie-breaker, never the driver — a noisy-but-trivial fact must never
+// outrank a once-stated durable decision.
+//
+//   heat = min(recurrence_count, RECUR_CAP) * W_REC  +  exp(-Δhours / τ)
+//
+// Shapes verified against real code (the 7-system study, D-228):
+//   • recency = exp(-Δhours/τ), τ=24h  — MemoryOS `compute_recency`
+//   • the cap = min(count, ceiling)    — MemOS `min(leaf_count*2, 20)`
+//   • threshold 3                      — memclaw `min_cluster_size` (diversity
+//                                        gate dropped: single-user, not a fleet)
+//
+// PURE: no I/O, no cron. Recency is computed AT READ from `now` + `lastAt`, so
+// there is no background job mutating a stored heat value (D-169 — automatic,
+// ritual-free). The caller passes `recurrence_count` (frontmatter, Task 151.1)
+// and the fact's last-surfaced timestamp.
+
+// The recurrence cap. Past this many recurrences, more adds nothing — recurrence
+// is a tie-breaker, not a runaway driver (MemOS). Chosen so the recurrence band
+// (0…RECUR_CAP·W_REC) is comparable to the recency band (0…1), keeping neither
+// signal able to bury the other.
+export const RECUR_CAP = 10;
+
+// Weight on the (capped) recurrence term. RECUR_CAP·W_REC ≈ 1.0 so a maxed-out
+// recurrence contributes about the same as a brand-new recency — the two signals
+// are balanced, then the cap prevents recurrence from dominating.
+export const W_REC = 0.1;
+
+// Recency half-life-ish constant (hours). exp(-Δh/τ): at τ hours the recency
+// term is e^-1 ≈ 0.368 of its fresh value. MemoryOS uses τ=24.
+export const TAU_HOURS = 24;
+
+// Promotion threshold: a fact promotes to the persona at this many recurrences
+// (memclaw min-cluster-size; diversity gate dropped for single-user). "I've
+// reached this same shape 3× → it's durable."
+export const PROMOTE_THRESHOLD = 3;
+
+/**
+ * Compute a fact's promotion heat. Pure — no I/O.
+ *
+ * @param {object} o
+ * @param {number} o.recurrenceCount  how many times this fact has surfaced (≥1)
+ * @param {string|null} [o.lastAt]     ISO timestamp the fact last surfaced; null/garbage → recency 0
+ * @param {number} [o.now]             ms epoch "now" (default Date.now()); injectable for tests
+ * @returns {number} heat score (recurrence band + recency band)
+ */
+export function computeHeat({ recurrenceCount = 1, lastAt = null, now = Date.now() } = {}) {
+  const count = Number.isFinite(recurrenceCount) && recurrenceCount > 0 ? recurrenceCount : 1;
+  const recurrenceTerm = Math.min(count, RECUR_CAP) * W_REC;
+
+  let recencyTerm = 0;
+  if (lastAt) {
+    const t = Date.parse(lastAt);
+    if (Number.isFinite(t)) {
+      const deltaHours = Math.max(0, (now - t) / 3_600_000); // clamp future skew → ≤1
+      recencyTerm = Math.exp(-deltaHours / TAU_HOURS);
+    }
+  }
+  return recurrenceTerm + recencyTerm;
+}
+
+/**
+ * Does this fact clear the promotion threshold? (recurrence-only — the gate is
+ * "seen ≥ N times", recency only orders WITHIN the promotable set.)
+ *
+ * @param {number} recurrenceCount
+ * @returns {boolean}
+ */
+export function isPromotable(recurrenceCount) {
+  return Number.isFinite(recurrenceCount) && recurrenceCount >= PROMOTE_THRESHOLD;
+}

package/src/index-db.mjs

@@ -68,6 +68,12 @@ CREATE TABLE IF NOT EXISTS observations (
   body TEXT NOT NULL,
   write_source TEXT NOT NULL,
   trust TEXT NOT NULL,
+  -- Task 151.6 (ADR-0016 §20.2): the evolving PROTECTION field — a FLOAT seeded
+  -- from source (user-explicit > auto-extract) on (re)index, then moved by passive
+  -- outcomes (151.7/151.8). Lives ONLY here (the rebuildable index), never in
+  -- committed frontmatter (D-218). DEFAULT 0.5 so a migrated pre-151.6 row + any
+  -- insert that omits it gets a sane medium seed until the next full reindex.
+  trust_score REAL NOT NULL DEFAULT 0.5,
   created_at INTEGER NOT NULL,
   superseded_by TEXT REFERENCES observations(id),
   deleted_at INTEGER
@@ -189,5 +195,21 @@ export function openIndexDb({ projectRoot, dbPath } = {}) {
   db.pragma('synchronous = NORMAL');
   // Apply schema (idempotent CREATE IF NOT EXISTS).
   db.exec(INDEX_DB_SCHEMA);
+  // Task 151.6: non-destructive column migration. CREATE TABLE IF NOT EXISTS does
+  // NOT add a new column to a pre-existing table, so an index built before 151.6
+  // would lack `trust_score`. Add it in place (ALTER preserves all rows — the
+  // index is rebuildable, but we don't force a full rebuild just for a column).
+  // The next full reindex reseeds real values; until then existing rows carry the
+  // DEFAULT 0.5 (medium). Idempotent: skip if the column already exists.
+  migrateAddColumn(db, 'observations', 'trust_score', 'REAL NOT NULL DEFAULT 0.5');
   return db;
 }
+
+// Add `column` to `table` if it isn't already present (idempotent). SQLite has no
+// "ADD COLUMN IF NOT EXISTS", so we check PRAGMA table_info first — a duplicate
+// ALTER would throw.
+function migrateAddColumn(db, table, column, definition) {
+  const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+  if (cols.some((c) => c.name === column)) return;
+  db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+}