@lh8ppl/claude-memory-kit 0.3.2 → 0.3.4

package/src/subcommands.mjs

@@ -416,7 +416,19 @@ async function runSearch(queryParts, options) {
     let mode = explicitMode ?? resolveDefaultSearchMode({ projectRoot });
     // Task 104.2 — the L3 raw tier: `--scope transcripts` searches the
     // separate transcript-chunk index (synthetic T: ids; no tier/trust).
+    // Task 156 — `--scope decisions` scans context/DECISIONS.md (the decision
+    // journal) for decision-history / "what did we reject" recall.
     const scope = options?.scope ?? 'facts';
+    // Task 156 / v0.3.3 cut-gate-16: the `decisions` scope is keyword-only BY
+    // DESIGN — it scans the flat `context/DECISIONS.md` journal, which is NOT
+    // embedded (no vec table). So it can never go through the semantic backend.
+    // Coerce to keyword BEFORE the semantic block, silently — a user who has the
+    // hybrid default (from `--with-semantic`) must not see a scary
+    // "unknown-scope:decisions" warning (configured default) or hard exit-2
+    // (explicit --mode) for using a real, shipped scope. The recall just works.
+    if (scope === 'decisions') {
+      mode = SEARCH_MODES.KEYWORD;
+    }
     let semanticBackend;
     if (mode === SEARCH_MODES.SEMANTIC || mode === SEARCH_MODES.HYBRID) {
       const { prepareSemanticBackend } = await import('./semantic-backend.mjs');
@@ -443,6 +455,7 @@ async function runSearch(queryParts, options) {
       query,
       mode,
       scope,
+      projectRoot, // Task 156: the decisions scope reads context/DECISIONS.md
       minTrust: options?.minTrust,
       tier: options?.tier,
       since: options?.since,
@@ -464,9 +477,15 @@ async function runSearch(queryParts, options) {
     for (const hit of r.results) {
       // Plain-text output suitable for terminal piping. Snippet uses
       // FTS5's <b>...</b> markers; preserved as-is so callers can pipe
-      // to a TUI that renders them OR strip via sed. Transcript hits carry
-      // no tier/trust (raw chunks) — the column shows the scope instead.
-      const provenance = hit.tier ? `${hit.tier}/${hit.trust}` : 'transcript';
+      // to a TUI that renders them OR strip via sed. Hits with no tier/trust
+      // (raw transcript chunks; decision-journal entries) show the scope's
+      // label instead — 'transcript' for the L3 raw tier, 'decision' for the
+      // journal (Task 156), plus a `(retracted)` marker so the "what did we
+      // reject" trail is visible at a glance.
+      let provenance;
+      if (hit.tier) provenance = `${hit.tier}/${hit.trust}`;
+      else if (r.scope === 'decisions') provenance = hit.retracted ? 'decision (retracted)' : 'decision';
+      else provenance = 'transcript';
       console.log(
         `${hit.id}\t${provenance}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
       );
@@ -512,10 +531,19 @@ export function withReadDb(fn, deps = {}) {
   }
 }
 
-export function runGet(ids, _options = {}, _command, deps = {}) {
+export function runGet(ids, options = {}, _command, deps = {}) {
   const log = deps.log ?? console.log;
   const list = Array.isArray(ids) ? ids : [ids];
-  const rows = withReadDb((db) => getObservations(db, list), deps);
+  // Task 155 (D-163): `--include-tombstoned` is the HUMAN-only recovery opt-in.
+  // It's a CLI flag ONLY — the MCP mk_get tool never exposes it, so automatic
+  // recall stays tombstone-blind. projectRoot is resolved the same way
+  // withReadDb does, so the tombstone-file fallback can find the archive.
+  const includeTombstoned = options.includeTombstoned === true;
+  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
+  const rows = withReadDb(
+    (db) => getObservations(db, list, { includeTombstoned, projectRoot }),
+    deps,
+  );
   log(JSON.stringify(rows, null, 2));
   // All-missing/invalid → exit 2 (lets a script tell "nothing matched" from a hit).
   if (rows.length > 0 && rows.every((r) => r.error)) process.exitCode = 2;
@@ -1999,6 +2027,12 @@ export const subcommands = [
     description: 'fetch full observation bodies + provenance by ID (parity with the mk_get MCP tool)',
     milestone: 108,
     argSpec: [{ flags: '<ids...>', description: 'one or more citation IDs (e.g. P-S79MJHFN)' }],
+    optionSpec: [
+      {
+        flags: '--include-tombstoned',
+        description: 'also recover forgotten (tombstoned) facts from the archive — human-only; the AI never reads tombstones',
+      },
+    ],
     action: runGet,
   },
   {

package/src/version-drift.mjs

@@ -0,0 +1,72 @@
+// HC-9: version-drift detection (Task 162 / D-176).
+//
+// WHY: after a user updates the global `cmk` (npm i -g @latest), a project's
+// version-stamped scaffold — the CLAUDE.md managed block, the hooks, the skills —
+// stays at the OLD version until `cmk install` re-runs in that project. Updating the
+// npm package ALONE does not touch a project (the per-project re-install is the
+// easily-forgotten step). Pre-162 the kit was silent about it (D-172: no update path).
+// HC-9 makes `cmk doctor` TELL the user the project is behind + the exact command.
+//
+// The project's installed version lives in the CLAUDE.md managed-block start marker
+// (`<!-- claude-memory-kit:start v0.3.3 -->`); the installed binary version is
+// getKitVersion(). Drift = binary NEWER than the project marker → "run cmk install".
+// A project marker NEWER than the binary is a downgrade (older global cli opening a
+// newer-scaffolded project), NOT drift — flag pass, not a false alarm.
+
+import { findManagedBlock, compareVersions } from './claude-md.mjs';
+
+/**
+ * Pure HC-9 check. Injectable inputs (no disk read here) so the logic is unit-tested
+ * without a fixture tree; the doctor wiring reads CLAUDE.md + getKitVersion() and
+ * passes them in.
+ *
+ * @param {object} args
+ * @param {string|null} args.claudeMdText — the project's CLAUDE.md content, or null if absent.
+ * @param {string} args.kitVersion        — the installed binary version (getKitVersion()).
+ * @returns {{id:'HC-9', name:string, status:'pass'|'fail'|'skip', message:string, recoveryCommand?:string}}
+ */
+export function checkVersionDrift({ claudeMdText, kitVersion } = {}) {
+  const id = 'HC-9';
+  const name = 'Project scaffold version matches the installed cmk';
+
+  // No CLAUDE.md, or no managed block → the project isn't kit-installed (or the block
+  // was hand-removed). Not a drift signal; skip (HC-1/repair owns the missing-block case).
+  if (!claudeMdText) {
+    return { id, name, status: 'skip', message: 'no CLAUDE.md found — project not kit-installed' };
+  }
+  const block = findManagedBlock(claudeMdText);
+  if (!block) {
+    return { id, name, status: 'skip', message: 'no claude-memory-kit managed block in CLAUDE.md' };
+  }
+
+  // `block.version` is the `:start vX` marker value (findManagedBlock recovers it
+  // even from a corrupted/orphan-start block — a stale corrupted block still earns
+  // the `cmk install` advice, which fixes both). compareVersions strips any
+  // `-prerelease` tag, so a `v0.3.4-beta` scaffold reads as `0.3.4` (the kit ships
+  // no prereleases today; this is the intended "close enough" behavior).
+  const projectVersion = block.version;
+  const cmp = compareVersions(kitVersion, projectVersion);
+
+  if (cmp <= 0) {
+    // Binary == project (match) OR binary < project (a downgrade — older cli, newer
+    // scaffold). Neither is "re-run install to catch up." Pass.
+    return {
+      id,
+      name,
+      status: 'pass',
+      message:
+        cmp === 0
+          ? `project scaffold (v${projectVersion}) matches the installed cmk (v${kitVersion})`
+          : `project scaffold (v${projectVersion}) is newer than the installed cmk (v${kitVersion}) — likely an older global cli; not drift`,
+    };
+  }
+
+  // Binary NEWER than the project marker → the project is stale. THE drift case.
+  return {
+    id,
+    name,
+    status: 'fail',
+    message: `this project's scaffold is v${projectVersion} but your installed cmk is v${kitVersion} — re-run \`cmk install\` here to refresh the CLAUDE.md block, hooks, and skills (then restart Claude Code)`,
+    recoveryCommand: 'cmk install',
+  };
+}

package/src/weekly-curate.mjs

@@ -39,6 +39,7 @@ import { canonicalize } from '@lh8ppl/cmk-canonicalize';
 import { nowIso } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
+import { compressWithRetry } from './compress-retry.mjs';
 import {
   DEFAULT_COOLDOWN_MS,
   isCooldownActive,
@@ -388,14 +389,21 @@ export async function weeklyCurate({
   const sourceDates = old.map((f) => f.date);
 
   let result;
+  let retries = 0; // Task 161.12: count retries so the log shows the retry RATE.
   try {
-    result = await backend.compress({
-      input: buffer,
-      instructions,
-      preserveCitationIds: true,
-      maxOutputBytes: archiveMaxBytes,
-      timeoutMs: 50_000,
-    });
+    // Task 161 / D-175: ceiling-free path (cron/detached child, NO 60s hook ceiling)
+    // → bounded transient-only retry (maxAttempts:2 = one retry). See compress-retry.mjs.
+    result = await compressWithRetry(
+      backend,
+      {
+        input: buffer,
+        instructions,
+        preserveCitationIds: true,
+        maxOutputBytes: archiveMaxBytes,
+        timeoutMs: 50_000,
+      },
+      { maxAttempts: 2, onRetry: () => { retries += 1; } },
+    );
     touchCooldownMarker({ projectRoot, now: ts });
   } catch (err) {
     touchCooldownMarker({ projectRoot, now: ts });
@@ -418,6 +426,10 @@ export async function weeklyCurate({
         duration_ms,
         success: false,
         error_category: errorCategory,
+        // Task 161 (D-173 observability): structured failure reason — see compress-session.mjs.
+        ...(err?.exitCode != null ? { exit_code: err.exitCode } : {}),
+        ...(err?.stderr ? { error_detail: String(err.stderr).slice(0, 500) } : {}),
+        ...(retries > 0 ? { retries } : {}), // 161.12: failed AFTER retrying
       },
     });
     return errorResult({
@@ -487,6 +499,7 @@ export async function weeklyCurate({
       archived_days: old.length,
       current_days: current.length,
       recent_rebuild_action: recentResult?.action ?? 'skipped',
+      ...(retries > 0 ? { retries } : {}), // 161.12: succeeded after a transient retry
       ...(deletionErrors.length > 0 ? { deletion_errors: deletionErrors } : {}),
     },
   });

package/template/.claude/skills/memory-search/SKILL.md

@@ -63,6 +63,26 @@ Hits are raw turn excerpts (dialogue + the tools the agent ran), keyed
 whole turns. If something found here is durably useful, say so in the
 summary so the caller can capture it as a proper fact.
 
+## Decision HISTORY — the `decisions` scope
+
+For "what did we DECIDE about X" a normal fact search (steps 1-3) is enough —
+the decision fact carries its own **Why**. But when the question is about how a
+decision **evolved**, what we **reject**ed or moved away from, or **why X
+changed** ("did we ever consider Y?", "weren't we using Postgres?", "what did
+we decide and did it change?"), search the **decision journal** — the
+append-only `context/DECISIONS.md`, which keeps superseded + retracted entries
+the live fact store no longer carries:
+
+- MCP: `mk_search` with `scope: "decisions"`.
+- CLI: `cmk search "<topic>" --scope decisions`
+
+Hits are decision entries keyed by their fact id, labelled `decision` (or
+`decision (retracted)` for a reversed one). The retracted/superseded entries
+ARE the answer to "what did we reject" — surface them explicitly, with the
+date, so the caller sees the trail. Use this scope IN ADDITION to the fact
+ladder when the question has a history/evolution axis; the fact search answers
+the "current decision", the journal answers "how it got there".
+
 ## When the query is vague
 
 If you cannot form a concrete query, look at recent activity first, then

package/template/CLAUDE.md.template

@@ -29,6 +29,7 @@ The `cmk doctor` health checks verify each layer is wired correctly: install int
 The snapshot injected at session start is a **bounded hot index, not everything** — there is a deeper, queryable archive. When a question is "what did we decide / what's our X / how does the user work / what's the setup / **how is this project structured or built / where does X live / what's the architecture**," **query your memory instead of re-deriving the answer from scratch** — the structure is a recorded decision, recall it before re-reading the files to reconstruct it:
 
 - **`cmk search "<topic>"`** — find any captured fact (decisions, preferences, config, lessons) across the project + user tiers.
+- **`cmk search "<topic>" --scope decisions`** — the append-only **decision journal** (`context/DECISIONS.md`). Use it for decision **history / evolution** — "what did we reject", "did X change", "why did we move away from Y" — it keeps superseded + retracted decisions the live fact store drops. (A plain `cmk search` answers "what's the current decision"; this answers "how it got there".)
 - **`context/memory/<type>_<slug>.md`** — the granular fact archive with full **Why / How** rationale (`context/memory/INDEX.md` lists them).
 - **`~/.claude-memory-kit/` (`USER.md` / `HABITS.md` / `LESSONS.md`)** — how this user works across *all* their projects.