@lh8ppl/claude-memory-kit 0.3.1 → 0.3.3

package/src/session-end-tasks.mjs

@@ -35,6 +35,7 @@
 import { compressSession } from './compress-session.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { graduateAllScratchpads } from './graduate-session.mjs';
+import { syncDecisionsJournal } from './decisions-journal.mjs';
 
 /**
  * Run the two independent SessionEnd Haiku passes concurrently.
@@ -45,7 +46,7 @@ import { graduateAllScratchpads } from './graduate-session.mjs';
  * @param {() => object} opts.makeBackend - factory returning a fresh CompressorBackend
  *   per call (each concurrent pass gets its own instance — no shared state).
  * @param {string} [opts.now] - ISO timestamp override (tests).
- * @returns {Promise<{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult, graduationOutcome: PromiseSettledResult}>}
+ * @returns {Promise<{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult, graduationOutcome: PromiseSettledResult, journalOutcome: PromiseSettledResult}>}
  */
 export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, now }) {
   const [compressOutcome, personaOutcome] = await Promise.allSettled([
@@ -75,7 +76,30 @@ export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, no
     graduationOutcome = { status: 'rejected', reason: err };
   }
 
-  return { compressOutcome, personaOutcome, graduationOutcome };
+  // Task 159 (D-169): auto-sync the decision journal. This is what makes
+  // DECISIONS.md "automatic" (D-164) — Task 147 BUILT the append logic but wired
+  // it to ONLY the manual `cmk digest`, so the journal never populated on its own.
+  // Same shape as the graduation sweep: SEQUENTIAL, pure local file I/O (reads the
+  // type:project fact files auto-extract wrote per-turn → rewrites DECISIONS.md),
+  // no Haiku/network (~175ms), no hook-ceiling risk, wrapped so a throw can't reject
+  // the hook. DISJOINT from compress (sessions/ tree) + persona (user-tier) +
+  // graduation (persona scratchpads) — nothing else in the block touches DECISIONS.md,
+  // so no lock contention. Session-end is the natural "this session's decisions
+  // landed → render them" boundary (squad's session-end Scribe instinct, made
+  // deterministic — the kit's typed-fact substrate needs no LLM to merge).
+  // syncDecisionsJournal is already best-effort (its own try/catch returns
+  // {written:false,error}); the wrapper here guards the unexpected synchronous throw.
+  let journalOutcome;
+  try {
+    journalOutcome = {
+      status: 'fulfilled',
+      value: syncDecisionsJournal({ projectRoot, now }),
+    };
+  } catch (err) {
+    journalOutcome = { status: 'rejected', reason: err };
+  }
+
+  return { compressOutcome, personaOutcome, graduationOutcome, journalOutcome };
 }
 
 /**
@@ -86,7 +110,7 @@ export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, no
  * @param {{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult}} outcomes
  * @returns {string[]}
  */
-export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduationOutcome }) {
+export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduationOutcome, journalOutcome }) {
   const lines = [];
 
   if (compressOutcome.status === 'fulfilled') {
@@ -123,5 +147,18 @@ export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduatio
     }
   }
 
+  // journalOutcome is optional (Task 159) — pre-159 callers render no journal line.
+  if (journalOutcome) {
+    if (journalOutcome.status === 'fulfilled') {
+      const j = journalOutcome.value ?? {};
+      lines.push(
+        `cmk-compress-session: journal (written: ${j.written ?? false}, appended: ${j.appended ?? 0})\n`,
+      );
+    } else {
+      const e = journalOutcome.reason;
+      lines.push(`cmk-compress-session: journal sync failed: ${e?.message ?? e}\n`);
+    }
+  }
+
   return lines;
 }

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;
@@ -869,6 +897,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
@@ -1973,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,
   },
   {
@@ -2019,6 +2079,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',

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.