@lh8ppl/claude-memory-kit 0.2.4 → 0.3.1

package/src/inject-context.mjs

@@ -26,14 +26,19 @@ import {
   readdirSync,
   appendFileSync,
   statSync,
+  openSync,
+  readSync,
+  closeSync,
 } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { SCRATCHPADS_BY_TIER, resolveTierRoot } from './tier-paths.mjs';
+import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleness } from './lazy-compress.mjs';
 import { isProvenanceCommentLine, parseBulletProvenance } from './provenance.mjs';
+import { listConflictQueue } from './conflict-queue.mjs';
+import { listReviewQueue } from './review-queue.mjs';
 
 // Importance ranking for value-ordered inject eviction (Task 93 / design §19.3).
 // When a tier exceeds its budget we drop the LOWEST-value sections first, not the
@@ -61,6 +66,33 @@ function trustLabel(rank) {
 const DEFAULT_CAP_BYTES = 13_000;
 const HOOK_EVENT_NAME = 'SessionStart';
 
+// Task 75.0 (D-64 / memory-os Layer-07 "Ground Truth", D-73 near-verbatim):
+// injecting memory is insufficient — the agent must be TOLD the injected
+// context is authoritative, or it re-derives from code what the snapshot
+// already answers (the D-40 cold-open failure). This preamble leads every
+// non-empty snapshot. It is code-generated (not template-scaffolded) on
+// purpose: always present, never consolidated/evicted/graduated, and
+// existing installs pick it up on upgrade with no re-scaffold (avoids the
+// Task-73 stale-template class).
+//
+// §7.1 composition: the preamble + its 2 joining newlines must fit the
+// 725-byte slack between Σ TIER_BUDGETS (12,275) and DEFAULT_CAP_BYTES
+// (13,000) — worst case 12,275 + len + 2 ≤ 13,000, i.e. len ≤ 723. The
+// boundary test pins len ≤ 700. injectContext also subtracts the reserve
+// from the cap handed to enforceCap, so custom capBytes stay honored.
+export const AUTHORITATIVE_MEMORY_PREAMBLE = [
+  '# Injected memory — AUTHORITATIVE (claude-memory-kit)',
+  '',
+  'Ground-truth ranking: (1) terminal/tool output → live system state;',
+  '(2) THIS snapshot + `cmk search` → documented knowledge & prior decisions;',
+  '(3) official docs → version-specifics; (4) training knowledge → verify against 1-3.',
+  '',
+  'When injected memory contradicts your assumptions, injected memory wins.',
+  'Lead with memory — never re-derive from code what it already answers, and',
+  'never treat a question as novel when the answer is already in your prompt.',
+  'This snapshot is a bounded hot index; `cmk search "<topic>"` reaches the facts not shown here.',
+].join('\n');
+
 // Match any line containing a `(P-XXXXXXXX)`-shaped citation id. Looser
 // than ID_PATTERN on purpose — alphabet-validation is the writer's job;
 // here we just want to recognize "any line that LOOKS like it carries a
@@ -520,7 +552,12 @@ function truncateTierToBudget(blockText, budget, valueById = new Map()) {
 // lowest-priority tier wholesale, logged as a dropped_tiers event.
 // This shouldn't fire under the documented budget table (1500+4500+
 // 4000 = 10000 ≤ 10240 default cap), but the safety net is cheap.
-function enforceCap(orderedBlocks, capBytes, ts) {
+// `reportCapBytes` (Task 75.0): the CALLER-facing cap for Door-4 events.
+// injectContext hands enforceCap a cap reduced by the preamble reserve;
+// truncation.log must still report the capBytes the user configured, not
+// the internal effective value, or the log reads as nonsense (411 when
+// the user set 1024).
+function enforceCap(orderedBlocks, capBytes, ts, reportCapBytes = capBytes) {
   const tierEvents = [];
   // Step 1: per-tier budget enforcement (section-granular).
   for (const block of orderedBlocks) {
@@ -559,7 +596,7 @@ function enforceCap(orderedBlocks, capBytes, ts) {
     bytes -= Buffer.byteLength(dropped.text, 'utf8');
     let event = dropEvents[dropEvents.length - 1];
     if (!event) {
-      event = { ts, capBytes, dropped_tiers: [] };
+      event = { ts, capBytes: reportCapBytes, dropped_tiers: [] };
       dropEvents.push(event);
     }
     event.dropped_tiers.push(dropped.tier);
@@ -707,15 +744,26 @@ export function injectContext({
   }
 
   // 3. Cap enforcement: drop whole tier blocks from the tail until within
-  // capBytes. Each drop emits one truncation event.
+  // capBytes. Each drop emits one truncation event. The authoritative-memory
+  // preamble (Task 75.0) is reserved out of the cap up front so the final
+  // snapshot (preamble + blocks) still honors capBytes exactly.
+  const preambleReserve =
+    rawBlocks.length > 0
+      ? Buffer.byteLength(AUTHORITATIVE_MEMORY_PREAMBLE, 'utf8') + 2
+      : 0;
   const { blocks: keptBlocks, truncationEvents } = enforceCap(
     rawBlocks,
-    cap,
+    Math.max(0, cap - preambleReserve),
     ts,
+    cap,
   );
 
-  // 4. Concatenate.
-  const snapshot = keptBlocks.map((b) => b.text).join('\n');
+  // 4. Concatenate. The preamble leads every non-empty snapshot; an empty
+  // snapshot stays empty (don't claim authoritative memory with nothing
+  // behind it).
+  const body = keptBlocks.map((b) => b.text).join('\n');
+  const snapshot =
+    body === '' ? '' : `${AUTHORITATIVE_MEMORY_PREAMBLE}\n\n${body}`;
 
   // 5. Persist side-effect logs under <projectRoot>/context/.locks/. We
   // only write the project-tier .locks file (which is the well-known
@@ -757,7 +805,14 @@ export function injectContext({
   // 7. Emit the Anthropic SessionStart hook output shape (design §5.1 +
   // Anthropic hook protocol). When the snapshot is empty, we still emit
   // the shape so downstream tooling can rely on the field's presence.
+  //
+  // Task 145 (D-130): `systemMessage` is the USER-DISPLAY channel (the
+  // D-116 primary-source check: additionalContext is model-facing,
+  // systemMessage is shown to the user) — one status line per session
+  // start, zero model-token cost. The trust loop every silent system
+  // lacks: when the kit works, the user finally SEES it working.
   const hookOutput = {
+    systemMessage: buildStatusLine({ snapshot, projectRoot, now: ts }),
     hookSpecificOutput: {
       hookEventName: HOOK_EVENT_NAME,
       additionalContext: snapshot,
@@ -773,3 +828,120 @@ export function injectContext({
     bytes: Buffer.byteLength(snapshot, 'utf8'),
   };
 }
+
+// --- Task 145: the session-start status line (user-display) -------------
+
+// Tail-read budget for audit.log: recency lives at the end; reading the
+// whole file would grow with project age inside a 500ms-budget hook.
+const STATUS_AUDIT_TAIL_BYTES = 64 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Derived from the shared ID_PATTERN (tier-paths.mjs) — strip its ^/$
+// anchors and wrap in the `(id)` bullet form. One alphabet, one source.
+const SNAPSHOT_ID_RE = new RegExp(`\\((${ID_PATTERN.source.slice(1, -1)})\\)`, 'g');
+
+/**
+ * One user-facing line summarizing what the kit just did for this session.
+ * Best-effort everywhere: a status line must NEVER turn a working hook into
+ * a crash — every data source degrades to its zero independently.
+ *
+ * @param {object} opts
+ * @param {string} opts.snapshot - the composed injection snapshot.
+ * @param {string} opts.projectRoot
+ * @param {string} [opts.now]
+ * @param {Function} [opts.listConflictsImpl] - test seam (default: the real queue lister).
+ * @param {Function} [opts.listReviewImpl] - test seam.
+ * @returns {string} the status line (always a string, never throws).
+ */
+export function buildStatusLine({
+  snapshot,
+  projectRoot,
+  now,
+  listConflictsImpl,
+  listReviewImpl,
+} = {}) {
+  const prefix = 'claude-memory-kit:';
+  try {
+    // 1. Unique injected fact ids — what the model can actually see.
+    const ids = new Set();
+    for (const m of String(snapshot ?? '').matchAll(SNAPSHOT_ID_RE)) ids.add(m[1]);
+
+    if (ids.size === 0) {
+      return `${prefix} memory is empty — capture starts this session`;
+    }
+    const parts = [`${ids.size} fact(s) in context`];
+
+    // 2. Captures in the last 24h, from the audit-log tail. A capture is a
+    // `created` entry or an APPLIED import — `action: 'import'` alone also
+    // covers skipped duplicates (reasonCode import-skipped-duplicate), and
+    // counting those would let a re-run import inflate the line by its
+    // whole dup count (skill-review finding, 2026-06-12).
+    const nowMs = Date.parse(now ?? nowIso());
+    let recent = 0;
+    try {
+      const auditPath = join(projectRoot, 'context', '.locks', 'audit.log');
+      if (existsSync(auditPath)) {
+        // Positioned read of the LAST 64KB only — recency lives at the end,
+        // and this runs inside the 500ms-budget SessionStart hook; reading a
+        // months-old multi-MB log in full would pay for history we discard.
+        const size = statSync(auditPath).size;
+        const start = Math.max(0, size - STATUS_AUDIT_TAIL_BYTES);
+        const buf = Buffer.alloc(size - start);
+        const fd = openSync(auditPath, 'r');
+        try {
+          readSync(fd, buf, 0, buf.length, start);
+        } finally {
+          closeSync(fd);
+        }
+        // Drop the (possibly torn) first line when we started mid-file.
+        const tail = start > 0 ? buf.toString('utf8').replace(/^[^\n]*\n/, '') : buf.toString('utf8');
+        for (const line of tail.split(/\r?\n/)) {
+          if (!line.trim()) continue;
+          try {
+            const e = JSON.parse(line);
+            const isCapture =
+              e.action === 'created' ||
+              (e.action === 'import' && e.reasonCode === 'import-applied');
+            if (
+              isCapture &&
+              nowMs - Date.parse(e.ts) <= DAY_MS &&
+              nowMs - Date.parse(e.ts) >= 0
+            ) {
+              recent += 1;
+            }
+          } catch {
+            // torn NDJSON line — skip
+          }
+        }
+      }
+    } catch {
+      // audit log unreadable — the count degrades to absent
+    }
+    if (recent > 0) parts.push(`${recent} captured in the last 24h`);
+
+    // 3. Pending curation — only mentioned when non-zero (a quiet queue
+    // earns a quiet line).
+    let conflicts = 0;
+    let review = 0;
+    try {
+      conflicts = (listConflictsImpl ?? listConflictQueue)({ tier: 'P', projectRoot }).length;
+    } catch {
+      // queue unreadable — degrade to zero
+    }
+    try {
+      review = (listReviewImpl ?? listReviewQueue)({ tier: 'P', projectRoot }).length;
+    } catch {
+      // queue unreadable — degrade to zero
+    }
+    if (conflicts > 0 || review > 0) {
+      const q = [];
+      if (conflicts > 0) q.push(`${conflicts} conflict(s)`);
+      if (review > 0) q.push(`${review} review item(s)`);
+      parts.push(`${q.join(' + ')} pending — cmk queue`);
+    }
+
+    return `${prefix} ${parts.join(', ')}`;
+  } catch {
+    // The line is decoration; the snapshot is the cargo. Never crash.
+    return `${prefix} memory loaded`;
+  }
+}

package/src/install.mjs

@@ -39,9 +39,11 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { injectClaudeMdBlock } from './claude-md.mjs';
+import { checkKitBinding, npmSupportsAllowScripts } from './native-binding.mjs';
 import { writeKitHooks, writeKitMcpServer } from './settings-hooks.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 
@@ -57,6 +59,13 @@ const CLI_PKG_DIR = resolve(CLI_SRC_DIR, '..');
 // it must not show a stale hardcode (was `v0.1.0` in every install). Built per
 // install from the kit version; see gitignoreStartMarker().
 const GITIGNORE_END = '# claude-memory-kit:gitignore:end';
+// D-126 CRLF-prevention: the .gitattributes managed block uses the SAME
+// marker discipline as .gitignore (version-stamped start, in-place refresh).
+const GITATTRIBUTES_END = '# claude-memory-kit:gitattributes:end';
+
+function gitattributesStartMarker(version) {
+  return `# claude-memory-kit:gitattributes:start v${version}`;
+}
 
 function gitignoreStartMarker(version) {
   return `# claude-memory-kit:gitignore:start v${version}`;
@@ -232,6 +241,52 @@ function buildGitignoreBlock(templateDir, version = getKitVersion()) {
   return `${gitignoreStartMarker(version)}\n${fragment}\n${GITIGNORE_END}\n`;
 }
 
+/**
+ * Build the canonical .gitattributes managed block from
+ * template/.gitattributes.fragment (D-126 CRLF prevention — force LF on the
+ * committed memory tiers so default Windows git doesn't mangle the bytes at
+ * clone). Same marker discipline as the .gitignore block.
+ */
+function buildGitattributesBlock(templateDir, version = getKitVersion()) {
+  const fragmentPath = join(templateDir, '.gitattributes.fragment');
+  const fragment = existsSync(fragmentPath)
+    ? readFileSync(fragmentPath, 'utf8').trim()
+    : 'context/**/*.md text eol=lf\ncontext/**/*.json text eol=lf';
+  return `${gitattributesStartMarker(version)}\n${fragment}\n${GITATTRIBUTES_END}\n`;
+}
+
+/**
+ * Inject (or refresh) the managed .gitattributes block. Same algorithm as
+ * injectGitignore (create / append-if-no-markers / replace-in-place),
+ * byte-preserving everything outside the markers.
+ *
+ * Returns: { action: 'created' | 'replaced' | 'unchanged', path: string }
+ */
+function injectGitattributes(projectRoot, block) {
+  const gaPath = join(projectRoot, '.gitattributes');
+  const startRe = /# claude-memory-kit:gitattributes:start[^\n]*\n/;
+  const endRe = /# claude-memory-kit:gitattributes:end\n?/;
+
+  if (!existsSync(gaPath)) {
+    writeFileSync(gaPath, block, 'utf8');
+    return { action: 'created', path: gaPath };
+  }
+  const existing = readFileSync(gaPath, 'utf8');
+  const startMatch = existing.match(startRe);
+  const endMatch = existing.match(endRe);
+  if (!startMatch || !endMatch || startMatch.index > endMatch.index) {
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(gaPath, existing + sep + block, 'utf8');
+    return { action: 'created', path: gaPath };
+  }
+  const before = existing.slice(0, startMatch.index);
+  const after = existing.slice(endMatch.index + endMatch[0].length);
+  const next = before + block + after;
+  if (next === existing) return { action: 'unchanged', path: gaPath };
+  writeFileSync(gaPath, next, 'utf8');
+  return { action: 'replaced', path: gaPath };
+}
+
 /**
  * Inject (or refresh) the managed .gitignore block in `<projectRoot>/.gitignore`.
  *
@@ -327,6 +382,10 @@ export async function install(options = {}) {
   }
 
   const gitignore = injectGitignore(projectRoot, buildGitignoreBlock(templateDir, version));
+  // D-126 CRLF prevention: pin LF on the committed memory tiers so default
+  // Windows git can't mangle the bytes at clone (the read-side self-heal
+  // shipped in v0.3.0; this prevents the mangling in the first place).
+  const gitattributes = injectGitattributes(projectRoot, buildGitattributesBlock(templateDir, version));
 
   // CLAUDE.md loader block — Task 4. Read the block content from the kit's
   // template/ and inject (or refresh) it inside marker delimiters. Never
@@ -411,7 +470,127 @@ export async function install(options = {}) {
     }
   }
 
-  return { projectRoot, userTier, created, skipped, gitignore, claudeMd, hooks, mcpServer, errors };
+  // Task 46 — semantic-recall opt-in/out. `--with-semantic`: install the
+  // optional embedder (~260 MB once, fully local), flip the project's
+  // default search mode to hybrid, and pre-warm the model so the one-time
+  // download happens NOW, not as a surprise on the first search.
+  // `--no-semantic`: pin keyword explicitly. Neither flag → settings
+  // untouched (keyword by absence). The npm spawn is injectable
+  // (options.spawnNpm) so tests assert the argv without touching the host.
+  // Both flags together → withSemantic wins (the affirmative opt-in beats
+  // the pin-off; checked first below).
+  let semantic = { action: 'skipped' };
+  if (options.withSemantic) {
+    semantic = await enableSemantic({ projectRoot, spawnNpm: options.spawnNpm, warm: options.warmEmbedder });
+    if (semantic.action === 'error') errors.push({ path: 'semantic', error: semantic.error });
+  } else if (options.noSemantic) {
+    const r = mergeProjectSettings(projectRoot, { search: { default_mode: 'keyword' } });
+    semantic = r.ok
+      ? { action: 'disabled', path: r.path }
+      : { action: 'error', error: r.error };
+    if (!r.ok) errors.push({ path: r.path, error: r.error });
+  }
+
+  // Task 141a (D-129): probe the kit's native binding so the CLI can ask the
+  // user to fix it INLINE (npm 12 blocks better-sqlite3's binding build on a
+  // fresh install). Reported, never an installer error — scaffold + hooks
+  // are fully functional without it; only search/reindex need the binding.
+  const bindingProbe = options.bindingProbe ?? checkKitBinding;
+  const nativeBinding = bindingProbe();
+
+  return { projectRoot, userTier, created, skipped, gitignore, gitattributes, claudeMd, hooks, mcpServer, semantic, nativeBinding, errors };
+}
+
+/**
+ * Read-merge-write <projectRoot>/context/settings.json, preserving every
+ * key the user already has (over-mutation-safe; deep-merges one level).
+ */
+export function mergeProjectSettings(projectRoot, patch) {
+  const path = join(projectRoot, 'context', 'settings.json');
+  try {
+    let current = {};
+    if (existsSync(path)) {
+      current = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    const next = { ...current };
+    for (const [key, value] of Object.entries(patch)) {
+      next[key] =
+        value && typeof value === 'object' && !Array.isArray(value)
+          ? { ...(current[key] ?? {}), ...value }
+          : value;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, path, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * The production npm-spawn closure, as an injectable-seam factory
+ * (Task 125.4) so its argv/shell/timeout contract is testable without
+ * running a real `npm install -g` (which stays a machine-level step
+ * tests must never take).
+ */
+export function buildDefaultNpmRunner({ spawnSyncImpl = spawnSync } = {}) {
+  return () => {
+    // Task 141a (D-129): on npm ≥ 11.16 the `allow-scripts` config exists
+    // and npm 12 BLOCKS onnxruntime-node's install script without it — the
+    // kit runs this install itself, so it carries the allow flag itself
+    // (no user friction). Older npm: plain command, no unknown-config noise.
+    const { supported } = npmSupportsAllowScripts({ spawnSyncImpl });
+    const cmd = supported
+      ? 'npm install -g @huggingface/transformers --allow-scripts=onnxruntime-node'
+      : 'npm install -g @huggingface/transformers';
+    // One constant command string under shell:true (no user input — and
+    // an args array + shell:true trips Node's DEP0190). npm is npm.cmd
+    // on Windows; the shell resolves it cross-platform.
+    const r = spawnSyncImpl(cmd, {
+      encoding: 'utf8',
+      stdio: 'inherit',
+      shell: true,
+      // spawn-discipline (design §8.5): a hung registry shouldn't hang
+      // install forever; 10 min covers the ~46 MB package on slow links.
+      timeout: 600_000,
+    });
+    return { status: r.status, error: r.error?.message };
+  };
+}
+
+async function enableSemantic({ projectRoot, spawnNpm, warm }) {
+  // 1. Install the optional embedder globally (it resolves as a sibling of
+  // the globally-installed kit). Injectable for tests.
+  const runNpm = spawnNpm ?? buildDefaultNpmRunner();
+  const npm = runNpm();
+  if (npm.status !== 0) {
+    return {
+      action: 'error',
+      error: `npm install -g @huggingface/transformers failed (${npm.error ?? `exit ${npm.status}`}) — semantic recall NOT enabled; keyword search is unaffected`,
+    };
+  }
+  // 2. Flip the project default to hybrid ONLY after the dependency landed
+  // (no half-state: a hybrid default without an embedder would degrade
+  // every search to a fallback warning).
+  const settings = mergeProjectSettings(projectRoot, { search: { default_mode: 'hybrid' } });
+  if (!settings.ok) {
+    return { action: 'error', error: settings.error };
+  }
+  // 3. Pre-warm (best-effort): the one-time model download happens during
+  // install, not on the first search. Injectable for tests.
+  let warmed = { ok: false, reason: 'skipped' };
+  try {
+    const warmFn =
+      warm ??
+      (async () => {
+        const { warmEmbedder } = await import('./semantic-backend.mjs');
+        return warmEmbedder();
+      });
+    warmed = await warmFn();
+  } catch (err) {
+    warmed = { ok: false, reason: err?.message ?? String(err) };
+  }
+  return { action: 'enabled', path: settings.path, defaultMode: 'hybrid', warmed };
 }
 
 /**

package/src/mcp-server.mjs

@@ -40,7 +40,7 @@ import { openIndexDb } from './index-db.mjs';
 import { reindexBoot } from './index-rebuild.mjs';
 import { search, SEARCH_MODES } from './search.mjs';
 import { memoryWrite } from './memory-write.mjs';
-import { rememberRich, nonProjectTierNote } from './remember-core.mjs';
+import { rememberRich, nonProjectTierNote, prepareNearDupGuard } from './remember-core.mjs';
 import { forget } from './forget.mjs';
 import { overrideTrust } from './trust.mjs';
 import { lessonsPromote } from './lessons-promote.mjs';
@@ -106,16 +106,60 @@ export function validatePath(p, { projectRoot, userDir }) {
 
 // --- Tool handlers ----------------------------------------------------
 
-function makeMkSearch({ db, semanticBackend }) {
-  return async ({ query, mode, tier, since, limit, min_trust }) => {
+function makeMkSearch({ db, semanticBackend, projectRoot }) {
+  return async ({ query, mode, scope, tier, since, limit, min_trust }) => {
+    // Task 46: explicit mode wins; otherwise the project's configured
+    // default (search.default_mode — set by `cmk install --with-semantic`).
+    const { prepareSemanticBackend, resolveDefaultSearchMode } = await import(
+      './semantic-backend.mjs'
+    );
+    let wantMode =
+      mode ??
+      (projectRoot ? resolveDefaultSearchMode({ projectRoot }) : SEARCH_MODES.KEYWORD);
+    // Task 65: when the caller asks for semantic/hybrid and no test seam is
+    // injected, prepare the REAL embedded backend (lazy-optional — an absent
+    // embedder degrades to the actionable error below; keyword unaffected).
+    let backend = semanticBackend;
+    let degradedNote = null;
+    if (
+      backend === undefined &&
+      (wantMode === SEARCH_MODES.SEMANTIC || wantMode === SEARCH_MODES.HYBRID)
+    ) {
+      const prep = await prepareSemanticBackend({ db, query, scope: scope ?? 'facts' });
+      if (!prep.ok && mode) {
+        // Explicitly requested — surface the actionable error.
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `error: semantic backend unavailable (${prep.reason}). ${prep.hint ?? 'Use mode "keyword".'}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      if (!prep.ok) {
+        // Configured default can't run — degrade gracefully to keyword,
+        // but NOT silently (Task 125.1, the user's call reversing the
+        // Task-46 review skip): the note below tells the model what it
+        // got, so it can relay the fix to the user.
+        wantMode = SEARCH_MODES.KEYWORD;
+        degradedNote =
+          `note: this project's configured default search is semantic (hybrid), but the embedder is unavailable (${prep.reason}) — these are keyword-only results. ` +
+          'Suggest the user run `cmk install --with-semantic` to restore semantic recall.';
+      } else {
+        backend = prep.backend;
+      }
+    }
     const r = search({
       db, query,
-      mode: mode ?? SEARCH_MODES.KEYWORD,
+      mode: wantMode,
+      scope,
       tier,
       since,
       limit,
       minTrust: min_trust,
-      semanticBackend,
+      semanticBackend: backend,
     });
     if (r.action === 'error') {
       return {
@@ -124,7 +168,12 @@ function makeMkSearch({ db, semanticBackend }) {
       };
     }
     return {
-      content: [{ type: 'text', text: JSON.stringify(r.results, null, 2) }],
+      content: [
+        { type: 'text', text: JSON.stringify(r.results, null, 2) },
+        // Results stay content[0] (shape-compatible); the degradation note,
+        // when present, rides as a second block.
+        ...(degradedNote ? [{ type: 'text', text: degradedNote }] : []),
+      ],
     };
   };
 }
@@ -232,6 +281,10 @@ function makeMkRemember({ projectRoot, userDir }) {
         ],
       };
     }
+    // Task 143 (D-130): the semantic near-dup guard (one embed of the
+    // incoming text when the project is semantic-configured + the embedder
+    // is available; {} = literal pipeline, never blocks capture).
+    const nearDup = await prepareNearDupGuard({ projectRoot, text });
     const r = memoryWrite({
       action: 'add',
       text,
@@ -242,6 +295,7 @@ function makeMkRemember({ projectRoot, userDir }) {
       sessionId: 'mcp-server',
       projectRoot,
       userDir,
+      ...nearDup,
     });
     if (r.action === 'error') {
       return {
@@ -505,17 +559,18 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
   server.registerTool(
     'mk_search',
     {
-      description: 'Search kit memory (FTS5 keyword by default; semantic + hybrid require the Layer-5b semantic backend, not yet shipped).',
+      description: 'Search kit memory. FTS5 keyword by default; semantic + hybrid use the embedded Layer-5b backend (sqlite-vec + a local ONNX embedder — needs the optional @huggingface/transformers install).',
       inputSchema: {
         query: z.string().min(1).describe('search query'),
         mode: z.enum(['keyword', 'semantic', 'hybrid']).optional(),
+        scope: z.enum(['facts', 'transcripts']).optional().describe("'facts' (default) = curated memory; 'transcripts' = the raw session record — the LAST-RESORT recall tier, search it only when curated memory has no answer"),
         tier: z.enum(['U', 'P', 'L']).optional(),
         since: z.string().optional().describe('ISO 8601 timestamp'),
         limit: z.number().int().positive().max(1000).optional(),
         min_trust: z.enum(['low', 'medium', 'high']).optional(),
       },
     },
-    makeMkSearch({ db, semanticBackend }),
+    makeMkSearch({ db, semanticBackend, projectRoot }),
   );
 
   // mk_get