@lh8ppl/claude-memory-kit 0.2.1 → 0.2.2

package/README.md

@@ -6,10 +6,10 @@
 
 - **Cross-project persona — the wedge (v0.2)** — when you state how you work *everywhere* ("always use uv, never pip", "from now on run the linter before committing"), the per-turn auto-extract promotes it into your **user tier** (`~/.claude-memory-kit/`) **that turn**. So a brand-new project **cold-opens already knowing your style** — layered structure, your tooling, your testing discipline — with no hand-curation and no waiting. Carry it between your own machines with `cmk persona export`/`import`, or pin a single fact across projects with `cmk lessons promote`.
 - **Frozen snapshot at session start** — MEMORY.md + USER.md + SOUL.md + INDEX.md + today's session log inject once at the first tool call, so Claude sees your context every session without you re-telling it.
-- **Auto-extract on every assistant turn** — a background `claude --print` subagent reads each turn and saves durable facts (decisions, preferences, environment) to memory. No manual writes needed.
+- **Auto-extract on every assistant turn** — a background `claude --print` subagent reads each turn and saves durable facts to memory. Durable project knowledge (setup/config, conventions, workflows, tool quirks) becomes a **rich Why/How fact file** (structured + searchable); lighter signals stay terse `MEMORY.md` bullets. Runs automatically, so the rich tier survives even when the model uses Claude Code's built-in memory instead. No manual writes needed.
 - **Explicit capture when you want it** — say "remember this" / "from now on" / "we decided" / "forget X" (the `memory-write` skill), or run `cmk remember "<fact>"`. Both dedup, screen for secrets, abstract machine paths to `~`, and write silently.
 - **Search + MCP** — `cmk search "<term>"` (keyword/hybrid over facts + scratchpads); `cmk mcp` exposes the same to Claude Code as tools.
-- **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows.
+- **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows. The session-buffer rollup self-heals at session start too, so memory stays bounded even if you never cleanly close the window.
 - **Per-project, in-repo** — `context/` lives inside your project and travels with `git clone`. Each project keeps its own memory.
 - **9 health checks** — `cmk doctor` validates install, hook wiring, distill freshness, INDEX consistency, cron registration, and stale locks.
 

package/bin/cmk-capture-prompt.mjs

@@ -11,7 +11,6 @@
 // transcript, emit {"continue": true}. Always exit 0 — a hook that errors
 // would interrupt the user mid-prompt.
 
-import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -19,35 +18,36 @@ function emitContinue() {
   process.stdout.write('{"continue": true}');
 }
 
-let rawInput = '';
-try {
-  rawInput = readFileSync(0, 'utf8');
-} catch {
-  emitContinue();
-  process.exit(0);
-}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'capture-prompt.mjs');
 
-let payload;
+let readHookStdin;
+let capturePrompt;
 try {
-  payload = rawInput.trim() === '' ? {} : JSON.parse(rawInput);
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ capturePrompt } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-prompt: failed to parse stdin JSON: ${err?.message ?? err}\n`,
+    `cmk-capture-prompt: failed to load modules: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);
 }
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const modulePath = join(__dirname, '..', 'src', 'capture-prompt.mjs');
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const rawInput = readHookStdin({ isTTY: process.stdin.isTTY });
 
-let capturePrompt;
+let payload;
 try {
-  ({ capturePrompt } = await import(pathToFileURL(modulePath).href));
+  payload = rawInput.trim() === '' ? {} : JSON.parse(rawInput);
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-prompt: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-capture-prompt: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);

package/bin/cmk-capture-turn.mjs

@@ -13,7 +13,7 @@
 // append to transcripts, spawn detached auto-extract, emit
 // {"continue": true}, exit 0 within ~50ms (NFR-1). Always exit 0.
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -21,27 +21,9 @@ function emitContinue() {
   process.stdout.write('{"continue": true}');
 }
 
-let raw = '';
-try {
-  raw = readFileSync(0, 'utf8');
-} catch {
-  emitContinue();
-  process.exit(0);
-}
-
-let payload;
-try {
-  payload = raw.trim() === '' ? {} : JSON.parse(raw);
-} catch (err) {
-  process.stderr.write(
-    `cmk-capture-turn: failed to parse stdin JSON: ${err?.message ?? err}\n`,
-  );
-  emitContinue();
-  process.exit(0);
-}
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
 const modulePath = join(__dirname, '..', 'src', 'capture-turn.mjs');
 
 // Auto-extract path: env override → sibling cmk-auto-extract.mjs (ships
@@ -53,12 +35,31 @@ const autoExtractPath =
     ? join(__dirname, 'cmk-auto-extract.mjs')
     : null);
 
+let readHookStdin;
 let captureTurn;
 try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
   ({ captureTurn } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-turn: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-capture-turn: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  emitContinue();
+  process.exit(0);
+}
+
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-turn: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);

package/bin/cmk-compress-session.mjs

@@ -43,8 +43,8 @@ try {
 }
 
 // Drain the hook payload so Claude Code's pipe closes cleanly — but NOT when
-// stdin is an interactive TTY (a manual run): readFileSync(0) would block
-// forever on a console that never sends EOF, hanging before any of the body
+// stdin is an interactive TTY (a manual run): a blocking stdin read would hang
+// forever on a console that never sends EOF, before any of the body
 // runs (DECISION-LOG 2026-06-06). The payload is discarded; we read state from
 // disk. readHookStdin returns '' for a TTY so a manual invocation finishes.
 readHookStdin({ isTTY: process.stdin.isTTY });

package/bin/cmk-inject-context.mjs

@@ -14,19 +14,13 @@
 // unconditionally — a throwing SessionStart hook would interrupt
 // session start, worse than an empty additionalContext.
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-// Drain stdin so callers blocking on EPIPE don't hang.
-try {
-  readFileSync(0, 'utf8');
-} catch {
-  // stdin not connected; fine.
-}
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
 const modulePath = join(__dirname, '..', 'src', 'inject-context.mjs');
 
 // Resolve the sibling lazy-compress bin (ships in this same bin/ dir) so
@@ -39,14 +33,14 @@ const compressLazyPath =
     ? join(__dirname, 'cmk-compress-lazy.mjs')
     : null);
 
+let readHookStdin;
 let injectContext;
 try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
   ({ injectContext } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-inject-context: failed to load module at ${modulePath}: ${
-      err?.message ?? String(err)
-    }\n`,
+    `cmk-inject-context: failed to load modules: ${err?.message ?? String(err)}\n`,
   );
   process.stdout.write(
     JSON.stringify({
@@ -59,6 +53,12 @@ try {
   process.exit(0);
 }
 
+// Drain stdin so callers blocking on EPIPE don't hang — but NOT on an
+// interactive TTY (a manual run): a blocking stdin read would hang forever on a
+// console that never sends EOF (Task 101; DECISION-LOG 2026-06-06). The payload
+// is discarded; readHookStdin returns '' for a TTY so a manual run finishes.
+readHookStdin({ isTTY: process.stdin.isTTY });
+
 try {
   const r = injectContext({ cwd: process.cwd(), compressLazyPath });
   process.stdout.write(JSON.stringify(r.hookOutput));

package/bin/cmk-observe-edit.mjs

@@ -11,37 +11,38 @@
 // must never surface in the user's session. The append is
 // fire-and-forget by design.
 
-import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-let raw = '';
-try {
-  raw = readFileSync(0, 'utf8');
-} catch {
-  process.exit(0);
-}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'observe-edit.mjs');
 
-let payload;
+let readHookStdin;
+let observeEdit;
 try {
-  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ observeEdit } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-observe-edit: failed to parse stdin JSON: ${err?.message ?? err}\n`,
+    `cmk-observe-edit: failed to load modules: ${err?.message ?? err}\n`,
   );
   process.exit(0);
 }
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const modulePath = join(__dirname, '..', 'src', 'observe-edit.mjs');
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
 
-let observeEdit;
+let payload;
 try {
-  ({ observeEdit } = await import(pathToFileURL(modulePath).href));
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
 } catch (err) {
   process.stderr.write(
-    `cmk-observe-edit: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-observe-edit: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {

package/src/auto-extract.mjs

@@ -48,8 +48,11 @@ import {
   appendFileSync,
 } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
 import { generateId } from '@lh8ppl/cmk-canonicalize';
 import { memoryWrite } from './memory-write.mjs';
+import { writeFact } from './write-fact.mjs';
+import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
 import { pidIsAlive } from './lock-discipline.mjs';
 import { nowIso } from './audit-log.mjs';
@@ -284,6 +287,21 @@ export function buildExtractionInstructions() {
     '',
     'Note: assistant-origin candidates are auto-demoted one trust level before routing (HIGH → MEDIUM → LOW → discarded). This is intentional — assistant inferences need user review. Emit your honest trust assessment; the routing layer handles demotion.',
     '',
+    'ALSO — rich fact files (durable project KNOWLEDGE). This is a SEPARATE output from the terse TRUST_ lines. When a turn reveals a durable, substantive piece of project knowledge worth a FULL record — a setup/configuration fact (trigger 3), a project convention (trigger 4), a completed multi-step workflow worth recording (trigger 5), or a tool quirk/workaround (trigger 6) — emit a BEGIN_FACT block (below) INSTEAD OF a terse TRUST_ line for it. Keep terse TRUST_ lines for the LIGHTER signals: user corrections and discovered preferences (triggers 1–2) and active threads. Emit each fact EITHER as a rich BEGIN_FACT block OR as a terse TRUST_ line — NEVER both.',
+    'Format (one block per durable fact):',
+    '  BEGIN_FACT',
+    '  type: project',
+    '  title: <short Title-Case headline, ≤ 80 chars>',
+    '  body: <what is true; if it has parts, give a short labelled markdown breakdown over multiple lines, NOT one vague sentence>',
+    '  why: <why it is true / why it matters — the rationale a future session needs>',
+    '  how: <how the next session should apply it>',
+    '  END_FACT',
+    'Rules for BEGIN_FACT blocks:',
+    '  - body may span multiple lines (markdown bullets are encouraged when the knowledge has parts — make the saved fact genuinely useful to a future session, at least as detailed as a careful hand-written note). Write it as plain markdown on the lines after `body:` — do NOT use a YAML block scalar (`|` or `>`).',
+    '  - title AND body are required; why/how are strongly preferred but optional. type defaults to project.',
+    '  - Do NOT invent facts; synthesize only what the turn shows. Never put a secret, token, password, or key in a block.',
+    '  - These facts are saved automatically (no review step), so be selective: only genuinely durable knowledge, at most a few per turn.',
+    '',
     'ALSO — cross-project doctrine. This is a REQUIRED, PER-FACT pass, separate from the TRUST_ lines above. Re-scan the SAME turn for EVERY fact that expresses how this user works in ALL their projects (tooling habits, how they structure their work, communication / process style — NOT specifics that belong to this ONE project, like a particular value, name, or detail that would not carry to their other projects). **For EACH such cross-project fact, emit its OWN PERSONA CANDIDATE line — one line per fact. If the turn states THREE cross-project rules, emit THREE PERSONA CANDIDATE lines. Never collapse several rules into one line, and never skip a rule because the turn is busy or already has TRUST_ lines.** Format (one line per cross-project fact):',
     '  PERSONA CANDIDATE | target=<HABITS.md|LESSONS.md|USER.md> | section=<Section> | confidence=<high|medium|low> | <one-line restatement>',
     '    - HABITS.md  → sections: Iteration Cadence | Destructive Operations | Communication Style',
@@ -310,7 +328,11 @@ function buildExtractionPrompt({ userTurn, assistantTurn, dedupContext }) {
   return sections.join('\n');
 }
 
-function parseCandidates(haikuOutput) {
+// Exported for the live-Haiku smoke (spawn-smoke-auto-extract-rich.test.js),
+// which asserts the enriched prompt still elicits parseable terse OR rich
+// output from real Haiku. The terse format is the extraction prompt's contract,
+// same as parseRichFacts above.
+export function parseCandidates(haikuOutput) {
   if (!haikuOutput || typeof haikuOutput !== 'string') return [];
   const lines = haikuOutput.split('\n');
   const candidates = [];
@@ -328,6 +350,127 @@ function parseCandidates(haikuOutput) {
   return candidates;
 }
 
+// --- Rich-fact parser (Task 103) ------------------------------------
+
+// Durable project KNOWLEDGE (the six triggers' config / convention / workflow /
+// quirk facts) is emitted by Haiku as a fenced block, parsed here into the
+// fields writeFact() needs. Lives next to parseCandidates + buildExtraction-
+// Instructions — the format and its parser stay together (same as the terse
+// TRUST_ surface). See design §6.4.
+//
+//   BEGIN_FACT
+//   type: project
+//   title: <short title>
+//   body: <summary; MAY continue as markdown bullets on following lines>
+//   why: <rationale>
+//   how: <how to apply>
+//   END_FACT
+//
+// A field's value continues across lines until the next recognized key or the
+// block close — so `body` can hold a multi-line structured breakdown (the
+// native-parity bar). type defaults to 'project' when absent/invalid; a block
+// missing title OR body is skipped (writeFact requires both).
+const RICH_FACT_VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
+const RICH_FACT_KEYS = new Set(['type', 'title', 'body', 'why', 'how']);
+// Defensive per-field cap so a runaway block can't write an unbounded fact body.
+const RICH_FACT_FIELD_CAP = 4000;
+
+// Match a `key: value` field line. String-based (not a regex) — deterministically
+// linear, no backtracking surface. Semantics: the key must be at the START of
+// the line (no leading whitespace, mirroring an `^key` anchor), with optional
+// whitespace before the colon. Returns {key, value} or null (a continuation /
+// non-key line, e.g. a `- bullet:` inside a body).
+function matchRichFactKey(line) {
+  const idx = line.indexOf(':');
+  if (idx <= 0) return null;
+  const keyPart = line.slice(0, idx);
+  if (keyPart.trimStart().length !== keyPart.length) return null; // leading ws → not a key
+  const key = keyPart.trimEnd().toLowerCase();
+  if (!RICH_FACT_KEYS.has(key)) return null;
+  return { key, value: line.slice(idx + 1).trimStart() };
+}
+
+// A YAML block-scalar indicator as a field's entire first-line value (`|`,
+// `|-`, `>`, `>+`, `|2`, …). Live Haiku formats a multi-line body as `body: |`
+// then indents the content — we must not keep the literal `|` or the indent.
+const BLOCK_SCALAR_RE = /^[|>][+-]?\d*$/;
+
+// Normalize a parsed field value: drop a leading block-scalar indicator line,
+// then dedent (strip the common leading whitespace the block scalar adds). A
+// plain single-line value passes through untouched.
+function cleanFieldValue(raw) {
+  const lines = (raw ?? '').split('\n');
+  if (lines.length && BLOCK_SCALAR_RE.test(lines[0].trim())) lines.shift();
+  const indents = lines
+    .filter((l) => l.trim() !== '')
+    .map((l) => (l.match(/^[ \t]*/)?.[0].length ?? 0));
+  const minIndent = indents.length ? Math.min(...indents) : 0;
+  return lines.map((l) => l.slice(minIndent)).join('\n').trim();
+}
+
+function parseRichFactBlock(blockLines) {
+  const fields = {};
+  let currentKey = null;
+  for (const line of blockLines) {
+    const m = matchRichFactKey(line);
+    if (m) {
+      currentKey = m.key;
+      fields[currentKey] = m.value; // first-line value (may be '' or a `|` scalar)
+    } else if (currentKey) {
+      // Continuation of the current field — multi-line body / why / how.
+      fields[currentKey] += '\n' + line;
+    }
+    // A non-key line before any key is ignored.
+  }
+  const title = cleanFieldValue(fields.title);
+  const body = cleanFieldValue(fields.body);
+  if (!title || !body) return null; // writeFact requires both
+  let type = cleanFieldValue(fields.type).toLowerCase();
+  if (!RICH_FACT_VALID_TYPES.has(type)) type = 'project';
+  const why = cleanFieldValue(fields.why);
+  const how = cleanFieldValue(fields.how);
+  return {
+    type,
+    title: title.slice(0, RICH_FACT_FIELD_CAP),
+    body: body.slice(0, RICH_FACT_FIELD_CAP),
+    why: why ? why.slice(0, RICH_FACT_FIELD_CAP) : '',
+    how: how ? how.slice(0, RICH_FACT_FIELD_CAP) : '',
+  };
+}
+
+// Exported for direct unit-testing (cli-rich-fact.test.js) — the BEGIN_FACT
+// format is the extraction prompt's contract, pinned independently of a live
+// Haiku call.
+export function parseRichFacts(haikuOutput) {
+  if (!haikuOutput || typeof haikuOutput !== 'string') return [];
+  const lines = haikuOutput.split('\n');
+  const facts = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i].trim().toUpperCase() !== 'BEGIN_FACT') {
+      i++;
+      continue;
+    }
+    // Collect block lines until END_FACT, the next BEGIN_FACT (missing close —
+    // don't let it swallow the following block), or end-of-output.
+    i++;
+    const blockLines = [];
+    while (i < lines.length) {
+      const marker = lines[i].trim().toUpperCase();
+      if (marker === 'END_FACT') {
+        i++;
+        break;
+      }
+      if (marker === 'BEGIN_FACT') break; // close here; leave i for the outer loop
+      blockLines.push(lines[i]);
+      i++;
+    }
+    const fact = parseRichFactBlock(blockLines);
+    if (fact) facts.push(fact);
+  }
+  return facts;
+}
+
 // Demote assistant-origin candidates one trust level. User-origin
 // candidates pass through unchanged — they're authoritative.
 // Order: must run BEFORE applyRetainOverride so the override beats
@@ -456,6 +599,45 @@ function routeMedium({ candidate, projectRoot, ts }) {
   return { action: 'queued', id, path: reviewPath };
 }
 
+// Route a rich fact to the project fact store via writeFact() (Task 103).
+//
+// Direct-to-fact-store (NOT the review queue the terse medium-trust path uses):
+// the point of Task 103 is AUTOMATIC native-parity capture — native writes its
+// fact files with no approval step, so parity requires the same. The fact store
+// is searchable-but-not-full-trust-injected, writeFact already screens every
+// write (home-path sanitize + Poison_Guard + schema + INDEX/reindex), and a
+// later explicit `cmk remember` (trust:high) supersedes. See design §6.4.
+//
+// trust:medium / write_source:auto-extract marks it as a Haiku synthesis
+// (proposal-grade), below the explicit-high tier. The body is built by the SAME
+// rich-fact.mjs helper the explicit path uses, so an auto-extracted fact reads
+// identically to a `cmk remember --why/--how` one.
+function routeRichFact({ candidate, projectRoot, ts }) {
+  const body = buildRichFactBody({
+    text: candidate.body,
+    why: candidate.why,
+    how: candidate.how,
+  });
+  return writeFact({
+    tier: 'P',
+    type: candidate.type,
+    slug: slugifyFact(candidate.title),
+    title: candidate.title,
+    body,
+    writeSource: 'auto-extract',
+    trust: 'medium',
+    sourceFile: 'auto-extract',
+    sourceLine: 1,
+    // Content fingerprint for the provenance field — NOT a security context.
+    // Matches the kit's sha1-of-content convention (write-fact.mjs caller in
+    // subcommands.runRememberRich, memory-write.mjs); writeFact dedups by the
+    // content-addressed id, this is just source_sha1. // NOSONAR
+    sourceSha1: createHash('sha1').update(body).digest('hex'), // NOSONAR
+    createdAt: ts,
+    projectRoot,
+  });
+}
+
 // --- NDJSON extract.log ---------------------------------------------
 
 function writeExtractLogEntry({ projectRoot, ts, entry }) {
@@ -668,6 +850,22 @@ export async function runAutoExtract({
     candidates = applyRetainOverride(candidates, retainSegments);
     candidates = dedupByCanonicalId(candidates);
 
+    // Task 103 — rich fact synthesis on the native-immune Stop-hook path. The
+    // SAME Haiku output may carry BEGIN_FACT blocks (durable project KNOWLEDGE)
+    // alongside the terse TRUST_ lines; route them to the fact store via
+    // writeFact (richer + searchable). No second LLM call — same outputText.
+    const richFacts = parseRichFacts(haikuResult.outputText);
+    // XOR safety net: the prompt asks Haiku to emit a fact as EITHER a rich
+    // block OR a terse line, never both. If it does both for the same fact, the
+    // rich block wins — drop any terse candidate whose canonical id matches a
+    // rich fact's body, so it isn't ALSO written as a MEMORY.md bullet. (Keyed
+    // on the rich fact's raw `body` headline vs the terse `text` — the prompt
+    // enforces the semantic XOR; this catches the exact-restatement case.)
+    if (richFacts.length > 0) {
+      const richIds = new Set(richFacts.map((f) => generateId('P', f.body)));
+      candidates = candidates.filter((c) => !richIds.has(generateId('P', c.text)));
+    }
+
     // Task 61 — inline cross-project promotion. The SAME Haiku output may
     // carry PERSONA CANDIDATE lines (cross-project doctrine); promote them to
     // the user tier THIS run (vs the weekly auto-persona janitor). No second
@@ -719,10 +917,11 @@ export async function runAutoExtract({
         }
       : {};
 
-    if (candidates.length === 0 && !personaLanded) {
+    if (candidates.length === 0 && richFacts.length === 0 && !personaLanded) {
       const entry = {
         ...baseEntry,
         ...personaLogFields,
+        rich_facts_written: 0,
         success: true,
         skipped_reason: 'nothing_durable',
         duration_ms: Date.now() - t0,
@@ -735,6 +934,7 @@ export async function runAutoExtract({
         duration_ms: entry.duration_ms,
         logPath,
         candidates: [],
+        richFacts: [],
         persona,
       };
     }
@@ -787,9 +987,57 @@ export async function runAutoExtract({
       }
     }
 
-    const observation_count = writes.filter(
-      (w) => w.written === 'memory' || w.written === 'review' || w.written === 'conflict',
-    ).length;
+    // 6b. Route rich facts to the fact store (Task 103). Each writeFact is
+    //     isolated in try/catch — a Poison_Guard / schema / collision rejection
+    //     (or an unexpected throw) must NOT take down terse routing or the
+    //     persona pass, exactly like the inline persona isolation above. A
+    //     'created' counts toward observation_count; a 'skipped' (content
+    //     duplicate) is a no-op success that doesn't re-count; anything else is
+    //     'rejected' with its category for analytics (Door 4).
+    const richWrites = [];
+    for (const fact of richFacts) {
+      try {
+        const r = routeRichFact({ candidate: fact, projectRoot, ts });
+        let written;
+        if (r?.action === 'created') written = 'fact';
+        else if (r?.action === 'skipped') written = 'fact-duplicate';
+        else written = 'rejected';
+        const rec = { ...fact, written, result: r };
+        if (written === 'rejected') {
+          rec.rejected_category = r?.errorCategory ?? 'unknown';
+          // Trace the drop (§6.5 don't-lose-without-trace), mirroring the terse
+          // low-discard trace — a rejected rich fact is otherwise invisible once
+          // the detached process exits. TITLE ONLY, never the body: a
+          // poison_guard rejection means the body may carry a secret (the
+          // redacted excerpt is already in poison-guard.log). One NDJSON entry
+          // per rejection (Door 4).
+          writeExtractLogEntry({
+            projectRoot,
+            ts,
+            entry: {
+              event: 'rich_fact_rejected',
+              reason: 'rich_fact_rejected',
+              rejected_category: rec.rejected_category,
+              title: fact.title.slice(0, LOW_DISCARD_EXCERPT_MAX),
+            },
+          });
+        }
+        richWrites.push(rec);
+      } catch (err) {
+        richWrites.push({
+          ...fact,
+          written: 'rejected',
+          rejected_category: 'exception',
+          error: err?.message ?? String(err),
+        });
+      }
+    }
+    const richFactsWritten = richWrites.filter((w) => w.written === 'fact').length;
+
+    const observation_count =
+      writes.filter(
+        (w) => w.written === 'memory' || w.written === 'review' || w.written === 'conflict',
+      ).length + richFactsWritten;
 
     // Persona-only turn: no project candidate landed, but cross-project
     // doctrine promoted to the user tier this run. That IS a durable
@@ -799,6 +1047,7 @@ export async function runAutoExtract({
       const entry = {
         ...baseEntry,
         ...personaLogFields,
+        rich_facts_written: richFactsWritten,
         success: true,
         skipped_reason: 'nothing_durable',
         duration_ms: Date.now() - t0,
@@ -811,6 +1060,7 @@ export async function runAutoExtract({
         duration_ms: entry.duration_ms,
         logPath,
         candidates: writes,
+        richFacts: richWrites,
         persona,
       };
     }
@@ -818,6 +1068,7 @@ export async function runAutoExtract({
     const entry = {
       ...baseEntry,
       ...personaLogFields,
+      rich_facts_written: richFactsWritten,
       success: true,
       observation_count,
       duration_ms: Date.now() - t0,
@@ -829,6 +1080,7 @@ export async function runAutoExtract({
       duration_ms: entry.duration_ms,
       logPath,
       candidates: writes,
+      richFacts: richWrites,
       persona,
     };
   } finally {

package/src/compress-session.mjs

@@ -30,7 +30,8 @@ import {
   readFileSync,
   writeFileSync,
   appendFileSync,
-  truncateSync,
+  renameSync,
+  unlinkSync,
 } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { nowIso } from './audit-log.mjs';
@@ -46,6 +47,10 @@ const DEFAULT_MAX_OUTPUT_BYTES = 4096;
 
 const NOW_MD_RELATIVE = ['context', 'sessions', 'now.md'];
 const SESSIONS_DIR_RELATIVE = ['context', 'sessions'];
+// Task 106 (§16.27): the live buffer is CLAIMED by an atomic rename to this
+// suffix before compression, so concurrent PostToolUse/capture-turn appends
+// land on a fresh now.md without racing the truncate.
+const ROLLING_SUFFIX = '.rolling-';
 
 // Compression prompt (design §8.4). Written from scratch per the
 // licensing posture in SOURCES.md (claude-remember's prompts are not
@@ -126,13 +131,74 @@ function dateFromIso(ts) {
   return ts.slice(0, 10);
 }
 
-function readNowBuffer(projectRoot) {
-  const p = readNowMdPath(projectRoot);
-  if (!existsSync(p)) return '';
+// Task 106 (§16.27 file-rename pattern). ATOMICALLY claim the live buffer:
+// rename now.md → now.md.rolling-{ts}, then read the claimed copy. The rename is
+// atomic on POSIX (rename(2)) + NTFS (MoveFileEx), so a concurrent appender
+// (PostToolUse/capture-turn) that fires DURING the ~5–10s Haiku call lands on a
+// fresh now.md with zero contention — its content is never inside the
+// read→clear window the old `read then truncate(0)` left open. Returns the
+// claimed buffer + the rolling path (null when now.md is absent / the rename
+// raced, which the caller treats as an empty buffer).
+//
+// Bonus property — the rename also SERIALIZES concurrent rolls. compressSession
+// is gated by the 120s cooldown, but the marker is only touched on success, so
+// two callers (a SessionEnd + the Task 105 SessionStart-lazy roll) can both pass
+// the cooldown gate and reach here. Only ONE renameSync wins; the other gets
+// ENOENT (now.md already claimed) → returns an empty buffer → skips. No lock
+// needed; the atomic rename IS the mutex.
+function claimNowBuffer(projectRoot, ts) {
+  const nowPath = readNowMdPath(projectRoot);
+  if (!existsSync(nowPath)) return { buffer: '', rollingPath: null };
+  const rollingPath = nowPath + ROLLING_SUFFIX + String(ts).replace(/[:.]/g, '-');
+  try {
+    renameSync(nowPath, rollingPath);
+  } catch {
+    // now.md vanished or the rename lost a race — nothing to roll.
+    return { buffer: '', rollingPath: null };
+  }
+  let buffer = '';
+  try {
+    buffer = readFileSync(rollingPath, 'utf8');
+  } catch {
+    buffer = '';
+  }
+  return { buffer, rollingPath };
+}
+
+// Success path: the claimed buffer is safely compressed into today-{date}.md.
+// Drop the rolling file. now.md is owned by the (new) session's appenders now —
+// we do NOT recreate or touch it, so a concurrent append is never clobbered.
+function discardRolling(rollingPath) {
+  if (!rollingPath) return;
   try {
-    return readFileSync(p, 'utf8');
+    unlinkSync(rollingPath);
   } catch {
-    return '';
+    // best-effort; a leaked rolling file is inert (the next roll claims now.md,
+    // not now.md.rolling-*) and harmless beyond disk noise.
+  }
+}
+
+// Error/timeout path: the claimed buffer was NOT compressed — restore it so the
+// next roll retries it (the old impl's "leave now.md intact" contract). Prepend
+// it to anything a concurrent session appended to the fresh now.md (the claimed
+// content is OLDER, so it leads), preserving both with no truncate. Best-effort:
+// if the restore write fails, the rolling file stays as a recovery breadcrumb.
+function restoreRolling(projectRoot, rollingPath) {
+  if (!rollingPath || !existsSync(rollingPath)) return;
+  const nowPath = readNowMdPath(projectRoot);
+  try {
+    const claimed = readFileSync(rollingPath, 'utf8');
+    const current = existsSync(nowPath) ? readFileSync(nowPath, 'utf8') : '';
+    // Guarantee a newline boundary between the claimed (older) buffer and any
+    // concurrent appends. String op, not a regex — a trailing-anchored `\n*$`
+    // trips static-analysis's ReDoS heuristic (same convention as slugify in
+    // rich-fact.mjs / graduation.mjs).
+    const sep = claimed.endsWith('\n') ? '' : '\n';
+    const merged = current ? claimed + sep + current : claimed;
+    writeFileSync(nowPath, merged, 'utf8');
+    unlinkSync(rollingPath);
+  } catch {
+    // best-effort — see above
   }
 }
 
@@ -146,18 +212,6 @@ function appendToTodayMd({ projectRoot, date, body }) {
   return path;
 }
 
-function truncateNowMd(projectRoot) {
-  const p = readNowMdPath(projectRoot);
-  if (!existsSync(p)) return;
-  try {
-    truncateSync(p, 0);
-  } catch {
-    // Best-effort. If truncate fails (perm error etc.), the next
-    // session compresses a slightly-larger buffer — not a data-loss
-    // event.
-  }
-}
-
 function writeCompressLogEntry({ projectRoot, date, entry }) {
   const path = compressLogPath(projectRoot, date);
   mkdirSync(dirname(path), { recursive: true });
@@ -231,9 +285,13 @@ export async function compressSession({
     };
   }
 
-  // 2. Read live buffer; no-op if empty (tasks.md 22.1).
-  const buffer = readNowBuffer(projectRoot);
+  // 2. CLAIM the live buffer by atomic rename (Task 106 / §16.27), then read it;
+  //    no-op if empty (tasks.md 22.1). Claiming before the Haiku call is what
+  //    closes the race — a concurrent append during compression lands on a
+  //    fresh now.md, never inside a read→truncate window.
+  const { buffer, rollingPath } = claimNowBuffer(projectRoot, ts);
   if (buffer.trim() === '') {
+    discardRolling(rollingPath); // drop the (empty) claimed file if one was renamed
     const duration_ms = Date.now() - t0;
     const entry = {
       ts,
@@ -257,13 +315,14 @@ export async function compressSession({
   const input_bytes = Buffer.byteLength(buffer, 'utf8');
   const instructions = buildCompressionInstructions(maxOutputBytes);
 
-  // 3. Invoke backend. On throw: leave now.md intact (22.5).
+  // 3. Invoke backend. On throw: RESTORE the claimed buffer to now.md (22.5) so
+  //    the next session-end retries it — the file-rename analogue of the old
+  //    "leave now.md intact".
   //
   // Subprocess timeout: 50_000 ms. Sits under the 60s SessionEnd
   // hook ceiling (design §5.1) so on timeout the catch + log write
-  // complete BEFORE Claude Code kills the parent. now.md is left
-  // intact in the timeout case (the truncate step is reached only
-  // on the success path), so the next session-end retries naturally.
+  // complete BEFORE Claude Code kills the parent — including the
+  // restoreRolling call, so the buffer is never stranded in the rolling file.
   // See design §8.5 for the composition rationale.
   let result;
   try {
@@ -285,6 +344,8 @@ export async function compressSession({
     const errorCategory = err instanceof HaikuTimeoutError
       ? ERROR_CATEGORIES.HAIKU_TIMEOUT
       : ERROR_CATEGORIES.COMPRESS_FAILED;
+    // The claimed buffer wasn't compressed — put it back so it isn't lost.
+    restoreRolling(projectRoot, rollingPath);
     const duration_ms = Date.now() - t0;
     const entry = {
       ts,
@@ -316,8 +377,10 @@ export async function compressSession({
     body: output,
   });
 
-  // 5. Truncate now.md (22.3).
-  truncateNowMd(projectRoot);
+  // 5. The claimed buffer is safely in today-{date}.md — drop the rolling file
+  //    (Task 106/§16.27). now.md is untouched: any turn the new session appended
+  //    while we compressed stays put.
+  discardRolling(rollingPath);
 
   // 6. Touch cooldown marker so the next caller within 120s skips.
   touchCooldownMarker({ projectRoot, now: ts });

package/src/graduation.mjs

@@ -35,7 +35,7 @@ const VALID_WRITE_SOURCES = new Set([
 
 function slugify(s) {
   // Collapse non-alphanumerics to single dashes, cap, trim edges (string ops,
-  // no trailing-dash quantifier — matches subcommands.slugifyFact's ReDoS-safe
+  // no trailing-dash quantifier — matches rich-fact.slugifyFact's ReDoS-safe
   // shape).
   let base = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
   if (base.startsWith('-')) base = base.slice(1);

package/src/inject-context.mjs

@@ -740,7 +740,11 @@ export function injectContext({
   try {
     const verdict = detectStaleness({ projectRoot, now: ts });
     lazyTrigger = { verdict: verdict.action, reason: verdict.reason };
-    if (verdict.action === 'stale-daily' || verdict.action === 'stale-weekly') {
+    if (
+      verdict.action === 'stale-now' ||
+      verdict.action === 'stale-daily' ||
+      verdict.action === 'stale-weekly'
+    ) {
       const spawner = typeof testSpawnLazy === 'function' ? testSpawnLazy : spawnLazyCompress;
       const spawnResult = spawner(projectRoot, compressLazyPath);
       lazyTrigger = { ...lazyTrigger, ...spawnResult };

package/src/install.mjs

@@ -51,9 +51,17 @@ const CLI_SRC_DIR = dirname(__filename);
 const REPO_ROOT_DEV = resolve(CLI_SRC_DIR, '..', '..', '..');
 const CLI_PKG_DIR = resolve(CLI_SRC_DIR, '..');
 
-const GITIGNORE_START = '# claude-memory-kit:gitignore:start v0.1.0';
+// The start marker carries the install version (matching the CLAUDE.md block,
+// which is load-bearing for upgrade detection). The replace-regex in
+// injectGitignore ignores the version, so it's cosmetic for idempotency — but
+// it must not show a stale hardcode (was `v0.1.0` in every install). Built per
+// install from the kit version; see gitignoreStartMarker().
 const GITIGNORE_END = '# claude-memory-kit:gitignore:end';
 
+function gitignoreStartMarker(version) {
+  return `# claude-memory-kit:gitignore:start v${version}`;
+}
+
 /**
  * Read the kit version from the cli package's package.json.
  * Used as the default version for the CLAUDE.md marker.
@@ -216,12 +224,12 @@ function installTier(srcDir, destDir, { created, skipped, errors, vars }) {
  * Build the canonical .gitignore managed block from template/.gitignore.fragment.
  * Adds start/end markers around the fragment so we can refresh in place.
  */
-function buildGitignoreBlock(templateDir) {
+function buildGitignoreBlock(templateDir, version = getKitVersion()) {
   const fragmentPath = join(templateDir, '.gitignore.fragment');
   const fragment = existsSync(fragmentPath)
     ? readFileSync(fragmentPath, 'utf8').trim()
     : 'context.local/\ncontext/.index/\ncontext/.locks/';
-  return `${GITIGNORE_START}\n${fragment}\n${GITIGNORE_END}\n`;
+  return `${gitignoreStartMarker(version)}\n${fragment}\n${GITIGNORE_END}\n`;
 }
 
 /**
@@ -318,7 +326,7 @@ export async function install(options = {}) {
     });
   }
 
-  const gitignore = injectGitignore(projectRoot, buildGitignoreBlock(templateDir));
+  const gitignore = injectGitignore(projectRoot, buildGitignoreBlock(templateDir, version));
 
   // CLAUDE.md loader block — Task 4. Read the block content from the kit's
   // template/ and inject (or refresh) it inside marker delimiters. Never

package/src/lazy-compress.mjs

@@ -29,6 +29,7 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
+  readFileSync,
   statSync,
   writeFileSync,
   unlinkSync,
@@ -42,11 +43,13 @@ import {
 } from './cooldown.mjs';
 import { dailyDistill } from './daily-distill.mjs';
 import { weeklyCurate } from './weekly-curate.mjs';
+import { compressSession } from './compress-session.mjs';
 
 const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const SESSIONS_REL = ['context', 'sessions'];
 const LOCKS_REL = ['context', '.locks'];
+const NOW_MD_REL = ['context', 'sessions', 'now.md'];
 const RECENT_MD_REL = ['context', 'sessions', 'recent.md'];
 const CRON_SENTINEL_REL = ['context', '.locks', 'cron-registered'];
 const LAZY_LOG_REL = ['context', '.locks', 'lazy-compress.log'];
@@ -100,6 +103,25 @@ function listTodayFiles(projectRoot) {
   return matches;
 }
 
+// Task 105 (D-75): does now.md carry prior-session content? The now→today
+// roll (compressSession) fires only at SessionEnd, and Claude Code fires
+// SessionEnd ONLY on a clean window-close — so a never-cleanly-closed session
+// leaves now.md growing unbounded with no today-*.md/recent.md built. We detect
+// a non-empty now.md at SessionStart and let the lazy worker roll it. At
+// SessionStart now.md can only hold PRIOR-session turns (this session's
+// capture-turn writes haven't fired yet), so non-empty ⇒ stale. Emptiness must
+// match compressSession's own `buffer.trim() === ''` check so the spawn verdict
+// and the actual roll agree (else we'd spawn for a roll that immediately skips).
+function nowMdHasContent(projectRoot) {
+  const p = join(projectRoot, ...NOW_MD_REL);
+  if (!existsSync(p)) return false;
+  try {
+    return readFileSync(p, 'utf8').trim() !== '';
+  } catch {
+    return false;
+  }
+}
+
 function recentMdMtimeMs(projectRoot) {
   const p = join(projectRoot, ...RECENT_MD_REL);
   if (!existsSync(p)) return null;
@@ -113,9 +135,11 @@ function recentMdMtimeMs(projectRoot) {
 /**
  * Cheap inline staleness check. Runs in <5ms — one stat + a few existsSync.
  *
- * Verdict semantics:
+ * Verdict semantics (precedence: cron > no-context-dir > now > weekly > daily > fresh):
  *   - 'cron-active'   : sentinel exists; cron will handle staleness. No-op.
  *   - 'no-context-dir': context/sessions/ doesn't exist. No-op (kit not installed).
+ *   - 'stale-now'     : now.md carries prior-session content (Task 105/D-75) — the
+ *                       now→today roll the SessionEnd hook would have done.
  *   - 'stale-weekly'  : ANY today-*.md older than 7d exists. Weekly curate needed.
  *   - 'stale-daily'   : no OLD today files, but recent.md is missing OR older than dailyTtlMs.
  *   - 'fresh'         : recent.md exists + younger than dailyTtlMs AND no OLD today files.
@@ -141,6 +165,16 @@ export function detectStaleness({
     return { action: 'no-context-dir', reason: 'sessions-dir-missing' };
   }
 
+  // Task 105 (D-75): a non-empty now.md is the now→today roll the SessionEnd
+  // hook would have done. It takes PRECEDENCE over daily/weekly because it's
+  // the FIRST pipeline level (now → today → recent → archive) — roll it this
+  // SessionStart; the today→recent + weekly levels cascade on subsequent
+  // SessionStarts once now.md is drained. (cron-active above still wins — a
+  // registered cron owns the whole pipeline.)
+  if (nowMdHasContent(projectRoot)) {
+    return { action: 'stale-now', reason: 'now-md-has-prior-session-content' };
+  }
+
   const ts = now ?? nowIso();
   const nowMs = new Date(ts).getTime();
   const files = listTodayFiles(projectRoot);
@@ -281,12 +315,24 @@ export async function runLazyCompress({
     return { action: 'skipped', reason: verdict.reason, duration_ms };
   }
 
-  // verdict.action is 'stale-daily' or 'stale-weekly'.
-  // Delegate to the appropriate cycle, passing cooldownMs=0 because we
-  // already gated above; the inner call shouldn't gate a second time on
-  // the same marker (which they would not touch yet).
+  // verdict.action is 'stale-now', 'stale-daily', or 'stale-weekly'.
+  // Delegate to the matching pipeline stage, passing cooldownMs=0 because we
+  // already gated above; the inner call shouldn't gate a second time on the
+  // same marker. Task 105: 'stale-now' rolls now.md → today-*.md via
+  // compressSession (the level the SessionEnd hook owns); the today→recent +
+  // weekly levels cascade on the next SessionStart once now.md is drained.
   let result;
-  if (verdict.action === 'stale-weekly') {
+  let delegatedTo;
+  if (verdict.action === 'stale-now') {
+    delegatedTo = 'compress-session';
+    result = await compressSession({
+      projectRoot,
+      backend,
+      now: ts,
+      cooldownMs: 0,
+    });
+  } else if (verdict.action === 'stale-weekly') {
+    delegatedTo = 'weekly-curate';
     result = await weeklyCurate({
       projectRoot,
       backend,
@@ -294,6 +340,7 @@ export async function runLazyCompress({
       cooldownMs: 0,
     });
   } else {
+    delegatedTo = 'daily-distill';
     result = await dailyDistill({
       projectRoot,
       backend,
@@ -310,17 +357,19 @@ export async function runLazyCompress({
       scope: 'lazy-compress',
       action: result?.action ?? 'unknown',
       verdict: verdict.action,
-      delegated_to: verdict.action === 'stale-weekly' ? 'weekly-curate' : 'daily-distill',
+      delegated_to: delegatedTo,
       duration_ms,
       success: result?.action !== 'error',
       ...(result?.errorCategory ? { error_category: result.errorCategory } : {}),
+      // compress-session reports its error via error_category (snake) — pass it
+      // through too so the lazy log captures either shape.
+      ...(result?.error_category ? { error_category: result.error_category } : {}),
     },
   });
   return {
     ...result,
     verdict: verdict.action,
-    delegatedTo:
-      verdict.action === 'stale-weekly' ? 'weekly-curate' : 'daily-distill',
+    delegatedTo,
     duration_ms,
   };
 }

package/src/rich-fact.mjs

@@ -0,0 +1,46 @@
+// Rich-fact body + slug shaping — the single source of truth for HOW a rich
+// fact's file body and filename slug are built (Task 103).
+//
+// Extracted from subcommands.mjs so the TWO rich-capture paths build identical
+// fact files (the shared-modules / no-drift rule, CLAUDE.md §1.3):
+//   1. explicit  — `cmk remember --why/--how` → runRememberRich (subcommands.mjs)
+//   2. automatic — the Stop-hook auto-extract synthesizing rich facts on the
+//                  native-immune path (auto-extract.mjs, Task 103)
+// Both call writeFact() with a body produced here, so an auto-extracted fact
+// reads the same as an explicitly-captured one.
+
+/**
+ * Build a slug for a rich fact's filename from its title.
+ *
+ * Collapse every run of non-alphanumerics to a single '-' (so dashes are never
+ * doubled), cap at 60 chars, then trim a leading/trailing dash without a regex
+ * quantifier (static analysis flags trailing `-+$` as ReDoS-prone; a single
+ * dash is all that can remain after the collapse, so string ops suffice).
+ *
+ * @param {string} s - the source text (typically the fact title).
+ * @returns {string} a `[a-z0-9][a-z0-9_-]*`-safe slug, or 'fact' if empty.
+ */
+export function slugifyFact(s) {
+  let base = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60);
+  if (base.startsWith('-')) base = base.slice(1);
+  if (base.endsWith('-')) base = base.slice(0, -1);
+  return base || 'fact';
+}
+
+/**
+ * Assemble the rich fact body in the v0.1.1 shape: headline + Why + How.
+ * The headline/body may itself be multi-line markdown (a structured breakdown);
+ * Why/How are appended as labelled blocks only when present.
+ *
+ * @param {object} opts
+ * @param {string} opts.text - the headline / body (may be multi-line markdown).
+ * @param {string} [opts.why] - the rationale → `**Why:**` block.
+ * @param {string} [opts.how] - how to apply → `**How to apply:**` block.
+ * @returns {string} the assembled markdown body for writeFact().
+ */
+export function buildRichFactBody({ text, why, how }) {
+  const parts = [String(text).trim()];
+  if (why && String(why).trim()) parts.push(`**Why:** ${String(why).trim()}`);
+  if (how && String(how).trim()) parts.push(`**How to apply:** ${String(how).trim()}`);
+  return parts.join('\n\n');
+}

package/src/subcommands.mjs

@@ -27,6 +27,7 @@ import { autoPersona } from './auto-persona.mjs';
 import { exportPersona, importPersona } from './persona-portability.mjs';
 import { setNativeAutoMemory, nativeMemoryInstallNote } from './native-memory.mjs';
 import { writeFact } from './write-fact.mjs';
+import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
 import { createHash } from 'node:crypto';
 import { runLazyCompress } from './lazy-compress.mjs';
 import { runDoctor } from './doctor.mjs';
@@ -356,25 +357,6 @@ function runSearch(queryParts, options) {
  */
 // Task 63 (F1): a slug derived from the title — lowercased, non-alphanumerics
 // collapsed to '-', trimmed, capped. Always passes writeFact's SLUG_PATTERN.
-function slugifyFact(s) {
-  // Collapse every run of non-alphanumerics to a single '-' (so dashes are
-  // never doubled), cap, then trim a leading/trailing dash without a regex
-  // quantifier (static analysis flags trailing `-+$` as ReDoS-prone; a single
-  // dash is all that can remain after the collapse, so string ops suffice).
-  let base = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60);
-  if (base.startsWith('-')) base = base.slice(1);
-  if (base.endsWith('-')) base = base.slice(0, -1);
-  return base || 'fact';
-}
-
-// Assemble the rich fact body in the v0.1.1 shape: headline + Why + How.
-function buildRichFactBody({ text, why, how }) {
-  const parts = [String(text).trim()];
-  if (why && String(why).trim()) parts.push(`**Why:** ${String(why).trim()}`);
-  if (how && String(how).trim()) parts.push(`**How to apply:** ${String(how).trim()}`);
-  return parts.join('\n\n');
-}
-
 /**
  * `cmk remember --why … --how … --type … --title …` (Task 63 / F1) — RICH
  * capture. Writes a real granular fact file (frontmatter + Why/How/links) via

package/template/.gitignore.fragment

@@ -12,7 +12,7 @@ context/.index/
 context/.locks/
 
 # Diagnostic NDJSON logs (observability only; carry raw turn excerpts —
-# e.g. Task 92's low_trust_discarded traces — that are NOT Poison_Guard-
-# screened, so they must never be committed). The durable memory lives in
-# the scratchpads + fact files, not these logs.
+# e.g. discarded-low-trust traces — that are NOT secret-screened, so they
+# must never be committed). The durable memory lives in the scratchpads +
+# fact files, not these logs.
 context/sessions/*.extract.log

package/template/CLAUDE.md.template

@@ -2,7 +2,7 @@
 
 This project uses **claude-memory-kit** for per-project, in-repo memory that survives session boundaries. Memory lives in `context/` (committed) and `context.local/` (gitignored). Cross-project memory lives at `~/.claude-memory-kit/` (or `$MEMORY_KIT_USER_DIR`).
 
-> v0.1.0 is under active development. This block is the runtime contract. Specific mechanisms (auto-extract, memory-write skill, MCP search) come online incrementally — `cmk doctor` will tell you which layers are active in the current install. Full architecture: <https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md>
+> This block is the runtime contract for the kit. `cmk doctor` reports which layers are active in your install. Docs: <https://github.com/LH8PPL/claude-memory-kit>
 
 ### Where memory lives
 
@@ -22,7 +22,7 @@ Precedence at session start: local > project > user (most-specific wins, others
 
 ### Health checks (when `cmk doctor` is live)
 
-Health checks (HC-1..HC-8) verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence. See [`docs/adr/`](docs/adr/) and [`specs/v0.1.0/design.md`](specs/v0.1.0/design.md) for the full contract.
+The `cmk doctor` health checks verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence, and stale locks. Full design + decision records: <https://github.com/LH8PPL/claude-memory-kit>.
 
 ### Recalling memory (for Claude)
 

package/template/docs/journey/journey-log.md.template

@@ -23,7 +23,7 @@ How to update it:
 
 For inspiration:
   See claude-memory-kit's own journey log as a worked example:
-  https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md
+  https://github.com/LH8PPL/claude-memory-kit/tree/main/docs/journey
 
 This template uses HTML comments (like this one) to coach the
 user through each section. The comments are stripped from