@lh8ppl/claude-memory-kit 0.1.0

package/src/capture-prompt.mjs

@@ -0,0 +1,61 @@
+// UserPromptSubmit hook real handler (Task 19, T-016). Second Layer 4
+// module — fires on every user prompt, sanitizes the privacy tags
+// before any disk write, and appends to the daily transcript file.
+//
+// Public boundary: capturePrompt({payload, projectRoot, now}) → result.
+// The bin wrapper deals with stdin parsing + protocol JSON; this
+// module is pure-function-ish: takes the parsed payload + project
+// root, produces the transcript file as a side effect.
+//
+// Privacy contract (FR-15, design §6.6):
+//   - <private>...</private> blocks are REPLACED with the literal
+//     "[private content redacted]" placeholder. The original content
+//     never touches any disk path under the project.
+//   - <retain>...</retain> blocks are preserved VERBATIM (including the
+//     tags). The Stop hook + auto-extract subagent downstream uses
+//     these tags as force-save signals; stripping them here would
+//     break that contract.
+//
+// Transcript format:
+//   ## <ISO timestamp> — user
+//
+//   <sanitized prompt body>
+//
+// One heading per turn so downstream tools can scan by ## markers
+// (matches claude-remember's compaction strategy).
+
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizePrivacyTags } from './privacy.mjs';
+
+function dateFromIso(iso) {
+  // Slice 'YYYY-MM-DD' from 'YYYY-MM-DDTHH:MM:SSZ'. Validating
+  // upstream would be over-engineering — callers pass nowIso() or a
+  // test fixture date.
+  return String(iso).slice(0, 10);
+}
+
+export function capturePrompt({ payload, projectRoot, now } = {}) {
+  if (!payload || typeof payload !== 'object') {
+    return { action: 'noop', reason: 'no-payload' };
+  }
+  const prompt = typeof payload.prompt === 'string' ? payload.prompt : '';
+  if (prompt === '') {
+    return { action: 'noop', reason: 'empty-prompt' };
+  }
+
+  const ts = now ?? new Date().toISOString();
+  const date = dateFromIso(ts);
+  const transcriptsDir = join(projectRoot, 'context', 'transcripts');
+  const transcriptPath = join(transcriptsDir, `${date}.md`);
+
+  const sanitized = sanitizePrivacyTags(prompt);
+  const entry = `## ${ts} — user\n\n${sanitized}\n\n`;
+
+  if (!existsSync(transcriptsDir)) {
+    mkdirSync(transcriptsDir, { recursive: true });
+  }
+  appendFileSync(transcriptPath, entry, 'utf8');
+
+  return { action: 'appended', transcriptPath };
+}

package/src/capture-turn.mjs

@@ -0,0 +1,273 @@
+// Stop hook real handler (Task 21, T-018). Sixth Layer 4 module.
+//
+// Public boundary: captureTurn({payload, projectRoot, now,
+// autoExtractPath}) → result. Does two things:
+//   1. Append the just-completed assistant turn to
+//      <projectRoot>/context/transcripts/{YYYY-MM-DD}.md (parallel to
+//      Task 19's capture-prompt, sharing the privacy sanitizer).
+//   2. Spawn the auto-extract subagent (Task 23) as a DETACHED child
+//      so it survives the parent's exit. The kit's hook must return
+//      within ~50ms; the subagent does its work in the background.
+//
+// stop_hook_active guard (design §5.2.1):
+//   The Stop hook can re-fire as a result of a prior Stop hook's
+//   decision: "block" response, causing a loop. Anthropic's hook
+//   payload carries stop_hook_active: true in those cases. When set,
+//   we short-circuit: no transcript append, no spawn, no work — just
+//   {action: 'noop'} and let the session close.
+//
+// Auto-extract subprocess (21.3 + 21.4):
+//   Unix path: `node ${autoExtractPath} ${turnTempFile}` spawned with
+//     detached:true + stdio:'ignore' + unref() — node's equivalent of
+//     the bash `</dev/null >/dev/null 2>&1 & disown` pattern from
+//     claude-remember. Works identically on Windows when the parent
+//     is Git Bash because we use node's spawn, not shell &.
+//   The turn text is buffered to a temp file under
+//     <projectRoot>/context/transcripts/.extract-<ts>.tmp
+//   so the detached child can read it without sharing stdin.
+//
+// Both-turns temp-file shape (design §6.4 amendment, 2026-05-26):
+//   The temp file now contains BOTH the prior user prompt AND the
+//   just-captured assistant turn, separated by literal markers:
+//     USER_TURN:
+//     <user body>
+//
+//     ASSISTANT_TURN:
+//     <assistant body>
+//   This lets auto-extract identify candidate-origin (user-stated vs
+//   assistant-inferred) and apply the demotion rule from design §6.4
+//   (assistant-origin facts demote one trust level so user review is
+//   required before they enter MEMORY.md). The user turn is sourced
+//   by reading the most recent `## <ts> — user` entry from today's
+//   transcript file — which Task 19's capture-prompt wrote just
+//   before this Stop hook fired.
+
+import {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { sanitizePrivacyTags } from './privacy.mjs';
+
+function dateFromIso(iso) {
+  return String(iso).slice(0, 10);
+}
+
+// Write a `phase: 'spawn'` NDJSON entry to `<projectRoot>/context/sessions/{date}.extract.log`
+// when the auto-extract spawn fails. This closes PR-A's class-1 audit
+// deferral (capture-turn Door 5 observability gap). Auto-extract's own
+// in-process log entries don't carry the `phase` field (default = extract);
+// the `phase: 'spawn'` discriminator lets log readers route capture-turn
+// failures distinct from extract-phase failures.
+function writeSpawnLogEntry({ projectRoot, ts, reason, error }) {
+  const date = dateFromIso(ts);
+  const logDir = join(projectRoot, 'context', 'sessions');
+  const logPath = join(logDir, `${date}.extract.log`);
+  try {
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    const entry = {
+      ts,
+      phase: 'spawn',
+      success: false,
+      error_category: 'spawn_failed',
+      reason,
+      ...(error ? { error } : {}),
+    };
+    appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+    return { logged: true, logPath };
+  } catch (logErr) {
+    // Logging failure must not crash the hook — emit to stderr so it
+    // surfaces in the Stop-hook stderr stream Claude Code captures.
+    process.stderr.write(
+      `cmk-capture-turn: failed to write spawn observability log: ${logErr?.message ?? logErr}\n`,
+    );
+    return { logged: false, error: logErr?.message ?? String(logErr) };
+  }
+}
+
+function extractTurnText(payload) {
+  // Anthropic Stop hook payload spelling has shifted across Claude Code
+  // versions. Probe the documented fields in priority order.
+  if (!payload || typeof payload !== 'object') return '';
+  if (typeof payload.assistant_message === 'string') return payload.assistant_message;
+  if (typeof payload.last_assistant_message === 'string') return payload.last_assistant_message;
+  if (typeof payload.response === 'string') return payload.response;
+  if (typeof payload.message === 'string') return payload.message;
+  return '';
+}
+
+// Scan today's transcript for the most recent `## <ts> — user` entry
+// and return its body. capture-prompt (Task 19) writes these entries
+// on every UserPromptSubmit; the most-recent one is by definition the
+// user prompt that triggered the assistant turn we're now capturing.
+// Returns '' if the transcript doesn't exist, no user entry is
+// present, or any read error occurs.
+function readLastUserTurnFromTranscript(transcriptPath) {
+  if (!existsSync(transcriptPath)) return '';
+  let text;
+  try {
+    text = readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return '';
+  }
+  const lines = text.split(/\r?\n/);
+  let lastUserHeadingIdx = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    // Match capture-prompt's format: "## <iso-ts> — user"
+    if (/^##\s+\S+\s+—\s+user\s*$/.test(lines[i])) {
+      lastUserHeadingIdx = i;
+      break;
+    }
+  }
+  if (lastUserHeadingIdx === -1) return '';
+  // The user body runs from the line after the heading until the next
+  // `## ` heading (the just-appended assistant entry) or EOF.
+  let endIdx = lines.length;
+  for (let i = lastUserHeadingIdx + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+  const body = lines.slice(lastUserHeadingIdx + 1, endIdx);
+  while (body.length > 0 && body[0].trim() === '') body.shift();
+  while (body.length > 0 && body[body.length - 1].trim() === '') body.pop();
+  return body.join('\n');
+}
+
+// Assemble the both-turns temp-file body. Both turns are sanitized
+// upstream — the user body comes from the transcript (which
+// capture-prompt sanitized when writing it) and the assistant body
+// is the now-sanitized argument. Markers are literal-prefix lines so
+// auto-extract's parser can split cleanly.
+function assembleBothTurnsBody({ userTurn, assistantTurn }) {
+  return [
+    'USER_TURN:',
+    userTurn,
+    '',
+    'ASSISTANT_TURN:',
+    assistantTurn,
+  ].join('\n');
+}
+
+function defaultAutoExtractPath() {
+  // Documented sibling of this script's bin wrapper. Resolved by the
+  // bin wrapper (which knows CLAUDE_PLUGIN_ROOT); we use this fallback
+  // only when the caller passes nothing. The path is allowed to not
+  // exist — see spawn block below.
+  return null;
+}
+
+function spawnAutoExtract(autoExtractPath, turnFile, projectRoot) {
+  if (!autoExtractPath) return { spawned: false, reason: 'no-auto-extract-path' };
+  if (!existsSync(autoExtractPath)) {
+    return { spawned: false, reason: 'auto-extract-missing' };
+  }
+  try {
+    // spawn-discipline: ignore detached-fire-and-forget (the auto-extract child intentionally outlives this hook process — parent-side timeout is incorrect by design; the child carries its own internal timeout via auto-extract.mjs's runAutoExtract → HaikuViaAnthropicApi.compress({timeoutMs: 25_000}) chain. PR-A class-1 audit confirmed this is the correct posture; the structural gap is the spawn-failed observability surface deferred to PR-D2b / Task 23.14.3.)
+    const child = spawn(
+      'node',
+      [autoExtractPath, turnFile],
+      {
+        detached: true,
+        stdio: 'ignore',
+        cwd: projectRoot,
+        env: { ...process.env, CMK_PROJECT_DIR: projectRoot },
+      },
+    );
+    child.unref();
+    return { spawned: true, pid: child.pid };
+  } catch (err) {
+    return { spawned: false, reason: 'spawn-failed', error: err?.message ?? String(err) };
+  }
+}
+
+export function captureTurn({
+  payload,
+  projectRoot,
+  now,
+  autoExtractPath,
+} = {}) {
+  // 1. stop_hook_active guard. Short-circuit BEFORE any disk write or
+  //    spawn so a recursive Stop firing can't poison the transcript.
+  if (payload?.stop_hook_active === true) {
+    return { action: 'noop', reason: 'stop-hook-active', spawned: false };
+  }
+
+  const turnText = extractTurnText(payload);
+  if (turnText.trim() === '') {
+    return { action: 'noop', reason: 'no-turn-text', spawned: false };
+  }
+
+  // 2. Append to today's transcript (sanitized).
+  const ts = now ?? new Date().toISOString();
+  const date = dateFromIso(ts);
+  const transcriptsDir = join(projectRoot, 'context', 'transcripts');
+  const transcriptPath = join(transcriptsDir, `${date}.md`);
+  if (!existsSync(transcriptsDir)) {
+    mkdirSync(transcriptsDir, { recursive: true });
+  }
+  const sanitized = sanitizePrivacyTags(turnText);
+  appendFileSync(
+    transcriptPath,
+    `## ${ts} — assistant\n\n${sanitized}\n\n`,
+    'utf8',
+  );
+
+  // 3. Buffer BOTH turns to a temp file so the detached child can read
+  //    them without sharing our stdin (which has already been consumed
+  //    by the parent bash wrapper). Per design §6.4, auto-extract
+  //    reads the user prompt + assistant response together so it can
+  //    distinguish user-stated facts from assistant-inferred ones.
+  //    The user portion comes from today's transcript (capture-prompt
+  //    wrote it before this Stop fired); the assistant portion is the
+  //    `sanitized` text we just appended above.
+  const userTurn = readLastUserTurnFromTranscript(transcriptPath);
+  const turnFile = join(transcriptsDir, `.extract-${Date.now()}.tmp`);
+  try {
+    writeFileSync(
+      turnFile,
+      assembleBothTurnsBody({ userTurn, assistantTurn: sanitized }),
+      'utf8',
+    );
+  } catch (err) {
+    // Continue without spawning — partial success is better than abort.
+    return {
+      action: 'captured',
+      transcriptPath,
+      spawned: false,
+      reason: 'turn-file-write-failed',
+      error: err?.message ?? String(err),
+    };
+  }
+
+  // 4. Spawn the auto-extract child (Task 23 fills in the script body).
+  const path = autoExtractPath ?? defaultAutoExtractPath();
+  const spawnResult = spawnAutoExtract(path, turnFile, projectRoot);
+
+  // 5. Door 5 (observability) — when the spawn doesn't succeed, write
+  //    an NDJSON entry to extract.log with `phase: 'spawn'`. Closes PR-A
+  //    class-1 audit deferral (Task 23.14.3). Successful spawns are NOT
+  //    logged here because their observability is provided by auto-
+  //    extract.mjs itself (the detached child writes its own entries
+  //    with `phase` absent, default = 'extract').
+  if (!spawnResult.spawned) {
+    writeSpawnLogEntry({
+      projectRoot,
+      ts,
+      reason: spawnResult.reason,
+      error: spawnResult.error,
+    });
+  }
+
+  return {
+    action: 'captured',
+    transcriptPath,
+    turnFile,
+    ...spawnResult,
+  };
+}

package/src/claude-md.mjs

@@ -0,0 +1,212 @@
+// claude-md.mjs — managed-block injection into the target project's CLAUDE.md.
+//
+// Public contract (tests assert this; internals can change freely):
+//
+//   injectClaudeMdBlock({
+//     projectRoot,   // <repo> root
+//     content,       // body of the block (without markers)
+//     version,       // kit version string, e.g. "0.1.0"
+//     force,         // allow downgrade (replace newer block with older)
+//   }) → {
+//     action:   'created'              // no CLAUDE.md before; one was created
+//             | 'appended'             // CLAUDE.md existed without our markers; block appended at EOF
+//             | 'replaced'             // same-version block content updated in place
+//             | 'upgraded'             // older-version block replaced (kit version is newer)
+//             | 'downgrade-blocked'    // newer-version block present and force not set
+//             | 'forced-downgrade'     // newer-version block replaced because force=true
+//             | 'unchanged',           // existing block content + version match the inputs exactly
+//     path:        string,             // absolute path to the CLAUDE.md
+//     oldVersion?: string,             // version of the block we replaced (when applicable)
+//   }
+//
+//   removeClaudeMdBlock({ projectRoot }) → {
+//     action:   'removed'              // managed block found + stripped
+//             | 'not-found'            // file exists but no managed markers
+//             | 'no-file',             // CLAUDE.md does not exist
+//     path:        string,
+//   }
+//
+// Design notes:
+//   - Deep module: the two boundary functions above are the only public
+//     surface. Internal helpers parse markers, compare versions, and
+//     splice the block — all private.
+//   - Markers wrap the kit-managed content. Everything outside markers is
+//     byte-preserved across inject + remove. This is what makes the
+//     installer safe to re-run.
+//   - Version comparison is semver-style (MAJOR.MINOR.PATCH). Prerelease
+//     suffixes (-dev, -alpha.1) are ignored when comparing.
+//   - Marker pattern is intentionally the same shape as the .gitignore
+//     marker pattern in install.mjs — same idea, same conventions.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+const MARKER_START_RE =
+  /<!--\s*claude-memory-kit:start\s+v([\d.]+(?:-[\w.]+)?)\s*-->/;
+const MARKER_END_RE = /<!--\s*claude-memory-kit:end\s*-->/;
+
+/**
+ * Wrap a content string with kit markers at the given version.
+ */
+function buildBlock(content, version) {
+  return `<!-- claude-memory-kit:start v${version} -->\n${content.trim()}\n<!-- claude-memory-kit:end -->`;
+}
+
+/**
+ * Find the start + end marker positions in the source text.
+ *   - Returns null when no start marker is present (no managed block).
+ *   - When a start marker is present but the end marker is missing or
+ *     misplaced, treats the block as extending to EOF. This recovers
+ *     gracefully from a corrupted block (e.g. the user accidentally
+ *     deleted the end marker by hand).
+ */
+function findManagedBlock(text) {
+  const startMatch = text.match(MARKER_START_RE);
+  if (!startMatch) return null;
+
+  const endMatch = text.match(MARKER_END_RE);
+  if (endMatch && startMatch.index < endMatch.index) {
+    return {
+      startIdx: startMatch.index,
+      endIdx: endMatch.index + endMatch[0].length,
+      version: startMatch[1],
+      fullText: text.slice(startMatch.index, endMatch.index + endMatch[0].length),
+      corrupted: false,
+    };
+  }
+
+  // Orphan start marker → treat the block as extending to EOF so we
+  // can replace it cleanly on the next install.
+  return {
+    startIdx: startMatch.index,
+    endIdx: text.length,
+    version: startMatch[1],
+    fullText: text.slice(startMatch.index),
+    corrupted: true,
+  };
+}
+
+/**
+ * Strip trailing -prerelease, parse MAJOR.MINOR.PATCH integers.
+ * Tolerates partial versions ("0.1" → [0,1,0]).
+ */
+function parseVersion(v) {
+  const base = String(v).replace(/^v/, '').split('-')[0];
+  const parts = base.split('.').map((n) => parseInt(n, 10) || 0);
+  while (parts.length < 3) parts.push(0);
+  return parts.slice(0, 3);
+}
+
+/**
+ * Semver-style comparator. Returns -1 / 0 / 1.
+ *   compareVersions('0.1.0', '0.2.0') === -1
+ *   compareVersions('1.0.0', '1.0.0') === 0
+ *   compareVersions('2.0.0', '1.9.9') === 1
+ */
+function compareVersions(a, b) {
+  const av = parseVersion(a);
+  const bv = parseVersion(b);
+  for (let i = 0; i < 3; i++) {
+    if (av[i] < bv[i]) return -1;
+    if (av[i] > bv[i]) return 1;
+  }
+  return 0;
+}
+
+export function injectClaudeMdBlock(opts = {}) {
+  const projectRoot = opts.projectRoot;
+  const content = String(opts.content || '');
+  const version = String(opts.version || '0.0.0');
+  const force = !!opts.force;
+  if (!projectRoot) throw new Error('injectClaudeMdBlock: projectRoot is required');
+
+  const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+  const newBlock = buildBlock(content, version);
+
+  // Case 1 — no CLAUDE.md
+  if (!existsSync(claudeMdPath)) {
+    writeFileSync(claudeMdPath, newBlock + '\n', 'utf8');
+    return { action: 'created', path: claudeMdPath };
+  }
+
+  const existing = readFileSync(claudeMdPath, 'utf8');
+  const found = findManagedBlock(existing);
+
+  // Case 2 — file exists but no (or corrupted) managed block → append
+  if (!found) {
+    // If the file ends without a newline, add one before the block for
+    // readability. Trim trailing whitespace so we don't accumulate blank
+    // lines on repeated installs.
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(claudeMdPath, existing.replace(/\s+$/, '') + sep + newBlock + '\n', 'utf8');
+    return { action: 'appended', path: claudeMdPath };
+  }
+
+  // Case 3 — managed block present. Compare versions to choose action.
+  const cmp = compareVersions(version, found.version);
+  const before = existing.slice(0, found.startIdx);
+  const after = existing.slice(found.endIdx);
+
+  let action;
+  if (cmp === 0) {
+    if (found.fullText === newBlock) {
+      return { action: 'unchanged', path: claudeMdPath, oldVersion: found.version };
+    }
+    action = 'replaced';
+  } else if (cmp > 0) {
+    action = 'upgraded';
+  } else {
+    // cmp < 0 → incoming version is older than installed
+    if (!force) {
+      return {
+        action: 'downgrade-blocked',
+        path: claudeMdPath,
+        oldVersion: found.version,
+      };
+    }
+    action = 'forced-downgrade';
+  }
+
+  writeFileSync(claudeMdPath, before + newBlock + after, 'utf8');
+  return { action, path: claudeMdPath, oldVersion: found.version };
+}
+
+export function removeClaudeMdBlock(opts = {}) {
+  const projectRoot = opts.projectRoot;
+  if (!projectRoot) throw new Error('removeClaudeMdBlock: projectRoot is required');
+
+  const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+
+  if (!existsSync(claudeMdPath)) {
+    return { action: 'no-file', path: claudeMdPath };
+  }
+
+  const existing = readFileSync(claudeMdPath, 'utf8');
+  const found = findManagedBlock(existing);
+
+  if (!found) {
+    return { action: 'not-found', path: claudeMdPath };
+  }
+
+  // Strip the block. If the block was followed by exactly one trailing
+  // newline (the one we wrote at injection time), strip it too so the
+  // surrounding content stays clean. We do NOT touch newlines that exist
+  // in the user's surrounding content.
+  let after = existing.slice(found.endIdx);
+  if (after.startsWith('\n') && (after.length === 1 || after[1] !== '\n')) {
+    after = after.slice(1);
+  }
+  const before = existing.slice(0, found.startIdx).replace(/\s+$/, '\n');
+
+  const next = (before + after).trimEnd() + (after.endsWith('\n') ? '\n' : '');
+
+  writeFileSync(claudeMdPath, next, 'utf8');
+  return { action: 'removed', path: claudeMdPath };
+}
+
+// Internal helpers are intentionally NOT exported — they're implementation
+// details. The boundary tests check the public actions + on-disk effects.