klypix-mcp 1.95.0 → 1.97.0

package/README.md

@@ -235,13 +235,23 @@ not a filing convention.
   session's brief. That is brief priority, not a retrieval-ranking boost.
 - **You can ask what the project believed then.** `brain_ask` with `as_of: 2026-03-01` reweights
   ranking by card lifecycle dates, so corrections made later do not leak backwards.
-- **Retrieval is local.** Lexical by default. If the optional on-device model is installed,
-  `brain_ask` and `search_all_brains` use BGE semantic ranking with lexical help for exact
-  identifiers, paths, and versions — still entirely on your machine. The previous cross-encoder
-  is available for experiments with `KLYPIX_RERANK=1`, but is off by default because it reduced
-  precision and added latency on the frozen human-paraphrase evaluation. Without the embedding
-  model, retrieval degrades cleanly to lexical. `npx klypix-mcp install` deliberately does not
-  install that model, so a fresh install is lexical.
+- **Retrieval is local.** With the on-device model ("search by meaning"), `brain_ask` and
+  `search_all_brains` use BGE semantic ranking with lexical help for exact identifiers, paths, and
+  versions — still entirely on your machine. Without it, retrieval is keyword-only. The previous
+  cross-encoder is available for experiments with `KLYPIX_RERANK=1`, but is off by default because
+  it reduced precision and added latency on the frozen human-paraphrase evaluation.
+- **Search by meaning is installed for you (1.97).** `npx klypix-mcp install` run by a person in a
+  terminal installs it: about 150 MB to download once, about 110 MB on disk after the files Node
+  never loads are removed. Skip it with `--no-semantic` (or `KLYPIX_SEMANTIC=0`). Installs with no
+  terminal — CI, scripts, an AI agent running the install — get it only with `--semantic`. The
+  Claude plugin never downloads it. Measured on the frozen 102-question set: the right card in the
+  top 5 for 54 questions with it, 19 without.
+- **Preparing a brain never makes a question wait.** Each card is turned into a meaning vector once
+  (about 45 ms a card on a laptop CPU, one card at a time, ~305 MB peak), newest cards first, by a
+  low-priority background job that saves as it goes. A question on a brain that is not ready yet
+  answers right away from what is ready plus keywords, and says how far along the preparation is
+  ("Getting this brain ready for search by meaning: 900 of 3,670 cards so far, about 5 min left").
+  After that, only new or edited cards are prepared.
 
 ### Bounded semantic-memory runtime
 
@@ -1143,6 +1153,15 @@ independently validated.
   0.43, top-1 33%. The stratum that matters most is the honest one: **paraphrase questions that share
   no words with their card reach recall@5 44%**; status, temporal and multi-hop questions sit at
   81–93% because they still share vocabulary. Lexical-only scores 0% on the same set.
+- **The caller's words (`brain_ask`, 1.96).** A question can end with one more line,
+  `Also: <words a card answering it would likely use>`; the calling agent is itself a model, so it
+  can guess the card's wording at no extra cost. The words join the meaning query only. Measured
+  2026-10-11 on the same brain grown to 3,829 cards (102 of the frozen questions still answerable),
+  with words written by Gemini 2.5 Flash as a stand-in for the calling agent: recall@5 54% → 59%
+  (8 found, 3 lost), recall@8 61% → 68%, recall@20 68% → 76%, MRR 0.375 → 0.424. With no local
+  model (a fresh install, the Claude plugin) the words count as extra keywords at half weight:
+  recall@5 19% → 24% (5 found, none lost), recall@10 25% → 31%. Without the line, ranking is
+  unchanged byte for byte.
 - **Second brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
   paraphrases, first cross-brain run): recall@5 **42%** (CI 23–64), top-1 11%, MRR 0.25. Paraphrase
   recall transfers between brains; the ranker is not tuned to the brain it was built on. It is

package/bin/klypix-install.mjs

@@ -12,6 +12,10 @@
 //   npx klypix-mcp install --codex-hooks  # optional prompt/file awareness; Codex asks for trust
 //   npx klypix-mcp install --allow-untagged  # acknowledge deploying an UNTAGGED source checkout
 //                                            # (dev deploy; also KLYPIX_MCP_ALLOW_UNTAGGED=1)
+//   npx klypix-mcp install --semantic     # also install search by meaning (~150 MB download, once)
+//   npx klypix-mcp install --no-semantic  # never (also KLYPIX_SEMANTIC=0)
+//   A person running install in a terminal gets search by meaning by default;
+//   scripted, CI and agent-run installs (no terminal) only with --semantic.
 //
 // Never-throws-silently: it's an explicit CLI, so it reports what it did and exits
 // non-zero on a real failure. Never wires a broken settings.json (refuse + restore).
@@ -35,6 +39,7 @@ import { brainInstallDecision, deploySourceDecision } from '../src/install-versi
 import { acquireInstallLockSync, releaseInstallLockSync } from '../src/install-lock.mjs';
 import { collectRepoState } from '../src/repo-state.mjs';
 import { runSetup, renderBrief } from '../src/setup.mjs';
+import { SEMANTIC_RUNTIME_MANIFEST, dirBytes, pruneSemanticRuntime, semanticInstallDecision } from '../src/semantic-install.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -60,6 +65,10 @@ const SETUP_JSON = process.argv.includes('--json');
 // this is source authority (knowingly deploy an untagged working tree).
 const ALLOW_UNTAGGED = process.argv.includes('--allow-untagged')
     || process.env.KLYPIX_MCP_ALLOW_UNTAGGED === '1';
+// Search by meaning (1.97.0). Measured 2026-10-11 on the real 102-question
+// set: the right card in the top 5 for 54 questions with it, 19 without.
+const SEMANTIC_FLAG = process.argv.includes('--semantic');
+const NO_SEMANTIC = process.argv.includes('--no-semantic') || process.env.KLYPIX_SEMANTIC === '0';
 
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
@@ -143,6 +152,52 @@ function wireCodex() {
     };
 }
 
+// ── Search by meaning: the optional on-device runtime (src/semantic-install.mjs) ──
+function installSemanticRuntimeIfWanted() {
+    const semanticDir = path.join(BRAIN_DIR, 'semantic');
+    const transformers = path.join(semanticDir, 'node_modules', '@huggingface', 'transformers');
+    const decision = semanticInstallDecision({
+        optOut: NO_SEMANTIC,
+        flag: SEMANTIC_FLAG,
+        runtimeOnly: RUNTIME_ONLY,
+        plugin: String(process.env.KLYPIX_PLUGIN ?? '').trim() === '1',
+        present: exists(transformers),
+        ci: Boolean(process.env.CI),
+        tty: Boolean(process.stdout.isTTY),
+    });
+    if (decision !== 'install') return { decision };
+    console.log('• Installing search by meaning (about 150 MB to download, once; skip with --no-semantic)…');
+    const started = Date.now();
+    try {
+        fs.mkdirSync(semanticDir, { recursive: true });
+        fs.writeFileSync(path.join(semanticDir, 'package.json'), `${JSON.stringify(SEMANTIC_RUNTIME_MANIFEST, null, 2)}\n`);
+        const npmArgs = ['install', '--prefix', semanticDir, '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'];
+        if (process.platform === 'win32') execFileSync('cmd.exe', ['/d', '/s', '/c', 'npm.cmd', ...npmArgs], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 600_000, windowsHide: true });
+        else execFileSync('npm', npmArgs, { stdio: ['ignore', 'ignore', 'pipe'], timeout: 600_000 });
+        if (!exists(transformers)) throw new Error('npm finished but the runtime is missing');
+        let freed = 0;
+        try { freed = pruneSemanticRuntime(semanticDir); } catch { /* pruning is an optimisation */ }
+        return { decision, ok: true, seconds: Math.round((Date.now() - started) / 1000), sizeMb: Math.round(dirBytes(path.join(semanticDir, 'node_modules')) / 1048576), freedMb: Math.round(freed / 1048576) };
+    } catch (error) {
+        const why = String(error?.stderr || error?.message || error).split('\n').map(s => s.trim()).filter(Boolean).slice(-1)[0] || 'npm failed';
+        return { decision, ok: false, error: why.slice(0, 200) };
+    }
+}
+
+function reportSemantic(step) {
+    const turnOn = 'npx klypix-mcp install --semantic';
+    if (!step) return;
+    if (step.decision === 'install' && step.ok) {
+        console.log(`✓ search by meaning installed in ${step.seconds}s (${step.sizeMb} MB on disk). Your project brains are being prepared in the background, newest cards first: questions work right away and get better as it finishes.`);
+    } else if (step.decision === 'install') {
+        console.error(`⚠ search by meaning could not be installed (${step.error}). Keyword search still works. Try again with: ${turnOn}`);
+    } else if (step.decision === 'present') {
+        console.log('✓ search by meaning: on');
+    } else if (step.decision === 'skip-noninteractive' || step.decision === 'skip-ci') {
+        console.log(`• search by meaning is off. Turn it on with: ${turnOn}  (about 150 MB, once; agents then find the right card about 3x as often)`);
+    }
+}
+
 function reportCodex(result) {
     if (result.ok) {
         const mcp = result.mcp.action === 'skipped-no-project-brain'
@@ -594,6 +649,9 @@ try {
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse', 'PreToolUse'].filter(e => !wiredFor(e));
 
     releaseInstallLockSync(installLock);
+    // Search by meaning: installed AFTER the brain itself is committed, so a
+    // slow or failed download never touches a working keyword-only install.
+    const semanticStep = installSemanticRuntimeIfWanted();
     // Users who already enabled the optional local semantic runtime should not
     // pay a multi-minute first question after a model/cache contract upgrade.
     // Migrate registered brains once in a detached process after the atomic
@@ -617,6 +675,7 @@ try {
     }
     if (!RUNTIME_ONLY) reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
+    reportSemantic(semanticStep);
     if (RUNTIME_ONLY) console.log('✓ runtime-only update: host settings and project files were preserved');
     else if (!notWired.length) console.log('✓ wired 5 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) · PreToolUse (--guard) → settings.json');
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);

package/bin/klypix-semantic-warm.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
-// One detached, best-effort cache migration after a compatible core update.
-// It runs only when the optional semantic runtime already exists, processes
-// registered brains sequentially, and never changes brain content.
+// One detached, best-effort preparation of brains for search by meaning: after
+// an install or a compatible core update (every registered brain), or started
+// by a question on a brain that is not ready yet (--brain <file> --only: that
+// brain alone). It runs at below-normal priority, reports progress to the
+// status file while it works (brainPreparationStatus reads it), refreshes its
+// lock so a long run is never taken for a dead one, and never changes brain
+// content.
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -9,6 +13,7 @@ import { parseKlypix } from '../src/klypix-format.mjs';
 import { readRegisteredProjectBrains } from '../src/mcp-auto-update.mjs';
 import {
   EMBEDDING_CACHE_KEY,
+  cachedVectorsForBrain,
   disposeSemanticModels,
   getEmbedderForUse,
   vectorsForBrain,
@@ -22,6 +27,7 @@ const brainDir = path.resolve(arg('brain-dir', path.join(os.homedir(), '.claude'
 const lockFile = path.join(brainDir, '.semantic-update-warm.lock');
 const statusFile = path.join(brainDir, '.semantic-update-warm.json');
 const explicitBrain = arg('brain');
+const onlyExplicit = process.argv.includes('--only');
 const startedAt = Date.now();
 let lock = null;
 
@@ -31,6 +37,9 @@ const atomicJson = (file, value) => {
   fs.renameSync(tmp, file);
 };
 
+// A background job: never compete with the person's own work for the CPU.
+try { os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL); } catch { /* best-effort */ }
+
 try {
   fs.mkdirSync(brainDir, { recursive: true });
   try {
@@ -45,13 +54,17 @@ try {
   }
   fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, startedAt, modelKey: EMBEDDING_CACHE_KEY }));
 
-  const registered = readRegisteredProjectBrains(brainDir).map(item => item.brainPath);
+  const registered = onlyExplicit && explicitBrain ? [] : readRegisteredProjectBrains(brainDir).map(item => item.brainPath);
   const candidates = [...new Set([explicitBrain ? path.resolve(explicitBrain) : null, ...registered].filter(Boolean))]
     .filter(file => {
       try { return fs.statSync(file).isFile(); } catch { return false; }
     });
   if (!candidates.length) {
-    atomicJson(statusFile, { protocol: 1, result: 'no-registered-brains', modelKey: EMBEDDING_CACHE_KEY, completedAt: new Date().toISOString() });
+    // Nothing to prepare yet, but fetch the model now (~33 MB, once) so the
+    // first question on a new brain does not pay for the download.
+    let model = 'unavailable';
+    try { model = (await getEmbedderForUse(() => {}, 5 * 60_000)) ? 'downloaded' : 'unavailable'; } catch { /* the first question fetches it */ }
+    atomicJson(statusFile, { protocol: 1, result: 'no-registered-brains', model, modelKey: EMBEDDING_CACHE_KEY, completedAt: new Date().toISOString() });
   } else {
     const pipe = await getEmbedderForUse(() => {}, 5 * 60_000);
     if (!pipe) {
@@ -61,7 +74,18 @@ try {
       for (const file of candidates) {
         try {
           const { struct } = await parseKlypix(fs.readFileSync(file));
-          const vectors = await vectorsForBrain(pipe, file, struct.cards);
+          const brainStarted = new Date().toISOString();
+          let lastReport = 0;
+          const report = ({ done, total }, force = false) => {
+            if (!force && Date.now() - lastReport < 3_000) return;
+            lastReport = Date.now();
+            try { atomicJson(statusFile, { protocol: 1, result: 'preparing', modelKey: EMBEDDING_CACHE_KEY, brain: file, done, total, startedAt: brainStarted, updatedAt: new Date().toISOString() }); } catch { /* advisory */ }
+            try { const now = new Date(); fs.utimesSync(lockFile, now, now); } catch { /* advisory */ }
+          };
+          let alreadyReady = 0;
+          try { alreadyReady = cachedVectorsForBrain(file, struct.cards).size; } catch { /* starts from zero */ }
+          report({ done: alreadyReady, total: struct.cards.filter(c => c.type !== 'container' && String(c.text || '').trim()).length }, true);
+          const vectors = await vectorsForBrain(pipe, file, struct.cards, { maxEmbed: Infinity, onProgress: report });
           warmed++;
           cards += vectors.size;
         } catch { failed++; }

package/bin/klypix-worker.mjs

@@ -508,7 +508,7 @@ server.registerTool('search_all_brains', {
 
 server.registerTool('brain_ask', {
   title: 'Ask the project brain a question (whole-brain, correction-aware answer)',
-  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card lexically, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh install is lexical; it degrades cleanly). INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Defaults to the project brain ("brain").',
+  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card by meaning with the on-device model (installed by `npx klypix-mcp install` run in a terminal, or with `--semantic`), with keywords for exact names; without the model it is keyword-only, and while a brain is still being prepared the answer says how far along it is. INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Cards are often worded differently from the question, so end the question with one more line, `Also: <8–14 words a card answering it would likely use: synonyms, feature, file or tool names>`; they widen the search while the question still leads (measured: right card in the top 5 for 60 of 102 test questions instead of 55; 24 instead of 19 when no local model is installed). Defaults to the project brain ("brain").',
   inputSchema: {
     question: z.string().describe('The natural-language question to answer from the brain.'),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.95.0",
+  "version": "1.97.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -86,7 +86,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",

package/src/klypix-core.mjs

@@ -30,7 +30,7 @@ import {
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
   selectGardenCandidates, applyGarden, detectContradictions,
   findDuplicatePartialNotes, collapseDuplicatePartialNotes,
-  rankForQuestion, questionContextToMarkdown, findLegacyShipCards,
+  rankForQuestion, splitAskWords, questionContextToMarkdown, findLegacyShipCards,
   challengeBrain, challengeContextToMarkdown, buildRenderSpec, structToBrief,
   brainLensData, lensToMarkdown, deathDateOfCard,
   statusContextToMarkdown, findFulfillmentCandidates, findStaleOpenCards, releaseFulfilledOpens, openStatusSummary, perAreaTableToMarkdown,
@@ -56,7 +56,7 @@ import {
   dot, embedTexts, getEmbedder, getEmbedderForUse, withRerankerForUse,
   rerankHits, semanticFallbackNotice, semanticMemorySnapshot,
   semanticRuntimeInstalled, shouldPrewarmSemantic, vectorsForBrain,
-  cachedVectorsForBrain,
+  cachedVectorsForBrain, startBrainPreparation, preparationNotice,
 } from './semantic-memory.mjs';
 
 // The MCP and A2A faces prewarm through this protocol-neutral module. Bounded
@@ -503,7 +503,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
     let struct;
     try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
     let vecs = null;
-    if (qv) { try { vecs = await vectorsForBrain(pipe, b.path, struct.cards); } catch { /* lexical for this brain */ } }
+    if (qv) { try { const r = await questionVectors(pipe, b.path, struct.cards); vecs = r.usable ? r.vecs : null; } catch { /* lexical for this brain */ } }
     for (const c of struct.cards) {
       if (c.type === 'container') continue;
       const t = String(c.text || '').toLowerCase();
@@ -765,8 +765,25 @@ export async function opBrainTaskContext({
   };
 }
 
+// Card meanings for a question, never waiting on a preparation (1.97.0): at
+// most a few seconds of embedding inline; whatever is still missing is handed
+// to the background preparation (startBrainPreparation) and the answer says
+// so (preparationNotice). Meaning ranking is used once at least
+// MEANING_READY_SHARE of the cards are ready — below that the keyword path
+// covers every card, which a mostly-unprepared meaning ranking would not.
+const MEANING_READY_SHARE = 0.5;
+async function questionVectors(pipe, file, cards) {
+  const stats = {};
+  const vecs = await vectorsForBrain(pipe, file, cards, { stats });
+  if (stats.pending > 0) startBrainPreparation(file);
+  const usable = Boolean(vecs && vecs.size) && (!stats.wanted || stats.ready / stats.wanted >= MEANING_READY_SHARE);
+  return { vecs, stats, usable };
+}
+
 export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log = () => {} }) {
-  const q = String(question || '').trim();
+  // A last line `Also: <words>` is the caller's guess at the card's wording; it
+  // joins the meaning query only (splitAskWords in klypix-format.mjs).
+  const { question: q, words } = splitAskWords(question);
   if (!q) return err('brain_ask needs a question.');
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
@@ -779,13 +796,14 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   // Semantic blend (best-effort, time-bounded): embed the question + the brain's
   // cards on-device, hand rankForQuestion a Map<cardId, cosine>. A missing/warming
   // model degrades cleanly to pure lexical.
-  let semantic = null, mode = 'lexical', cardVecs = null;
+  let semantic = null, mode = 'lexical', cardVecs = null, prep = null;
   try {
     const pipe = await getEmbedderForUse(log, 20_000);
     if (pipe) {
-      const [qv] = await embedTexts(pipe, [q], { kind: 'query' });
-      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
-      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = 'semantic+lexical (on-device)'; }
+      const [qv] = await embedTexts(pipe, [words ? `${q}\n${words}` : q], { kind: 'query' });
+      const { vecs, stats, usable } = await questionVectors(pipe, t.file, struct.cards);
+      prep = stats;
+      if (qv && usable) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = `semantic+lexical (on-device)${words ? ' + your Also words' : ''}`; }
     }
   } catch { semantic = null; cardVecs = null; }
   // Parity with search_all_brains (8445e9c): never say "warming — retry" to a
@@ -799,6 +817,8 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   if (!semantic) {
     fallbackNotice = semanticFallbackNotice(false);
     if (fallbackNotice) mode = fallbackNotice.startsWith('LEXICAL ONLY') ? 'lexical-only (no semantic runtime)' : 'lexical (semantic warming)';
+    if (prep?.pending > 0) mode = 'lexical (preparing search by meaning)';
+    if (words) mode += ' + your Also words';
   }
   const kk = Math.max(1, Math.min(20, k || 10));
   const timeTravel = asOfTs != null;
@@ -811,7 +831,7 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   // vectors that rank the question, reused; null degrades pairing to its
   // lexical anchor/coverage fallback (works on every host, embeddings or not).
   const pairSim = cardVecs ? (a, b) => { const va = cardVecs.get(a), vb = cardVecs.get(b); return va && vb ? dot(va, vb) : null; } : null;
-  const result = rankForQuestion(struct, q, { semantic, k: wantRerank ? Math.max(kk, 50) : kk, as_of: timeTravel ? as_of : null, pairSim });
+  const result = rankForQuestion(struct, q, { semantic, k: wantRerank ? Math.max(kk, 50) : kk, as_of: timeTravel ? as_of : null, pairSim, words });
   if (wantRerank && result.hits.length > 1) {
     try {
       const reranked = await withRerankerForUse(log, 8_000, rr => rerankHits(rr, q, result.hits));
@@ -846,7 +866,11 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
       mode += ' + status-mode';
     } catch { statusMd = ''; }
   }
-  const noticeMd = fallbackNotice ? `> ${fallbackNotice}\n\n` : '';
+  // While the brain is still being prepared, that is the one thing to say: the
+  // runtime IS installed, so the "warming — retry" fallback line would only
+  // repeat it less precisely.
+  const prepNotice = preparationNotice(t.file, prep, { usedMeaning: Boolean(semantic) });
+  const noticeMd = prepNotice ? `> ${prepNotice}\n\n` : (fallbackNotice ? `> ${fallbackNotice}\n\n` : '');
   const evidenceCache = new Map();
   const evidenceForCard = (card) => formatCardEvidence(inspectCardEvidence(card, { projectRoot: path.dirname(t.file), cache: evidenceCache }));
   return { blocks: [text(stamp + noticeMd + statusMd + questionContextToMarkdown(q, result, { mode, as_of: timeTravel ? as_of : null, evidenceForCard }))] };
@@ -871,8 +895,8 @@ export async function opBrainChallenge({ vault, canvas, claim, k = 8, via, log =
     const pipe = await getEmbedderForUse(log, 20_000);
     if (pipe) {
       const [qv] = await embedTexts(pipe, [q], { kind: 'query' });
-      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
-      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
+      const { vecs, usable } = await questionVectors(pipe, t.file, struct.cards);
+      if (qv && usable) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
     }
   } catch { semantic = null; }
   const result = challengeBrain(struct, q, { semantic, k: Math.max(1, Math.min(20, k || 8)) });
@@ -1160,7 +1184,11 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all', ref
         if (mode === 'plans' && cold && installed) {
           try {
             const pipe = await getEmbedderForUse(log, 20_000);
-            if (pipe) vecs = await vectorsForBrain(pipe, file, struct.cards);
+            if (pipe) {
+              const stats = {};
+              vecs = await vectorsForBrain(pipe, file, struct.cards, { stats });
+              if (stats.pending > 0) startBrainPreparation(file);
+            }
           } catch (e) { embedErr = e; }
         }
         let pairSim = null, how;
@@ -1696,7 +1724,9 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
   try { pipe = await getEmbedderForUse(log, 20_000); } catch { /* saturated/unavailable → structural */ }
   if (pipe) {
     try {
-      const vecs = await vectorsForBrain(pipe, file, struct.cards);
+      const stats = {};
+      const vecs = await vectorsForBrain(pipe, file, struct.cards, { stats });
+      if (stats.pending > 0) startBrainPreparation(file);
       const items = live.filter(c => vecs.get(c.id));
       const sources = normalizedScope === 'orphans' ? items.filter(c => orphanIds.has(c.id)) : items;
       for (const a of sources) {

package/src/klypix-format.mjs

@@ -4042,14 +4042,51 @@ export const deathDateOfCard = (card) => {
     const m = /(?:↩︎ superseded|↩ superseded|✅|⤵ consolidated) (\d{4}-\d{2}-\d{2})/.exec(String(c.text || ''));
     return m ? Date.parse(m[1]) : null;
 };
-export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), recentDays = 30, pairSim = null } = {}) {
+// THE CALLER'S WORDS (1.96.0). A question is worded the asker's way; the card
+// that answers it was worded the day it was written ("magnification controls"
+// vs a card that says "zoom"). The calling agent is itself a model, so brain_ask
+// invites it to add one last line `Also: <words a card answering this would
+// likely use>`. Those words join the MEANING query only (embedded together with
+// the question, one vector); the keyword anchor test, status shape and the
+// rendered question all stay the question's own. Measured 2026-10-11 on the
+// real 3,829-card brain, frozen v2 set (102 answerable), production embedder +
+// warm enrichment-aware vectors, model-written words: recall@5 55 → 60
+// (+8 −3), @8 62 → 69, @20 69 → 78, MRR .375 → .424. Fusing a separate words
+// vector by rank instead did less (+5 −2 at equal weight). Carried inside
+// `question` because no existing tool's input schema may change (see
+// test/tool-schema-freeze.mjs) — a new property would force every host to
+// reconnect; a line in the text works the moment the worker hot-swaps.
+export const ASK_WORDS_MAX = 240;
+// Keyword-only mode (no meaning model), same brain and set, words as extra
+// tokens, through splitAskWords: recall@5 19 → 24 of 102 at half weight with
+// none lost (@10 26 → 32); full weight lost a question the question alone
+// found. Measured 2026-10-11.
+export const ASK_WORDS_LEXICAL_WEIGHT = 0.5;
+export function splitAskWords(question) {
+    const whole = String(question || '').trim();
+    const lines = whole.split(/\r?\n/);
+    const last = lines.length > 1 ? /^\s*also\s*:\s*(.*)$/i.exec(lines[lines.length - 1]) : null;
+    const rest = last ? lines.slice(0, -1).join('\n').trim() : '';
+    // No words line, or nothing above it: the text is the question, untouched.
+    if (!last || !rest) return { question: whole, words: '' };
+    const words = last[1].replace(/\s+/g, ' ').trim().slice(0, ASK_WORDS_MAX).trim();
+    // An empty `Also:` line is dropped; words equal to the question add nothing.
+    return { question: rest, words: words.toLowerCase() === rest.toLowerCase() ? '' : words };
+}
+
+export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), recentDays = 30, pairSim = null, words = '' } = {}) {
     // Status-shaped questions score by their CONTENT tokens only — "remaining"
     // must never lexically select the stale cards that say "remaining:".
     const { content: tokens, statusShaped, strong: statusStrong, areaFamilies = [] } = splitQueryTokens(question);
+    // The caller's Also words (splitAskWords). With the meaning model they ride
+    // the query vector (opBrainAsk); WITHOUT it — a fresh install, the Claude
+    // plugin — they are extra keyword tokens at ASK_WORDS_LEXICAL_WEIGHT, after
+    // the question's own, so the question still leads.
+    const extra = words && !semantic ? splitQueryTokens(words).content.filter(t => !tokens.includes(t)) : [];
     // Area scope (1.85.0): this function HAS the struct, so it resolves the
     // prompt's static families to exact area titles for the status renderer.
     const areas = statusStrong ? areaHintsFromPrompt(struct, question) : null;
-    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !semantic)) return { hits: [], total: 0, tokens, statusShaped, statusStrong, areaFamilies, areas };
+    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !extra.length && !semantic)) return { hits: [], total: 0, tokens, statusShaped, statusStrong, areaFamilies, areas };
     const isArchived = (c) => /^archive$/i.test(c.area || '');
     const asOfTs = as_of ? Date.parse(as_of) : null;
     const timeTravel = asOfTs != null && Number.isFinite(asOfTs);
@@ -4087,6 +4124,10 @@ export function rankForQuestion(struct, question, { semantic = null, k = 10, as_
             else if (wordMatches(tagWords, tagStems, tok)) lex += 3;
             else if (wordMatches(bodyW, bodyStems, tok)) lex += lenNorm;
         }
+        for (const tok of extra) {
+            if (wordMatches(titleW, titleStems, tok) || wordMatches(tagWords, tagStems, tok)) lex += 3 * ASK_WORDS_LEXICAL_WEIGHT;
+            else if (wordMatches(bodyW, bodyStems, tok)) lex += lenNorm * ASK_WORDS_LEXICAL_WEIGHT;
+        }
         const sem = semantic ? (semantic.get(c.id) ?? null) : null;
         if (!semantic && lex <= 0) continue;
         if (semantic && lex <= 0 && sem == null) continue;

package/src/semantic-install.mjs

@@ -0,0 +1,84 @@
+// Search by meaning: what the installer installs, who gets it, and what it
+// trims afterwards. Pure helpers, kept out of bin/klypix-install.mjs because
+// that file runs the install the moment it is imported.
+//
+// Measured 2026-10-11 on a clean npm cache: ~150 MB download, ~20 s on a fast
+// line. Pruning what Node never loads (onnxruntime-web, other platforms' and
+// architectures' native binaries) leaves ~110 MB on disk instead of ~390 MB,
+// with the same answers and memory (load + 50 questions checked on the pruned
+// tree). The gain, on the real 102-question set: the right card in the top 5
+// for 54 questions with it, 19 without.
+import fs from 'fs';
+import path from 'path';
+
+// Same pins as the desktop app's electron/semanticInstaller.ts: an owned npm
+// tree, so a vulnerable sharp can never be resolved independently.
+export const SEMANTIC_RUNTIME_MANIFEST = Object.freeze({
+  name: 'klypix-semantic-runtime',
+  private: true,
+  version: '1.0.0',
+  dependencies: { '@huggingface/transformers': '4.2.0', sharp: '0.35.5' },
+  overrides: {
+    '@huggingface/transformers': { sharp: '$sharp' },
+    'onnxruntime-node': { 'adm-zip': '0.6.1' },
+    'onnxruntime-web': { protobufjs: '7.6.5' },
+  },
+});
+
+// Who gets it. A person at a terminal gets it unless they opt out; anything
+// without a terminal (CI, scripts, an agent running the install, the test
+// suite) only when it asks with --semantic. Plugin mode never: the Claude
+// plugin runs only its pinned package and downloads no models.
+export function semanticInstallDecision({ optOut, flag, runtimeOnly, plugin, present, ci, tty }) {
+  if (plugin) return 'skip-plugin';
+  if (optOut) return 'skip-optout';
+  if (present) return 'present';
+  if (flag) return 'install';
+  if (runtimeOnly) return 'skip-runtime-only';
+  if (ci) return 'skip-ci';
+  if (!tty) return 'skip-noninteractive';
+  return 'install';
+}
+
+export function dirBytes(dir) {
+  let total = 0;
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) total += dirBytes(p);
+    else { try { total += fs.statSync(p).size; } catch { /* gone */ } }
+  }
+  return total;
+}
+
+// Remove what Node never loads. Touches only <semanticDir>/node_modules, and
+// never removes the running platform's binary for the running architecture
+// (a tree without it is left alone rather than pruned to nothing).
+export function pruneSemanticRuntime(semanticDir, platform = process.platform, arch = process.arch) {
+  const nm = path.join(semanticDir, 'node_modules');
+  let freed = 0;
+  const drop = (p) => {
+    try { fs.statSync(p); } catch { return; }
+    freed += dirBytes(p);
+    fs.rmSync(p, { recursive: true, force: true });
+  };
+  drop(path.join(nm, 'onnxruntime-web'));
+  const binRoot = path.join(nm, 'onnxruntime-node', 'bin');
+  let napis = [];
+  try { napis = fs.readdirSync(binRoot); } catch { /* none */ }
+  for (const napi of napis) {
+    let platforms = [];
+    try { platforms = fs.readdirSync(path.join(binRoot, napi)); } catch { continue; }
+    if (!platforms.includes(platform)) continue;
+    for (const plat of platforms) {
+      const platDir = path.join(binRoot, napi, plat);
+      if (plat !== platform) { drop(platDir); continue; }
+      let arches = [];
+      try { arches = fs.readdirSync(platDir); } catch { continue; }
+      if (!arches.includes(arch)) continue;
+      for (const a of arches) if (a !== arch) drop(path.join(platDir, a));
+    }
+  }
+  return freed;
+}

package/src/semantic-memory.mjs

@@ -10,6 +10,8 @@ import path from 'path';
 import crypto from 'crypto';
 import { enrichmentTextFor, readEnrichment } from './enrichment.mjs';
 import { createRequire } from 'module';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 import * as autoUpdateLib from './mcp-auto-update.mjs';
 
 // Plugin mode (KLYPIX_PLUGIN=1) never loads the on-device semantic runtime:
@@ -42,7 +44,13 @@ const intEnv = (name, fallback, min, max) => {
   const n = Number(process.env[name]);
   return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.trunc(n))) : fallback;
 };
-const EMBED_BATCH_SIZE = intEnv('KLYPIX_EMBED_BATCH_SIZE', 16, 1, 64);
+// One card per inference call. A batch pads every card to its longest member
+// (cards run up to 1,500 characters), so batching wastes work on a brain's
+// mixed lengths. Measured 2026-10-11, real bge-small q8, 400 real cards on a
+// laptop CPU: batch 16 = 96 ms a card, 1,176 MB peak; 8 = 79 ms, 720 MB;
+// 4 = 63–70 ms, ~505 MB; 1 = 41–49 ms, ~305 MB. The fastest is also the lightest.
+export const EMBED_BATCH_DEFAULT = 1;
+const EMBED_BATCH_SIZE = intEnv('KLYPIX_EMBED_BATCH_SIZE', EMBED_BATCH_DEFAULT, 1, 64);
 const RERANK_BATCH_SIZE = intEnv('KLYPIX_RERANK_BATCH_SIZE', 4, 1, 32);
 const MAX_INFERENCE_QUEUE = intEnv('KLYPIX_SEMANTIC_MAX_QUEUE', 16, 1, 256);
 const idleRaw = process.env.KLYPIX_SEMANTIC_IDLE_MS;
@@ -351,13 +359,12 @@ export function semanticFallbackNotice(hadSemantic) {
   if (semanticRuntimeInstalled()) {
     return 'lexical only — the on-device semantic model is still warming or the queue is saturated; retry shortly for semantic ranking';
   }
-  // Deliberately names no install command: there is no `--semantic` flag, and
-  // bin/klypix-install.mjs skips @huggingface/transformers on purpose ("optional,
-  // huge"). Inventing a command here would ship a wrong instruction to every
-  // MCP host. State the fact and the location; let the caller decide.
-  return 'LEXICAL ONLY — @huggingface/transformers is not present, so these are keyword matches with no semantic ranking. '
-    + 'Measured on a real 2,377-card brain: recall@5 0% lexical vs ~30% with the runtime. Retrying will not help. '
-    + `Semantic ranking activates once the runtime resolves, or is placed at ${path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers')}.`;
+  // Since 1.97.0 there IS an install command (bin/klypix-install.mjs --semantic,
+  // which a person at a terminal gets by default), so the notice names it: an
+  // agent reading this can offer it to the person instead of guessing.
+  return 'LEXICAL ONLY — search by meaning is not installed, so these are keyword matches. '
+    + 'Measured on a real 3,829-card brain: the right card in the top 5 for 19 of 102 questions with keywords, 54 with search by meaning. Retrying will not help. '
+    + 'Turn it on with: npx klypix-mcp install --semantic (about 150 MB to download, once).';
 }
 
 export function getEmbedder(log = () => {}) {
@@ -500,11 +507,11 @@ function cacheCandidates(brainPath) {
 
 const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 
-async function withCrossProcessCacheLock(brainPath, fn) {
+async function withCrossProcessCacheLock(brainPath, fn, timeoutMs = CACHE_LOCK_TIMEOUT_MS) {
   const file = cacheCandidates(brainPath)[0].file;
   const lockFile = `${file}.lock`;
   fs.mkdirSync(EMB_DIR, { recursive: true });
-  const deadline = Date.now() + CACHE_LOCK_TIMEOUT_MS;
+  const deadline = Date.now() + timeoutMs;
   let handle = null;
   let waited = false;
   while (!handle) {
@@ -527,7 +534,10 @@ async function withCrossProcessCacheLock(brainPath, fn) {
       await wait(75);
     }
   }
-  try { return await fn(); }
+  // A long holder (the background preparation) refreshes the lock so it is
+  // never mistaken for an abandoned one at CACHE_LOCK_STALE_MS.
+  const touch = () => { try { const now = new Date(); fs.utimesSync(lockFile, now, now); } catch { /* best-effort */ } };
+  try { return await fn(touch); }
   finally {
     try { fs.closeSync(handle); } catch { /* */ }
     try { fs.unlinkSync(lockFile); } catch { /* stale cleanup handles leftovers */ }
@@ -658,7 +668,23 @@ function readCache(brainPath, accept) {
   };
 }
 
-async function vectorsForBrainUnlocked(pipe, brainPath, cards) {
+// PREPARING A BRAIN NEVER HOLDS A QUESTION (1.97.0). Embedding every card of a
+// fresh brain takes ~110 ms a card on a laptop CPU (measured 2026-10-11: 100
+// cards 11 s, 3,670 cards 6.8 min), and the old writer did it inside the first
+// question and saved nothing until the end — the agent's call waited minutes
+// and an interrupted run lost everything. Now an interactive caller embeds at
+// most INTERACTIVE_EMBED_BUDGET missing cards (a few seconds) and gets back
+// what is ready; the rest is prepared by the detached, low-priority warm
+// process (bin/klypix-semantic-warm.mjs, maxEmbed: Infinity), which saves as
+// it goes so progress survives an interruption and readers see it.
+export const INTERACTIVE_EMBED_BUDGET = 32;
+const INTERACTIVE_LOCK_WAIT_MS = 3_000;
+const PERSIST_EVERY_MS = 15_000;
+const EMBED_CHUNK = 64;
+
+async function vectorsForBrainUnlocked(pipe, brainPath, cards, opts = {}) {
+  const maxEmbed = Number.isFinite(opts.maxEmbed) ? Math.max(0, opts.maxEmbed) : (opts.maxEmbed === Infinity ? Infinity : INTERACTIVE_EMBED_BUDGET);
+  const stats = opts.stats && typeof opts.stats === 'object' ? opts.stats : {};
   const want = cards.filter((card) => card.type !== 'container' && (card.text || '').trim());
   // Question enrichment (1.77): the prompt/intent that produced a card is
   // appended to its EMBED input — the asker's own vocabulary bridging the
@@ -692,26 +718,51 @@ ${extra}` : base;
     if (entry.t !== textHashes.get(card.id)) { entry.t = textHashes.get(card.id); repaired++; }
   }
   if (repaired) dirty = true;
-  const missing = want.filter((card) => cache.cards[card.id]?.h !== desiredHashes.get(card.id));
-  if (missing.length) {
-    let vectors;
-    try { vectors = await embedTexts(pipe, missing.map((card) => embedInputFor(card))); }
-    catch (error) {
-      // The repair above needs no model, so it lands even when the embed does
-      // not. Everything the merge refused goes back beside it: those vectors
-      // are still on disk and a reader may still accept them through `t`.
-      // The persisted file is a superset snapshot: it can contain refused
-      // entries and entries for deleted cards. Readers reject them through
-      // the acceptance rule, and the next write that is dirty for another
-      // reason trims them.
-      if (repaired) await persistCache(file, { ...cache, cards: { ...loaded.held, ...cache.cards } });
-      throw error;
+  // Newest first: the cards people ask about most are ready soonest.
+  const missing = want
+    .filter((card) => cache.cards[card.id]?.h !== desiredHashes.get(card.id))
+    .sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+  const toEmbed = maxEmbed === Infinity ? missing : missing.slice(0, maxEmbed);
+  stats.wanted = want.length;
+  stats.embedded = 0;
+  stats.pending = missing.length - toEmbed.length;
+  if (toEmbed.length) {
+    let lastPersist = Date.now();
+    for (let offset = 0; offset < toEmbed.length; offset += EMBED_CHUNK) {
+      const chunk = toEmbed.slice(offset, offset + EMBED_CHUNK);
+      let vectors;
+      try { vectors = await embedTexts(pipe, chunk.map((card) => embedInputFor(card))); }
+      catch (error) {
+        // The repair above needs no model, so it lands even when the embed does
+        // not, and so do the chunks already embedded. Everything the merge
+        // refused goes back beside them: those vectors are still on disk and a
+        // reader may still accept them through `t`. The persisted file is a
+        // superset snapshot: it can contain refused entries and entries for
+        // deleted cards. Readers reject them through the acceptance rule, and
+        // the next write that is dirty for another reason trims them.
+        if (repaired || stats.embedded) await persistCache(file, { ...cache, cards: { ...loaded.held, ...cache.cards } });
+        stats.pending = missing.length - stats.embedded;
+        throw error;
+      }
+      chunk.forEach((card, index) => {
+        cache.cards[card.id] = { h: desiredHashes.get(card.id), t: textHashes.get(card.id), v: vectors[index] };
+      });
+      stats.embedded += chunk.length;
+      dirty = true;
+      if (typeof opts.touch === 'function') opts.touch();
+      const more = offset + EMBED_CHUNK < toEmbed.length;
+      // Save as it goes, so a long preparation survives an interruption and
+      // readers (cachedVectorsForBrain) see the progress.
+      if (more && Date.now() - lastPersist >= PERSIST_EVERY_MS) {
+        await persistCache(file, { ...cache, cards: { ...loaded.held, ...cache.cards } });
+        lastPersist = Date.now();
+      }
+      if (typeof opts.onProgress === 'function') {
+        try { opts.onProgress({ done: want.length - (missing.length - stats.embedded), total: want.length }); } catch { /* progress is advisory */ }
+      }
     }
-    missing.forEach((card, index) => {
-      cache.cards[card.id] = { h: desiredHashes.get(card.id), t: textHashes.get(card.id), v: vectors[index] };
-    });
-    dirty = true;
   }
+  stats.ready = want.length - stats.pending;
   const live = new Set(want.map((card) => card.id));
   for (const id of Object.keys(cache.cards)) {
     if (!live.has(id)) { delete cache.cards[id]; dirty = true; }
@@ -725,6 +776,72 @@ ${extra}` : base;
   return map;
 }
 
+// ── Background preparation: start it, read how far it got ────────────────────
+// startBrainPreparation spawns the detached, low-priority warm process for ONE
+// brain (--only: a question never makes this machine prepare every registered
+// project). At most once a minute per brain from this process; the warm
+// process's own lock makes a second start a no-op. The warm writes its
+// progress to WARM_STATUS_FILE while it runs; brainPreparationStatus reads it
+// so an answer can say how far along the preparation is.
+const WARM_STATUS_FILE = path.join(PB_DIR, '.semantic-update-warm.json');
+const WARM_STALE_MS = 2 * 60_000;
+const lastPreparationStart = new Map();
+
+export function startBrainPreparation(brainPath, { spawnFn = spawn, now = Date.now() } = {}) {
+  if (semanticDisabledByPlugin()) return false;
+  const key = canonicalBrainKey(brainPath);
+  if (now - (lastPreparationStart.get(key) || 0) < 60_000) return false;
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const script = [path.join(here, 'klypix-semantic-warm.mjs'), path.join(here, '..', 'bin', 'klypix-semantic-warm.mjs')]
+    .find((file) => fs.existsSync(file));
+  if (!script) return false;
+  lastPreparationStart.set(key, now);
+  try {
+    const child = spawnFn(process.execPath, [script, '--brain-dir', PB_DIR, '--brain', path.resolve(brainPath), '--only'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env: { ...process.env },
+    });
+    child.unref?.();
+    return true;
+  } catch { return false; }
+}
+
+export function brainPreparationStatus(brainPath, { now = Date.now(), statusFile = WARM_STATUS_FILE } = {}) {
+  try {
+    const status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+    if (status?.result !== 'preparing' || typeof status.brain !== 'string') return null;
+    if (canonicalBrainKey(status.brain) !== canonicalBrainKey(brainPath)) return null;
+    const updated = Date.parse(status.updatedAt || '');
+    if (!Number.isFinite(updated) || now - updated > WARM_STALE_MS) return null; // the run died
+    const done = Number(status.done) || 0, total = Number(status.total) || 0;
+    const started = Date.parse(status.startedAt || '');
+    const ratePerMs = done > 0 && Number.isFinite(started) && updated > started ? done / (updated - started) : null;
+    return { done, total, remainingMs: ratePerMs && total > done ? Math.round((total - done) / ratePerMs) : null };
+  } catch { return null; }
+}
+
+// One sentence an answer carries while a brain is being prepared. `stats`
+// comes from vectorsForBrain; the live progress, when the warm reports it,
+// is fresher.
+export function preparationNotice(brainPath, stats, { usedMeaning = false, now = Date.now() } = {}) {
+  if (!stats || !(stats.pending > 0)) return null;
+  const live = brainPreparationStatus(brainPath, { now });
+  const total = live?.total || stats.wanted || 0;
+  const done = live ? live.done : (stats.ready || 0);
+  const minutes = live?.remainingMs != null
+    ? Math.max(1, Math.round(live.remainingMs / 60_000))
+    // ~45 ms a card measured one at a time; ~0.1 s leaves room for a busy
+    // machine and the low-priority run until the live rate is known.
+    : Math.max(1, Math.round(((total - done) * 0.1) / 60));
+  const n = (x) => Number(x).toLocaleString('en-US');
+  return `Getting this brain ready for search by meaning: ${n(done)} of ${n(total)} cards so far, about ${minutes} min left. `
+    + (usedMeaning
+      ? 'This answer used the cards that are ready plus keywords; it gets better as the rest finish.'
+      : 'This answer used keyword search; ask again when it is done for better matches.');
+}
+
 // READ-ONLY card vectors from the warm cache: never loads the model, never
 // embeds a missing card, never writes. For fast paths (brain_sync task context)
 // that may USE card↔card similarity when it is already paid for — plan ↔ 🏁
@@ -771,16 +888,32 @@ export function cachedVectorsForBrain(brainPath, cards) {
   return map;
 }
 
-export async function vectorsForBrain(pipe, brainPath, cards) {
-  if (!BOUNDED) return vectorsForBrainUnlocked(pipe, brainPath, cards);
+// opts.maxEmbed: how many missing cards this call may embed — the interactive
+// default is INTERACTIVE_EMBED_BUDGET; the background warm passes Infinity.
+// opts.stats receives { wanted, ready, embedded, pending }; opts.onProgress
+// gets { done, total } after each saved chunk.
+export async function vectorsForBrain(pipe, brainPath, cards, opts = {}) {
+  if (!BOUNDED) return vectorsForBrainUnlocked(pipe, brainPath, cards, opts);
   const key = canonicalBrainKey(brainPath);
   const previous = vectorBuildTails.get(key) || Promise.resolve();
+  // A question never waits behind a preparation: it gets INTERACTIVE_LOCK_WAIT_MS,
+  // then reads what the preparation has saved so far (below).
+  const interactive = opts.maxEmbed !== Infinity;
   const run = previous.catch(() => {}).then(() => withCrossProcessCacheLock(
     brainPath,
-    () => vectorsForBrainUnlocked(pipe, brainPath, cards),
+    (touch) => vectorsForBrainUnlocked(pipe, brainPath, cards, { ...opts, touch }),
+    interactive ? INTERACTIVE_LOCK_WAIT_MS : CACHE_LOCK_TIMEOUT_MS,
   ));
   vectorBuildTails.set(key, run);
   try { return await run; }
+  catch (error) {
+    if (!interactive || error?.code !== 'KLYPIX_SEMANTIC_CACHE_BUSY') throw error;
+    // The background preparation holds the lock: answer from what it has saved.
+    const map = cachedVectorsForBrain(brainPath, cards);
+    const wanted = cards.filter((card) => card && card.type !== 'container' && typeof card.text === 'string' && card.text.trim()).length;
+    if (opts.stats && typeof opts.stats === 'object') Object.assign(opts.stats, { wanted, ready: map.size, embedded: 0, pending: Math.max(0, wanted - map.size), busy: true });
+    return map;
+  }
   finally { if (vectorBuildTails.get(key) === run) vectorBuildTails.delete(key); }
 }