@lh8ppl/claude-memory-kit 0.4.1 → 0.4.3

package/src/scratchpad.mjs

@@ -36,7 +36,7 @@ import {
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { writeBullet, parseBulletProvenance, isProvenanceCommentLine } from './provenance.mjs';
-import { graduateForCapRelief } from './graduation.mjs';
+import { graduateForCapRelief, condenseScratchpadForCapRelief } from './graduation.mjs';
 
 const VALID_TRUST = new Set(['high', 'medium', 'low']);
 const VALID_WRITE_SOURCES = new Set([
@@ -227,6 +227,19 @@ export function ensureSectionExists(scratchpadPath, sectionTitle) {
 
 const EVICTED_ID_RE = /^- \(([PUL]-[A-Za-z0-9]+)\)/;
 
+// Sweep order (Task 151.5, ADR-0016 §20.3): within the stale, non-high swept
+// set, LOW-trust evicts before MEDIUM — value-ordered, not the value-BLIND
+// single-axis sweep (MemoryOS-LFU / MemOS-top-N) the research flags as the
+// Task-151 bug. The drop GATE stays a two-axis CONJUNCTION (not-high AND stale);
+// this only orders the eviction LIST (→ the archive + audit order), so a
+// debugger / a future partial-drop sees the cheapest bullets first.
+// 151.6 re-eval RESOLVED (D-238): KEEP the `trust` ENUM here — the evolved
+// trust_score is a FLOOR/protection signal (memclaw/letta/graphiti), NOT a sweep-
+// ranking driver (rank-and-sweep-by-score = the MemoryOS-LFU/MemOS-top-N bug). The
+// floor (never-zero) + the enum's high-trust-exempt already deliver the protection;
+// no index-db I/O on this path. See design §20.3.
+const CONSOLIDATE_TRUST_ORDER = { low: 0, medium: 1, high: 2 };
+
 function consolidate(text, { nowDate }) {
   const lines = text.split(/\r?\n/); // Task 139: CRLF-tolerant
   const removeIdx = new Set();
@@ -253,14 +266,28 @@ function consolidate(text, { nowDate }) {
     removeIdx.add(i + 1);
     // Task 91.2: capture the dropped bullet so the caller can ARCHIVE it
     // (recoverable, per the §6.5 tombstone principle) instead of hard-deleting.
+    // Carry trust + age so the eviction list can be value-ordered (151.5).
     const idMatch = bulletLine.match(EVICTED_ID_RE);
-    evicted.push({ id: idMatch ? idMatch[1] : 'unknown', block: `${bulletLine}\n${commentLine}` });
+    evicted.push({
+      id: idMatch ? idMatch[1] : 'unknown',
+      block: `${bulletLine}\n${commentLine}`,
+      trust: prov.trust,
+      atMs: at.getTime(),
+    });
     bulletsRemoved++;
   }
 
   if (removeIdx.size === 0) {
     return { text, bulletsRemoved: 0, evicted: [] };
   }
+  // 151.5: order the eviction list LOW-trust first, then OLDEST first (the
+  // "long-unaccessed" axis, capture-age proxy until 151.6). The file removal
+  // (removeIdx) is unchanged — only the archive/audit order reflects value.
+  evicted.sort(
+    (a, b) =>
+      (CONSOLIDATE_TRUST_ORDER[a.trust] ?? 1) - (CONSOLIDATE_TRUST_ORDER[b.trust] ?? 1) ||
+      a.atMs - b.atMs,
+  );
   const out = lines.filter((_, i) => !removeIdx.has(i)).join('\n');
   return { text: out, bulletsRemoved, evicted };
 }
@@ -365,21 +392,23 @@ export function appendScratchpadBullet(opts = {}) {
     evictedBullets = consolidated.evicted ?? [];
   }
 
-  // 2b. Graduation (Task 91, generalized to all tiers by Task 94 / §19.2). If
-  // still over the LOAD-cap after stale-drop — which is what happens when the
-  // bullets are high-trust (consolidate() never drops those) — graduate the
-  // oldest high-trust bullets OUT of the hot index into the tier's permanent
-  // fact store, keeping the injected slice small (the write already succeeded
-  // via the load-cap; graduation is about injection budget, not write success).
-  // ALL FACT-BEARING TIERS (D-61): project (MEMORY.md + SOUL.md) AND the user-
-  // tier persona (USER/HABITS/LESSONS) — graduating into the tier's existing
-  // fact store (project context/memory/, user <userDir>/fragments/; writeFact
-  // already routes tier-U facts there). Local tier (machine-paths/overrides) is
-  // excluded: it's machine-specific config, not durable facts.
+  // 2b. Cap relief after stale-drop. The path DIFFERS by tier (Task 151.4, §20.3):
+  //   - PROJECT (tier P): GRADUATE the oldest high-trust bullets OUT of the hot
+  //     index into the permanent fact store (context/memory/*.md). Those stay
+  //     recall-reachable (`cmk search`), so moving them out of MEMORY.md is fine —
+  //     it's an injection-budget trim, not data loss.
+  //   - USER PERSONA (tier U): NEVER graduate — the persona's value IS being
+  //     injected at cold-open, and the user-tier graduation target (fragments/) is
+  //     NOT read by inject-context, so graduating a promoted trait there strands it
+  //     (Hole B — the v0.3.1 cold-open bug). Instead CONDENSE in place (mechanical,
+  //     no LLM — drops no bullet); if still over cap the file grows past the inject
+  //     budget (load-cap, not write-cap — D-61) and the snapshot load-cap + sweep
+  //     order (151.5) keeps the high-trust traits injected. LLM rewrite is Task 95.
+  // Local tier (machine-paths/overrides) is excluded: machine config, not facts.
   let bulletsGraduated = 0;
   let graduatedIds = [];
   let finalBytes = Buffer.byteLength(finalContent, 'utf8');
-  if (finalBytes > cap && (tier === 'P' || tier === 'U')) {
+  if (finalBytes > cap && tier === 'P') {
     const grad = graduateForCapRelief({
       text: finalContent,
       capBytes: cap,
@@ -392,6 +421,10 @@ export function appendScratchpadBullet(opts = {}) {
     graduatedIds = grad.graduated;
     bulletsGraduated = graduatedIds.length;
     finalBytes = Buffer.byteLength(finalContent, 'utf8');
+  } else if (finalBytes > cap && tier === 'U') {
+    // Demote-not-evict: reclaim bytes without losing a single persona trait.
+    finalContent = condenseScratchpadForCapRelief(finalContent);
+    finalBytes = Buffer.byteLength(finalContent, 'utf8');
   }
 
   // 3. Load-cap, NOT write-cap (Task 94 / D-61 / design §19). The write ALWAYS
@@ -529,17 +562,23 @@ export function sweepScratchpadForCapRelief({
 
   let graduatedIds = [];
   if (Buffer.byteLength(working, 'utf8') > cap) {
-    // tier is already guaranteed P||U by the gate above.
-    const grad = graduateForCapRelief({
-      text: working,
-      capBytes: cap,
-      tier,
-      projectRoot,
-      userDir,
-      now: ts,
-    });
-    working = grad.text;
-    graduatedIds = grad.graduated;
+    // Task 151.4 (§20.3): PROJECT graduates to the recall-reachable fact store;
+    // USER PERSONA condenses in place — never graduates to un-injected fragments/
+    // (Hole B). tier is guaranteed P||U by the gate above.
+    if (tier === 'P') {
+      const grad = graduateForCapRelief({
+        text: working,
+        capBytes: cap,
+        tier,
+        projectRoot,
+        userDir,
+        now: ts,
+      });
+      working = grad.text;
+      graduatedIds = grad.graduated;
+    } else {
+      working = condenseScratchpadForCapRelief(working);
+    }
   }
 
   if (working === original) {

package/src/trust-score.mjs

@@ -0,0 +1,120 @@
+// trust-score.mjs — the evolving PROTECTION field (Task 151.6+, ADR-0016 §20.2).
+//
+// `trust_score` is a FLOAT per fact, stored in the REBUILDABLE INDEX (the
+// index-db `observations.trust_score` column), NOT in committed frontmatter
+// (D-218: a moving value in a committed .md = git-diff noise; markdown-as-truth
+// keeps committed files clean). It is reconstructed on every full reindex.
+//
+// Two trust signals, two homes (the kit's deliberate split — MemOS proves a
+// single unified score lets a noisy fact rank high):
+//   - `trust` ENUM (high/medium/low) — committed frontmatter, the CURATED signal
+//     a human/classifier assigned; it gates promotion-protection coarsely and is
+//     the INIT seed here.
+//   - `trust_score` FLOAT — this module, the rebuildable index; it EVOLVES from
+//     passive outcomes (151.7 update rule + 151.8 signals) so a fact that keeps
+//     getting contradicted sinks and a fact that keeps getting restated rises,
+//     with NO ritual (D-169).
+//
+// 151.6 ships ONLY the INIT (source-based seed). 151.7 adds the asymmetric,
+// clamped, floored update rule; 151.8 wires the three passive signals.
+
+// The floor (memclaw `_adjust_weights`): trust_score never reaches zero, so a
+// fact is never auto-deleted purely by trust decay — demote-not-evict (§20.3).
+export const TRUST_SCORE_FLOOR = 0.05;
+// The ceiling: cap below 1.0 so a maxed-out fact still has reinforcement headroom
+// and the init never starts at the top.
+export const TRUST_SCORE_CEIL = 0.95;
+
+// Base score per committed trust enum — the curated coarse signal.
+const TRUST_ENUM_BASE = { high: 0.8, medium: 0.5, low: 0.3 };
+const DEFAULT_ENUM_BASE = 0.5; // unknown enum → treat as medium
+
+// Source adjustment: a USER-ATTESTED write (the user stated/curated it) starts
+// higher than a MACHINE-DERIVED one at the same enum — the design's
+// "user-explicit > auto-extract" (memory-os source-based init). `imported` is
+// neutral (provenance unknown); `seed` is a scaffold placeholder, slightly low.
+const SOURCE_ADJUST = {
+  'user-explicit': +0.1,
+  'manual-edit': +0.1,
+  imported: 0,
+  'auto-extract': -0.05,
+  compressor: -0.05,
+  seed: -0.1,
+};
+const DEFAULT_SOURCE_ADJUST = 0; // unknown source → neutral
+
+// Recurrence contribution to the SEED (Task 151.8 — the research fix). A re-stated
+// fact seeds HIGHER, and durably: this is reconstructed from the committed
+// `recurrence_count` (151.1) on every reindex, so the "restatement reinforcement"
+// can never be wiped by a reseed (unlike a fragile overlay delta would be). This
+// is the MemoryOS/MemOS/honcho pattern — the recurrence COUNT is a TERM in the
+// score, NOT a separate event. The cap is LOAD-BEARING (MemOS `min(count·w, 2)`):
+// recurrence is a tie-breaker, never a runaway driver — a high-recurrence LOW-trust
+// fact must never outrank a once-stated HIGH-trust one (the value-blind-LFU bug).
+const RECUR_WEIGHT = 0.02; // per recurrence beyond the first
+const RECUR_CONTRIB_CAP = 0.1; // max total recurrence lift (5 recurrences = full)
+
+function recurrenceTerm(recurrenceCount) {
+  const n = Number.isFinite(recurrenceCount) && recurrenceCount > 1 ? recurrenceCount : 1;
+  return Math.min((n - 1) * RECUR_WEIGHT, RECUR_CONTRIB_CAP);
+}
+
+function clamp(n) {
+  if (!Number.isFinite(n)) return DEFAULT_ENUM_BASE;
+  return Math.min(TRUST_SCORE_CEIL, Math.max(TRUST_SCORE_FLOOR, n));
+}
+
+/**
+ * Initial trust_score for a fact, from its committed signals (Task 151.6 + .8).
+ * Pure + deterministic — same inputs, same score; reconstructed on every full
+ * reindex. A user-attested source outranks a machine-derived one at the same
+ * trust enum; a re-stated fact (higher `recurrenceCount`) seeds higher, CAPPED;
+ * the result is clamped to [FLOOR, CEIL].
+ *
+ * @param {object} o
+ * @param {string} [o.trust]            the committed trust enum (high|medium|low)
+ * @param {string} [o.writeSource]      the committed write source (user-explicit|…)
+ * @param {number} [o.recurrenceCount]  the committed recurrence_count (151.1); a
+ *                                      re-stated fact seeds higher (capped) — the
+ *                                      DURABLE restatement-reinforcement (151.8)
+ * @returns {number} the seed trust_score in [FLOOR, CEIL]
+ */
+export function initTrustScore({ trust, writeSource, recurrenceCount } = {}) {
+  const base = TRUST_ENUM_BASE[trust] ?? DEFAULT_ENUM_BASE;
+  const adjust = SOURCE_ADJUST[writeSource] ?? DEFAULT_SOURCE_ADJUST;
+  return clamp(base + adjust + recurrenceTerm(recurrenceCount));
+}
+
+// The asymmetric event deltas (Task 151.7; memclaw `evolve_service._adjust_weights`):
+// a dampen moves MORE than a reinforce, so a contradicted/superseded fact sinks
+// faster than a restated one rises — the conservative, fail-loud posture (a single
+// failure outweighs a single success). Event-driven, NOT clock-driven.
+export const REINFORCE_DELTA = +0.1;
+export const DAMPEN_DELTA = -0.15;
+
+// The event → delta map. An unknown event contributes 0 (no-op) so a future
+// signal that isn't wired yet can't silently corrupt a score.
+const EVENT_DELTA = {
+  reinforce: REINFORCE_DELTA,
+  dampen: DAMPEN_DELTA,
+};
+
+/**
+ * Apply one passive-outcome event to a fact's trust_score (Task 151.7).
+ * Pure + deterministic — the SAME (current, event) always yields the same result
+ * (event-driven, NOT time-decayed; recency decay is a search-ranking concern
+ * computed at read, never stored). The result is clamped to [FLOOR, CEIL]; the
+ * floor is load-bearing — repeated dampens settle at 0.05, never zero, so a fact
+ * is never auto-deleted by trust decay (demote-not-evict, §20.3). 151.8 maps the
+ * three passive signals (contradiction / supersession / restatement) onto the
+ * 'dampen' / 'reinforce' events.
+ *
+ * @param {number} current  the fact's current trust_score
+ * @param {string} [event]  'reinforce' | 'dampen' (unknown → no-op)
+ * @returns {number} the updated trust_score in [FLOOR, CEIL]
+ */
+export function updateTrustScore(current, event) {
+  const base = Number.isFinite(current) ? current : DEFAULT_ENUM_BASE;
+  const delta = EVENT_DELTA[event] ?? 0;
+  return clamp(base + delta);
+}

package/src/trust-signal.mjs

@@ -0,0 +1,73 @@
+// trust-signal.mjs — apply a PASSIVE outcome event to a fact's trust_score
+// (Task 151.8, ADR-0016 §20.2). The I/O half of the trust layer; the pure
+// arithmetic is `updateTrustScore` in trust-score.mjs.
+//
+// The three passive signals (D-169, zero ritual — no `cmk` command):
+//   - CONTRADICTION  (a write conflicts with an existing fact)   → dampen the existing
+//   - SUPERSESSION   (`superseded_by` set / a replace)           → dampen the OLD fact
+//   - RE-SURFACE     (the 151.1 recurrence bump)                 → reinforce the fact
+// 151.8 wires these call sites to this helper.
+//
+// DURABILITY POSTURE (decided 2026-06-30, D-237 — research- + code-grounded):
+// trust_score lives in the REBUILDABLE index (the `observations.trust_score`
+// column), which the kit treats as a "regenerable read-cache" (index-db.mjs).
+// So this is a RUNTIME OVERLAY: the delta survives the common path (reindexBoot
+// skips unchanged files) → durable session-to-session on a machine; a FULL
+// reindex (`cmk reindex --full` / repair) reseeds from the committed `trust`
+// enum and resets the overlay — acceptable because trust_score is the LOCAL
+// protection signal, while the committed `trust` enum is the PORTABLE one (the
+// two-fields design). Every surveyed system that evolves trust (memclaw
+// `_adjust_weights`, MemoryOS, honcho, EverOS, captain-claw) keeps it in the
+// runtime DB store, not in a committed/replayed log — this matches them.
+//
+// BEST-EFFORT: a trust nudge must NEVER break the primary write. Every failure
+// (no projectRoot, no DB, missing row, bad input) returns a benign result and
+// NEVER throws — the caller (a write path) is unaffected.
+
+import { openIndexDb } from './index-db.mjs';
+import { updateTrustScore } from './trust-score.mjs';
+
+const SELECT_TRUST_SCORE_SQL = 'SELECT trust_score FROM observations WHERE id = ?';
+const UPDATE_TRUST_SCORE_SQL = 'UPDATE observations SET trust_score = ? WHERE id = ?';
+
+/**
+ * Apply one passive-outcome event to a fact's trust_score overlay (Task 151.8).
+ * BEST-EFFORT — swallows every error, never throws.
+ *
+ * @param {object} o
+ * @param {string} [o.projectRoot]  the project whose index-db holds the row
+ *                                  (ignored when `db` is supplied)
+ * @param {string} [o.id]           the affected fact's canonical id
+ * @param {string} [o.event]        'reinforce' | 'dampen' (unknown → no-op write)
+ * @param {object} [o.db]           an ALREADY-OPEN index-db handle to reuse — a
+ *                                  caller that fires several signals in one op
+ *                                  (e.g. a merge dampening idA+idB) passes one
+ *                                  handle to avoid open/close per call. When given,
+ *                                  this function does NOT close it (the caller owns
+ *                                  its lifecycle). Omit → open + close our own.
+ * @returns {{action:'updated'|'not-found'|'skipped', id?:string, trust_score?:number}}
+ */
+export function applyTrustSignal({ projectRoot, id, event, db: sharedDb } = {}) {
+  if (!id || (!projectRoot && !sharedDb)) return { action: 'skipped' };
+  let db = sharedDb;
+  try {
+    if (!db) db = openIndexDb({ projectRoot });
+    const row = db.prepare(SELECT_TRUST_SCORE_SQL).get(id);
+    if (!row) return { action: 'not-found', id };
+    const next = updateTrustScore(row.trust_score, event);
+    db.prepare(UPDATE_TRUST_SCORE_SQL).run(next, id);
+    return { action: 'updated', id, trust_score: next };
+  } catch {
+    // best-effort: a trust overlay update must never break the primary write.
+    return { action: 'skipped', id };
+  } finally {
+    // Only close a handle WE opened — never the caller's shared handle.
+    if (!sharedDb && db) {
+      try {
+        db.close();
+      } catch {
+        // ignore close errors on a best-effort path
+      }
+    }
+  }
+}

package/src/write-fact.mjs

@@ -106,6 +106,12 @@ function buildFrontmatterObject(opts, computed) {
     created_at: computed.createdAt,
     write_source: opts.writeSource,
     trust: opts.trust,
+    // Task 151.1 (ADR-0016 / design §20.1): the capped-recurrence promotion
+    // signal. Starts at 1 on create; the duplicate-hit path bumps it when the
+    // SAME canonical fact re-surfaces (same content-hash id). A promotion fact,
+    // so it lives in committed frontmatter (diffable) — unlike trust_score,
+    // which moves on every recall and lives in the rebuildable index (D-218).
+    recurrence_count: computed.recurrenceCount ?? 1,
     source_file: opts.sourceFile,
     source_line: opts.sourceLine,
     source_sha1: opts.sourceSha1,
@@ -141,6 +147,27 @@ function readExistingFactId(path) {
   return frontmatter?.id ?? null;
 }
 
+// Task 151.1 (ADR-0016 / design §20.1): a duplicate write = the SAME canonical
+// fact re-surfaced → bump its `recurrence_count` in place. Only the bumped fact
+// is touched (the over-mutation guard). Returns the new count, or null if the
+// file can't be read/parsed (best-effort: a re-surface bump must never turn a
+// successful no-op into an error).
+function bumpRecurrence(path) {
+  try {
+    const { frontmatter, body } = parse(readFileSync(path, 'utf8'));
+    if (!frontmatter) return null;
+    const current = Number.isInteger(frontmatter.recurrence_count)
+      ? frontmatter.recurrence_count
+      : 1; // pre-151 facts have no field → treat as 1, this re-surface makes 2
+    const next = current + 1;
+    frontmatter.recurrence_count = next;
+    writeFileSync(path, format({ frontmatter, body }), 'utf8');
+    return next;
+  } catch {
+    return null;
+  }
+}
+
 export function writeFact(opts = {}) {
   const errors = validateOptions(opts);
   if (errors.length > 0) {
@@ -211,15 +238,25 @@ export function writeFact(opts = {}) {
   const existingIdAtPath = readExistingFactId(path);
   if (existingIdAtPath !== null) {
     if (existingIdAtPath === id) {
+      // Task 151.1: the same canonical fact re-surfaced → bump recurrence_count.
+      const recurrenceCount = bumpRecurrence(path);
       appendAuditEntry(tierRoot, {
         ts: createdAt,
-        action: 'skipped',
+        action: 'recurrence',
         tier: opts.tier,
         id,
-        reasonCode: REASON_CODES.DUPLICATE,
+        reasonCode: REASON_CODES.RECURRENCE,
+        extra: { recurrenceCount },
         paths: { before: path },
       });
-      return { action: 'skipped', skipReason: 'duplicate', id, path };
+      // Task 151.8 (research fix): the re-surface RESTATEMENT signal is NOT a
+      // fragile overlay delta — `bumpRecurrence` just wrote the new recurrence_count
+      // to the committed file, and `initTrustScore` folds a CAPPED recurrence term
+      // into the seed, so the next reindex reconstructs a HIGHER trust_score from
+      // the durable count (MemoryOS/MemOS/honcho: the count IS a score term). No
+      // overlay write here — it would only be reseeded away by the reindex that the
+      // file change triggers. Durable-by-construction.
+      return { action: 'skipped', skipReason: 'duplicate', id, path, recurrenceCount };
     }
     return errorResult({
       category: ERROR_CATEGORIES.COLLISION,
@@ -233,20 +270,28 @@ export function writeFact(opts = {}) {
 
   const elsewhere = findExistingFactById(factDir, id);
   if (elsewhere) {
+    // Task 151.1: re-surface via a different slug → bump the ORIGINAL fact.
+    const recurrenceCount = bumpRecurrence(elsewhere);
     appendAuditEntry(tierRoot, {
       ts: createdAt,
-      action: 'skipped',
+      action: 'recurrence',
       tier: opts.tier,
       id,
       reasonCode: REASON_CODES.DUPLICATE_ELSEWHERE,
+      extra: { recurrenceCount },
       paths: { before: elsewhere, after: path },
     });
+    // Task 151.8 (research fix): restatement reinforcement is DURABLE via the seed
+    // (initTrustScore folds the committed recurrence_count), not a doomed overlay —
+    // the bump rewrote the file, so any overlay write would be reseeded away. See
+    // the same-id branch above.
     return {
       action: 'skipped',
       skipReason: 'duplicate-elsewhere',
       id,
       path,
       duplicateAt: elsewhere,
+      recurrenceCount,
     };
   }