@lh8ppl/claude-memory-kit 0.1.0

package/bin/cmk-compress-lazy.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Lazy compress bin wrapper (Task 35, T-030). Invoked detached from
+// inject-context.mjs (SessionStart hook) when staleness is detected
+// and cron is NOT active. Humans normally don't invoke this directly;
+// the documented user-facing entry point is `cmk compress --lazy`.
+//
+// Protocol: one-shot process; exits when done. No stdin payload.
+// Project root from CMK_PROJECT_DIR env or cwd.
+//
+// Composes on runLazyCompress() per design §8.2.2. Always exits 0 —
+// a crashed lazy-compress should never propagate back to the
+// SessionStart hook that spawned it (detached posture); the kit's
+// lazy-compress.log NDJSON + cooldown marker are the load-bearing
+// observability surfaces.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const lazyCompressModulePath = join(__dirname, '..', 'src', 'lazy-compress.mjs');
+const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+
+let runLazyCompress;
+let HaikuViaAnthropicApi;
+try {
+  ({ runLazyCompress } = await import(pathToFileURL(lazyCompressModulePath).href));
+  ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-compress-lazy: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  process.exit(0);
+}
+
+// Task 36 B1 fix: accept projectRoot via argv[2]. Inject-context.mjs's
+// detached spawn passes CMK_PROJECT_DIR via env; accepting argv[2]
+// keeps the bin uniform with cmk-daily-distill / cmk-weekly-curate
+// and makes manual debugging (`node cmk-compress-lazy.mjs /path`) work.
+const argvRoot = process.argv[2] && process.argv[2].length > 0 ? process.argv[2] : null;
+const envRoot = process.env.CMK_PROJECT_DIR && process.env.CMK_PROJECT_DIR.length > 0
+  ? process.env.CMK_PROJECT_DIR
+  : null;
+const projectRoot = argvRoot ?? envRoot ?? process.cwd();
+
+try {
+  const backend = new HaikuViaAnthropicApi();
+  const r = await runLazyCompress({ projectRoot, backend });
+  process.stderr.write(
+    `cmk-compress-lazy: ${r.action}${r.reason ? ` (${r.reason})` : ''}${r.delegatedTo ? ` → ${r.delegatedTo}` : ''} ms: ${r.duration_ms ?? 0}\n`,
+  );
+} catch (err) {
+  process.stderr.write(
+    `cmk-compress-lazy: unexpected error: ${err?.message ?? err}\n`,
+  );
+}
+
+process.exit(0);

package/bin/cmk-daily-distill.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Daily distill bin wrapper (Task 33, T-028). Invoked by the
+// host scheduler (cron / launchd / Task Scheduler) registered via
+// `cmk register-crons` per design §8.6.2.
+//
+// Protocol: the wrapper is a one-shot process that exits when done.
+// No stdin payload expected (unlike Stop/SessionEnd hooks). The kit's
+// project root is read from CMK_PROJECT_DIR env (set by the cron
+// command line) or falls back to cwd.
+//
+// Composes on dailyDistill() per design §8.6.1. Always exits 0 — a
+// crashed cron job rotates noise into the scheduler logs without any
+// recovery affordance for the user; the kit's distill.log NDJSON
+// + cooldown marker are the load-bearing observability surfaces.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// This bin lives under packages/cli/bin/ (Task 33 B1 fix — was originally
+// under plugin/bin/ but that tree isn't in the published @lh8ppl/claude-memory-kit
+// npm package, so `cmk register-crons` emitted cron commands pointing at
+// paths that don't exist in `npm install -g` installs). Paths resolved
+// relative to bin/ → ../src/ for both modules.
+const dailyDistillModulePath = join(__dirname, '..', 'src', 'daily-distill.mjs');
+const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+
+let dailyDistill;
+let HaikuViaAnthropicApi;
+try {
+  ({ dailyDistill } = await import(pathToFileURL(dailyDistillModulePath).href));
+  ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-daily-distill: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  process.exit(0);
+}
+
+// Task 36 B1 fix: accept projectRoot via argv[2] (the registered cron
+// emits an absolute path here). Env var + cwd remain as fallbacks for
+// users invoking the bin manually. Host schedulers (cron / launchd /
+// schtasks) all have a non-kit default cwd, so argv-or-env is the
+// load-bearing source for cron-emitted invocations.
+// Treat empty-string env var as "missing" (?? falls through only on
+// null/undefined; empty strings would otherwise become invalid paths).
+const argvRoot = process.argv[2] && process.argv[2].length > 0 ? process.argv[2] : null;
+const envRoot = process.env.CMK_PROJECT_DIR && process.env.CMK_PROJECT_DIR.length > 0
+  ? process.env.CMK_PROJECT_DIR
+  : null;
+const projectRoot = argvRoot ?? envRoot ?? process.cwd();
+
+try {
+  const backend = new HaikuViaAnthropicApi();
+  const r = await dailyDistill({ projectRoot, backend });
+  process.stderr.write(
+    `cmk-daily-distill: ${r.action}${r.reason ? ` (${r.reason})` : ''}${r.bytesIn ? ` (in: ${r.bytesIn}b, out: ${r.bytesOut}b, days: ${r.sourceDays})` : ''} ms: ${r.duration_ms ?? 0}\n`,
+  );
+} catch (err) {
+  process.stderr.write(
+    `cmk-daily-distill: unexpected error: ${err?.message ?? err}\n`,
+  );
+}
+
+process.exit(0);

package/bin/cmk-weekly-curate.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Weekly curate bin wrapper (Task 34, T-029). Invoked by the host
+// scheduler (cron / launchd / Task Scheduler) registered via
+// `cmk register-crons --weekly` per design §8.7.
+//
+// Protocol: one-shot process; exits when done. No stdin payload
+// expected. Project root from CMK_PROJECT_DIR env or cwd.
+//
+// Composes on weeklyCurate() per design §8.7.1. Always exits 0 — a
+// crashed cron job rotates noise into the scheduler logs without any
+// recovery affordance for the user; the kit's curate.log NDJSON +
+// cooldown marker are the load-bearing observability surfaces.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const weeklyCurateModulePath = join(__dirname, '..', 'src', 'weekly-curate.mjs');
+const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+
+let weeklyCurate;
+let HaikuViaAnthropicApi;
+try {
+  ({ weeklyCurate } = await import(pathToFileURL(weeklyCurateModulePath).href));
+  ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-weekly-curate: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  process.exit(0);
+}
+
+// Task 36 B1 fix: accept projectRoot via argv[2] (the registered cron
+// emits an absolute path here). Env var + cwd remain as fallbacks.
+// See cmk-daily-distill.mjs for rationale.
+const argvRoot = process.argv[2] && process.argv[2].length > 0 ? process.argv[2] : null;
+const envRoot = process.env.CMK_PROJECT_DIR && process.env.CMK_PROJECT_DIR.length > 0
+  ? process.env.CMK_PROJECT_DIR
+  : null;
+const projectRoot = argvRoot ?? envRoot ?? process.cwd();
+
+try {
+  const backend = new HaikuViaAnthropicApi();
+  const r = await weeklyCurate({ projectRoot, backend });
+  process.stderr.write(
+    `cmk-weekly-curate: ${r.action}${r.reason ? ` (${r.reason})` : ''}${r.archivedDays ? ` (archived: ${r.archivedDays}d, current: ${r.currentDays}d, in: ${r.bytesIn}b, out: ${r.bytesOut}b)` : ''} ms: ${r.duration_ms ?? 0}\n`,
+  );
+} catch (err) {
+  process.stderr.write(
+    `cmk-weekly-curate: unexpected error: ${err?.message ?? err}\n`,
+  );
+}
+
+process.exit(0);

package/bin/cmk.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// cmk — claude-memory-kit CLI entry point.
+// Thin shim: defers all argv parsing + dispatch to src/index.mjs.
+// Kept thin so the bin file rarely needs to change once installed.
+
+import { run } from '../src/index.mjs';
+
+run(process.argv).catch((err) => {
+  console.error('cmk: unexpected error');
+  console.error(err && err.stack ? err.stack : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@lh8ppl/claude-memory-kit",
+  "version": "0.1.0",
+  "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
+  "type": "module",
+  "bin": {
+    "cmk": "./bin/cmk.mjs",
+    "cmk-daily-distill": "./bin/cmk-daily-distill.mjs",
+    "cmk-weekly-curate": "./bin/cmk-weekly-curate.mjs",
+    "cmk-compress-lazy": "./bin/cmk-compress-lazy.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "prepublishOnly": "node ../../scripts/prepublish-copy-template.mjs"
+  },
+  "dependencies": {
+    "@lh8ppl/cmk-canonicalize": "0.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LH8PPL/claude-memory-kit.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "anthropic",
+    "cli"
+  ]
+}

package/src/audit-log.mjs

@@ -0,0 +1,103 @@
+// Canonical audit-log writer for every kit module that mutates state.
+// Per the Layer-2 review's I4 finding, the three writers (writeFact-skipped,
+// forget, merge-facts) had been writing to the same <tierRoot>/.locks/audit.log
+// in three different schemas — `path` vs `originalPath` vs `newPath`; `reason`
+// overloaded as enum vs free-text; `tier` missing from writeFact entries.
+//
+// This module is the single sanctioned audit-log writer. New writers (Task 24
+// memory-write, Task 15 trust override, etc.) MUST import appendAuditEntry
+// from here. See CLAUDE.md "Shared modules" rule.
+//
+// Schema v1 (canonical):
+//   {
+//     ts: ISO 8601 UTC,
+//     schema: 1,
+//     action: enum string,
+//     tier: 'P' | 'L' | 'U',
+//     id: citation ID of the affected fact,
+//     reasonCode: enum string (machine-parseable),
+//     reasonText?: free-form string (human-readable, optional),
+//     paths?: { before?, after?, archive? } where each value is string|string[],
+//     extra?: object (action-specific extension fields)
+//   }
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const AUDIT_LOG_SCHEMA_VERSION = 1;
+
+// Enum of reasonCode values seen in v0.1. New writers may add codes here as
+// they come online; the rule is one canonical machine-parseable token per
+// kind of audit event (not a free-text reason field).
+export const REASON_CODES = Object.freeze({
+  DUPLICATE: 'duplicate', // writeFact: same path + same id
+  DUPLICATE_ELSEWHERE: 'duplicate-elsewhere', // writeFact: different path + same id
+  USER_REQUESTED: 'user-requested', // forget: user-initiated tombstone
+  CURATED_MERGE: 'curated-merge', // mergeFacts: explicit merge of A + B → C
+  SCRATCHPAD_APPEND: 'scratchpad-append', // scratchpad: appendScratchpadBullet (Task 12)
+  TRUST_CHANGE: 'trust-change', // trust: overrideTrust (Task 15)
+  CONFLICT_QUEUED: 'conflict-queued', // conflict-queue: new write contradicts existing higher-trust fact, routed to queues/conflicts.md (Task 25, design §6.8)
+  CONFLICT_RESOLVED: 'conflict-resolved', // conflict-queue: user resolved a pending conflict via cmk queue conflicts (keep-old / keep-new / merge-both)
+  REVIEW_PROMOTED: 'review-promoted', // review-queue: user promoted a medium-trust auto-extract to MEMORY.md (Task 26, design §6.2)
+  REVIEW_DISCARDED: 'review-discarded', // review-queue: user discarded a medium-trust auto-extract via cmk queue review
+  IMPORT_APPLIED: 'import-applied', // import-anthropic-memory: bullet applied to project MEMORY.md with write_source:imported (Task 38)
+  IMPORT_SKIPPED_DUPLICATE: 'import-skipped-duplicate', // import-anthropic-memory: candidate canonicalize-matched existing fact, skipped (Task 38)
+  REPAIR_HOOKS_APPLIED: 'repair-hooks-applied', // cmk repair --hooks: settings.json updated with canonical kit hooks (Task 39)
+  REPAIR_HOOKS_NOOP: 'repair-hooks-noop', // cmk repair --hooks: settings.json already canonical, no-op (Task 39)
+  REPAIR_LOCK_REMOVED: 'repair-lock-removed', // cmk repair --locks: stale lock unlinked (Task 39)
+});
+
+export function nowIso() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function auditLogPath(tierRoot) {
+  return join(tierRoot, '.locks', 'audit.log');
+}
+
+export function appendAuditEntry(tierRoot, entry) {
+  // Required-field validation. Throw immediately on caller error; this catches
+  // schema drift at write time rather than at log-parse time later.
+  for (const field of ['action', 'tier', 'id', 'reasonCode']) {
+    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
+      throw new Error(
+        `audit-log: missing required field "${field}" in entry ${JSON.stringify(entry)}`,
+      );
+    }
+  }
+
+  const canonical = {
+    ts: entry.ts ?? nowIso(),
+    schema: AUDIT_LOG_SCHEMA_VERSION,
+    action: entry.action,
+    tier: entry.tier,
+    id: entry.id,
+    reasonCode: entry.reasonCode,
+  };
+  if (entry.reasonText !== undefined) canonical.reasonText = entry.reasonText;
+  if (entry.paths !== undefined) canonical.paths = entry.paths;
+  // Field name is `extra` (singular). Caller convention across the kit
+  // (memory-write, conflict-queue, etc.); plural `extras` is a common
+  // typo — caught in tests but worth naming here so future modules
+  // pick the right key.
+  if (entry.extra !== undefined) canonical.extra = entry.extra;
+
+  const locksDir = join(tierRoot, '.locks');
+  mkdirSync(locksDir, { recursive: true });
+  appendFileSync(
+    auditLogPath(tierRoot),
+    JSON.stringify(canonical) + '\n',
+    'utf8',
+  );
+}
+
+// Convenience reader, useful for tests + future cmk doctor + cmk queue
+// commands. Returns [] if the log doesn't exist yet.
+export function readAuditLog(tierRoot) {
+  const path = auditLogPath(tierRoot);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l));
+}