@lh8ppl/claude-memory-kit 0.2.4 → 0.3.0

package/src/subcommands.mjs

@@ -17,6 +17,7 @@ import { install as installAction, initUserTier as initUserTierAction } from './
 import { removeClaudeMdBlock } from './claude-md.mjs';
 import { reindex as reindexAction } from './reindex.mjs';
 import { openIndexDb } from './index-db.mjs';
+import { resolveDefaultSearchMode } from './semantic-backend.mjs';
 import { reindexBoot, reindexFull } from './index-rebuild.mjs';
 import { search as searchAction, SEARCH_MODES } from './search.mjs';
 import { memoryWrite } from './memory-write.mjs';
@@ -63,6 +64,32 @@ import { resolve as resolvePath, join, basename } from 'node:path';
 
 const NOTICE_PREFIX = 'not yet implemented';
 
+/**
+ * The install summary line for the Task-46 semantic outcome (Task 125.4:
+ * pure + exported so the branches are testable without running install).
+ * Returns null when there is nothing to print: an `error` action already
+ * surfaces through result.errors, and the opt-in tip is suppressed under
+ * --no-hooks (scaffold-only installs).
+ */
+export function formatSemanticSummary(semantic, { noHooks = false } = {}) {
+  if (semantic?.action === 'enabled') {
+    const w = semantic.warmed;
+    return (
+      '  Semantic recall ENABLED — `cmk search` now defaults to hybrid here.' +
+      (w?.ok
+        ? ` Model cached (${Math.round(w.ms / 1000)}s).`
+        : ' Model downloads on first search.')
+    );
+  }
+  if (semantic?.action === 'disabled') {
+    return '  Semantic recall pinned OFF for this project (search.default_mode=keyword).';
+  }
+  if (semantic?.action === 'skipped' && !noHooks) {
+    return '  Tip: `cmk install --with-semantic` adds local semantic recall (ask in your own words; one-time ~260 MB, no API calls).';
+  }
+  return null;
+}
+
 /**
  * Real `cmk install` action — wired in Task 3, extended in Task 4 with
  * --force passed through to the CLAUDE.md downgrade guard. Reads CLI
@@ -74,7 +101,16 @@ async function runInstall(options /* , command */) {
   // commander maps `--no-hooks` to options.hooks === false.
   const noHooks = !!(options && options.hooks === false);
   const verbose = !!(options && options.verbose);
-  const result = await installAction({ force: !!(options && options.force), noHooks });
+  const result = await installAction({
+    force: !!(options && options.force),
+    noHooks,
+    // Task 46: two flags, 3-state semantics (enable / pin-off / untouched).
+    // commander maps `--no-semantic` to options.semantic === false (the
+    // same negation pattern as --no-hooks above); `--with-semantic` maps
+    // to options.withSemantic.
+    withSemantic: !!(options && options.withSemantic),
+    noSemantic: !!(options && options.semantic === false),
+  });
 
   // Outcome over inventory (self-test UX finding): state the resulting state +
   // next action, not a file tally. The old "scaffolded 5, skipped 4 existing"
@@ -112,6 +148,11 @@ async function runInstall(options /* , command */) {
   // opted out, so we don't nag).
   const nativeNote = nativeMemoryInstallNote(result.projectRoot);
   if (nativeNote) console.log(nativeNote);
+  // Task 46: semantic-recall outcome (pure formatter, Task 125.4 — testable
+  // without spawning install; the error case returns null because enableSemantic
+  // errors already land in result.errors and print through the error path).
+  const semanticLine = formatSemanticSummary(result.semantic, { noHooks });
+  if (semanticLine) console.log(semanticLine);
   if (verbose) {
     console.log(
       `  files: ${result.created.length} created, ${result.skipped.length} already present` +
@@ -251,8 +292,9 @@ function runLessonsPromote(id, options = {}) {
  *
  * The keyword backend (FTS5 BM25 over the observations index) always
  * ships. Semantic + hybrid modes require the Layer-5b semantic backend,
- * which is not yet shipped; both error with exit code 2 and a clear
- * "not yet shipped" hint per tasks.md 30.2. The `semanticBackend` DI seam
+ * (Task 65: prepared automatically when the optional embedder is installed;
+ * absent embedder errors with exit code 2 + an install hint, per the 30.2
+ * contract). The `semanticBackend` DI seam
  * is the drop-in point for the future backend.
  *
  * Filter flags (per tasks.md 30.4):
@@ -263,7 +305,7 @@ function runLessonsPromote(id, options = {}) {
  *   --limit <N>                        (default 20)
  *   --include-tombstoned               (default false)
  */
-function runSearch(queryParts, options) {
+async function runSearch(queryParts, options) {
   const projectRoot = resolvePath(process.cwd());
   const userDir =
     process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
@@ -287,15 +329,51 @@ function runSearch(queryParts, options) {
           'searching the existing index. Run `cmk reindex --full` if results look stale.',
       );
     }
+    // Task 65: semantic/hybrid prepare the REAL embedded backend (async —
+    // search() itself stays sync; the seam gets a sync closure over the
+    // pre-embedded query vector). Task 46: an explicit --mode wins;
+    // otherwise the project's configured default (context/settings.json
+    // search.default_mode, set by `cmk install --with-semantic`), falling
+    // back to keyword. Explicit-but-unavailable → exit 2 + hint (the 30.2
+    // contract); configured-but-unavailable → graceful keyword fallback
+    // (the default must never break every search).
+    const explicitMode = options?.mode;
+    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).
+    const scope = options?.scope ?? 'facts';
+    let semanticBackend;
+    if (mode === SEARCH_MODES.SEMANTIC || mode === SEARCH_MODES.HYBRID) {
+      const { prepareSemanticBackend } = await import('./semantic-backend.mjs');
+      const prep = await prepareSemanticBackend({ db, query, scope });
+      if (!prep.ok && explicitMode) {
+        console.error(
+          `cmk search: semantic backend unavailable (${prep.reason}).` +
+            (prep.hint ? `\n  ${prep.hint}` : ' Use --mode=keyword.'),
+        );
+        process.exitCode = 2;
+        return;
+      }
+      if (!prep.ok) {
+        console.error(
+          `cmk search: semantic default unavailable (${prep.reason}) — falling back to keyword.`,
+        );
+        mode = SEARCH_MODES.KEYWORD;
+      } else {
+        semanticBackend = prep.backend;
+      }
+    }
     const r = searchAction({
       db,
       query,
-      mode: options?.mode ?? SEARCH_MODES.KEYWORD,
+      mode,
+      scope,
       minTrust: options?.minTrust,
       tier: options?.tier,
       since: options?.since,
       limit: options?.limit !== undefined ? Number(options.limit) : undefined,
       includeTombstoned: options?.includeTombstoned === true,
+      semanticBackend,
     });
     if (r.action === 'error') {
       for (const e of r.errors) console.error(`cmk search: ${e}`);
@@ -311,13 +389,15 @@ 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.
+      // 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';
       console.log(
-        `${hit.id}\t${hit.tier}/${hit.trust}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
+        `${hit.id}\t${provenance}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
       );
     }
     console.log(
-      `\ncmk search: ${r.results.length} result(s) (mode=${r.mode})`,
+      `\ncmk search: ${r.results.length} result(s) (mode=${r.mode}${r.scope && r.scope !== 'facts' ? `, scope=${r.scope}` : ''})`,
     );
   } finally {
     db.close();
@@ -1611,6 +1691,8 @@ export const subcommands = [
     optionSpec: [
       { flags: '--force', description: 'allow downgrade of an existing newer-version CLAUDE.md block' },
       { flags: '--no-hooks', description: 'scaffold only; do NOT wire hooks into .claude/settings.json' },
+      { flags: '--with-semantic', description: 'enable semantic recall: install the local embedder (~260 MB once), default search to hybrid, pre-warm the model' },
+      { flags: '--no-semantic', description: 'pin keyword-only search for this project (writes search.default_mode=keyword)' },
       { flags: '--verbose', description: 'show the per-tier created/skipped file breakdown' },
     ],
     action: runInstall,
@@ -1653,7 +1735,8 @@ export const subcommands = [
     milestone: 30,
     argSpec: [{ flags: '<query...>', description: 'query terms' }],
     optionSpec: [
-      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic + hybrid need the Layer-5b semantic backend, not yet shipped)' },
+      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic + hybrid use the embedded Layer-5b backend — needs the optional @huggingface/transformers embedder)' },
+      { flags: '--scope <scope>', description: 'facts | transcripts (default: facts — curated memory; transcripts = the raw session record, the last-resort recall tier)' },
       { flags: '--min-trust <level>', description: 'low | medium | high' },
       { flags: '--tier <tier>', description: 'U | P | L (filter to a single tier)' },
       { flags: '--since <date>', description: 'ISO date — exclude observations older than this' },
@@ -1737,13 +1820,6 @@ export const subcommands = [
     ],
     action: stub('config', 'v0.1.x'),
   },
-  {
-    name: 'view',
-    description: 'open a local markdown viewer at 127.0.0.1:37778',
-    milestone: 'v0.1.x',
-    optionSpec: [{ flags: '--port <n>', description: 'override default port 37778' }],
-    action: stub('view', 'v0.1.x'),
-  },
   {
     name: 'import-anthropic-memory',
     description: "merge useful bullets from Anthropic's auto-memory into this project's MEMORY.md",

package/src/transcript-index.mjs

@@ -0,0 +1,162 @@
+// Task 104.2 (D-117) — transcript chunking + index sync: the SEARCH half of
+// the L3 raw tier (the capture half shipped in 104.1). Transcript files
+// (context/transcripts/{date}.md — dialogue + per-turn Tools blocks) are
+// chunked by `## ` turn headings and windowed to ≤1500 chars (the memsearch
+// chunking rule Task 65 adopted), then synced into the SEPARATE
+// transcript_chunks table (index-db.mjs) so `cmk search --scope transcripts`
+// reaches them WITHOUT polluting L1 fact results (the MemPalace last-resort
+// contract, D-70/D-72).
+//
+// Sync strategy mirrors the observation indexer: per-file mtime/sha1 rows in
+// the shared `files` table (keyed with a 'transcript:' prefix so they never
+// collide with observation sources) → unchanged files cost one stat.
+//
+// Public boundary:
+//   chunkTranscript(text) → [{heading, body, sourceLine, chunkIdx}]  (pure)
+//   syncTranscriptChunks({db, projectRoot, now?}) → {files, chunks}
+
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CHUNK_MAX_CHARS = 1500; // the Task-65 / memsearch chunking rule
+const FILES_KEY_PREFIX = 'transcript:';
+
+export function chunkTranscript(text) {
+  if (typeof text !== 'string' || text.trim() === '') return [];
+  const lines = text.split(/\r?\n/);
+  // Locate turn headings (`## <ts> — speaker`, the capture-prompt/-turn shape).
+  const headings = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) headings.push(i);
+  }
+  if (headings.length === 0) return [];
+
+  const chunks = [];
+  let chunkIdx = 0;
+  for (let h = 0; h < headings.length; h++) {
+    const start = headings[h];
+    const end = h + 1 < headings.length ? headings[h + 1] : lines.length;
+    const heading = lines[start].trim();
+    const body = lines
+      .slice(start + 1, end)
+      .join('\n')
+      .trim();
+    if (body === '') continue;
+    // Window oversized turns; every window keeps its turn heading so a hit
+    // is always attributable to a specific turn.
+    for (let off = 0; off < body.length; off += CHUNK_MAX_CHARS) {
+      chunks.push({
+        heading,
+        body: body.slice(off, off + CHUNK_MAX_CHARS),
+        sourceLine: start + 1, // 1-based heading line — the drill-back anchor
+        chunkIdx: chunkIdx++,
+      });
+    }
+  }
+  return chunks;
+}
+
+function sha1(text) {
+  return createHash('sha1').update(text, 'utf8').digest('hex');
+}
+
+// Task 126 (D-119) — the raw-tier scope covers BOTH halves of the session
+// record: verbatim transcripts AND the Haiku-compressed sessions summaries
+// (today-*.md / recent.md / archive.md — the middle tier that was otherwise
+// a recall blind spot: discussed-but-never-graduated content). Exclusions:
+// now.md (the volatile live buffer — already in context, and its constant
+// truncation would churn the index) and non-.md observability files.
+const RAW_TIER_DIRS = ['transcripts', 'sessions'];
+const SESSIONS_EXCLUDE = new Set(['now.md']);
+
+export function syncTranscriptChunks({ db, projectRoot, now = Date.now() } = {}) {
+  let files = 0;
+  let chunks = 0;
+
+  const entries = []; // {abs, sourceFile}
+  for (const sub of RAW_TIER_DIRS) {
+    const dir = join(projectRoot, 'context', sub);
+    if (!existsSync(dir)) continue;
+    let names;
+    try {
+      names = readdirSync(dir).filter(
+        (n) => n.endsWith('.md') && !(sub === 'sessions' && SESSIONS_EXCLUDE.has(n)),
+      );
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      entries.push({ abs: join(dir, name), sourceFile: `context/${sub}/${name}` });
+    }
+  }
+
+  const getFileRow = db.prepare('SELECT mtime, sha1 FROM files WHERE path = ?');
+  const upsertFileRow = db.prepare(
+    'INSERT INTO files (path, mtime, sha1, indexed_at) VALUES (?, ?, ?, ?) ' +
+      'ON CONFLICT(path) DO UPDATE SET mtime = excluded.mtime, sha1 = excluded.sha1, indexed_at = excluded.indexed_at',
+  );
+  const deleteChunks = db.prepare('DELETE FROM transcript_chunks WHERE source_file = ?');
+  const insertChunk = db.prepare(
+    'INSERT INTO transcript_chunks (source_file, chunk_idx, source_line, heading, body) VALUES (?, ?, ?, ?, ?)',
+  );
+
+  for (const { abs, sourceFile } of entries) {
+    const filesKey = FILES_KEY_PREFIX + sourceFile;
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    const prev = getFileRow.get(filesKey);
+    // NO mtime fast-path: two appends inside the filesystem's mtime
+    // resolution would make the second invisible (caught as a flaky test —
+    // rapid Stop hooks are the same shape in production). sha1 is the
+    // authority; day-files are small and reindex reads its other sources
+    // anyway, so the read cost is negligible.
+    let text;
+    try {
+      text = readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const digest = sha1(text);
+    if (prev && prev.sha1 === digest) {
+      continue; // content unchanged
+    }
+
+    const parsed = chunkTranscript(text);
+    const replaceFile = db.transaction(() => {
+      deleteChunks.run(sourceFile);
+      for (const c of parsed) {
+        insertChunk.run(sourceFile, c.chunkIdx, c.sourceLine, c.heading, c.body);
+      }
+      upsertFileRow.run(filesKey, Math.trunc(st.mtimeMs), digest, now);
+    });
+    replaceFile();
+    files += 1;
+    chunks += parsed.length;
+  }
+
+  // Orphan-prune for THIS scope: a deleted/rotated file (transcripts OR
+  // sessions — weekly-curate rotates today-*.md into archive.md) leaves its
+  // chunks + checkpoint behind otherwise. The observation indexer's prune
+  // deliberately skips 'transcript:' rows (they are not observation sources)
+  // — pruning them is this function's job, scoped by the key prefix.
+  const live = new Set(entries.map((e) => FILES_KEY_PREFIX + e.sourceFile));
+  const known = db
+    .prepare("SELECT path FROM files WHERE path LIKE ?")
+    .all(FILES_KEY_PREFIX + '%');
+  const pruneTxn = db.transaction((filesKey) => {
+    db.prepare('DELETE FROM transcript_chunks WHERE source_file = ?').run(
+      filesKey.slice(FILES_KEY_PREFIX.length),
+    );
+    db.prepare('DELETE FROM files WHERE path = ?').run(filesKey);
+  });
+  for (const { path } of known) {
+    if (!live.has(path)) pruneTxn(path);
+  }
+
+  return { files, chunks };
+}

package/src/turn-tools.mjs

@@ -0,0 +1,179 @@
+// Task 104.1 — extract the CURRENT turn's tool activity from Anthropic's
+// session JSONL (the Stop payload's `transcript_path`) so capture-turn can
+// enrich the kit's own committed transcript (the L3 raw tier of the recall
+// waterfall, design §19 / D-117).
+//
+// Why read the live JSONL: it is the only record of tool calls + results
+// (the Stop payload itself carries only the assistant TEXT), and it expires
+// (~30 days, machine-local) — we extract the current turn into OUR format at
+// capture time; we never copy/snapshot the file (the user's 2026-06-06
+// directive: enriching our own transcript, not a JSONL crutch).
+//
+// The JSONL internal format is NOT a documented Anthropic contract (only
+// `transcript_path` is). Shapes below were verified EMPIRICALLY across 6
+// sessions / 4 projects (2026-06-10):
+//   - entries: {type: 'user'|'assistant'|<harness types to skip>, message?}
+//   - message.content: a block LIST or a plain STRING (both real)
+//   - blocks: text / thinking / tool_use {id,name,input} / tool_result
+//     {tool_use_id, content: STRING or LIST of {type:'text',text}}
+//   - tool_result blocks ride USER-role entries (API convention) — a user
+//     entry is a real prompt boundary ONLY if it has text and no tool_result.
+// Everything here is defensive: unrecognized shapes are skipped; any failure
+// returns null. A format shift degrades the enrichment, never the capture.
+//
+// Public boundary:
+//   extractTurnToolActivity(jsonlText) → string|null   (pure)
+//   readTranscriptTail(path, maxBytes?) → string        (bounded file read)
+
+import { openSync, readSync, closeSync, fstatSync } from 'node:fs';
+
+// Caps (git-bloat control, the D-117 sub-decision (a)): one turn's Tools
+// block stays a small fraction of a transcript day.
+const RESULT_SNIPPET_CHARS = 300;
+const INPUT_SUMMARY_CHARS = 160;
+const BLOCK_CAP_CHARS = 4000;
+// Tail bound: one turn comfortably fits; a mega-session file is never read whole.
+const DEFAULT_TAIL_BYTES = 768 * 1024;
+
+// The most informative input field per common tool; unknown tools fall back
+// to a compact JSON summary. Order matters — first present key wins.
+const REPRESENTATIVE_INPUT_KEYS = [
+  'command',
+  'file_path',
+  'pattern',
+  'query',
+  'url',
+  'path',
+  'prompt',
+];
+
+function oneLine(s, max) {
+  const flat = String(s).replace(/\s+/g, ' ').trim();
+  return flat.length > max ? flat.slice(0, max) + '…' : flat;
+}
+
+function summarizeInput(input) {
+  if (!input || typeof input !== 'object') return '';
+  for (const key of REPRESENTATIVE_INPUT_KEYS) {
+    if (typeof input[key] === 'string' && input[key].trim() !== '') {
+      return oneLine(input[key], INPUT_SUMMARY_CHARS);
+    }
+  }
+  try {
+    return oneLine(JSON.stringify(input), INPUT_SUMMARY_CHARS);
+  } catch {
+    return '';
+  }
+}
+
+function flattenResultContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => (b && typeof b === 'object' && typeof b.text === 'string' ? b.text : ''))
+      .filter(Boolean)
+      .join(' ');
+  }
+  return '';
+}
+
+function contentBlocks(message) {
+  const c = message?.content;
+  return Array.isArray(c) ? c.filter((b) => b && typeof b === 'object') : [];
+}
+
+// A user entry is a REAL prompt boundary when it carries prompt text (string
+// content or a text block) and no tool_result blocks (results ride user role).
+function isRealUserPrompt(entry) {
+  if (entry?.type !== 'user') return false;
+  const c = entry.message?.content;
+  if (typeof c === 'string') return c.trim() !== '';
+  const blocks = contentBlocks(entry.message);
+  if (blocks.some((b) => b.type === 'tool_result')) return false;
+  return blocks.some((b) => b.type === 'text' && typeof b.text === 'string' && b.text.trim() !== '');
+}
+
+export function extractTurnToolActivity(jsonlText) {
+  if (typeof jsonlText !== 'string' || jsonlText.trim() === '') return null;
+
+  const entries = [];
+  for (const raw of jsonlText.split('\n')) {
+    if (raw.trim() === '') continue;
+    try {
+      const e = JSON.parse(raw);
+      if (e && (e.type === 'user' || e.type === 'assistant')) entries.push(e);
+    } catch {
+      // partial first line of a tail read, or harness noise — skip
+    }
+  }
+  if (entries.length === 0) return null;
+
+  let lastPromptIdx = -1;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (isRealUserPrompt(entries[i])) {
+      lastPromptIdx = i;
+      break;
+    }
+  }
+  // No prompt boundary in the (tail) window → attribute everything we see to
+  // the current turn rather than dropping it (the tail bound already scopes us).
+  const turn = entries.slice(lastPromptIdx + 1);
+
+  const calls = []; // {id, name, summary, result}
+  const byId = new Map();
+  for (const e of turn) {
+    for (const b of contentBlocks(e.message)) {
+      if (b.type === 'tool_use' && typeof b.name === 'string') {
+        const call = { id: b.id, name: b.name, summary: summarizeInput(b.input), result: '' };
+        calls.push(call);
+        if (typeof b.id === 'string') byId.set(b.id, call);
+      } else if (b.type === 'tool_result') {
+        const call = typeof b.tool_use_id === 'string' ? byId.get(b.tool_use_id) : undefined;
+        if (call && !call.result) {
+          call.result = oneLine(flattenResultContent(b.content), RESULT_SNIPPET_CHARS);
+        }
+      }
+    }
+  }
+  if (calls.length === 0) return null;
+
+  const lines = [];
+  let used = 0;
+  let shown = 0;
+  for (const call of calls) {
+    const line = `- ${call.name}(${call.summary})${call.result ? ` → ${call.result}` : ''}`;
+    if (used + line.length + 1 > BLOCK_CAP_CHARS) break;
+    lines.push(line);
+    used += line.length + 1;
+    shown += 1;
+  }
+  if (shown < calls.length) {
+    lines.push(`- …${calls.length - shown} more tool call(s) truncated`);
+  }
+  return lines.join('\n');
+}
+
+// Bounded tail read — a turn comfortably fits in the window; a multi-MB
+// session file is never loaded whole inside the Stop hook's budget.
+export function readTranscriptTail(path, maxBytes = DEFAULT_TAIL_BYTES) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, start);
+    return buf.toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // best-effort close
+      }
+    }
+  }
+}

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

@@ -0,0 +1,86 @@
+---
+name: memory-search
+description: Searches the project's deep memory archive (claude-memory-kit) and returns a curated summary of relevant facts, decisions, and history. Use when the answer may already be recorded from a past session — "what did we decide about X", "why did we do Y", "have we seen this error before", "how did we solve this last time", "what's our convention for Z" — or before re-deriving any project knowledge, setup, or prior decision from the code. The session-start memory snapshot is a bounded hot index, not everything; this skill reaches the rest. Skip when the question is purely about current code state (use Read/Grep), about this conversation only, or the user asked to ignore memory.
+context: fork
+allowed-tools: mcp__cmk__mk_search mcp__cmk__mk_get mcp__cmk__mk_timeline mcp__cmk__mk_recent_activity Bash(cmk search *) Bash(cmk get *) Bash(cmk timeline *) Bash(cmk recent-activity *)
+---
+
+# Recalling from deep memory
+
+You are a memory-retrieval agent. Search the kit's memory archive for: $ARGUMENTS
+
+Query well: search the core noun phrases (e.g. "deploy target", "auth
+library decision"), not a full sentence. If the line above carries NO query
+(you run isolated and cannot see the conversation), start from the
+"When the query is vague" section below instead.
+
+Memory is the ground truth for documented knowledge and prior decisions
+(the injected-snapshot authority rule). Your job is to find what is already
+recorded and return ONLY a curated summary — never the raw dumps.
+
+## The 3-step ladder (filter before you fetch)
+
+Work index → context → bodies. Full bodies are ~10x the tokens of an index
+line; fetch them only for the ids that survived filtering.
+
+**Step 1 — Search the index.** Prefer the MCP tool when the `cmk` server is
+connected; otherwise the CLI:
+
+- MCP: `mk_search` with `query` (natural language is fine — when semantic
+  recall is enabled the project default searches by meaning; paraphrase hits).
+- CLI: `cmk search "<query>"`
+
+Each hit is one line: id, tier/trust, source location, snippet. Run 1-3
+query variants if the first misses (synonyms; the key noun alone). Drop
+hits that are clearly off-topic or too generic.
+
+**Step 2 — Context around an anchor (optional).** When a hit looks right
+but you need what happened around it (what led to a decision, what followed
+a fix):
+
+- MCP: `mk_timeline` with `anchor: "<id>"` (and `depth_before`/`depth_after`).
+- CLI: `cmk timeline <id>`
+
+**Step 3 — Fetch full bodies for the survivors only.**
+
+- MCP: `mk_get` with `ids: [...]` — batch all survivors in ONE call.
+- CLI: `cmk get <id> <id> ...`
+
+Rich facts carry **Why** / **How to apply** blocks — include those when the
+question is about rationale or how to act on a rule.
+
+**Step 4 — LAST RESORT: the session record.** Only when curated memory
+(steps 1-3) has no answer and the question is about what actually happened
+in a past session (an exact error message, the command that fixed
+something, how a discussion went). This scope covers the verbatim
+transcripts AND the compressed session summaries:
+
+- MCP: `mk_search` with `scope: "transcripts"`.
+- CLI: `cmk search "<query>" --scope transcripts`
+
+Hits are raw turn excerpts (dialogue + the tools the agent ran), keyed
+`T:<file>:<line>` — quote the relevant fragment in your summary; never dump
+whole turns. If something found here is durably useful, say so in the
+summary so the caller can capture it as a proper fact.
+
+## When the query is vague
+
+If you cannot form a concrete query, look at recent activity first, then
+search the topic that stands out:
+
+- MCP: `mk_recent_activity` (window `7d`) · CLI: `cmk recent-activity --window 7d`
+
+## Output
+
+Return a short, curated answer for the main conversation:
+
+- The relevant facts/decisions, each with its citation id (e.g. `P-XXXXXXXX`)
+  and the Why when it matters.
+- One line of source traceability per item (the source file the index line
+  showed).
+- If nothing relevant exists, say exactly that — "no recorded memory on
+  this" — so the caller knows to derive it fresh and capture it afterward.
+
+Never paste full fact files or long bodies into the summary; condense.
+This skill is read-only — capturing new facts is the `memory-write` skill's
+job.

package/template/CLAUDE.md.template

@@ -34,6 +34,8 @@ The snapshot injected at session start is a **bounded hot index, not everything*
 
 Reach for these *first* — re-deriving an answer the project already recorded (by re-reading files, re-searching, or working it out again) wastes the memory that exists precisely so you don't have to. Recall from memory first, then verify against the source if needed.
 
+**Authority rule:** when injected memory contradicts your assumptions, injected memory wins — it is the ground truth for documented knowledge and prior decisions (terminal/tool output stays the ground truth for live system state; official docs for version-specifics). Never treat a question as novel when the answer is already in your prompt.
+
 ### Memory write rules (for Claude)
 
 Most capture is automatic — the Stop hook extracts durable facts each turn, no action needed. To capture something **explicitly**, the **`memory-write` skill** carries the full procedure; it loads on demand when you save a fact. The invariants it enforces: