@lh8ppl/claude-memory-kit 0.1.0

package/src/tier-paths.mjs

@@ -0,0 +1,74 @@
+// Shared tier-path resolution for every cmk module that touches the 3-tier
+// filesystem. Per the Layer-2 review's I1 finding, this used to live in
+// triplicated form inside write-fact / reindex / forget / merge-facts —
+// any future change to the user-tier default path had to update four files.
+//
+// Public surface (used by all packages/cli/src/*.mjs that touch facts):
+//   VALID_TIERS  — Set of tier prefixes (U, P, L)
+//   ID_PATTERN   — RegExp for the kit's custom-alphabet citation ID format
+//   resolveTierRoot({tier, projectRoot, userDir}) → absolute path
+//   resolveFactDir(tier, tierRoot) → absolute path to <memory|fragments>
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const VALID_TIERS = new Set(['U', 'P', 'L']);
+
+// Matches IDs produced by @lh8ppl/cmk-canonicalize.generateId(). Tier prefix +
+// 8 chars from the custom 32-char base32 alphabet that excludes the six
+// ambiguous chars (0, O, 1, l, I, 8). See design §3.1.
+export const ID_PATTERN = /^[PUL]-[2345679ABCDEFGHJKLMNPQRSTUVWXYZa]{8}$/;
+
+export function resolveTierRoot({ tier, projectRoot, userDir }) {
+  if (tier === 'P') return join(projectRoot ?? process.cwd(), 'context');
+  if (tier === 'L') return join(projectRoot ?? process.cwd(), 'context.local');
+  return (
+    userDir ??
+    process.env.MEMORY_KIT_USER_DIR ??
+    join(homedir(), '.claude-memory-kit')
+  );
+}
+
+export function resolveFactDir(tier, tierRoot) {
+  return tier === 'U' ? join(tierRoot, 'fragments') : join(tierRoot, 'memory');
+}
+
+// Scratchpads live at the tier root (no subdir). Filename is the scratchpad
+// canonical name (e.g. 'MEMORY.md', 'USER.md'). Per design §1.1 + §2.1.
+export function resolveScratchpadPath({ tier, scratchpad, projectRoot, userDir }) {
+  return join(resolveTierRoot({ tier, projectRoot, userDir }), scratchpad);
+}
+
+// Allow-list of scratchpads per tier, per design §1.1.
+export const SCRATCHPADS_BY_TIER = Object.freeze({
+  P: new Set(['SOUL.md', 'MEMORY.md']),
+  L: new Set(['machine-paths.md', 'overrides.md']),
+  U: new Set(['USER.md', 'HABITS.md', 'LESSONS.md']),
+});
+
+// Hardcoded scratchpad cap defaults (chars). Tunable via settings.json per
+// design §2.1; defaults are the fallback when no settings.json override exists.
+export const DEFAULT_SCRATCHPAD_CAPS = Object.freeze({
+  'SOUL.md': 1800,
+  'MEMORY.md': 2500,
+  'USER.md': 1375, // Hermes-verified
+  'HABITS.md': 1800,
+  'LESSONS.md': 1800,
+  'machine-paths.md': 1500,
+  'overrides.md': 1500,
+});
+
+// Canonical 3 fixed sections per scratchpad (Task 14 / design §2.1). Each seed
+// template MUST emit exactly these `## <section>` headings; appendScratchpadBullet
+// callers MUST pass one of these exact section names. The test in
+// tests/cli-seed-templates.test.js asserts that every shipped seed contains
+// all 3 documented sections.
+export const SCRATCHPAD_DOCUMENTED_SECTIONS = Object.freeze({
+  'SOUL.md': ['Tone and Disposition', 'Operating Defaults', 'Boundary Rules'],
+  'MEMORY.md': ['Active Threads', 'Environment Notes', 'Pending Decisions'],
+  'USER.md': ['About', 'Preferences', 'Working Style'],
+  'HABITS.md': ['Iteration Cadence', 'Destructive Operations', 'Communication Style'],
+  'LESSONS.md': ['Tooling Lessons', 'Process Lessons', 'Anti-patterns'],
+  'machine-paths.md': ['Tool Paths', 'Project Paths', 'Misc Paths'],
+  'overrides.md': ['Tool Overrides', 'Behavior Overrides', 'Path Overrides'],
+});

package/src/transcripts.mjs

@@ -0,0 +1,234 @@
+// `cmk transcripts extract` (Task 38b, T-032).
+//
+// Two public boundaries:
+//
+//   extractTranscript({inputPath, outputPath, includeThinking?})
+//     → {turnsKept, rawLines, outputSize, sessionStart, sessionEnd}
+//
+//   discoverSessions({slug?, sessionUuidSuffix?, sinceIso?, harnessRoot?})
+//     → Array<{slug, sessionId, jsonlPath, mtimeMs}>
+//
+// Promotes the existing `scripts/extract-session-transcript.mjs` (kit-
+// dev utility) to a user-facing CLI subcommand. Lets users mine months
+// of pre-kit conversation history at
+// `~/.claude/projects/<slug>/<uuid>.jsonl` into clean markdown corpora
+// they can curate from.
+//
+// Filter contract (matches the scripts version + tasks.md 38.6):
+//   - Keep user + assistant text content
+//   - Drop tool_use / tool_result / image blocks
+//   - Drop thinking blocks UNLESS --include-thinking
+//   - Strip <system-reminder>, <command-name>, <command-message>,
+//     <command-args>, <ide_opened_file>, <ide_selection>,
+//     <local-command-stdout>, <local-command-stderr> from user text
+//
+// Per design §16.8 + tasks.md 38b (38.6–38.9).
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+  mkdirSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+const SYSTEM_REMINDER_RE = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
+const COMMAND_NAME_RE = /<command-name>[\s\S]*?<\/command-name>/g;
+const COMMAND_MESSAGE_RE = /<command-message>[\s\S]*?<\/command-message>/g;
+const COMMAND_ARGS_RE = /<command-args>[\s\S]*?<\/command-args>/g;
+const IDE_OPENED_RE = /<ide_opened_file>[\s\S]*?<\/ide_opened_file>/g;
+const IDE_SELECTION_RE = /<ide_selection>[\s\S]*?<\/ide_selection>/g;
+const LOCAL_STDOUT_RE = /<local-command-stdout>[\s\S]*?<\/local-command-stdout>/g;
+const LOCAL_STDERR_RE = /<local-command-stderr>[\s\S]*?<\/local-command-stderr>/g;
+
+const UUID_RE = /^([0-9a-f-]{36})\.jsonl$/i;
+
+function stripHarnessNoise(text) {
+  return String(text)
+    .replace(SYSTEM_REMINDER_RE, '')
+    .replace(COMMAND_NAME_RE, '')
+    .replace(COMMAND_MESSAGE_RE, '')
+    .replace(COMMAND_ARGS_RE, '')
+    .replace(IDE_OPENED_RE, '')
+    .replace(IDE_SELECTION_RE, '')
+    .replace(LOCAL_STDOUT_RE, '')
+    .replace(LOCAL_STDERR_RE, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function extractText(content, includeThinking) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text);
+    } else if (
+      includeThinking &&
+      block.type === 'thinking' &&
+      typeof block.thinking === 'string'
+    ) {
+      parts.push(`\n[thinking]\n${block.thinking}\n[/thinking]\n`);
+    }
+    // Drop tool_use, tool_result, image, etc.
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Extract a single session jsonl into a clean markdown transcript.
+ *
+ * @returns {object} {turnsKept, rawLines, outputSize, sessionStart, sessionEnd}
+ */
+export function extractTranscript({
+  inputPath,
+  outputPath,
+  includeThinking = false,
+} = {}) {
+  const errors = [];
+  if (!inputPath) errors.push('inputPath: required');
+  if (!outputPath) errors.push('outputPath: required');
+  if (errors.length > 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
+  }
+  if (!existsSync(inputPath)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.NOT_FOUND,
+      errors: [`inputPath does not exist: ${inputPath}`],
+    });
+  }
+  const raw = readFileSync(inputPath, 'utf8');
+  const lines = raw.split('\n').filter(Boolean);
+
+  const turns = [];
+  let firstTimestamp = null;
+  let lastTimestamp = null;
+  let turnIndex = 0;
+
+  for (const line of lines) {
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const t = obj.type;
+    if (t !== 'user' && t !== 'assistant') continue;
+    const msg = obj.message || {};
+    const role = msg.role || t;
+    const ts = obj.timestamp;
+    if (ts) {
+      if (!firstTimestamp) firstTimestamp = ts;
+      lastTimestamp = ts;
+    }
+    const text = stripHarnessNoise(extractText(msg.content, !!includeThinking));
+    if (!text) continue;
+    turnIndex += 1;
+    turns.push({ n: turnIndex, role, ts: ts || null, text });
+  }
+
+  const sessionStart = firstTimestamp ? new Date(firstTimestamp).toISOString() : null;
+  const sessionEnd = lastTimestamp ? new Date(lastTimestamp).toISOString() : null;
+
+  const out = [];
+  out.push('# Session transcript');
+  out.push('');
+  out.push(`- **Source jsonl**: \`${inputPath}\``);
+  out.push(`- **Spans**: ${sessionStart ?? '?'} → ${sessionEnd ?? '?'}`);
+  out.push(`- **Turns kept**: ${turns.length} (raw lines: ${lines.length})`);
+  out.push(
+    `- **Filters applied**: tool calls + tool results + thinking blocks + system reminders + IDE state + slash-command annotations removed${includeThinking ? ' (EXCEPT thinking, retained per --include-thinking)' : ''}`,
+  );
+  out.push('');
+  out.push('---');
+  out.push('');
+
+  for (const turn of turns) {
+    const tsLabel = turn.ts
+      ? new Date(turn.ts).toISOString().replace('T', ' ').replace(/\..+/, ' UTC')
+      : '';
+    out.push(`## Turn ${turn.n} — ${turn.role}${tsLabel ? ` — ${tsLabel}` : ''}`);
+    out.push('');
+    out.push(turn.text);
+    out.push('');
+  }
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, out.join('\n'), 'utf8');
+  const outputSize = statSync(outputPath).size;
+  return {
+    action: 'completed',
+    turnsKept: turns.length,
+    rawLines: lines.length,
+    outputSize,
+    sessionStart,
+    sessionEnd,
+  };
+}
+
+/**
+ * Discover Claude Code session jsonls under ~/.claude/projects/.
+ *
+ * @param {object} opts
+ * @param {string} [opts.slug]  filter to this slug only
+ * @param {string} [opts.sessionUuidSuffix]  match the session jsonl whose basename ends with this UUID suffix
+ * @param {string} [opts.sinceIso]  filter by mtime >= this ISO date
+ * @param {string} [opts.harnessRoot]  override (test injection) for ~/.claude/projects
+ * @returns {Array<{slug, sessionId, jsonlPath, mtimeMs}>}
+ */
+export function discoverSessions({
+  slug,
+  sessionUuidSuffix,
+  sinceIso,
+  harnessRoot,
+} = {}) {
+  const root = harnessRoot ?? join(homedir(), '.claude', 'projects');
+  if (!existsSync(root)) return [];
+  const slugsToScan = slug ? [slug] : safeReaddir(root).filter((s) => isDir(join(root, s)));
+  const sinceMs = sinceIso ? new Date(sinceIso).getTime() : null;
+  const results = [];
+  for (const s of slugsToScan) {
+    const dir = join(root, s);
+    if (!isDir(dir)) continue;
+    for (const name of safeReaddir(dir)) {
+      const m = UUID_RE.exec(name);
+      if (!m) continue;
+      const jsonlPath = join(dir, name);
+      let mtimeMs;
+      try {
+        mtimeMs = statSync(jsonlPath).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (sinceMs !== null && mtimeMs < sinceMs) continue;
+      const sessionId = m[1];
+      if (sessionUuidSuffix && !sessionId.endsWith(sessionUuidSuffix)) continue;
+      results.push({ slug: s, sessionId, jsonlPath, mtimeMs });
+    }
+  }
+  // Sort newest first
+  results.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return results;
+}
+
+function safeReaddir(path) {
+  try {
+    return readdirSync(path);
+  } catch {
+    return [];
+  }
+}
+
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/trust.mjs

@@ -0,0 +1,226 @@
+// Trust override (Task 15, T-013). Last Layer 3 module.
+//
+// Public boundary: overrideTrust({id, level, ...}) → result.
+// Locates an id in BOTH the granular per-fact archive (YAML frontmatter)
+// AND scratchpad-bullet HTML-comment provenance lines, then updates the
+// `trust:` field in every matched location. The two trust values are
+// independent — a fact file and a scratchpad bullet sharing an id can
+// drift; this command brings them back in sync at the new level.
+//
+// Uses shared modules per CLAUDE.md "Shared modules" rule:
+//   tier-paths.mjs    — VALID_TIERS, ID_PATTERN, SCRATCHPADS_BY_TIER,
+//                       resolveTierRoot, resolveFactDir
+//   frontmatter.mjs   — parse + format (for fact-file YAML round-trip)
+//   audit-log.mjs     — appendAuditEntry, nowIso, REASON_CODES.TRUST_CHANGE
+//   result-shapes.mjs — ERROR_CATEGORIES, errorResult, notFoundResult
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  VALID_TIERS,
+  ID_PATTERN,
+  SCRATCHPADS_BY_TIER,
+  resolveTierRoot,
+  resolveFactDir,
+} from './tier-paths.mjs';
+import { parse, format } from './frontmatter.mjs';
+import { readBullet, writeBullet } from './provenance.mjs';
+import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
+import {
+  ERROR_CATEGORIES,
+  errorResult,
+  notFoundResult,
+} from './result-shapes.mjs';
+
+const VALID_TRUST_LEVELS = new Set(['high', 'medium', 'low']);
+
+function validateOptions(opts) {
+  const errors = [];
+  if (!opts.id || typeof opts.id !== 'string') {
+    errors.push('id: required, non-empty string');
+  } else if (!ID_PATTERN.test(opts.id)) {
+    errors.push(
+      `id: must match the kit's citation-ID format (got ${JSON.stringify(opts.id)})`,
+    );
+  }
+  if (!opts.level || typeof opts.level !== 'string') {
+    errors.push('level: required, one of high/medium/low');
+  } else if (!VALID_TRUST_LEVELS.has(opts.level)) {
+    errors.push(
+      `level: must be one of high/medium/low (got ${JSON.stringify(opts.level)})`,
+    );
+  }
+  return errors;
+}
+
+function listFactFiles(factDir) {
+  if (!existsSync(factDir)) return [];
+  const out = [];
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    out.push(entry.name);
+  }
+  return out;
+}
+
+function findFactFileById(factDir, id) {
+  for (const filename of listFactFiles(factDir)) {
+    const path = join(factDir, filename);
+    if (!statSync(path).isFile()) continue;
+    const { frontmatter } = parse(readFileSync(path, 'utf8'));
+    if (frontmatter?.id === id) {
+      return { path, frontmatter };
+    }
+  }
+  return null;
+}
+
+function updateFactFileTrust(path, newLevel) {
+  const text = readFileSync(path, 'utf8');
+  const { frontmatter, body } = parse(text);
+  if (!frontmatter) return null; // shouldn't happen — caller already matched
+  const priorTrust = frontmatter.trust ?? null;
+  const updated = { ...frontmatter, trust: newLevel };
+  writeFileSync(path, format({ frontmatter: updated, body }), 'utf8');
+  return { priorTrust };
+}
+
+// Locate the bullet with matching leading id and rewrite both its lines via
+// the canonical provenance.mjs reader+writer pair. PR-15 review finding:
+// the prior `bulletLine.includes('(' + id + ')')` match was too loose — it
+// also matched bullets whose BODY TEXT referenced another fact's id (e.g.
+// "see also (P-XYZ)"). readBullet returns the leading id deterministically,
+// so `parsed.id === id` only matches the actual target. Bonus: this closes
+// the read/write-path asymmetry self-flagged in the PR description —
+// overrideTrust now round-trips through the same provenance pair that
+// appendScratchpadBullet uses.
+function updateScratchpadBulletTrust(path, id, newLevel) {
+  const text = readFileSync(path, 'utf8');
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length - 1; i++) {
+    const parsed = readBullet({
+      bulletLine: lines[i],
+      commentLine: lines[i + 1],
+    });
+    if (!parsed || parsed.id !== id) continue;
+    const priorTrust = parsed.provenance.trust;
+    const result = writeBullet({
+      id: parsed.id,
+      text: parsed.text,
+      provenance: { ...parsed.provenance, trust: newLevel },
+    });
+    if (result.action !== 'formatted') {
+      throw new Error(
+        'overrideTrust: writeBullet failed for re-formatted bullet — ' +
+          (result.errors?.join('; ') ?? 'unknown'),
+      );
+    }
+    const [newBullet, newComment] = result.lines.split('\n');
+    lines[i] = newBullet;
+    lines[i + 1] = newComment;
+    writeFileSync(path, lines.join('\n'), 'utf8');
+    return { priorTrust };
+  }
+  return null;
+}
+
+function listScratchpadsForTier(tier, tierRoot) {
+  const allowed = SCRATCHPADS_BY_TIER[tier];
+  const out = [];
+  for (const scratchpad of allowed) {
+    out.push({ name: scratchpad, path: join(tierRoot, scratchpad) });
+  }
+  return out;
+}
+
+export function overrideTrust(opts = {}) {
+  const errors = validateOptions(opts);
+  if (errors.length > 0) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors,
+    });
+  }
+
+  const { id, level, projectRoot, userDir, actor, now } = opts;
+  const tier = id[0];
+  if (!VALID_TIERS.has(tier)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`id tier prefix invalid: ${tier}`],
+    });
+  }
+
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+  const updatedLocations = [];
+
+  // 1. Try fact file (granular archive)
+  const factMatch = findFactFileById(factDir, id);
+  if (factMatch) {
+    const r = updateFactFileTrust(factMatch.path, level);
+    if (r) {
+      updatedLocations.push({
+        type: 'fact',
+        path: factMatch.path,
+        priorTrust: r.priorTrust,
+      });
+    }
+  }
+
+  // 2. Try every scratchpad in the tier
+  for (const { path: scratchpadPath } of listScratchpadsForTier(tier, tierRoot)) {
+    if (!existsSync(scratchpadPath)) continue;
+    const r = updateScratchpadBulletTrust(scratchpadPath, id, level);
+    if (r) {
+      updatedLocations.push({
+        type: 'scratchpad',
+        path: scratchpadPath,
+        priorTrust: r.priorTrust,
+      });
+    }
+  }
+
+  if (updatedLocations.length === 0) {
+    return notFoundResult({
+      errors: [
+        `no matching id ${id} found in tier ${tier} (searched fact files + scratchpads)`,
+      ],
+    });
+  }
+
+  // 3. Audit log
+  const ts = now ?? nowIso();
+  appendAuditEntry(tierRoot, {
+    ts,
+    action: 'trust-changed',
+    tier,
+    id,
+    reasonCode: REASON_CODES.TRUST_CHANGE,
+    extra: {
+      actor: actor ?? 'user-explicit',
+      newTrust: level,
+      priorTrust: updatedLocations.map((l) => ({
+        type: l.type,
+        path: l.path,
+        value: l.priorTrust,
+      })),
+    },
+  });
+
+  return {
+    action: 'trust-updated',
+    id,
+    tier,
+    level,
+    updatedLocations,
+  };
+}