@lh8ppl/claude-memory-kit 0.2.2 → 0.2.4

package/README.md

@@ -7,8 +7,8 @@
 - **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 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.
+- **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. For backtick/quote-heavy rich facts, capture them shell-safe as JSON: `cmk remember --from-file fact.json` (or `--json` from stdin) — content never touches the shell.
+- **Search + MCP — Claude runs every memory op for you, in conversation** — `cmk search "<term>"` (keyword/hybrid over facts + scratchpads). `cmk install` registers the kit's **MCP server**, so Claude can do the whole memory surface as tools without you ever typing `cmk`: capture (`mk_remember`, rich Why/How too), recall (`mk_search` / `mk_get` / `mk_timeline` / `mk_cite`), adjust trust (`mk_trust`), promote a fact across projects (`mk_lessons_promote`), forget (`mk_forget` — previews first, then deletes on confirm), and clear the review/conflict queues (`mk_queue_list` / `mk_queue_resolve`). The tools are allow-listed on install, so they run prompt-free.
 - **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.
@@ -26,7 +26,7 @@ cmk install        # scaffolds context/ + the memory-write skill AND wires the l
 cmk doctor         # verify, then restart Claude Code
 ```
 
-`cmk install` is a complete entry point: it scaffolds `context/`, drops the `memory-write` skill into `.claude/skills/` (committed — travels with `git clone`), and writes the 5 lifecycle hooks (PATH-resolved, cross-OS) into the project's `.claude/settings.json`. No separate `/plugin` step needed. Use `cmk install --no-hooks` for a scaffold-only install.
+`cmk install` is a complete entry point: it scaffolds `context/`, drops the `memory-write` skill into `.claude/skills/` (committed — travels with `git clone`), and writes the 5 lifecycle hooks (PATH-resolved, cross-OS) into the project's `.claude/settings.json`. It also **registers the kit's MCP server** in `.mcp.json` and allow-lists its tools (`mcp__cmk__*`) in `.claude/settings.json`, so Claude can drive memory as tools with no per-call prompt. No separate `/plugin` step needed. Use `cmk install --no-hooks` to skip the hooks + MCP wiring (scaffold-only).
 
 > Installing the package globally adds the `cmk` CLI **and** the installer. It's the `cmk install` *subcommand* that wires the hooks — not the bare `npm install`.
 
@@ -51,9 +51,10 @@ Most-used commands (full list via `cmk --help`):
 | `cmk doctor` | Run HC-1..HC-9 health checks, surface repair commands |
 | `cmk repair --hooks` / `--locks` / `--index` / `--all` | Idempotent self-repair |
 | `cmk search "<query>" [--mode keyword\|semantic\|hybrid]` | Search accumulated memory (keyword default) |
+| `cmk get <id…>` / `cmk timeline <id>` / `cmk cite <id>` / `cmk recent-activity` | Read the index back — full fact bodies + provenance, sequential context around an observation, a canonical citation link, recent changes (the CLI side of the `mk_*` MCP read tools) |
 | `cmk roll --scope now\|today\|recent` | Manually trigger a compression pipeline |
 | `cmk register-crons [--dry-run] [--unregister]` | Register daily + weekly jobs with cron / launchd / Task Scheduler |
-| `cmk forget <id>` | Tombstone a fact (preserves audit trail) |
+| `cmk forget <id>` | Tombstone a fact — disappears from `cmk search` immediately, no manual reindex (audit trail preserved) |
 | `cmk lessons promote <id> [--to USER.md\|HABITS.md]` | Promote one captured fact to your cross-project **user tier** (the safe path — sanitized, secret-screened, audited) so it applies in **every** project |
 | `cmk disable-native-memory` / `enable-native-memory` | Opt out of Claude Code's built-in Auto Memory so the kit is your single, lean memory layer (committable — travels with `git clone`) |
 | `cmk persona generate` | Run cross-project persona synthesis on demand (instead of waiting for the weekly pass) |

package/package.json

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

package/src/audit-log.mjs

@@ -30,6 +30,7 @@ export const AUDIT_LOG_SCHEMA_VERSION = 1;
 // 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({
+  FACT_CREATED: 'fact-created', // writeFact: a new fact file was written (Task 123.A — the default create audit; callers emitting a richer code opt out via audit:false)
   DUPLICATE: 'duplicate', // writeFact: same path + same id
   DUPLICATE_ELSEWHERE: 'duplicate-elsewhere', // writeFact: different path + same id
   USER_REQUESTED: 'user-requested', // forget: user-initiated tombstone

package/src/auto-extract.mjs

@@ -796,7 +796,7 @@ export async function runAutoExtract({
         // duration ≈ 25000ms = hitting the cap, not finishing) → automatic
         // capture + persona promotion (F2) silently never ran. This call is
         // DETACHED (fire-and-forget, never blocks the session), so a generous
-        // ceiling is free. Live-test finding (2026-06-01, lior-test-4 baseline).
+        // ceiling is free. Live-test finding (2026-06-01, live-test-4 baseline).
         timeoutMs: 90_000,
       });
       // Touch the cooldown marker IMMEDIATELY after the Haiku call

package/src/auto-persona.mjs

@@ -4,11 +4,11 @@
 // reproduced design §16.16's predicted failure: cross-project doctrine
 // ("how I work everywhere" — venv-3.13, layered-backend) was captured
 // but filed PROJECT-tier; the USER tier stayed empty, collapsing the
-// 3-tier value prop to project+local. Lior won't hand-curate the user
+// 3-tier value prop to project+local. The user won't hand-curate the user
 // tier ("too much of a hassle"), so the user tier must fill itself.
 //
 // Posture (tasks.md 45.6 — supersedes 45.2/45.3's manual gate):
-// OPTIMISTIC AUTO-PROMOTE. Lior 2026-05-30: "i dont want to do
+// OPTIMISTIC AUTO-PROMOTE. The user (2026-05-30): "i dont want to do
 // anything, i want it to be automatic." A synthesized doctrine that
 // applies beyond the current project is auto-promoted to the user tier
 // at trust:medium — no manual `cmk persona accept` step. A confidence
@@ -75,6 +75,11 @@ export const PERSONA_CANDIDATE_RE =
 // userDir is passed through to listObservationSources purely to keep the
 // U-tier resolution sandbox-scoped (never walk the real home dir —
 // design §16.36); we then filter to tier P, the synthesis SOURCE.
+// Byte budget for the `facts` persona corpus (Task 111 / F-2). Bounds the Haiku
+// classifier input so a large project's whole-memory sweep can't blow the timeout.
+// Generous (facts are high-signal) but bounded; whole facts only (see below).
+export const PERSONA_CORPUS_BYTES = 60_000;
+
 function assembleProjectCorpus({ projectRoot, userDir }) {
   const sources = listObservationSources({ projectRoot, userDir });
   const parts = [];
@@ -94,7 +99,30 @@ function assembleProjectCorpus({ projectRoot, userDir }) {
       parts.push((content ?? '').trim());
     }
   }
-  return parts.filter(Boolean).join('\n\n');
+  // Task 111 (F-2): BOUND the corpus. Previously this joined EVERY tier-P fact
+  // + scratchpad with no cap, so on a real project with substantial memory the
+  // classifier prompt grew unbounded and the Haiku `claude --print` call blew the
+  // timeout (the reported "did not return within 50000ms"). Accumulate WHOLE
+  // facts up to a byte budget (never split a fact mid-body) and mark truncation.
+  // KNOWN LIMITATION (mirrors TRANSCRIPT_WINDOW_BYTES): facts past the budget are
+  // dropped in file-iteration order — a doctrine fact in the tail can be missed
+  // on one pass, but the weekly janitor re-runs, and some doctrine beats a
+  // timed-out zero. A value-ordered (trust/recency-first) accumulation is the
+  // follow-up if a large corpus drops doctrine.
+  const out = [];
+  let used = 0;
+  let truncated = false;
+  for (const part of parts.filter(Boolean)) {
+    const cost = Buffer.byteLength(part, 'utf8') + 2; // +2 for the '\n\n' join
+    if (used + cost > PERSONA_CORPUS_BYTES) {
+      truncated = true;
+      break;
+    }
+    out.push(part);
+    used += cost;
+  }
+  if (truncated) out.push('### …\n(corpus truncated — additional project facts omitted for this pass)');
+  return out.join('\n\n');
 }
 
 // Default size of the recent-transcript window handed to the SessionEnd persona
@@ -111,7 +139,7 @@ function assembleProjectCorpus({ projectRoot, userDir }) {
 // 40k chars ≈ a long session's worth of turns ≈ ~10k tokens — trivial cost for a
 // once-per-session call, and the classifier prompt's "IGNORE anything specific to
 // this ONE project" instruction guards precision at the larger size (live test:
-// clean 2/2, no false promotes). The exact bound is a lior-test-9 tuning item.
+// clean 2/2, no false promotes). The exact bound is a live-test-9 tuning item.
 // KNOWN LIMITATION (documented, not yet fixed): only the most-recent date-named
 // file is read, so a session spanning midnight loses the pre-midnight turns. Rare;
 // a multi-file read is the follow-up if it bites.
@@ -250,7 +278,7 @@ export function parsePersonaCandidates(outputText) {
  */
 export async function autoPersona(opts = {}) {
   const t0 = Date.now();
-  const { projectRoot, userDir, backend, now, settings, cooldownMs = DEFAULT_COOLDOWN_MS, source = 'facts' } = opts;
+  const { projectRoot, userDir, backend, now, settings, cooldownMs = DEFAULT_COOLDOWN_MS, source = 'facts', timeoutMs = 50_000 } = opts;
 
   if (!projectRoot) {
     return errorResult({
@@ -302,7 +330,11 @@ export async function autoPersona(opts = {}) {
       instructions: buildClassifierInstructions(source),
       preserveCitationIds: false,
       maxOutputBytes: 4096,
-      timeoutMs: 50_000,
+      // Task 111 (F-2): the timeout is caller-supplied. The SessionEnd hook path
+      // keeps the 50_000 default (it composes with the 60s SessionEnd ceiling per
+      // design §8.5 / D-42). The CLI `cmk persona generate` has NO outer hook
+      // ceiling, so it passes a generous value — the explicit command can wait.
+      timeoutMs,
     });
     // Spent a Haiku call — refresh the shared cooldown marker so the next
     // gated caller backs off. (touch even on cooldownMs:0 cycles: the call
@@ -349,7 +381,7 @@ export async function autoPersona(opts = {}) {
  *     inferred noise. This still holds for every medium/inferred write.
  *   - trust:'high' (explicit path — Task 76 `cmk lessons promote` + Task 78
  *     inline grading of an EXPLICITLY-STATED rule). **45.4 REFINEMENT
- *     (2026-06-02, D-32 — Lior chose "latest explicit wins"):** an explicit,
+ *     (2026-06-02, D-32 — the user chose "latest explicit wins"):** an explicit,
  *     user-attested rule at trust:high MAY supersede an equal-trust same-topic
  *     entry (high >= high → supersede). The newest explicit statement wins,
  *     even over a hand-curated high. The original protection is unchanged for
@@ -359,7 +391,7 @@ export async function autoPersona(opts = {}) {
  */
 // Persist low/medium-confidence (and otherwise-not-promoted) candidates to a
 // durable review-queue FILE at <userDir>/queues/persona-review.md, so they are
-// not lost when only returned in the response (Lior 2026-05-31: "response
+// not lost when only returned in the response (the user, 2026-05-31: "response
 // object can get lost — i dont like it"). Dedup by canonical id against what's
 // already in the file so repeated synthesis passes don't pile up duplicates.
 // Returns the queue path (or null when there's nothing to write).

package/src/capture-turn.mjs

@@ -48,6 +48,9 @@ import {
   appendFileSync,
   readFileSync,
   writeFileSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
 } from 'node:fs';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -57,6 +60,41 @@ function dateFromIso(iso) {
   return String(iso).slice(0, 10);
 }
 
+// A `.extract-<ts>.tmp` turn-file lives only for the duration of one
+// auto-extract run (bounded by the Stop-hook ceiling, design §8.5). The owning
+// child unlinks it in its `finally`; capture-turn unlinks it here when the spawn
+// fails. But a child KILLED before its finally (hook ceiling), or a Windows
+// unlink refused by a scanner, leaks the temp (cut-gate7 found 2 lingering —
+// D-103 finding E). This janitor sweeps any `.extract-*.tmp` older than the
+// threshold — far longer than any live run, so it can't race an in-flight child.
+// Best-effort: a sweep hiccup must never block the capture.
+const STALE_TURN_FILE_MS = 10 * 60 * 1000; // 10 min — well beyond the hook ceiling
+
+export function sweepStaleTurnFiles(transcriptsDir, maxAgeMs = STALE_TURN_FILE_MS, now = Date.now()) {
+  let swept = 0;
+  if (!existsSync(transcriptsDir)) return swept;
+  let entries;
+  try {
+    entries = readdirSync(transcriptsDir);
+  } catch {
+    return swept;
+  }
+  for (const name of entries) {
+    if (!name.startsWith('.extract-') || !name.endsWith('.tmp')) continue;
+    const p = join(transcriptsDir, name);
+    try {
+      if (now - statSync(p).mtimeMs > maxAgeMs) {
+        unlinkSync(p);
+        swept += 1;
+      }
+    } catch {
+      // best-effort: a stat/unlink failure (already gone, or briefly locked)
+      // must not abort the sweep or the capture.
+    }
+  }
+  return swept;
+}
+
 // 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
@@ -143,7 +181,7 @@ function readLastUserTurnFromTranscript(transcriptPath) {
 // (context/sessions/now.md). Before this, now.md was fed ONLY by observe-edit's
 // file-write lines ("[ts] Write file=X lines=N"), so the SessionEnd compressor
 // summarized a list of filenames and hallucinated content the dialogue never
-// contained (lior-test-6: "Flask app: app.py" — inferred a framework from a
+// contained (live-test-6: "Flask app: app.py" — inferred a framework from a
 // filename). Buffering the actual user+assistant turns here means the summary
 // reflects what was DISCUSSED. Same `## <ts> — speaker` shape as the transcript
 // so the compressor reads it as dialogue; now.md is truncated after each compress
@@ -281,6 +319,10 @@ export function captureTurn({
   // summarizes the DIALOGUE, not observe-edit's filename log. Best-effort.
   appendConversationToNowMd({ projectRoot, ts, userTurn, assistantTurn: sanitized });
 
+  // Janitor: clear any orphaned turn-files from a prior killed/crashed child
+  // before writing this turn's (D-103 finding E). Best-effort.
+  sweepStaleTurnFiles(transcriptsDir);
+
   const turnFile = join(transcriptsDir, `.extract-${Date.now()}.tmp`);
   try {
     writeFileSync(
@@ -316,6 +358,11 @@ export function captureTurn({
       reason: spawnResult.reason,
       error: spawnResult.error,
     });
+    // NB: we do NOT unlink the turn-file here. Ownership is clean — auto-extract
+    // owns deletion (its `finally`); when the spawn fails (or a child is killed
+    // before its finally), the file becomes an orphan that the entry-sweep above
+    // reaps once it's stale (D-103 finding E). capture-turn never deletes a file
+    // it handed off, so tests can still inspect the IPC shape on the no-spawn path.
   }
 
   return {

package/src/compressor.mjs

@@ -24,7 +24,7 @@
 // Note on the allowedTools split: design.md §6.1 documents
 // `--allowed-tools "Read"`; the code-dive note recommended tightening
 // to fully empty per claude-remember's actual pattern. This PR
-// implements empty per Lior's instruction (the auto-extract sub-Claude
+// implements empty per the user's instruction (the auto-extract sub-Claude
 // never needs Read either — the turn content arrives in the prompt).
 
 import { spawn as defaultSpawn } from 'node:child_process';

package/src/conflict-queue.mjs

@@ -427,6 +427,20 @@ function parseQueue(queueText) {
  *
  * Returns { resolved: N, kept_old: N, kept_new: N, merged: N, skipped: N }.
  */
+/**
+ * Pure-read list of PENDING conflict-queue entries (no mutation). Used by the MCP
+ * `mk_queue_list` tool so a "list" never rewrites the queue file — unlike
+ * resolveConflictQueue, which reserializes on every call. Returns `[]` when the
+ * queue file doesn't exist.
+ */
+export function listConflictQueue({ tier = 'P', projectRoot, userDir } = {}) {
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const queuePath = join(tierRoot, ...QUEUE_RELATIVE);
+  if (!existsSync(queuePath)) return [];
+  const { entries } = parseQueue(readFileSync(queuePath, 'utf8'));
+  return entries.filter((e) => e.fields.resolution === 'pending');
+}
+
 export async function resolveConflictQueue({
   tier,
   projectRoot,