@lh8ppl/claude-memory-kit 0.1.0

package/src/forget.mjs

@@ -0,0 +1,335 @@
+// Tombstone-write + tombstone-aware fact resolver (Task 9, refactored in
+// cleanup-layer-2-cross-module-drift). Two public boundaries:
+//   forget(opts) → result          — user-requested deletion
+//   resolveFact(opts) → state      — read-side, knows live/tombstoned/superseded
+//
+// Uses shared modules: tier-paths, frontmatter, audit-log, result-shapes.
+// See design §6.5 + CLAUDE.md "Shared modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { canonicalize } from '@lh8ppl/cmk-canonicalize';
+import {
+  VALID_TIERS,
+  ID_PATTERN,
+  resolveTierRoot,
+  resolveFactDir,
+} from './tier-paths.mjs';
+import { parse, format } from './frontmatter.mjs';
+import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
+
+// Layer-2 review: PR-1 rejected \n / \r / : in the `reason` field as a
+// minimum fix for the naive serializer (finding B2). PR-2's frontmatter.mjs
+// (js-yaml CORE_SCHEMA) quotes those chars properly. The B2 restriction is
+// LIFTED here — reasons may contain newlines, colons, etc. and round-trip
+// correctly. Round-trip tests in cli-forget.test.js (`B2 relaxation`) prove it.
+
+function listLiveFactFiles(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 readFactAt(filePath) {
+  const text = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = parse(text);
+  return { frontmatter, body, text };
+}
+
+function resolveById(id, { projectRoot, userDir }) {
+  const tier = id[0];
+  if (!VALID_TIERS.has(tier)) return { matches: [] };
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+  for (const filename of listLiveFactFiles(factDir)) {
+    const p = join(factDir, filename);
+    if (!statSync(p).isFile()) continue;
+    const { frontmatter, body } = readFactAt(p);
+    if (frontmatter?.id === id && !frontmatter.deleted_at) {
+      return {
+        matches: [
+          { id, tier, path: p, frontmatter, body, tierRoot, factDir },
+        ],
+      };
+    }
+  }
+  return { matches: [] };
+}
+
+function resolveByQuery(query, { projectRoot, userDir }) {
+  const canonicalQuery = canonicalize(query);
+  if (!canonicalQuery) return { matches: [] };
+  const tiersToSearch = [];
+  if (projectRoot) tiersToSearch.push('P', 'L');
+  if (userDir) tiersToSearch.push('U');
+
+  const matches = [];
+  for (const tier of tiersToSearch) {
+    const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+    const factDir = resolveFactDir(tier, tierRoot);
+    for (const filename of listLiveFactFiles(factDir)) {
+      const p = join(factDir, filename);
+      if (!statSync(p).isFile()) continue;
+      const { frontmatter, body } = readFactAt(p);
+      if (!frontmatter?.id || frontmatter.deleted_at) continue;
+      if (canonicalize(body).includes(canonicalQuery)) {
+        matches.push({
+          id: frontmatter.id,
+          tier,
+          path: p,
+          frontmatter,
+          body,
+          tierRoot,
+          factDir,
+        });
+      }
+    }
+  }
+  // Layer-2 review M3: sort matches deterministically so ambiguous-error
+  // messages list candidate ids in stable order across machines.
+  matches.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { matches };
+}
+
+function moveFactToTombstone(match, { deletedAt, reason, deletedBy }) {
+  const tombDir = join(match.factDir, 'archive', 'tombstones');
+  mkdirSync(tombDir, { recursive: true });
+  const tombPath = join(tombDir, `${match.id}.md`);
+  // Read + parse the original, inject deletion fields at the top of the
+  // frontmatter object, write via the canonical formatter. No regex hacks.
+  const { frontmatter, body } = parse(readFileSync(match.path, 'utf8'));
+  const updated = {
+    deleted_at: deletedAt,
+    deleted_reason: reason,
+    deleted_by: deletedBy,
+    ...(frontmatter ?? {}),
+  };
+  writeFileSync(tombPath, format({ frontmatter: updated, body }), 'utf8');
+  unlinkSync(match.path);
+  return tombPath;
+}
+
+function scrubScratchpadFile(filePath, id) {
+  const text = readFileSync(filePath, 'utf8');
+  const lines = text.split('\n');
+  const removeIdx = new Set();
+
+  for (let i = 0; i < lines.length; i++) {
+    if (removeIdx.has(i)) continue;
+    const line = lines[i];
+
+    if (line.startsWith('- ') && line.includes(id)) {
+      removeIdx.add(i);
+      const next = lines[i + 1];
+      if (next && /^\s*<!--/.test(next)) {
+        removeIdx.add(i + 1);
+      }
+    } else if (
+      /^\s*<!--/.test(line) &&
+      line.includes(id) &&
+      line.includes('-->')
+    ) {
+      removeIdx.add(i);
+      if (i > 0 && lines[i - 1].startsWith('- ') && !removeIdx.has(i - 1)) {
+        removeIdx.add(i - 1);
+      }
+    }
+  }
+
+  if (removeIdx.size === 0) return { changed: false, removed: 0 };
+
+  const bulletsRemoved = [...removeIdx].filter((i) =>
+    lines[i].startsWith('- '),
+  ).length;
+  const out = lines.filter((_, i) => !removeIdx.has(i));
+  writeFileSync(filePath, out.join('\n'), 'utf8');
+  return { changed: true, removed: bulletsRemoved };
+}
+
+function scrubAllScratchpads(tierRoot, id) {
+  if (!existsSync(tierRoot)) return [];
+  const edits = [];
+  for (const entry of readdirSync(tierRoot, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    const p = join(tierRoot, entry.name);
+    const r = scrubScratchpadFile(p, id);
+    if (r.changed) edits.push({ path: p, removed: r.removed });
+  }
+  return edits;
+}
+
+export function forget(opts = {}) {
+  const {
+    idOrQuery,
+    projectRoot,
+    userDir,
+    reason,
+    deletedBy,
+    yes,
+    confirm,
+    now,
+  } = opts;
+
+  if (!idOrQuery || typeof idOrQuery !== 'string') {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: ['idOrQuery: required, non-empty string'],
+    });
+  }
+
+  // PR-2: B2 restriction on reason is RELAXED (js-yaml quotes strings with
+  // \n / \r / :). Only type-check remains.
+  if (reason !== undefined && reason !== null && typeof reason !== 'string') {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: ['reason: must be a string'],
+    });
+  }
+
+  const resolved = ID_PATTERN.test(idOrQuery)
+    ? resolveById(idOrQuery, { projectRoot, userDir })
+    : resolveByQuery(idOrQuery, { projectRoot, userDir });
+
+  if (resolved.matches.length === 0) {
+    return notFoundResult({
+      errors: [`no matching fact for "${idOrQuery}"`],
+    });
+  }
+  if (resolved.matches.length > 1) {
+    const ids = resolved.matches.map((m) => m.id);
+    return errorResult({
+      category: ERROR_CATEGORIES.COLLISION,
+      errors: [
+        `ambiguous query "${idOrQuery}" matched multiple facts: ${ids.join(', ')}`,
+      ],
+      candidateIds: ids,
+    });
+  }
+
+  const match = resolved.matches[0];
+
+  if (!yes) {
+    if (typeof confirm !== 'function') {
+      throw new Error(
+        "forget(): must provide either yes: true or a confirm() callback (refusing to silently delete)",
+      );
+    }
+    const proceed = confirm({
+      id: match.id,
+      tier: match.tier,
+      path: match.path,
+      title: match.frontmatter?.title,
+      body: match.body,
+    });
+    if (!proceed) {
+      return {
+        action: 'cancelled',
+        id: match.id,
+        tier: match.tier,
+        originalPath: match.path,
+      };
+    }
+  }
+
+  const deletedAt = now ?? nowIso();
+  const tombstoneReason = reason ?? '';
+  const tombstoneDeletedBy = deletedBy ?? 'user-explicit';
+  const tombstonePath = moveFactToTombstone(match, {
+    deletedAt,
+    reason: tombstoneReason,
+    deletedBy: tombstoneDeletedBy,
+  });
+
+  const scratchpadEdits = scrubAllScratchpads(match.tierRoot, match.id);
+
+  appendAuditEntry(match.tierRoot, {
+    ts: deletedAt,
+    action: 'tombstoned',
+    tier: match.tier,
+    id: match.id,
+    reasonCode: REASON_CODES.USER_REQUESTED,
+    reasonText: tombstoneReason || undefined,
+    paths: { before: match.path, archive: tombstonePath },
+    extra: {
+      deletedBy: tombstoneDeletedBy,
+      scratchpadEdits: scratchpadEdits.map((e) => ({
+        path: e.path,
+        removed: e.removed,
+      })),
+    },
+  });
+
+  return {
+    action: 'tombstoned',
+    id: match.id,
+    tier: match.tier,
+    originalPath: match.path,
+    tombstonePath,
+    scratchpadEdits,
+  };
+}
+
+export function resolveFact({ id, projectRoot, userDir }) {
+  if (!id || !ID_PATTERN.test(id)) return { state: 'not-found' };
+  const tier = id[0];
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+
+  for (const filename of listLiveFactFiles(factDir)) {
+    const p = join(factDir, filename);
+    if (!statSync(p).isFile()) continue;
+    const { frontmatter, body } = readFactAt(p);
+    if (frontmatter?.id === id) {
+      return {
+        state: frontmatter.deleted_at ? 'tombstoned' : 'live',
+        path: p,
+        body,
+        frontmatter,
+        deletedAt: frontmatter.deleted_at,
+      };
+    }
+  }
+
+  const tombPath = join(factDir, 'archive', 'tombstones', `${id}.md`);
+  if (existsSync(tombPath)) {
+    const { frontmatter, body } = readFactAt(tombPath);
+    return {
+      state: 'tombstoned',
+      path: tombPath,
+      body,
+      frontmatter,
+      deletedAt: frontmatter?.deleted_at,
+    };
+  }
+
+  const supersededPath = join(factDir, 'archive', 'superseded', `${id}.md`);
+  if (existsSync(supersededPath)) {
+    const { frontmatter, body } = readFactAt(supersededPath);
+    return {
+      state: 'superseded',
+      path: supersededPath,
+      body,
+      frontmatter,
+      supersededBy: frontmatter?.superseded_by,
+    };
+  }
+
+  return { state: 'not-found' };
+}

package/src/frontmatter.mjs

@@ -0,0 +1,73 @@
+// Canonical frontmatter serializer/parser. Single js-yaml-backed pair that
+// every kit module uses to read and write per-fact frontmatter + scratchpad
+// HTML-comment provenance (Layer 3+ will join).
+//
+// Per the Layer-2 review's I2 finding, the previous code had THREE different
+// naive parsers across four modules (split-on-first-colon read; verbatim
+// stringify write). Output and input weren't symmetric: booleans round-tripped
+// as strings, arrays didn't round-trip at all, strings with `:` truncated on
+// read. js-yaml fixes all of these AND lifts the B2 minimum-fix restriction
+// that PR-1 added — values with `\n` / `\r` / `:` are now quoted properly.
+//
+// Public surface:
+//   parse(text) → {frontmatter, body, parseError?}
+//     - text: full file contents (with or without `---` markers)
+//     - returns frontmatter as a typed object (string/number/bool/array/etc.)
+//     - returns body as the markdown after the closing `---\n` (or empty)
+//     - if no frontmatter block: frontmatter is null, body is the full text
+//     - if YAML parse fails: frontmatter is null, parseError carries the message
+//
+//   format({frontmatter, body}) → text
+//     - frontmatter: typed object; key order preserved per insertion
+//     - body: markdown; written verbatim after the closing `---\n`
+//     - if frontmatter is null/empty: just returns body
+//
+// js-yaml schema: CORE_SCHEMA (no implicit timestamp/Date conversion;
+// ISO strings stay as strings). Output uses flowLevel: 1 — top-level
+// mapping is block style; nested arrays render as `[a, b]` (matches the
+// pre-refactor visual format).
+
+import yaml from 'js-yaml';
+
+const DUMP_OPTIONS = Object.freeze({
+  schema: yaml.CORE_SCHEMA,
+  flowLevel: 1,
+  lineWidth: -1, // no line wrapping
+  noRefs: true, // never emit YAML anchors / refs
+  sortKeys: false, // preserve insertion order
+});
+
+const LOAD_OPTIONS = Object.freeze({
+  schema: yaml.CORE_SCHEMA,
+});
+
+export function parse(text) {
+  if (typeof text !== 'string') return { frontmatter: null, body: '' };
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { frontmatter: null, body: text };
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(m[1], LOAD_OPTIONS);
+  } catch (e) {
+    return { frontmatter: null, body: text, parseError: e.message };
+  }
+  if (frontmatter === undefined || frontmatter === null) {
+    return { frontmatter: null, body: m[2] ?? '' };
+  }
+  if (typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return {
+      frontmatter: null,
+      body: text,
+      parseError: 'frontmatter is not a mapping',
+    };
+  }
+  return { frontmatter, body: m[2] ?? '' };
+}
+
+export function format({ frontmatter, body }) {
+  if (!frontmatter || (typeof frontmatter === 'object' && Object.keys(frontmatter).length === 0)) {
+    return body ?? '';
+  }
+  const yamlBody = yaml.dump(frontmatter, DUMP_OPTIONS);
+  return `---\n${yamlBody}---\n${body ?? ''}`;
+}

package/src/import-anthropic-memory.mjs

@@ -0,0 +1,266 @@
+// `cmk import-anthropic-memory` (Task 38a, T-032).
+//
+// Public boundary:
+//   async importAnthropicMemory({projectRoot, now, dryRun?, acceptAll?, harnessRoot?})
+//     → {action, proposals, accepted, skipped, errors, duration_ms}
+//
+// Reads Anthropic's native auto-memory at
+// `~/.claude/projects/<slug>/memory/MEMORY.md` (same slug pattern HC-8
+// uses) and merges useful bullets into the project's MEMORY.md as
+// `write_source: imported, trust: medium` entries.
+//
+// Dedup contract: a candidate whose canonicalize(text) collides with an
+// existing entry in the project MEMORY.md is skipped. Audit-logged via
+// the canonical appendAuditEntry shape with reasonCode IMPORT_SKIPPED_DUPLICATE.
+// This is intentional — Anthropic's auto-memory and the kit's
+// auto-extract often converge on the same facts; we don't want to
+// silently double-write.
+//
+// Per design §11.2 + tasks.md 38a (38.1–38.5).
+//
+// B1 fix (Task 38 skill-review 2026-05-28): uses appendAuditEntry +
+// REASON_CODES.IMPORT_* per CLAUDE.md "Shared modules" rule. Previous
+// implementation wrote raw JSON to audit.log, missing schema/action/tier
+// fields → re-introduced the format drift the I4 review codified.
+// B2 fix: harnessRoot test-injection parameter mirrors discoverSessions.
+
+import {
+  appendFileSync, // platform-commands: ignore — used only for the in-place MEMORY.md append (not audit log; that goes through appendAuditEntry)
+  existsSync,
+  mkdirSync,
+  readFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { canonicalize, generateId } from '@lh8ppl/cmk-canonicalize';
+import {
+  appendAuditEntry,
+  nowIso,
+  REASON_CODES,
+} from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+const MEMORY_REL = ['context', 'MEMORY.md'];
+
+// Same slug pattern HC-8 uses (matches Python's
+// `re.sub(r'[^a-zA-Z0-9]', '-', project_dir)`).
+export function anthropicSlugFor(projectRoot) {
+  return String(projectRoot).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Where to find Anthropic's auto-memory for a given project root.
+ *
+ * @param {string} projectRoot
+ * @param {string} [harnessRoot]  override (test injection); defaults to ~/.claude/projects
+ */
+export function anthropicMemoryPath(projectRoot, harnessRoot) {
+  const root = harnessRoot ?? join(homedir(), '.claude', 'projects');
+  return join(root, anthropicSlugFor(projectRoot), 'memory', 'MEMORY.md');
+}
+
+// M2 (skill-review 2026-05-28): permissive regex accepts -/*/+ markers.
+// Anthropic's MEMORY.md format isn't externally documented; the permissive
+// match also pulls in list items from prose. v0.1.0 trade-off: noisy
+// proposals are fine because --dry-run lets the user inspect first.
+// TODO(v0.1.x): tighten if user feedback surfaces over-extraction noise.
+function parseBullets(markdown) {
+  const out = [];
+  for (const line of markdown.split('\n')) {
+    const m = /^\s*[-*+]\s+(.+?)\s*$/.exec(line);
+    if (m && m[1].trim().length > 0) out.push(m[1].trim());
+  }
+  return out;
+}
+
+/**
+ * Run the import pipeline.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} [opts.now]
+ * @param {boolean} [opts.dryRun]  print proposals; no file modified
+ * @param {boolean} [opts.acceptAll]  apply every proposal (non-interactive path; in v0.1.0 the CLI either does --dry-run OR --yes-accept-all; interactive y/N is a v0.1.x candidate per design §16)
+ * @param {string} [opts.harnessRoot]  override (test injection); defaults to ~/.claude/projects
+ * @returns {Promise<object>}
+ */
+export async function importAnthropicMemory({
+  projectRoot,
+  now,
+  dryRun = false,
+  acceptAll = false,
+  harnessRoot,
+} = {}) {
+  const ts = now ?? nowIso();
+  const t0 = Date.now();
+
+  if (!projectRoot) {
+    return errorResult({
+      category: ERROR_CATEGORIES.MISSING_PROJECT_ROOT,
+      errors: ['projectRoot is required'],
+      duration_ms: Date.now() - t0,
+    });
+  }
+
+  const sourcePath = anthropicMemoryPath(projectRoot, harnessRoot);
+  if (!existsSync(sourcePath)) {
+    return {
+      action: 'completed',
+      proposals: [],
+      accepted: 0,
+      skipped: 0,
+      errors: 0,
+      reason: 'no-source',
+      sourcePath,
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  let sourceText;
+  try {
+    sourceText = readFileSync(sourcePath, 'utf8');
+  } catch (err) {
+    return {
+      action: 'completed',
+      proposals: [],
+      accepted: 0,
+      skipped: 0,
+      errors: 1,
+      reason: `read-source-failed: ${err?.message ?? err}`,
+      sourcePath,
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  // Read existing project MEMORY.md for dedup (canonicalize each bullet).
+  const targetPath = join(projectRoot, ...MEMORY_REL);
+  const existingCanonical = new Set();
+  if (existsSync(targetPath)) {
+    try {
+      const existing = readFileSync(targetPath, 'utf8');
+      for (const bullet of parseBullets(existing)) {
+        existingCanonical.add(canonicalize(bullet));
+      }
+    } catch {
+      // best-effort: empty set means we treat everything as new
+    }
+  }
+
+  const sourceBullets = parseBullets(sourceText);
+  const proposals = [];
+  let skippedDup = 0;
+  const tierRoot = join(projectRoot, 'context');
+  for (const bullet of sourceBullets) {
+    const canonical = canonicalize(bullet);
+    if (!canonical) continue;
+    const id = generateId('P', bullet);
+    if (existingCanonical.has(canonical)) {
+      skippedDup += 1;
+      try {
+        appendAuditEntry(tierRoot, {
+          ts,
+          action: 'import',
+          tier: 'P',
+          id,
+          reasonCode: REASON_CODES.IMPORT_SKIPPED_DUPLICATE,
+          extra: { source: 'anthropic-auto-memory' },
+        });
+      } catch {
+        // best-effort — never block the import flow on audit-log failure
+      }
+      continue;
+    }
+    proposals.push({ text: bullet, canonical, id });
+  }
+
+  // Dry-run: report proposals + don't touch files.
+  if (dryRun) {
+    return {
+      action: 'completed',
+      mode: 'dry-run',
+      proposals,
+      accepted: 0,
+      skipped: skippedDup,
+      errors: 0,
+      sourcePath,
+      targetPath,
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  // Apply mode: write each proposal as a new bullet under an
+  // `## Imported (Anthropic auto-memory, YYYY-MM-DD)` section.
+  if (!acceptAll && proposals.length > 0) {
+    // v0.1.0 has no interactive prompt at this layer — the CLI handler
+    // is responsible for the readline flow if it wants one. v0.1.0
+    // requires explicit `--yes` to apply.
+    return {
+      action: 'completed',
+      mode: 'requires-confirmation',
+      proposals,
+      accepted: 0,
+      skipped: skippedDup,
+      errors: 0,
+      sourcePath,
+      targetPath,
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  if (proposals.length === 0) {
+    return {
+      action: 'completed',
+      mode: 'apply',
+      proposals: [],
+      accepted: 0,
+      skipped: skippedDup,
+      errors: 0,
+      sourcePath,
+      targetPath,
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  // Append section to MEMORY.md.
+  // M3 (skill-review 2026-05-28): same-day re-runs create a NEW section
+  // header. Append-only is correct for audit fidelity; cosmetic
+  // deduplication of section headers is a v0.1.x candidate per design §16.
+  const today = ts.slice(0, 10);
+  const sectionHeader = `\n## Imported (Anthropic auto-memory, ${today})\n`;
+  const bulletLines = proposals.map((p) => `- (${p.id}) ${p.text}\n<!-- write_source: imported, trust: medium, source: anthropic-auto-memory, imported_at: ${ts} -->`).join('\n');
+  mkdirSync(join(projectRoot, 'context'), { recursive: true });
+  appendFileSync(targetPath, sectionHeader + '\n' + bulletLines + '\n', 'utf8');
+
+  let accepted = 0;
+  for (const p of proposals) {
+    accepted += 1;
+    try {
+      appendAuditEntry(tierRoot, {
+        ts,
+        action: 'import',
+        tier: 'P',
+        id: p.id,
+        reasonCode: REASON_CODES.IMPORT_APPLIED,
+        extra: {
+          source: 'anthropic-auto-memory',
+          trust: 'medium',
+          write_source: 'imported',
+        },
+      });
+    } catch {
+      // best-effort
+    }
+  }
+
+  return {
+    action: 'completed',
+    mode: 'apply',
+    proposals,
+    accepted,
+    skipped: skippedDup,
+    errors: 0,
+    sourcePath,
+    targetPath,
+    duration_ms: Date.now() - t0,
+  };
+}