@lh8ppl/claude-memory-kit 0.3.0 → 0.3.2

package/src/decisions-journal.mjs

@@ -0,0 +1,223 @@
+// The append-only decision journal — context/DECISIONS.md (Task 147, D-161).
+//
+// A chronological, human-readable page of every decision + its why. The VIEW
+// the kit was missing: decisions are captured as facts but scattered across N
+// per-fact files with no chronological decision page (cmk search is pull, not
+// browse; MEMORY.md is bounded + rolls). This is the squad `decisions.md` /
+// our own DECISION-LOG.md equivalent, made automatic.
+//
+// LIFECYCLE — APPEND-ONLY, never regenerated, never parked (D-161):
+//   - This is NOT a derived view like INDEX.md. Regenerating from live facts
+//     would silently ERASE superseded/forgotten decisions — rewriting history
+//     to look like the current state was always obvious (the exact failure the
+//     decision-trail-preservation rule exists to prevent).
+//   - A decision journal is unbounded by design: old decisions are the MOST
+//     valuable part (they explain why the codebase is shaped as it is), so the
+//     MEMORY.md rolling-window must NOT apply.
+//   - Mechanics: new decision → appended; tombstoned → its entry MARKED
+//     retracted IN PLACE (never removed); every pre-existing entry survives
+//     every update.
+//
+// The update is triggered like a derived view (runs where reindex runs, so the
+// journal stays current) but its WRITE LOGIC is append-only — the file is the
+// accumulator, the facts are only the trigger. Each entry carries a stable
+// machine marker `<!-- decision:P-XXXXXXXX -->` so the updater knows which ids
+// are already journaled + which entries to annotate, without parsing prose
+// (and so a human can freely add their own prose between entries — preserved).
+//
+// v0.3.2 scope: explicit signals only (capture appends; forget marks retracted;
+// explicit supersession annotates). AUTOMATIC semantic contradiction-detection
+// is deferred to F-D / Task 95.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
+import { ID_PATTERN } from './tier-paths.mjs';
+
+export const DECISIONS_HEADER =
+  '# Decisions\n\n' +
+  '> Append-only decision journal — every decision the kit captured, in order, with its why.\n' +
+  '> Maintained by claude-memory-kit (`cmk digest`). Superseded/retracted entries stay (the trail is the point).';
+
+// Only this fact type is a "decision" in the kit taxonomy (the project/state
+// category — what project-memory's decisions.md and our DECISION-LOG track).
+const DECISION_TYPE = 'project';
+
+const markerFor = (id) => `<!-- decision:${id} -->`;
+const RETRACT_TAG = '_(retracted';
+
+/** The yyyy-mm-dd slice of an ISO timestamp, or the raw value if unparseable. */
+function dateOnly(iso) {
+  if (typeof iso !== 'string') return 'unknown-date';
+  const m = iso.match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : iso;
+}
+
+/**
+ * Render ONE journal entry for a decision fact. The machine marker lets the
+ * updater dedup + annotate; the human-readable lines are Title / date / Why / id.
+ *
+ * @param {{id:string,title:string,createdAt?:string,why?:string|null}} f
+ * @returns {string} the entry block (no trailing newline)
+ */
+export function buildDecisionEntry(f) {
+  const date = dateOnly(f.createdAt);
+  const lines = [
+    markerFor(f.id),
+    `### ${f.title}`,
+    `**When:** ${date} · **Fact:** \`${f.id}\``,
+  ];
+  if (f.why && String(f.why).trim()) {
+    lines.push(`**Why:** ${String(f.why).trim()}`);
+  }
+  return lines.join('\n');
+}
+
+// The kit's id matcher, DERIVED from the canonical ID_PATTERN (tier-paths.mjs)
+// so the base32 alphabet lives in exactly ONE place and can't drift. The
+// original bug: this module hardcoded `[A-Z2-9]` (uppercase only), but the real
+// alphabet includes a lowercase `a` — so any id containing `a` never matched
+// "already journaled" → re-appended on EVERY digest run (the cut-gate find).
+// Strip the `^…$` anchors to embed the pattern inside larger regexes.
+const ID_CHARS = ID_PATTERN.source.replace(/^\^/, '').replace(/\$$/, '');
+
+/** ids already present in the journal body (by their machine marker). */
+function journaledIds(content) {
+  const ids = new Set();
+  const re = new RegExp(`<!-- decision:(${ID_CHARS}) -->`, 'g');
+  let m;
+  while ((m = re.exec(content)) !== null) ids.add(m[1]);
+  return ids;
+}
+
+/**
+ * Append-only journal update (D-161). Pure: content in → content out.
+ *
+ * @param {object} a
+ * @param {string}   a.existingContent  current DECISIONS.md (‘’ if absent)
+ * @param {Array}    a.facts            live decision-class facts ({id,type,title,createdAt,why})
+ * @param {Set<string>} a.tombstonedIds ids whose fact has been forgotten
+ * @param {string}   a.now             ISO timestamp for retraction stamps
+ * @returns {string} the new DECISIONS.md content
+ */
+export function updateDecisionsJournal({ existingContent = '', facts = [], tombstonedIds = new Set(), now }) {
+  let content = existingContent.trim() === '' ? DECISIONS_HEADER + '\n' : existingContent;
+  const already = journaledIds(content);
+
+  // 1) Append entries for decision-class facts not yet journaled.
+  const newEntries = [];
+  for (const f of facts) {
+    if (f.type !== DECISION_TYPE) continue; // only decisions
+    if (already.has(f.id)) continue; // already journaled — never duplicate
+    newEntries.push(buildDecisionEntry(f));
+    already.add(f.id);
+  }
+  if (newEntries.length > 0) {
+    if (!content.endsWith('\n')) content += '\n';
+    content += '\n' + newEntries.join('\n\n') + '\n';
+  }
+
+  // 2) Mark retracted (in place) any journaled entry whose fact is now
+  //    tombstoned and not already marked. Never removes the entry.
+  const stamp = dateOnly(now);
+  for (const id of tombstonedIds) {
+    const marker = markerFor(id);
+    const idx = content.indexOf(marker);
+    if (idx === -1) continue; // not journaled — nothing to retract
+    // Bound the search to THIS entry's span — up to the next decision marker
+    // (or end-of-file). Prevents a malformed/hand-edited entry with no heading
+    // from attaching the retraction note to the NEXT entry's heading.
+    const nextMarker = content.indexOf('<!-- decision:', idx + marker.length);
+    const spanEnd = nextMarker === -1 ? content.length : nextMarker;
+    // Find this entry's heading line (the `### …` after the marker, within span).
+    const headingStart = content.indexOf('### ', idx);
+    if (headingStart === -1 || headingStart >= spanEnd) continue;
+    const headingEnd = content.indexOf('\n', headingStart);
+    if (headingEnd === -1) continue;
+    // Already retracted? (the note sits right after the heading)
+    const afterHeading = content.slice(headingEnd + 1, headingEnd + 1 + RETRACT_TAG.length);
+    if (afterHeading === RETRACT_TAG) continue;
+    const note = `${RETRACT_TAG} ${stamp})_`;
+    content = content.slice(0, headingEnd + 1) + note + '\n' + content.slice(headingEnd + 1);
+  }
+
+  if (!content.endsWith('\n')) content += '\n';
+  return content;
+}
+
+// --- File-IO orchestration (the impure shell over the pure core) ----------
+
+// Leading indent is [ \t]* (NOT \s*) so it can't match the newline the
+// (?:^|\n) anchor already consumed — that overlap is the backtracking
+// ambiguity SonarCloud flags as ReDoS. Disjoint character classes = linear.
+const RICH_WHY_RE = /(?:^|\n)[ \t]*\*\*Why:\*\*[ \t]*([^\n]+)/;
+
+/** Read decision-class facts (type:project) from the project tier. */
+function readProjectDecisionFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter, body } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.type !== DECISION_TYPE) continue;
+      if (frontmatter.deleted_at) continue;
+      const whyMatch = String(body ?? '').match(RICH_WHY_RE);
+      out.push({
+        id: frontmatter.id,
+        type: frontmatter.type,
+        title: frontmatter.title ?? frontmatter.id,
+        createdAt: frontmatter.created_at ?? null,
+        why: whyMatch ? whyMatch[1].trim() : null,
+      });
+    } catch {
+      // unparseable file — reindex/HC-4 own that class; the journal skips it
+    }
+  }
+  // Stable chronological order (oldest first) so appends read like a timeline.
+  out.sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+  return out;
+}
+
+/** ids of forgotten facts (tombstone archive). */
+function readTombstonedIds(projectRoot) {
+  const ids = new Set();
+  const dir = join(projectRoot, 'context', 'memory', 'archive', 'tombstones');
+  if (!existsSync(dir)) return ids;
+  for (const name of readdirSync(dir)) {
+    const m = name.match(new RegExp(`^(${ID_CHARS})\\.md$`));
+    if (m) ids.add(m[1]);
+  }
+  return ids;
+}
+
+/**
+ * Read → append-only update → write context/DECISIONS.md. Idempotent: a run
+ * with nothing new is a no-op write (same bytes). Best-effort: never throws
+ * into the caller (a journal failure must not break a capture/read path).
+ *
+ * @returns {{written:boolean, path:string, appended:number}|{written:false,error:string}}
+ */
+export function syncDecisionsJournal({ projectRoot, now } = {}) {
+  try {
+    const path = join(projectRoot, 'context', 'DECISIONS.md');
+    const existingContent = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const facts = readProjectDecisionFacts(projectRoot);
+    const tombstonedIds = readTombstonedIds(projectRoot);
+    const before = existingContent;
+    const next = updateDecisionsJournal({
+      existingContent,
+      facts,
+      tombstonedIds,
+      now: now ?? new Date().toISOString(),
+    });
+    if (next !== before) {
+      writeFileSync(path, next, 'utf8');
+      return { written: true, path, appended: next.length - before.length };
+    }
+    return { written: false, path, appended: 0 };
+  } catch (err) {
+    return { written: false, error: err?.message ?? String(err) };
+  }
+}

package/src/digest.mjs

@@ -0,0 +1,89 @@
+// `cmk digest` — a regenerated, readable render of everything the kit currently
+// knows (Task 147, D-132). Facts by type + the persona + active threads, as one
+// markdown page. The README-demo artifact.
+//
+// REGENERATED (not append-only): unlike DECISIONS.md (the permanent journal),
+// the digest is a CURRENT-KNOWLEDGE snapshot — it should reflect only what
+// exists now, so it is rebuilt on every invocation (the INDEX.md lifecycle,
+// correct here). The two surfaces differ on purpose: digest = "what do we know
+// now", DECISIONS.md = "what did we decide over time" (D-161).
+//
+// Read-only by contract: pure reads over the fact archive + scratchpads. The
+// `--decisions` flag also triggers the DECISIONS.md journal sync (the one
+// mutation, delegated to the append-only writer).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
+
+const TYPE_ORDER = ['project', 'feedback', 'reference', 'user'];
+const TYPE_LABEL = {
+  project: 'Decisions & project state',
+  feedback: 'Working-style & preferences',
+  reference: 'References',
+  user: 'About the user',
+};
+
+function readFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const facts = [];
+  if (!existsSync(dir)) return facts;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.deleted_at) continue;
+      facts.push({
+        id: frontmatter.id,
+        type: frontmatter.type ?? 'unknown',
+        title: frontmatter.title ?? frontmatter.id,
+        trust: frontmatter.trust ?? 'unknown',
+        createdAt: frontmatter.created_at ?? null,
+      });
+    } catch {
+      // unparseable — reindex/HC-4 own that class
+    }
+  }
+  return facts;
+}
+
+/**
+ * Build the digest markdown from facts (pure — exported for testing).
+ * @param {Array} facts
+ * @param {{now?:string}} [opts]
+ */
+export function buildDigest(facts, { now } = {}) {
+  const stamp = (now ?? new Date().toISOString()).slice(0, 10);
+  const lines = [`# Memory digest — ${stamp}`, ''];
+  if (facts.length === 0) {
+    lines.push('_Memory is empty — capture starts as you work._', '');
+    return lines.join('\n');
+  }
+  lines.push(`${facts.length} fact(s) in project memory.`, '');
+
+  const byType = new Map();
+  for (const f of facts) {
+    if (!byType.has(f.type)) byType.set(f.type, []);
+    byType.get(f.type).push(f);
+  }
+  const orderedTypes = [
+    ...TYPE_ORDER.filter((t) => byType.has(t)),
+    ...[...byType.keys()].filter((t) => !TYPE_ORDER.includes(t)),
+  ];
+  for (const type of orderedTypes) {
+    const group = byType.get(type).slice().sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    lines.push(`## ${TYPE_LABEL[type] ?? type} (${group.length})`, '');
+    for (const f of group) {
+      const date = String(f.createdAt ?? '').slice(0, 10) || '—';
+      lines.push(`- **${f.title}** · \`${f.id}\` · ${f.trust} · ${date}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/** Read facts + render the digest for a project (read-only). */
+export function digest({ projectRoot, now } = {}) {
+  const facts = readFacts(projectRoot);
+  return buildDigest(facts, { now });
+}

package/src/doctor.mjs

@@ -1,4 +1,4 @@
-// `cmk doctor` — health checks HC-1..HC-7 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120).
+// `cmk doctor` — health checks HC-1..HC-8 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120; HC-8 native bindings added in Task 141a).
 //
 // Public boundary:
 //   async runDoctor({projectRoot, userDir, now, promptUser?, ...overrides})
@@ -44,6 +44,8 @@ import { nowIso } from './audit-log.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
 import { cronSentinelPath } from './lazy-compress.mjs';
 import { getNativeAutoMemoryState } from './native-memory.mjs';
+import { checkKitBinding, checkEmbedderBinding } from './native-binding.mjs';
+import { resolveDefaultSearchMode } from './semantic-backend.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -470,13 +472,67 @@ function hc7StaleLocks({ projectRoot, userDir }) {
   };
 }
 
+// --- HC-8: native bindings present (npm 12 readiness, Task 141a) -------
+// The BACKSTOP, not the primary UX: `cmk install` probes + asks inline
+// (the user's 2026-06-12 steer); HC-8 catches the after-the-fact states
+// (npm upgraded later, package reinstalled without the allow flag).
+// The repair is an `npm install -g` → requiresInstall per the design §14
+// ask-before-install rule.
+async function hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe }) {
+  const kitProbe = kitBindingProbe ?? checkKitBinding;
+  const kit = kitProbe();
+  if (!kit.ok) {
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'fail',
+      message: `better-sqlite3 native binding unavailable (${kit.reason}) — most common cause: npm 12 blocks dependency install scripts by default, so a fresh install skips the binding build (a Node major upgrade is the other); search/reindex will crash until it is rebuilt`,
+      recoveryCommand: kit.remedy,
+      requiresInstall: true,
+    };
+  }
+  // The embedder matters only when this project actually defaults to it.
+  const mode = resolveDefaultSearchMode({ projectRoot });
+  if (mode === 'keyword') {
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'pass',
+      message: 'better-sqlite3 binding healthy (semantic not configured — embedder not checked)',
+    };
+  }
+  const embedderProbe = embedderBindingProbe ?? checkEmbedderBinding;
+  const embedder = await embedderProbe();
+  if (!embedder.ok) {
+    const state = embedder.installed
+      ? `installed but its native binding failed (${embedder.reason}) — npm 12 blocks onnxruntime-node's install script by default`
+      : `not installed, but search.default_mode is '${mode}'`;
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'fail',
+      message: `semantic embedder ${state}; searches degrade to keyword until fixed`,
+      recoveryCommand: embedder.remedy,
+      requiresInstall: true,
+    };
+  }
+  return {
+    id: 'HC-8',
+    name: 'Native bindings present (npm 12 readiness)',
+    status: 'pass',
+    message: `better-sqlite3 binding healthy; embedder import OK (default mode: ${mode}; the deep pipeline check runs at --with-semantic warm)`,
+  };
+}
+
 /**
- * Run the full 7-check health audit.
+ * Run the full 8-check health audit.
  *
  * @param {object} opts
  * @param {string} opts.projectRoot
  * @param {string} [opts.userDir]
  * @param {string} [opts.now]
+ * @param {Function} [opts.kitBindingProbe] - HC-8 test seam.
+ * @param {Function} [opts.embedderBindingProbe] - HC-8 test seam.
  * @returns {Promise<{action, checks, duration_ms}>}
  *
  * Note: M3 fix (skill-review 2026-05-28) dropped the v0.1.0 `promptUser`
@@ -489,6 +545,8 @@ export async function runDoctor({
   projectRoot,
   userDir,
   now,
+  kitBindingProbe,
+  embedderBindingProbe,
 } = {}) {
   const t0 = Date.now();
   if (!projectRoot) {
@@ -510,10 +568,11 @@ export async function runDoctor({
   const c5 = hc5CronRegistered({ projectRoot });
   const c6 = hc6NativeAutoMemory({ projectRoot, now: ts });
   const c7 = hc7StaleLocks({ projectRoot, userDir: resolvedUserDir });
+  const c8 = await hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe });
 
   return {
     action: 'completed',
-    checks: [c1, c2, c3, c4, c5, c6, c7],
+    checks: [c1, c2, c3, c4, c5, c6, c7, c8],
     duration_ms: Date.now() - t0,
   };
 }

package/src/forget.mjs

@@ -172,6 +172,12 @@ function scrubAllScratchpads(tierRoot, id) {
     if (!entry.isFile()) continue;
     if (!entry.name.endsWith('.md')) continue;
     if (entry.name === 'INDEX.md') continue;
+    // DECISIONS.md is the APPEND-ONLY decision journal (Task 147 / D-161), NOT
+    // a scratchpad — forget must NOT strip its id-bearing lines (the marker +
+    // **Fact:** line). The journal sync marks the entry RETRACTED in place
+    // instead (preserving the trail). Scrubbing it here would delete the
+    // entry's marker and break the retract-in-place path (composition bug).
+    if (entry.name === 'DECISIONS.md') continue;
     const p = join(tierRoot, entry.name);
     const r = scrubScratchpadFile(p, id);
     if (r.changed) edits.push({ path: p, removed: r.removed });

package/src/import-anthropic-memory.mjs

@@ -40,7 +40,7 @@ import {
 } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { writeBullet } from './provenance.mjs';
-import { createHash } from 'node:crypto';
+import { hashContent } from './content-hash.mjs';
 
 const MEMORY_REL = ['context', 'MEMORY.md'];
 
@@ -236,7 +236,7 @@ export async function importAnthropicMemory({
   // an import failed and search degraded to the stale index (cut-gate9 F-13).
   const bulletLines = proposals
     .map((p) => {
-      const sha1 = createHash('sha1').update(p.text, 'utf8').digest('hex');
+      const sha1 = hashContent(p.text);
       const formatted = writeBullet({
         id: p.id,
         text: p.text,