@lh8ppl/claude-memory-kit 0.3.1 → 0.3.2

package/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LH8PPL/claude-memory-kit/main/docs/public/assets/wordmark-dark.svg">
+    <img src="https://raw.githubusercontent.com/LH8PPL/claude-memory-kit/main/docs/public/assets/wordmark.svg" alt="claude-memory-kit" width="340">
+  </picture>
+</p>
+
 # @lh8ppl/claude-memory-kit
 
 **`cmk`** — the CLI for [claude-memory-kit](https://github.com/LH8PPL/claude-memory-kit), a per-project, in-repo memory system for [Claude Code](https://docs.claude.com/en/docs/claude-code). It fixes Claude's per-session amnesia so you don't have to re-tell the backstory every time you start a new session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.2.0",
     "sqlite-vec": "^0.1.9",
     "zod": "^4.4.3"
   },

package/src/decisions-journal.mjs

@@ -0,0 +1,223 @@
+// The append-only decision journal — context/DECISIONS.md (Task 147, D-161).
+//
+// A chronological, human-readable page of every decision + its why. The VIEW
+// the kit was missing: decisions are captured as facts but scattered across N
+// per-fact files with no chronological decision page (cmk search is pull, not
+// browse; MEMORY.md is bounded + rolls). This is the squad `decisions.md` /
+// our own DECISION-LOG.md equivalent, made automatic.
+//
+// LIFECYCLE — APPEND-ONLY, never regenerated, never parked (D-161):
+//   - This is NOT a derived view like INDEX.md. Regenerating from live facts
+//     would silently ERASE superseded/forgotten decisions — rewriting history
+//     to look like the current state was always obvious (the exact failure the
+//     decision-trail-preservation rule exists to prevent).
+//   - A decision journal is unbounded by design: old decisions are the MOST
+//     valuable part (they explain why the codebase is shaped as it is), so the
+//     MEMORY.md rolling-window must NOT apply.
+//   - Mechanics: new decision → appended; tombstoned → its entry MARKED
+//     retracted IN PLACE (never removed); every pre-existing entry survives
+//     every update.
+//
+// The update is triggered like a derived view (runs where reindex runs, so the
+// journal stays current) but its WRITE LOGIC is append-only — the file is the
+// accumulator, the facts are only the trigger. Each entry carries a stable
+// machine marker `<!-- decision:P-XXXXXXXX -->` so the updater knows which ids
+// are already journaled + which entries to annotate, without parsing prose
+// (and so a human can freely add their own prose between entries — preserved).
+//
+// v0.3.2 scope: explicit signals only (capture appends; forget marks retracted;
+// explicit supersession annotates). AUTOMATIC semantic contradiction-detection
+// is deferred to F-D / Task 95.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
+import { ID_PATTERN } from './tier-paths.mjs';
+
+export const DECISIONS_HEADER =
+  '# Decisions\n\n' +
+  '> Append-only decision journal — every decision the kit captured, in order, with its why.\n' +
+  '> Maintained by claude-memory-kit (`cmk digest`). Superseded/retracted entries stay (the trail is the point).';
+
+// Only this fact type is a "decision" in the kit taxonomy (the project/state
+// category — what project-memory's decisions.md and our DECISION-LOG track).
+const DECISION_TYPE = 'project';
+
+const markerFor = (id) => `<!-- decision:${id} -->`;
+const RETRACT_TAG = '_(retracted';
+
+/** The yyyy-mm-dd slice of an ISO timestamp, or the raw value if unparseable. */
+function dateOnly(iso) {
+  if (typeof iso !== 'string') return 'unknown-date';
+  const m = iso.match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : iso;
+}
+
+/**
+ * Render ONE journal entry for a decision fact. The machine marker lets the
+ * updater dedup + annotate; the human-readable lines are Title / date / Why / id.
+ *
+ * @param {{id:string,title:string,createdAt?:string,why?:string|null}} f
+ * @returns {string} the entry block (no trailing newline)
+ */
+export function buildDecisionEntry(f) {
+  const date = dateOnly(f.createdAt);
+  const lines = [
+    markerFor(f.id),
+    `### ${f.title}`,
+    `**When:** ${date} · **Fact:** \`${f.id}\``,
+  ];
+  if (f.why && String(f.why).trim()) {
+    lines.push(`**Why:** ${String(f.why).trim()}`);
+  }
+  return lines.join('\n');
+}
+
+// The kit's id matcher, DERIVED from the canonical ID_PATTERN (tier-paths.mjs)
+// so the base32 alphabet lives in exactly ONE place and can't drift. The
+// original bug: this module hardcoded `[A-Z2-9]` (uppercase only), but the real
+// alphabet includes a lowercase `a` — so any id containing `a` never matched
+// "already journaled" → re-appended on EVERY digest run (the cut-gate find).
+// Strip the `^…$` anchors to embed the pattern inside larger regexes.
+const ID_CHARS = ID_PATTERN.source.replace(/^\^/, '').replace(/\$$/, '');
+
+/** ids already present in the journal body (by their machine marker). */
+function journaledIds(content) {
+  const ids = new Set();
+  const re = new RegExp(`<!-- decision:(${ID_CHARS}) -->`, 'g');
+  let m;
+  while ((m = re.exec(content)) !== null) ids.add(m[1]);
+  return ids;
+}
+
+/**
+ * Append-only journal update (D-161). Pure: content in → content out.
+ *
+ * @param {object} a
+ * @param {string}   a.existingContent  current DECISIONS.md (‘’ if absent)
+ * @param {Array}    a.facts            live decision-class facts ({id,type,title,createdAt,why})
+ * @param {Set<string>} a.tombstonedIds ids whose fact has been forgotten
+ * @param {string}   a.now             ISO timestamp for retraction stamps
+ * @returns {string} the new DECISIONS.md content
+ */
+export function updateDecisionsJournal({ existingContent = '', facts = [], tombstonedIds = new Set(), now }) {
+  let content = existingContent.trim() === '' ? DECISIONS_HEADER + '\n' : existingContent;
+  const already = journaledIds(content);
+
+  // 1) Append entries for decision-class facts not yet journaled.
+  const newEntries = [];
+  for (const f of facts) {
+    if (f.type !== DECISION_TYPE) continue; // only decisions
+    if (already.has(f.id)) continue; // already journaled — never duplicate
+    newEntries.push(buildDecisionEntry(f));
+    already.add(f.id);
+  }
+  if (newEntries.length > 0) {
+    if (!content.endsWith('\n')) content += '\n';
+    content += '\n' + newEntries.join('\n\n') + '\n';
+  }
+
+  // 2) Mark retracted (in place) any journaled entry whose fact is now
+  //    tombstoned and not already marked. Never removes the entry.
+  const stamp = dateOnly(now);
+  for (const id of tombstonedIds) {
+    const marker = markerFor(id);
+    const idx = content.indexOf(marker);
+    if (idx === -1) continue; // not journaled — nothing to retract
+    // Bound the search to THIS entry's span — up to the next decision marker
+    // (or end-of-file). Prevents a malformed/hand-edited entry with no heading
+    // from attaching the retraction note to the NEXT entry's heading.
+    const nextMarker = content.indexOf('<!-- decision:', idx + marker.length);
+    const spanEnd = nextMarker === -1 ? content.length : nextMarker;
+    // Find this entry's heading line (the `### …` after the marker, within span).
+    const headingStart = content.indexOf('### ', idx);
+    if (headingStart === -1 || headingStart >= spanEnd) continue;
+    const headingEnd = content.indexOf('\n', headingStart);
+    if (headingEnd === -1) continue;
+    // Already retracted? (the note sits right after the heading)
+    const afterHeading = content.slice(headingEnd + 1, headingEnd + 1 + RETRACT_TAG.length);
+    if (afterHeading === RETRACT_TAG) continue;
+    const note = `${RETRACT_TAG} ${stamp})_`;
+    content = content.slice(0, headingEnd + 1) + note + '\n' + content.slice(headingEnd + 1);
+  }
+
+  if (!content.endsWith('\n')) content += '\n';
+  return content;
+}
+
+// --- File-IO orchestration (the impure shell over the pure core) ----------
+
+// Leading indent is [ \t]* (NOT \s*) so it can't match the newline the
+// (?:^|\n) anchor already consumed — that overlap is the backtracking
+// ambiguity SonarCloud flags as ReDoS. Disjoint character classes = linear.
+const RICH_WHY_RE = /(?:^|\n)[ \t]*\*\*Why:\*\*[ \t]*([^\n]+)/;
+
+/** Read decision-class facts (type:project) from the project tier. */
+function readProjectDecisionFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter, body } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.type !== DECISION_TYPE) continue;
+      if (frontmatter.deleted_at) continue;
+      const whyMatch = String(body ?? '').match(RICH_WHY_RE);
+      out.push({
+        id: frontmatter.id,
+        type: frontmatter.type,
+        title: frontmatter.title ?? frontmatter.id,
+        createdAt: frontmatter.created_at ?? null,
+        why: whyMatch ? whyMatch[1].trim() : null,
+      });
+    } catch {
+      // unparseable file — reindex/HC-4 own that class; the journal skips it
+    }
+  }
+  // Stable chronological order (oldest first) so appends read like a timeline.
+  out.sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+  return out;
+}
+
+/** ids of forgotten facts (tombstone archive). */
+function readTombstonedIds(projectRoot) {
+  const ids = new Set();
+  const dir = join(projectRoot, 'context', 'memory', 'archive', 'tombstones');
+  if (!existsSync(dir)) return ids;
+  for (const name of readdirSync(dir)) {
+    const m = name.match(new RegExp(`^(${ID_CHARS})\\.md$`));
+    if (m) ids.add(m[1]);
+  }
+  return ids;
+}
+
+/**
+ * Read → append-only update → write context/DECISIONS.md. Idempotent: a run
+ * with nothing new is a no-op write (same bytes). Best-effort: never throws
+ * into the caller (a journal failure must not break a capture/read path).
+ *
+ * @returns {{written:boolean, path:string, appended:number}|{written:false,error:string}}
+ */
+export function syncDecisionsJournal({ projectRoot, now } = {}) {
+  try {
+    const path = join(projectRoot, 'context', 'DECISIONS.md');
+    const existingContent = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const facts = readProjectDecisionFacts(projectRoot);
+    const tombstonedIds = readTombstonedIds(projectRoot);
+    const before = existingContent;
+    const next = updateDecisionsJournal({
+      existingContent,
+      facts,
+      tombstonedIds,
+      now: now ?? new Date().toISOString(),
+    });
+    if (next !== before) {
+      writeFileSync(path, next, 'utf8');
+      return { written: true, path, appended: next.length - before.length };
+    }
+    return { written: false, path, appended: 0 };
+  } catch (err) {
+    return { written: false, error: err?.message ?? String(err) };
+  }
+}

package/src/digest.mjs

@@ -0,0 +1,89 @@
+// `cmk digest` — a regenerated, readable render of everything the kit currently
+// knows (Task 147, D-132). Facts by type + the persona + active threads, as one
+// markdown page. The README-demo artifact.
+//
+// REGENERATED (not append-only): unlike DECISIONS.md (the permanent journal),
+// the digest is a CURRENT-KNOWLEDGE snapshot — it should reflect only what
+// exists now, so it is rebuilt on every invocation (the INDEX.md lifecycle,
+// correct here). The two surfaces differ on purpose: digest = "what do we know
+// now", DECISIONS.md = "what did we decide over time" (D-161).
+//
+// Read-only by contract: pure reads over the fact archive + scratchpads. The
+// `--decisions` flag also triggers the DECISIONS.md journal sync (the one
+// mutation, delegated to the append-only writer).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
+
+const TYPE_ORDER = ['project', 'feedback', 'reference', 'user'];
+const TYPE_LABEL = {
+  project: 'Decisions & project state',
+  feedback: 'Working-style & preferences',
+  reference: 'References',
+  user: 'About the user',
+};
+
+function readFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const facts = [];
+  if (!existsSync(dir)) return facts;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.deleted_at) continue;
+      facts.push({
+        id: frontmatter.id,
+        type: frontmatter.type ?? 'unknown',
+        title: frontmatter.title ?? frontmatter.id,
+        trust: frontmatter.trust ?? 'unknown',
+        createdAt: frontmatter.created_at ?? null,
+      });
+    } catch {
+      // unparseable — reindex/HC-4 own that class
+    }
+  }
+  return facts;
+}
+
+/**
+ * Build the digest markdown from facts (pure — exported for testing).
+ * @param {Array} facts
+ * @param {{now?:string}} [opts]
+ */
+export function buildDigest(facts, { now } = {}) {
+  const stamp = (now ?? new Date().toISOString()).slice(0, 10);
+  const lines = [`# Memory digest — ${stamp}`, ''];
+  if (facts.length === 0) {
+    lines.push('_Memory is empty — capture starts as you work._', '');
+    return lines.join('\n');
+  }
+  lines.push(`${facts.length} fact(s) in project memory.`, '');
+
+  const byType = new Map();
+  for (const f of facts) {
+    if (!byType.has(f.type)) byType.set(f.type, []);
+    byType.get(f.type).push(f);
+  }
+  const orderedTypes = [
+    ...TYPE_ORDER.filter((t) => byType.has(t)),
+    ...[...byType.keys()].filter((t) => !TYPE_ORDER.includes(t)),
+  ];
+  for (const type of orderedTypes) {
+    const group = byType.get(type).slice().sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    lines.push(`## ${TYPE_LABEL[type] ?? type} (${group.length})`, '');
+    for (const f of group) {
+      const date = String(f.createdAt ?? '').slice(0, 10) || '—';
+      lines.push(`- **${f.title}** · \`${f.id}\` · ${f.trust} · ${date}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/** Read facts + render the digest for a project (read-only). */
+export function digest({ projectRoot, now } = {}) {
+  const facts = readFacts(projectRoot);
+  return buildDigest(facts, { now });
+}

package/src/forget.mjs

@@ -172,6 +172,12 @@ function scrubAllScratchpads(tierRoot, id) {
     if (!entry.isFile()) continue;
     if (!entry.name.endsWith('.md')) continue;
     if (entry.name === 'INDEX.md') continue;
+    // DECISIONS.md is the APPEND-ONLY decision journal (Task 147 / D-161), NOT
+    // a scratchpad — forget must NOT strip its id-bearing lines (the marker +
+    // **Fact:** line). The journal sync marks the entry RETRACTED in place
+    // instead (preserving the trail). Scrubbing it here would delete the
+    // entry's marker and break the retract-in-place path (composition bug).
+    if (entry.name === 'DECISIONS.md') continue;
     const p = join(tierRoot, entry.name);
     const r = scrubScratchpadFile(p, id);
     if (r.changed) edits.push({ path: p, removed: r.removed });

package/src/search.mjs

@@ -136,6 +136,109 @@ function validateInput(opts) {
   return { errors, mode, scope };
 }
 
+// --- FTS5 query sanitization (Task 153) -------------------------------
+//
+// FTS5's MATCH grammar (sqlite.org/fts5 §3) treats many characters a user
+// would type in a natural query as operators or syntax errors:
+//   - a bareword may ONLY contain letters / digits / underscore / non-ASCII;
+//     a `.`, `-`, `:`, `+`, `^`, `(`, etc. in a bareword is a SYNTAX ERROR.
+//   - `AND` / `OR` / `NOT` (case-sensitive) are reserved boolean operators.
+// So `cmk search v0.3` crashed (`v0` then `.3` → `.` violates the bareword
+// grammar), and `cmk search user-explicit` parsed `-` as a column-exclude.
+//
+// The SQLite-sanctioned fix is to double-quote the offending token: inside a
+// quoted string the tokenizer treats `.`/`-`/`:` as separators, so `"v0.3"`
+// tokenizes to `v0` + `3` and matches the literal content. We quote
+// PER-TOKEN (not the whole query) so a plain multi-word query keeps its
+// implicit-AND semantics (better recall) rather than collapsing to a strict
+// adjacency phrase. A token the user already quoted is left untouched.
+//
+// Validated against the FTS5 spec AND basic-memory's real implementation
+// (the kit's closest FTS5 + markdown-native design analog). Full rationale:
+// docs/research/2026-06-15-fts5-query-preparation-cross-system.md.
+
+// A bareword that FTS5 accepts as-is: letters, digits, underscore, non-ASCII.
+// Anything else in the token means it must be quoted to be a literal.
+const FTS5_BAREWORD_RE = /^[\p{L}\p{N}_]+$/u;
+const FTS5_RESERVED_WORDS = new Set(['AND', 'OR', 'NOT']);
+
+// Quote a single token for literal FTS5 matching, escaping embedded `"`
+// SQL-style (double it) per the spec. Used only when the token isn't a safe
+// bareword.
+function quoteFtsToken(token) {
+  return `"${token.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Transform a raw user query into an FTS5-safe MATCH string.
+ *
+ * Per-token: a safe bareword passes through untouched (preserving
+ * implicit-AND between words); a token with FTS5-special characters or a
+ * bare reserved word (AND/OR/NOT) is double-quoted (literal). A token the
+ * user already wrapped in `"…"` is preserved verbatim — explicit phrase
+ * search still works for power users.
+ *
+ * Exported for isolated unit testing (like reciprocalRankFusion).
+ *
+ * @param {string} raw the user's query
+ * @returns {string} an FTS5-safe MATCH expression ('' for empty input)
+ */
+export function prepareFtsQuery(raw) {
+  if (typeof raw !== 'string') return '';
+  const trimmed = raw.trim();
+  if (trimmed === '') return '';
+
+  return tokenizeQuery(trimmed)
+    .map((token) => {
+      // Already a user-quoted phrase (`"…"`, possibly multi-word): leave it
+      // exactly as typed — explicit phrase search still works for power users.
+      if (token.length >= 2 && token.startsWith('"') && token.endsWith('"')) {
+        return token;
+      }
+      // Safe bareword that isn't a reserved operator: pass through.
+      if (FTS5_BAREWORD_RE.test(token) && !FTS5_RESERVED_WORDS.has(token)) {
+        return token;
+      }
+      // Everything else (special chars, or a bare AND/OR/NOT): quote literal.
+      return quoteFtsToken(token);
+    })
+    .join(' ');
+}
+
+// Split a query into tokens, keeping a double-quoted span (which may contain
+// spaces, e.g. `"thin routes"`) as ONE token. A naive whitespace split would
+// tear `"thin routes"` into `"thin` + `routes"` and corrupt the quoting.
+// Unbalanced trailing quote: the final quoted run extends to end-of-string.
+function tokenizeQuery(query) {
+  const tokens = [];
+  let i = 0;
+  while (i < query.length) {
+    if (/\s/.test(query[i])) {
+      i += 1;
+      continue;
+    }
+    if (query[i] === '"') {
+      // A `"` at a token boundary opens a phrase span: consume up to and
+      // including the closing quote (or end-of-string if unbalanced).
+      let j = i + 1;
+      while (j < query.length && query[j] !== '"') j += 1;
+      const end = j < query.length ? j + 1 : query.length;
+      tokens.push(query.slice(i, end));
+      i = end;
+    } else {
+      // A run of non-space characters. A `"` that appears MID-run (e.g.
+      // `he"llo`) is part of this token, NOT a phrase delimiter — it'll be
+      // escaped + quoted as a literal by prepareFtsQuery. Only whitespace
+      // ends the run.
+      let j = i;
+      while (j < query.length && !/\s/.test(query[j])) j += 1;
+      tokens.push(query.slice(i, j));
+      i = j;
+    }
+  }
+  return tokens;
+}
+
 // --- Keyword (FTS5 BM25) backend --------------------------------------
 
 const KEYWORD_BASE_SQL = `
@@ -158,7 +261,7 @@ WHERE observations_fts MATCH @query
 
 function buildKeywordSql(opts) {
   const clauses = [];
-  const params = { query: opts.query };
+  const params = { query: prepareFtsQuery(opts.query) };
   if (opts.tier !== undefined) {
     clauses.push('o.tier = @tier');
     params.tier = opts.tier;
@@ -265,7 +368,7 @@ function runTranscriptKeywordSearch(db, opts) {
   try {
     rows = db
       .prepare(TRANSCRIPT_KEYWORD_SQL)
-      .all({ query: opts.query, limit: opts.limit ?? DEFAULT_LIMIT });
+      .all({ query: prepareFtsQuery(opts.query), limit: opts.limit ?? DEFAULT_LIMIT });
   } catch (err) {
     if (err?.code === 'SQLITE_ERROR' || /fts5:|no such column:/i.test(err?.message ?? '')) {
       throw new FTS5ParseError(err, opts.query);

package/src/subcommands.mjs

@@ -869,6 +869,32 @@ function runReindex(options /* , command */) {
   }
 }
 
+/**
+ * `cmk digest` (Task 147) — print a regenerated, readable render of everything
+ * the kit currently knows, AND sync the append-only context/DECISIONS.md
+ * journal (the permanent decision ledger; D-161). The digest goes to stdout;
+ * the journal is a committed file the sync maintains in place.
+ */
+async function runDigestCli(options) {
+  const projectRoot = resolvePath(process.cwd());
+  const { digest } = await import('./digest.mjs');
+  const { syncDecisionsJournal } = await import('./decisions-journal.mjs');
+
+  // Keep the permanent decision journal current (append-only; best-effort —
+  // a journal hiccup must not break the digest render).
+  const sync = syncDecisionsJournal({ projectRoot });
+
+  console.log(digest({ projectRoot }));
+
+  if (sync.written) {
+    console.log(`\ncontext/DECISIONS.md updated (+${sync.appended} bytes) — the append-only decision journal.`);
+  } else if (sync.error) {
+    console.error(`\n(decision journal not updated: ${sync.error})`);
+  } else {
+    console.log('\ncontext/DECISIONS.md is up to date.');
+  }
+}
+
 /**
  * `cmk forget <id-or-query>` — wired in Task 9. Tombstones the matching
  * fact (moves it to <tier>/<memory|fragments>/archive/tombstones/<id>.md
@@ -2019,6 +2045,12 @@ export const subcommands = [
     milestone: 37,
     action: runDoctorCli,
   },
+  {
+    name: 'digest',
+    description: 'print a readable digest of everything in memory + sync the append-only DECISIONS.md decision journal',
+    milestone: 147,
+    action: runDigestCli,
+  },
   {
     name: 'config',
     description: 'read/write kit settings (context/settings.json) without hand-editing JSON',