clawmem 0.16.0 → 0.18.0

package/AGENTS.md

@@ -19,6 +19,7 @@ Three services — **embedding**, **LLM** (query expansion / intent / A-MEM), **
 - The zerank-2 **GGUF is inert** — llama.cpp drops the score head → ranking silently collapses to RRF. Use the **seq-cls sidecar**; verify with `clawmem rerank-health` (liveness ≠ correctness).
 - `-ub` must equal `-b` for embedding/reranking (non-causal attention) or `llama-server` asserts.
 - Changing embedding dimensions → `clawmem embed --force` (full re-embed).
+- Changing the embedding **model** (even at the same dimension) → `clawmem embed --force`; querying otherwise now throws `VecReadModelMismatchError` instead of serving cosine-meaningless results (v0.18.0).
 - `CLAWMEM_NO_LOCAL_MODELS=true` to fail fast instead of silent CPU fallback.
 
 → Stack decision matrix + server setup: [docs/guides/inference-services.md](docs/guides/inference-services.md) · cloud: [docs/guides/cloud-embedding.md](docs/guides/cloud-embedding.md) · all env vars: [docs/reference/configuration.md](docs/reference/configuration.md).

package/README.md

@@ -782,10 +782,12 @@ Notes referenced by the agent during a session get boosted (`access_count++`). U
 | `CLAWMEM_EMBED_TPM_LIMIT` | `100000` | Tokens-per-minute limit for cloud embedding pacing. Match to your provider tier. |
 | `CLAWMEM_EMBED_DIMENSIONS` | (none) | Output dimensions for OpenAI `text-embedding-3-*` Matryoshka models (e.g. `512`, `1024`). |
 | `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server URL for intent/query/A-MEM. Without it, falls to `node-llama-cpp` (if allowed). |
+| `CLAWMEM_LLM_API_KEY` | (none) | Bearer token for an authenticated remote LLM endpoint. Independent of the embed and rerank keys. |
 | `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent to the configured LLM endpoint. Override this for OpenAI-compatible proxies such as `gpt-5.4-mini`. |
 | `CLAWMEM_LLM_REASONING_EFFORT` | (none) | Optional top-level `reasoning_effort` field for Chat Completions endpoints that support it (for example OpenAI reasoning models). Leave unset for llama-server/vLLM unless your serving stack explicitly accepts that field. |
 | `CLAWMEM_LLM_NO_THINK` | `true` | Append `/no_think` to remote LLM prompts. Set to `false` for standard OpenAI models and other endpoints that reject or treat the Qwen-style suffix as literal prompt text. |
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server URL. Without it, falls to `node-llama-cpp` (if allowed). |
+| `CLAWMEM_RERANK_API_KEY` | (none) | Bearer token for an authenticated remote reranker endpoint. Independent of the embed and LLM keys. |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Block `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups where you want fail-fast on unreachable endpoints. |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 consolidation merge-safety threshold when candidate and existing anchors align. Merges above this normalized 3-gram cosine score are allowed. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety threshold — fallback when anchor sets are ambiguous. |

package/docs/reference/cli.md

@@ -169,10 +169,12 @@ The session ID is resolved from `--session-id <id>`, then `CLAUDE_SESSION_ID`, t
 | `CLAWMEM_EMBED_TPM_LIMIT` | `100000` | Tokens-per-minute limit for cloud embedding pacing |
 | `CLAWMEM_EMBED_DIMENSIONS` | — | Output dimensions for OpenAI `text-embedding-3-*` models |
 | `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server |
+| `CLAWMEM_LLM_API_KEY` | — | Bearer token for an authenticated remote LLM endpoint |
 | `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent to the configured LLM endpoint |
 | `CLAWMEM_LLM_REASONING_EFFORT` | — | Optional top-level `reasoning_effort` field for Chat Completions endpoints that support it (for example OpenAI reasoning models). Leave unset for llama-server/vLLM unless explicitly supported. |
 | `CLAWMEM_LLM_NO_THINK` | `true` | Append `/no_think` to remote prompts; set `false` for standard OpenAI models and other endpoints that reject or treat it as literal prompt text |
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server |
+| `CLAWMEM_RERANK_API_KEY` | — | Bearer token for an authenticated remote reranker endpoint |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Block node-llama-cpp auto-downloads |
 | `CLAWMEM_PROFILE` | `balanced` | Performance profile: `speed` (BM25 only), `balanced` (BM25+vector), `deep` (BM25+vector+expansion+reranking) |
 | `CLAWMEM_VAULTS` | — | JSON map of vault name to SQLite path |

package/docs/reference/configuration.md

@@ -12,7 +12,9 @@ See also: [../guides/inference-services.md](../guides/inference-services.md) (st
 |---|---|---|
 | `CLAWMEM_EMBED_URL` | `http://localhost:8088` | Embedding server URL. Local `llama-server`, cloud API, or in-process `node-llama-cpp` fallback if unset. |
 | `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server for intent, expansion, A-MEM, entity extraction. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. Point at a 7B+ model or cloud API during `reindex --enrich` for better entity extraction. |
+| `CLAWMEM_LLM_API_KEY` | (none) | Bearer token for an authenticated remote LLM endpoint. Independent of the embed/rerank keys — set it when the LLM points at a different authenticated host. |
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. |
+| `CLAWMEM_RERANK_API_KEY` | (none) | Bearer token for an authenticated remote reranker endpoint. Independent of the embed/LLM keys. |
 | `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent on LLM requests. |
 | `CLAWMEM_LLM_REASONING_EFFORT` | (none) | Top-level `reasoning_effort` for Chat Completions endpoints that support it (e.g. a remote reasoning model). Optional. |
 | `CLAWMEM_LLM_NO_THINK` | enabled | Appends `/no_think` to remote LLM prompts (Qwen3 emits thinking tokens by default). Set `false` for standard OpenAI-compatible models that would treat `/no_think` as literal text. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "On-device memory layer for AI agents. Claude Code, OpenClaw, and Hermes. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -9,6 +9,8 @@ import { resolve as pathResolve, basename } from "path";
 import {
   createStore,
   prewarmVectors,
+  startPeriodicPrewarm,
+  resolvePrewarmIntervalMs,
   enableProductionMode,
   getDefaultDbPath,
   canonicalDocId,
@@ -1071,6 +1073,15 @@ function printResults(results: Array<{ displayPath: string; title: string; compo
 // Hook dispatch
 // =============================================================================
 
+// B3: the context-surfacing UserPromptSubmit hook runs under a tight budget
+// (8s repo default). Its OWN writes — dedup UPSERT, context_usage, recall
+// events, co-activations — are all best-effort/fail-open, but under writer
+// contention each could otherwise wait up to the store default busy_timeout
+// (5000ms) and blow the budget. Cap this process's busy_timeout so a contended
+// write fails fast (SQLITE_BUSY → skipped by the fail-open guards) instead of
+// stalling. Reads are unaffected (WAL readers never wait on the write lock).
+const CONTEXT_SURFACING_WRITE_BUSY_TIMEOUT_MS = 1500;
+
 async function cmdHook(args: string[]) {
   const hookName = args[0];
   if (!hookName) die("Usage: clawmem hook <name>");
@@ -1082,6 +1093,11 @@ async function cmdHook(args: string[]) {
   try {
     switch (hookName) {
       case "context-surfacing":
+        // Scope the small busy_timeout to THIS process only. Each `clawmem
+        // hook` invocation runs exactly one hook, so the Stop hooks
+        // (decision-extractor / handoff-generator / feedback-loop, 30s budget)
+        // run in separate processes and keep the store default (5000ms).
+        try { s.db.exec(`PRAGMA busy_timeout = ${CONTEXT_SURFACING_WRITE_BUSY_TIMEOUT_MS}`); } catch { /* non-fatal */ }
         output = await contextSurfacing(s, input);
         break;
       case "session-bootstrap":
@@ -1831,6 +1847,7 @@ async function cmdWatch() {
   let stopHeavyLane: (() => Promise<void>) | null = null;
   let watcherHandle: { close: () => void } | null = null;
   let checkpointTimerHandle: Timer | null = null;
+  let prewarmTimerHandle: ReturnType<typeof setInterval> | null = null;
 
   // Graceful shutdown — stop workers, close watchers, then exit. SIGTERM
   // handling is critical for systemd `systemctl --user stop` to shut down
@@ -1839,6 +1856,13 @@ async function cmdWatch() {
   // its own withWorkerLease finally block before we close the store.
   const shutdown = async (signal: string) => {
     console.log(`\n${c.dim}[watch] Received ${signal}, shutting down...${c.reset}`);
+    // Clear the periodic prewarm FIRST — before the awaited worker drains below. The timer is
+    // unref'd but still fires while the loop is alive; a tick landing mid-drain would run the
+    // synchronous ~1.5 GB scan and delay shutdown. Clearing it here is the only guard against that.
+    if (prewarmTimerHandle) {
+      clearInterval(prewarmTimerHandle);
+      prewarmTimerHandle = null;
+    }
     if (stopHeavyLane) {
       await stopHeavyLane();
       stopHeavyLane = null;
@@ -1901,6 +1925,21 @@ async function cmdWatch() {
     } catch { /* best-effort: unexpected SQL error */ }
   }, 0);
 
+  // B5 Option C: keep the vector payload warm against OS page-cache eviction BETWEEN hook calls.
+  // The one-shot prewarm above warms once; on a long-running host under memory pressure the kernel
+  // can evict the payload and let a cold synchronous MATCH creep back into the context-surfacing
+  // hook path. Re-touching the pages on an interval biases the kernel LRU toward keeping them
+  // resident (a PROBABILITY reduction, not a hard cap — the hard cap is the deferred BACKLOG
+  // Source 46 daemon). Cleared FIRST in shutdown(); the handle is unref'd so it never keeps the
+  // process alive by itself. resolvePrewarmIntervalMs enforces a strict parse + 60s floor so a
+  // stray tiny value (e.g. "1", or "1e3" which parseInt would read as 1) cannot schedule a
+  // near-continuous scan loop. Set CLAWMEM_PREWARM_INTERVAL_MS=0 to disable. Default 10 min.
+  const prewarmIntervalMs = resolvePrewarmIntervalMs(Bun.env.CLAWMEM_PREWARM_INTERVAL_MS);
+  prewarmTimerHandle = startPeriodicPrewarm(s.db, prewarmIntervalMs);
+  if (prewarmTimerHandle) {
+    console.log(`${c.dim}[watch] periodic vector prewarm every ${Math.round(prewarmIntervalMs / 1000)}s${c.reset}`);
+  }
+
   watcherHandle = startWatcher(dirs, {
     debounceMs: 2000,
     onChanged: async (fullPath, event) => {

package/src/consolidation.ts

@@ -15,6 +15,7 @@
 import type { Store } from "./store.ts";
 import type { LlamaCpp } from "./llm.ts";
 import { extractJsonFromLLM } from "./amem.ts";
+import { isSchemaPlaceholder } from "./schema-placeholder.ts";
 import { hashContent } from "./indexer.ts";
 import { passesMergeSafety } from "./text-similarity.ts";
 import { withWorkerLease } from "./worker-lease.ts";
@@ -68,6 +69,8 @@ export interface DeductiveSynthesisStats {
   unsupportedRejects: number;
   /** Drafts rejected because the conclusion was empty/trivial */
   emptyRejects: number;
+  /** Drafts rejected because the conclusion echoed the schema skeleton residue (anti-parrot) */
+  placeholderRejects: number;
   /** Accepted drafts that were then skipped as deductive dedupe duplicates */
   dedupSkipped: number;
   /**
@@ -93,6 +96,7 @@ function emptyDeductiveStats(considered: number = 0): DeductiveSynthesisStats {
     invalidIndexRejects: 0,
     unsupportedRejects: 0,
     emptyRejects: 0,
+    placeholderRejects: 0,
     dedupSkipped: 0,
     validatorFallbackAccepts: 0,
   };
@@ -1030,11 +1034,12 @@ For each valid deduction:
 2. List the premises (which observations support it)
 3. List the source indices (1-indexed)
 
-Return ONLY valid JSON array:
+Return ONLY a JSON array in this shape (structure only — replace every {{...}} with real content
+drawn from the observations above; never emit the {{...}} tokens or any schema text literally):
 [
   {
-    "conclusion": "Clear deductive statement",
-    "premises": ["Premise from obs 1", "Premise from obs 3"],
+    "conclusion": "{{new conclusion combining 2+ observations, 1-2 sentences}}",
+    "premises": ["{{fact from one source observation}}", "{{fact from another}}"],
     "source_indices": [1, 3]
   }
 ]
@@ -1073,6 +1078,18 @@ Return ONLY the JSON array. /no_think`;
       continue;
     }
 
+    // Anti-parrot: reject a draft whose conclusion echoes the JSON skeleton's placeholder residue
+    // ({{...}} tokens / "clear deductive statement") before the expensive validator runs. Premises
+    // that are placeholder residue are filtered (non-fatal — the conclusion carries the deduction).
+    if (isSchemaPlaceholder(deduction.conclusion)) {
+      stats.rejected++;
+      stats.placeholderRejects++;
+      continue;
+    }
+    if (Array.isArray(deduction.premises)) {
+      deduction.premises = deduction.premises.filter(p => typeof p === "string" && !isSchemaPlaceholder(p));
+    }
+
     const sourceDocIds = [...new Set(
       deduction.source_indices
         .filter(i => i >= 1 && i <= recentObs.length)

package/src/conversation-synthesis.ts

@@ -28,6 +28,7 @@
 import type { Store } from "./store.ts";
 import type { LlamaCpp } from "./llm.ts";
 import { extractJsonFromLLM } from "./amem.ts";
+import { isSchemaPlaceholder } from "./schema-placeholder.ts";
 import type { ContentType } from "./memory.ts";
 
 // =============================================================================
@@ -179,7 +180,7 @@ For each fact provide:
 - contentType: one of [decision, preference, milestone, problem]
 - narrative: 1-3 sentence description of the fact in context
 - facts: optional array of supporting fact strings (evidence)
-- aliases: optional alternative titles for linking (e.g., ["OAuth choice"] for "Use OAuth 2.0")
+- aliases: optional alternative titles for linking (help match this fact to related ones)
 - links: optional array of cross-fact references. Each link is
   {targetTitle, relationType, weight}
   - targetTitle may refer to another fact extracted from this conversation OR from
@@ -189,18 +190,20 @@ For each fact provide:
   - weight is 0.0-1.0 (default 0.6)
 
 Only extract facts the conversation clearly supports. Do NOT fabricate.
+Never copy the {{...}} tokens or any schema text below into your output — replace every {{...}}
+with real content drawn from the conversation. Emit only real extracted facts.
 Return ONLY valid JSON array. Return empty array [] if no structured facts found.
 
-Example output:
+Shape (structure only — not example content):
 [
   {
-    "title": "Use OAuth 2.0 with PKCE",
-    "contentType": "decision",
-    "narrative": "Team decided to use OAuth 2.0 with PKCE for user authentication, replacing session cookies.",
-    "facts": ["PKCE chosen for mobile support", "Legacy session auth to be deprecated Q2"],
-    "aliases": ["OAuth decision", "switch to OAuth"],
+    "title": "{{concise 3-8 word title}}",
+    "contentType": "{{one of: decision, preference, milestone, problem}}",
+    "narrative": "{{1-3 sentence description of the fact in context}}",
+    "facts": ["{{supporting evidence string}}"],
+    "aliases": ["{{optional alternative title}}"],
     "links": [
-      { "targetTitle": "Deprecate session auth", "relationType": "causal", "weight": 0.8 }
+      { "targetTitle": "{{another fact's title}}", "relationType": "{{one of: semantic, supporting, contradicts, causal, temporal, entity}}", "weight": 0.6 }
     ]
   }
 ]`;
@@ -219,6 +222,8 @@ function normalizeExtractedFact(
 
   const title = typeof obj.title === "string" ? obj.title.trim() : "";
   if (!title) return null;
+  // Anti-parrot: reject a fact whose title is echoed schema/skeleton residue.
+  if (isSchemaPlaceholder(title)) return null;
 
   const contentType = obj.contentType;
   if (typeof contentType !== "string") return null;
@@ -226,13 +231,14 @@ function normalizeExtractedFact(
 
   const narrative = typeof obj.narrative === "string" ? obj.narrative.trim() : "";
   if (!narrative) return null;
+  if (isSchemaPlaceholder(narrative)) return null;
 
   const facts: string[] = Array.isArray(obj.facts)
-    ? obj.facts.filter((f): f is string => typeof f === "string" && f.trim().length > 0)
+    ? obj.facts.filter((f): f is string => typeof f === "string" && f.trim().length > 0 && !isSchemaPlaceholder(f))
     : [];
 
   const aliases: string[] = Array.isArray(obj.aliases)
-    ? obj.aliases.filter((a): a is string => typeof a === "string" && a.trim().length > 0)
+    ? obj.aliases.filter((a): a is string => typeof a === "string" && a.trim().length > 0 && !isSchemaPlaceholder(a))
     : [];
 
   const links: ExtractedFactLink[] = Array.isArray(obj.links)

package/src/hooks/context-surfacing.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Store, SearchResult } from "../store.ts";
-import { DEFAULT_EMBED_MODEL, DEFAULT_QUERY_MODEL, DEFAULT_RERANK_MODEL, extractSnippet, resolveStore } from "../store.ts";
+import { DEFAULT_EMBED_MODEL, DEFAULT_QUERY_MODEL, DEFAULT_RERANK_MODEL, warnOnceOnVectorModelMismatch, extractSnippet, resolveStore } from "../store.ts";
 import { getVaultPath, getActiveProfile } from "../config.ts";
 import type { HookInput, HookOutput } from "../hooks.ts";
 import {
@@ -149,6 +149,21 @@ export async function contextSurfacing(
   const tokenBudget = profile.tokenBudget;
   const startTime = Date.now();
 
+  // High-fix (B3): the hook's writes to the MAIN store are bounded by the
+  // busy_timeout cmdHook set for this process (1500ms for context-surfacing).
+  // But skill-vault stores are opened separately via resolveStore(), which
+  // would otherwise use the 5000ms operational default — so a contended
+  // skill-vault write (the recall mirror below) could still stall the hook up
+  // to 5s. Inherit the main store's current cap and pass it to EVERY
+  // skill-vault open so those opens/writes are bounded identically. (Reads are
+  // WAL-safe regardless; this primarily bounds the mirror write.)
+  let hookBusyTimeout = 5000;
+  try {
+    const bt = (store.db.prepare("PRAGMA busy_timeout").get() as { timeout?: number } | undefined)?.timeout;
+    if (typeof bt === "number" && bt > 0) hookBusyTimeout = bt;
+  } catch { /* keep default */ }
+  const skillStoreOpts = { busyTimeout: hookBusyTimeout };
+
   // §11.4: Resolve session-scoped focus topic. Primary signal is the
   // per-session focus file at ~/.cache/clawmem/sessions/<id>.focus
   // (file > env var precedence via resolveSessionTopic). Env var
@@ -195,8 +210,11 @@ export async function contextSurfacing(
         vectorTimer = setTimeout(() => reject(new Error("vector timeout")), profile.vectorTimeout);
       });
       results = await Promise.race([vectorPromise, timeoutPromise]);
-    } catch {
-      // Vector search unavailable, timed out, or errored — fall back to BM25
+    } catch (e) {
+      // Vector search unavailable, timed out, or errored — fall back to BM25. A vault-wide
+      // embedding-model mismatch is a persistent config error, not a transient miss: surface it
+      // loudly once, then degrade (the hook stays fail-open).
+      warnOnceOnVectorModelMismatch(e);
     } finally {
       // Clear the timer when the vector promise won the race: a pending (ref'd) setTimeout keeps the
       // Bun hook process alive for the full vectorTimeout after results are already in hand.
@@ -221,7 +239,7 @@ export async function contextSurfacing(
   // Dual-query: also search skill vault if configured (secondary source)
   if (getVaultPath("skill")) {
     try {
-      const skillStore = resolveStore("skill");
+      const skillStore = resolveStore("skill", skillStoreOpts);
       const skillResults = skillStore.searchFTS(retrievalQuery, 5);
       // Tag skill vault results for identification in output
       for (const r of skillResults) {
@@ -292,7 +310,7 @@ export async function contextSurfacing(
                   deepTimer = setTimeout(() => reject(new Error("vector timeout")), remainingMs);
                 });
                 hits = await Promise.race([deepVec, deepTimeout]);
-              } catch { /* vector leg non-fatal (timed out or errored) */ }
+              } catch (e) { warnOnceOnVectorModelMismatch(e); /* vector leg non-fatal (timed out or errored) */ }
               finally { if (deepTimer) clearTimeout(deepTimer); }  // don't let a pending timer keep the hook process alive
             }
             for (const r of hits) {
@@ -346,7 +364,7 @@ export async function contextSurfacing(
     // expects the collection-relative path, not the full virtual path
     const parsed = r.filepath.startsWith('clawmem://') ? r.filepath.replace(/^clawmem:\/\/[^/]+\/?/, '') : r.filepath;
     // Use the correct store for skill-vault results
-    const targetStore = (r as any)._fromVault === "skill" ? (() => { try { return resolveStore("skill"); } catch { return store; } })() : store;
+    const targetStore = (r as any)._fromVault === "skill" ? (() => { try { return resolveStore("skill", skillStoreOpts); } catch { return store; } })() : store;
     const doc = targetStore.findActiveDocument(r.collectionName, parsed);
     if (!doc) return true;
     if (doc.snoozed_until && new Date(doc.snoozed_until) > now) return false;
@@ -374,7 +392,7 @@ export async function contextSurfacing(
   let enriched = enrichResults(store, generalResults, prompt);
   if (skillResults.length > 0) {
     try {
-      const skillStore = resolveStore("skill");
+      const skillStore = resolveStore("skill", skillStoreOpts);
       enriched = [...enriched, ...enrichResults(skillStore, skillResults, prompt)];
     } catch {
       // Skill store unavailable — enrich with general store as fallback
@@ -500,7 +518,7 @@ export async function contextSurfacing(
           writeRecallEvents(store, input.sessionId, qHash, mappedDocs, validUsageId, turnIndex);
         } else {
           try {
-            const vaultStore = resolveStore(vault);
+            const vaultStore = resolveStore(vault, skillStoreOpts);
             // Mirror context_usage row into named vault for correct FK + attribution
             const vaultPaths = docs.map(r => r.displayPath);
             const vaultUsageId = vaultStore.insertUsage({

package/src/hooks/decision-extractor.ts

@@ -23,7 +23,7 @@ import { loadConfig } from "../collections.ts";
 import { getDefaultLlamaCpp } from "../llm.ts";
 import type { ObservationWithDoc } from "../amem.ts";
 import { extractJsonFromLLM } from "../amem.ts";
-import { DEFAULT_EMBED_MODEL, extractSnippet, type SearchResult } from "../store.ts";
+import { DEFAULT_EMBED_MODEL, warnOnceOnVectorModelMismatch, extractSnippet, type SearchResult } from "../store.ts";
 import { ensureEntityCanonical, resolveEntityTypeExact } from "../entity.ts";
 
 // Observation types that are allowed to contribute SPO triples. Widened from the
@@ -92,7 +92,8 @@ export async function checkMergePolicy(
       if (sameType.length > 0) {
         return { action: 'skip' };
       }
-    } catch {
+    } catch (e) {
+      warnOnceOnVectorModelMismatch(e);
       // Vector search unavailable — fall through to insert
     }
     return { action: 'insert' };
@@ -211,7 +212,8 @@ async function detectContradictions(
   let existingDocs: SearchResult[];
   try {
     existingDocs = await store.searchVec(queryText, DEFAULT_EMBED_MODEL, 5);
-  } catch {
+  } catch (e) {
+    warnOnceOnVectorModelMismatch(e);
     existingDocs = store.searchFTS(queryText, 5);
   }
 

package/src/hooks.ts

@@ -213,13 +213,25 @@ export function wasPromptSeenRecently(store: Store, hookName: string, prompt: st
   }
 
   const preview = normalized.slice(0, 120);
-  store.db.prepare(`
-    INSERT INTO hook_dedupe (hook_name, prompt_hash, prompt_preview, last_seen_at)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT(hook_name, prompt_hash) DO UPDATE SET
-      prompt_preview = excluded.prompt_preview,
-      last_seen_at = excluded.last_seen_at
-  `).run(hookName, hash, preview, nowIso);
+  // Best-effort dedup bookkeeping. Under writer contention this UPSERT can hit
+  // SQLITE_BUSY — especially from the context-surfacing hook, which caps its
+  // busy_timeout low (B3) so its own writes cannot stall the tight
+  // UserPromptSubmit budget. A failed write only means the next identical
+  // prompt won't be suppressed; it is never a reason to throw and abort the
+  // hook. The `recent` verdict comes from the READ above (WAL-safe, does not
+  // wait on the write lock), so same-prompt dedup still works when the row
+  // already exists even if this refresh write is skipped.
+  try {
+    store.db.prepare(`
+      INSERT INTO hook_dedupe (hook_name, prompt_hash, prompt_preview, last_seen_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(hook_name, prompt_hash) DO UPDATE SET
+        prompt_preview = excluded.prompt_preview,
+        last_seen_at = excluded.last_seen_at
+    `).run(hookName, hash, preview, nowIso);
+  } catch {
+    /* best-effort: contended/failed dedup write must never abort the hook */
+  }
 
   return recent;
 }

package/src/llm.ts

@@ -109,6 +109,14 @@ export type EmbedOptions = {
   model?: string;
   isQuery?: boolean;
   title?: string;
+  /**
+   * Abort signal for the remote embed fetch AND its 429-retry backoff (B4).
+   * The query path passes AbortSignal.timeout(<remaining budget>) so a slow or
+   * rate-limited embed cannot outlive the caller's deadline. Without it, the
+   * hook's Promise.race only ABANDONS the embed promise — the underlying fetch
+   * and retry sleeps keep running; the signal actually CANCELS them.
+   */
+  signal?: AbortSignal;
 };
 
 /**
@@ -319,6 +327,13 @@ export type LlamaCppConfig = {
    * When set, generate() calls /v1/chat/completions instead of local node-llama-cpp.
    */
   remoteLlmUrl?: string;
+  /**
+   * API key for the remote LLM service (independent of the embed/rerank keys —
+   * the LLM endpoint may point at a different authenticated host than embedding).
+   * When set, sent as Authorization: Bearer header with chat completion requests.
+   * Env: CLAWMEM_LLM_API_KEY
+   */
+  remoteLlmApiKey?: string;
   /**
    * Remote LLM model name to send with chat completion requests.
    * Env: CLAWMEM_LLM_MODEL
@@ -393,6 +408,7 @@ export class LlamaCpp implements LLM {
   private remoteEmbedApiKey: string | null;
   private remoteEmbedModel: string;
   private remoteLlmUrl: string | null;
+  private remoteLlmApiKey: string | null;
   private remoteLlmModel: string;
   private remoteLlmReasoningEffort: string | null;
   private remoteLlmNoThink: boolean;
@@ -428,6 +444,7 @@ export class LlamaCpp implements LLM {
     this.remoteEmbedApiKey = config.remoteEmbedApiKey || null;
     this.remoteEmbedModel = config.remoteEmbedModel || "embedding";
     this.remoteLlmUrl = config.remoteLlmUrl || null;
+    this.remoteLlmApiKey = config.remoteLlmApiKey || null;
     const normalizedRemoteLlmModel = config.remoteLlmModel?.trim();
     this.remoteLlmModel = normalizedRemoteLlmModel || "qwen3";
     this.remoteLlmReasoningEffort = normalizeRemoteLlmReasoningEffort(config.remoteLlmReasoningEffort);
@@ -697,7 +714,7 @@ export class LlamaCpp implements LLM {
     // Remote server or cloud API — preferred path
     if (this.remoteEmbedUrl && !this.isRemoteEmbedDown()) {
       const extraParams = this.getCloudEmbedParams(!!options.isQuery);
-      const result = await this.embedRemote(text, extraParams);
+      const result = await this.embedRemote(text, extraParams, undefined, options.signal);
       if (result) return result;
       // Cloud providers don't fall back — if API key is set, the user chose cloud
       if (this.isCloudEmbedding()) return null;
@@ -710,6 +727,13 @@ export class LlamaCpp implements LLM {
     // Remote is in cooldown or was never configured — try local fallback
     if (this.remoteEmbedUrl && this.isRemoteEmbedDown()) {
       if (process.env.CLAWMEM_NO_LOCAL_MODELS === "true") return null;
+      // Medium-fix (B4): a deadline-bounded caller (query path, signal set)
+      // cannot afford a local model load/download during a remote cooldown —
+      // embedLocal ignores the abort signal and can run for seconds/minutes.
+      // Skip the local fallback and let the caller degrade (searchVec → [] →
+      // FTS). Pure-local mode (no remoteEmbedUrl) never enters this branch, so
+      // local-only deployments still embed.
+      if (options.signal) return null;
       this.noteRemoteFallback(
         "embed",
         this.isLoopbackUrl(this.remoteEmbedUrl)
@@ -929,6 +953,14 @@ export class LlamaCpp implements LLM {
     return headers;
   }
 
+  private getLlmHeaders(): Record<string, string> {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.remoteLlmApiKey) {
+      headers["Authorization"] = `Bearer ${this.remoteLlmApiKey}`;
+    }
+    return headers;
+  }
+
   private truncateForEmbed(text: string): string {
     // Cloud providers handle their own context window limits
     if (this.isCloudEmbedding()) return text;
@@ -952,22 +984,47 @@ export class LlamaCpp implements LLM {
     return Math.floor(delayMs * (0.75 + Math.random() * 0.5));
   }
 
-  private async embedRemote(text: string, extraParams: Record<string, unknown> = {}, retries = 5): Promise<EmbeddingResult | null> {
+  /**
+   * Sleep for `ms`, resolving early if `signal` aborts. Returns true if the
+   * wait was cut short by an abort (caller should stop retrying), false if it
+   * slept the full duration. Without this, a 429 backoff (up to 30s) would run
+   * to completion even after the caller's deadline elapsed (B4).
+   */
+  private async abortableDelay(ms: number, signal?: AbortSignal): Promise<boolean> {
+    if (signal?.aborted) return true;
+    if (!signal) {
+      await new Promise(r => setTimeout(r, ms));
+      return false;
+    }
+    return await new Promise<boolean>((resolve) => {
+      const onAbort = () => { clearTimeout(timer); resolve(true); };
+      const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(false);
+      }, ms);
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  private async embedRemote(text: string, extraParams: Record<string, unknown> = {}, retries = 5, signal?: AbortSignal): Promise<EmbeddingResult | null> {
     if (this.isRemoteEmbedDown()) return null;
     const input = this.truncateForEmbed(text);
     for (let attempt = 0; attempt < retries; attempt++) {
+      if (signal?.aborted) return null; // caller deadline already elapsed — do not start another attempt
       try {
         const body: Record<string, unknown> = { input, model: this.remoteEmbedModel, ...extraParams };
         const resp = await fetch(`${this.remoteEmbedUrl}/v1/embeddings`, {
           method: "POST",
           headers: this.getEmbedHeaders(),
           body: JSON.stringify(body),
+          signal,
         });
         if (resp.status === 429) {
           const retryAfter = this.parseRetryAfter(resp);
           const delay = retryAfter ?? Math.min(1000 * 2 ** attempt, 30000);
-          console.error(`Remote embed rate-limited, retry ${attempt + 1}/${retries} in ${this.jitter(delay)}ms`);
-          await new Promise(r => setTimeout(r, this.jitter(delay)));
+          const jittered = this.jitter(delay);
+          console.error(`Remote embed rate-limited, retry ${attempt + 1}/${retries} in ${jittered}ms`);
+          if (await this.abortableDelay(jittered, signal)) return null; // deadline elapsed during backoff
           continue;
         }
         if (!resp.ok) {
@@ -983,6 +1040,13 @@ export class LlamaCpp implements LLM {
           model: data.model || this.remoteEmbedUrl!,
         };
       } catch (error) {
+        // An abort/timeout is an intentional caller-driven cancellation (the
+        // query-path deadline), NOT a transport failure — do not trip the 60s
+        // remote-down cooldown, which would needlessly force local fallback.
+        const name = (error as { name?: string })?.name;
+        if (signal?.aborted || name === "AbortError" || name === "TimeoutError") {
+          return null;
+        }
         if (this.isTransportError(error)) {
           this.markRemoteEmbedDown();
         } else {
@@ -1120,7 +1184,7 @@ export class LlamaCpp implements LLM {
       }
       const resp = await fetch(buildRemoteChatCompletionsUrl(this.remoteLlmUrl!), {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: this.getLlmHeaders(),
         body: JSON.stringify(body),
         signal,
       });
@@ -1438,6 +1502,7 @@ export function getDefaultLlamaCpp(): LlamaCpp {
       remoteEmbedApiKey: embedApiKey,
       remoteEmbedModel: process.env.CLAWMEM_EMBED_MODEL || undefined,
       remoteLlmUrl: process.env.CLAWMEM_LLM_URL || undefined,
+      remoteLlmApiKey: process.env.CLAWMEM_LLM_API_KEY || undefined,
       remoteLlmModel: process.env.CLAWMEM_LLM_MODEL?.trim() || undefined,
       remoteLlmReasoningEffort: process.env.CLAWMEM_LLM_REASONING_EFFORT || undefined,
       remoteLlmNoThink: (() => {

package/src/maintenance.ts

@@ -479,6 +479,7 @@ export async function runHeavyMaintenanceTick(
             invalidIndexRejects: stats.invalidIndexRejects,
             unsupportedRejects: stats.unsupportedRejects,
             emptyRejects: stats.emptyRejects,
+            placeholderRejects: stats.placeholderRejects,
             dedupSkipped: stats.dedupSkipped,
             validatorFallbackAccepts: stats.validatorFallbackAccepts,
           },

package/src/mcp.ts

@@ -20,6 +20,7 @@ import {
   DEFAULT_QUERY_MODEL,
   DEFAULT_RERANK_MODEL,
   DEFAULT_MULTI_GET_MAX_BYTES,
+  rethrowIfFatalVectorError,
   type Store,
   type SearchResult,
   type CausalLink,
@@ -283,7 +284,7 @@ This is the recommended entry point for ALL memory queries.`,
         const intent = await classifyIntent(query, llm, store.db);
         const bm25Results = store.searchFTS(query, 30);
         let vecResults: SearchResult[] = [];
-        try { vecResults = await store.searchVec(query, DEFAULT_EMBED_MODEL, 30); } catch { /* no vectors */ }
+        try { vecResults = await store.searchVec(query, DEFAULT_EMBED_MODEL, 30); } catch (e) { rethrowIfFatalVectorError(e); /* else: no vectors */ }
         const rrfWeights = intent.intent === 'WHY' ? [1.0, 1.5] : intent.intent === 'WHEN' ? [1.5, 1.0] : [1.0, 1.0];
         const fusedRanked = reciprocalRankFusion([bm25Results.map(toRanked), vecResults.map(toRanked)], rrfWeights);
         const allSearch = [...bm25Results, ...vecResults];
@@ -354,7 +355,7 @@ This is the recommended entry point for ALL memory queries.`,
         for (const clause of clauses.sort((a, b) => a.priority - b.priority)) {
           let results: SearchResult[] = [];
           if (clause.type === 'bm25') results = store.searchFTS(clause.query, 20, undefined, clause.collections);
-          else if (clause.type === 'vector') { try { results = await store.searchVec(clause.query, DEFAULT_EMBED_MODEL, 20, undefined, clause.collections); } catch { /* */ } }
+          else if (clause.type === 'vector') { try { results = await store.searchVec(clause.query, DEFAULT_EMBED_MODEL, 20, undefined, clause.collections); } catch (e) { rethrowIfFatalVectorError(e); /* */ } }
           else if (clause.type === 'graph') { results = store.searchFTS(clause.query, 15, undefined, clause.collections); }
           allResults.push(...results);
         }
@@ -378,12 +379,12 @@ This is the recommended entry point for ALL memory queries.`,
       if (effectiveMode === "keyword") {
         results = store.searchFTS(query, lim);
       } else if (effectiveMode === "semantic" || effectiveMode === "discovery") {
-        try { results = await store.searchVec(query, DEFAULT_EMBED_MODEL, lim); } catch { results = store.searchFTS(query, lim); }
+        try { results = await store.searchVec(query, DEFAULT_EMBED_MODEL, lim); } catch (e) { rethrowIfFatalVectorError(e); results = store.searchFTS(query, lim); }
       } else {
         // Hybrid: BM25 + vector + RRF
         const bm25 = store.searchFTS(query, 30);
         let vec: SearchResult[] = [];
-        try { vec = await store.searchVec(query, DEFAULT_EMBED_MODEL, 30); } catch { /* */ }
+        try { vec = await store.searchVec(query, DEFAULT_EMBED_MODEL, 30); } catch (e) { rethrowIfFatalVectorError(e); /* */ }
         if (vec.length > 0) {
           const fusedRanked = reciprocalRankFusion([bm25.map(toRanked), vec.map(toRanked)], [1.0, 1.0]);
           const allSearch = [...bm25, ...vec];
@@ -961,7 +962,8 @@ This is the recommended entry point for ALL memory queries.`,
           }));
         }
       }
-    } catch {
+    } catch (e) {
+      rethrowIfFatalVectorError(e);
       // Vector search unavailable — degrade gracefully
     }
 

package/src/observer.ts

@@ -9,6 +9,7 @@
 import type { TranscriptMessage } from "./hooks.ts";
 import { getDefaultLlamaCpp } from "./llm.ts";
 import { MAX_LLM_GENERATE_TIMEOUT_MS } from "./limits.ts";
+import { isSchemaPlaceholder } from "./schema-placeholder.ts";
 
 // =============================================================================
 // Types
@@ -179,31 +180,9 @@ export const VALID_PREDICATES = new Set([
 // Predicates whose <object> should be stored as a literal (not resolved to an entity).
 export const LITERAL_PREDICATES = new Set(["prefers", "avoids"]);
 
-// Exact placeholder strings that must never be persisted as facts or triple components.
-// Defense-in-depth: even though the prompt no longer places example text inside
-// <fact>/<subject>/<object> tags, a weak model could still echo these phrases.
-const SCHEMA_PLACEHOLDER_STRINGS = new Set([
-  "individual atomic fact",
-  "atomic fact",
-  "one atomic claim per fact element",
-  "brief descriptive title",
-  "canonical entity name",
-]);
-
-// Regex for template placeholder markers: {{...}}, <!--...-->, ${...}.
-// Intentionally narrow — earlier drafts rejected any line starting with
-// "example:" / "placeholder:", which false-positived legitimate facts like
-// "Example: QMD switched to Bun in v0.2". Shape-only matching avoids that
-// drift; the exact-string blocklist above handles known echoed placeholders.
-const PLACEHOLDER_REGEX = /^(\{\{.*\}\}|<!--.*-->|\$\{.*\})/;
-
-function isSchemaPlaceholder(text: string): boolean {
-  if (!text) return true;
-  const normalized = text.trim().toLowerCase();
-  if (SCHEMA_PLACEHOLDER_STRINGS.has(normalized)) return true;
-  if (PLACEHOLDER_REGEX.test(normalized)) return true;
-  return false;
-}
+// Anti-parrot residue guard (SCHEMA_PLACEHOLDER_STRINGS / PLACEHOLDER_REGEX / isSchemaPlaceholder)
+// now lives in ./schema-placeholder.ts, shared with the consolidation + conversation-synthesis
+// extraction paths. Imported at the top of this file.
 
 export function parseObservationXml(xml: string): Observation | null {
   const typeMatch = xml.match(/<type>\s*(.*?)\s*<\/type>/s);

package/src/schema-placeholder.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared anti-parrot guard.
+ *
+ * A weak local extraction model, run out-of-distribution, may echo the schema example text or
+ * template placeholders from its prompt verbatim instead of extracting real content — the confirmed
+ * root cause of a failed mining run with the 1.7B model. This guard rejects that residue on output.
+ *
+ * Extracted from observer.ts so all three extraction paths — observer (Stop-hook observations),
+ * consolidation (Phase-3 deductive synthesis), and conversation-synthesis (mining/import) — share
+ * one residue check instead of each re-implementing (or omitting) it.
+ *
+ * Design note on what does NOT belong here: this blocklist holds only strings that no real fact
+ * could legitimately be (schema-instruction words, obviously-synthetic skeleton phrases). It must
+ * NOT hold plausible real content — an earlier draft rejected any line starting with
+ * "example:" / "placeholder:", which false-positived legitimate facts like
+ * "Example: QMD switched to Bun in v0.2". The prompts kill the parrot at the source by using
+ * {{...}} skeleton tokens (caught generically by PLACEHOLDER_REGEX) rather than copyable
+ * real-looking examples, so this blocklist stays narrow.
+ */
+
+// Exact placeholder strings that must never be persisted as facts, titles, or triple components.
+// Defense-in-depth: even though prompts now use structure-only skeletons (no copyable example
+// content), a weak model could still echo these phrases from the schema description itself.
+export const SCHEMA_PLACEHOLDER_STRINGS = new Set([
+  // observer.ts schema-instruction residue
+  "individual atomic fact",
+  "atomic fact",
+  "one atomic claim per fact element",
+  "brief descriptive title",
+  "canonical entity name",
+  // consolidation.ts deductive-skeleton residue (former copyable example — safe to blocklist
+  // because no genuine deduction is literally "clear deductive statement" / "premise from obs N")
+  "clear deductive statement",
+  "premise from obs 1",
+  "premise from obs 3",
+]);
+
+// Regex for template placeholder markers: {{...}}, <!--...-->, ${...}.
+// Intentionally narrow — earlier drafts rejected any line starting with
+// "example:" / "placeholder:", which false-positived legitimate facts like
+// "Example: QMD switched to Bun in v0.2". Shape-only matching avoids that
+// drift; the exact-string blocklist above handles known echoed placeholders.
+export const PLACEHOLDER_REGEX = /^(\{\{.*\}\}|<!--.*-->|\$\{.*\})/;
+
+/**
+ * True when `text` is empty, a known schema-placeholder string, or a template marker — i.e.
+ * residue a model echoed from its prompt rather than real extracted content.
+ */
+export function isSchemaPlaceholder(text: string): boolean {
+  if (!text) return true;
+  const normalized = text.trim().toLowerCase();
+  if (!normalized) return true; // whitespace-only is effectively empty content
+  if (SCHEMA_PLACEHOLDER_STRINGS.has(normalized)) return true;
+  if (PLACEHOLDER_REGEX.test(normalized)) return true;
+  return false;
+}

package/src/server.ts

@@ -23,6 +23,7 @@ import {
   DEFAULT_QUERY_MODEL,
   DEFAULT_RERANK_MODEL,
   extractSnippet,
+  rethrowIfFatalVectorError,
 } from "./store.ts";
 
 // =============================================================================
@@ -149,7 +150,8 @@ async function handleSearch(req: Request, _url: URL, store: Store): Promise<Resp
   } else if (mode === "semantic") {
     try {
       results = await store.searchVec(query, DEFAULT_EMBED_MODEL, limit * 2, undefined, collections);
-    } catch {
+    } catch (e) {
+      rethrowIfFatalVectorError(e);
       results = store.searchFTS(query, limit * 2, undefined, collections);
     }
   } else {
@@ -158,7 +160,7 @@ async function handleSearch(req: Request, _url: URL, store: Store): Promise<Resp
     let vecResults: SearchResult[] = [];
     try {
       vecResults = await store.searchVec(query, DEFAULT_EMBED_MODEL, limit * 2, undefined, collections);
-    } catch { /* vector unavailable */ }
+    } catch (e) { rethrowIfFatalVectorError(e); /* vector unavailable */ }
     // Simple merge — dedupe by filepath, take max score
     const merged = new Map<string, SearchResult>();
     for (const r of [...ftsResults, ...vecResults]) {
@@ -612,7 +614,7 @@ async function handleRetrieve(req: Request, _url: URL, store: Store): Promise<Re
     let vec: SearchResult[] = [];
     try {
       vec = await store.searchVec(query, DEFAULT_EMBED_MODEL, limit * 2, undefined, collections);
-    } catch { /* vector unavailable */ }
+    } catch (e) { rethrowIfFatalVectorError(e); /* vector unavailable */ }
     const weights = intent.intent === "WHEN" ? [1.5, 1.0] : [1.0, 1.5];
     const fused = reciprocalRankFusion([bm25.map(toRanked), vec.map(toRanked)], weights);
     const allResults = [...bm25, ...vec];
@@ -625,7 +627,8 @@ async function handleRetrieve(req: Request, _url: URL, store: Store): Promise<Re
   } else if (mode === "semantic") {
     try {
       results = await store.searchVec(query, DEFAULT_EMBED_MODEL, limit * 2, undefined, collections);
-    } catch {
+    } catch (e) {
+      rethrowIfFatalVectorError(e);
       results = store.searchFTS(query, limit * 2, undefined, collections);
     }
   } else {
@@ -634,7 +637,7 @@ async function handleRetrieve(req: Request, _url: URL, store: Store): Promise<Re
     let vec: SearchResult[] = [];
     try {
       vec = await store.searchVec(query, DEFAULT_EMBED_MODEL, limit * 2, undefined, collections);
-    } catch { /* vector unavailable */ }
+    } catch (e) { rethrowIfFatalVectorError(e); /* vector unavailable */ }
     const merged = new Map<string, SearchResult>();
     for (const r of [...fts, ...vec]) {
       const existing = merged.get(r.filepath);

package/src/store.ts

@@ -1035,6 +1035,16 @@ const contextUsageHasQueryTextCache = new WeakMap<Database, boolean>();
  */
 export class FatalVectorError extends Error {}
 
+/**
+ * Rethrow a fatal vector error (dimension / model / schema mismatch) so a searchVec() fallback
+ * catch surfaces it instead of silently degrading to BM25. Transient conditions (timeout, absent
+ * vectors) are NOT FatalVectorError and remain swallowed by the caller, as before. Apply this at the
+ * FTS-fallback catch sites that wrap searchVec.
+ */
+export function rethrowIfFatalVectorError(e: unknown): void {
+  if (e instanceof FatalVectorError) throw e;
+}
+
 export class VecDimensionMismatchError extends FatalVectorError {
   constructor(public readonly existingDim: number, public readonly requestedDim: number) {
     super(`Embedding dimension changed: vectors_vec is float[${existingDim}] but the model now returns float[${requestedDim}]. Run 'clawmem embed --force' to clear and rebuild the full vault.`);
@@ -1056,6 +1066,33 @@ export class VecModelMismatchError extends FatalVectorError {
   }
 }
 
+/**
+ * Read-path sibling of VecModelMismatchError. VecModelMismatchError fires only mid-embed-run; this
+ * one fires on the QUERY path when the vault's stored vectors were embedded with one model but the
+ * active embedding endpoint now returns a different model at the SAME dimension (so the dimension
+ * guard cannot catch it). Matching the new model's query vector against the old model's stored
+ * vectors is cosine-meaningless, so searchVec throws this rather than serving corrupted results.
+ */
+export class VecReadModelMismatchError extends FatalVectorError {
+  constructor(public readonly storedModels: string[], public readonly activeModel: string) {
+    super(`Embedding model mismatch on the query path: the vault's vectors were embedded with ${storedModels.map(m => `"${m}"`).join(", ")} but the active embedding endpoint now returns "${activeModel}". At the same dimension the dimension guard cannot catch this, and matching the new model's query vector against the old model's stored vectors makes cosine similarity meaningless. Run 'clawmem embed --force' to rebuild the vault with the current model.`);
+    this.name = "VecReadModelMismatchError";
+  }
+}
+
+// Fail-open surfacing for a read-path model mismatch: warn LOUDLY once per process, then let the
+// caller degrade to BM25. For hooks that MUST NOT throw — context-surfacing (UserPromptSubmit) and
+// the Stop hooks (decision-extractor) — a throwing hook breaks that turn. Explicit query paths use
+// rethrowIfFatalVectorError instead. The once-flag is process-global so the warning fires exactly
+// once no matter which hook trips it first.
+let _warnedVectorModelMismatch = false;
+export function warnOnceOnVectorModelMismatch(e: unknown): void {
+  if (e instanceof VecReadModelMismatchError && !_warnedVectorModelMismatch) {
+    _warnedVectorModelMismatch = true;
+    console.warn(`[clawmem] ${e.message}`);
+  }
+}
+
 // A FatalVectorError so it propagates out of the per-fragment catch and aborts the
 // embed run. Thrown both by cmdEmbed (between fragments) and INSIDE insertEmbedding's
 // write transaction (atomic lease-token fence) when the lease was reclaimed.
@@ -1162,6 +1199,67 @@ export function prewarmVectors(db: Database): boolean {
   return true;
 }
 
+/**
+ * Keep the sqlite-vec payload resident in the OS page cache by re-running the brute-force
+ * prewarm on an interval. The one-shot prewarm at watcher startup warms the cache ONCE; on a
+ * long-running host under memory pressure the kernel can evict the (potentially ~1.5 GB) vector
+ * payload between hook calls, and the next cold SYNCHRONOUS MATCH in the context-surfacing hook
+ * path can then blow the 8-15s hook budget (bun:sqlite exposes no interrupt, so an in-flight
+ * scan cannot be abandoned). Re-touching the pages biases the kernel LRU toward keeping them
+ * resident — a PROBABILITY reduction, NOT a hard cap. The hard cap (moving the blocking scan off
+ * the hook's event loop so its deadline can fire) is the deferred BACKLOG Source 46 daemon.
+ *
+ * Best-effort: never throws; a per-tick failure is swallowed so the timer keeps running. Returns
+ * the interval handle (the caller MUST clear it on shutdown) or null when disabled (intervalMs
+ * <= 0 or non-finite). The handle is unref'd so it never by itself keeps the process alive.
+ * `onPrewarm(ran)` is an optional observability hook fired after each attempt — `ran` is whether
+ * a scan actually executed (i.e. a dimensioned vector table exists).
+ */
+export function startPeriodicPrewarm(
+  db: Database,
+  intervalMs: number,
+  onPrewarm?: (ran: boolean) => void,
+): ReturnType<typeof setInterval> | null {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) return null;
+  const timer = setInterval(() => {
+    let ran = false;
+    try { ran = prewarmVectors(db); } catch { /* best-effort: unexpected SQL error */ }
+    if (onPrewarm) { try { onPrewarm(ran); } catch { /* observer must never break the timer */ } }
+  }, intervalMs);
+  (timer as { unref?: () => void }).unref?.();
+  return timer;
+}
+
+/** Floor for the periodic re-prewarm interval. Below this, a large-vault (~1.5 GB) brute-force scan
+ *  runs near-continuously and can saturate the watcher event loop + I/O, so any smaller positive
+ *  request is clamped UP to this value. */
+export const PREWARM_MIN_INTERVAL_MS = 60_000;
+/** Default periodic re-prewarm interval when CLAWMEM_PREWARM_INTERVAL_MS is unset or unparseable. */
+export const PREWARM_DEFAULT_INTERVAL_MS = 600_000;
+
+/**
+ * Resolve the raw CLAWMEM_PREWARM_INTERVAL_MS env value into a SAFE interval for the watcher. This
+ * policy is kept OUT of the permissive `startPeriodicPrewarm` mechanism (so unit tests can still use
+ * tiny intervals) and applied only on the production env path.
+ *   - unset / empty / unparseable → default (600000). Garbage must NOT silently disable the
+ *     mitigation, nor be read as a tiny interval.
+ *   - exactly 0 → 0 (the documented off switch; `startPeriodicPrewarm` then returns null).
+ *   - negative → default (nonsensical; neither an intentional disable nor a fast loop).
+ *   - 0 < n < floor → clamped UP to the 60s floor. Prevents the near-continuous scan loop that e.g.
+ *     "1" or "1e3" would otherwise schedule. NOTE: `Number("1e3") === 1000` whereas
+ *     `parseInt("1e3", 10) === 1`, so `Number()` is used deliberately (parseInt silently truncates
+ *     at the "e").
+ *   - n >= floor → floored to an integer and used as-is.
+ */
+export function resolvePrewarmIntervalMs(raw: string | undefined): number {
+  if (raw === undefined || raw.trim() === "") return PREWARM_DEFAULT_INTERVAL_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return PREWARM_DEFAULT_INTERVAL_MS;
+  if (n === 0) return 0;
+  if (n < 0) return PREWARM_DEFAULT_INTERVAL_MS;
+  return Math.max(PREWARM_MIN_INTERVAL_MS, Math.floor(n));
+}
+
 /**
  * The DISTINCT non-empty embedding models stored in the vault (empty array if no
  * embeddings exist). Used to detect model drift BETWEEN runs — a different model at
@@ -3387,12 +3485,54 @@ export function searchFTS(db: Database, query: string, limit: number = 20, colle
 // Vector Search
 // =============================================================================
 
+// W1 read-path model-consistency cache, keyed on SQLite's `data_version` so a CROSS-PROCESS vault
+// rebuild invalidates a stale OK verdict. `data_version` changes whenever ANOTHER connection commits
+// (e.g. a separate `clawmem embed --force` process re-embeds with a different model) — exactly the
+// multi-process staleness case — and is a cheap header read (no scan), unlike the getVecModels()
+// DISTINCT+JOIN it guards. Same-connection writes don't bump it, but in-process model swaps are
+// already blocked by the embed-time VecModelMismatchError / clearAllEmbeddings drop.
+const verifiedQueryEmbedModels = new WeakMap<Database, { dataVersion: number; model: string }>();
+
+/**
+ * Guard the query path against a same-dimension embedding-model swap. Compares the ENDPOINT-returned
+ * model (NOT the caller's DEFAULT_EMBED_MODEL arg, which is a local alias unrelated to what the
+ * endpoint actually serves) against the models the vault's active vectors were embedded with. The
+ * vault is consistent ONLY when it holds EXACTLY ONE model equal to the endpoint's — a heterogeneous
+ * vault (length > 1) is cosine-corrupt even if the endpoint matches one of the models, because the
+ * other model's vectors still pollute the space. Throws VecReadModelMismatchError otherwise; no-ops
+ * when the vault has no vectors yet.
+ */
+function assertQueryEmbedModelConsistent(db: Database, endpointModel: string): void {
+  const dataVersion = (db.prepare("PRAGMA data_version").get() as { data_version: number }).data_version;
+  const cached = verifiedQueryEmbedModels.get(db);
+  if (cached && cached.dataVersion === dataVersion && cached.model === endpointModel) return;
+
+  const storedModels = getVecModels(db);
+  if (storedModels.length === 0) return; // nothing embedded yet — nothing to be inconsistent with
+
+  if (!(storedModels.length === 1 && storedModels[0] === endpointModel)) {
+    throw new VecReadModelMismatchError(storedModels, endpointModel);
+  }
+
+  // Consistent — memoize under the current data_version. A cross-process rebuild bumps data_version,
+  // invalidating this entry so the next query re-reads content_vectors.
+  verifiedQueryEmbedModels.set(db, { dataVersion, model: endpointModel });
+}
+
 export async function searchVec(db: Database, query: string, model: string, limit: number = 20, collectionId?: number, collections?: string[], dateRange?: { start: string; end: string }, deadlineMs?: number): Promise<SearchResult[]> {
   const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
   if (!tableExists) return [];
 
-  const embedding = await getEmbedding(query, model, true);
-  if (!embedding) return [];
+  const embedResult = await getEmbedding(query, model, true, deadlineMs);
+  if (!embedResult) return [];
+
+  // W1: read-path embedding-model consistency gate. On a same-dimension model swap (which
+  // VecDimensionMismatchError cannot catch) this throws VecReadModelMismatchError rather than
+  // serving cosine-meaningless results. Cached per (db, model) — the DISTINCT runs at most once
+  // per model per process.
+  assertQueryEmbedModelConsistent(db, embedResult.model);
+
+  const embedding = embedResult.embedding;
 
   // Guard-defect fix: the caller's Promise.race(vectorTimeout) cannot interrupt the SYNCHRONOUS
   // sqlite-vec MATCH below (bun:sqlite blocks the event loop) and does NOT cancel this promise.
@@ -3499,12 +3639,24 @@ export async function searchVec(db: Database, query: string, model: string, limi
 // Embeddings
 // =============================================================================
 
-async function getEmbedding(text: string, model: string, isQuery: boolean): Promise<number[] | null> {
+async function getEmbedding(text: string, model: string, isQuery: boolean, deadlineMs?: number): Promise<{ embedding: number[]; model: string } | null> {
   const llm = getDefaultLlamaCpp();
   // Format text using the appropriate prompt template
   const formattedText = isQuery ? formatQueryForEmbedding(text) : formatDocForEmbedding(text);
-  const result = await llm.embed(formattedText, { model, isQuery });
-  return result?.embedding || null;
+  // B4: bound the remote embed fetch + its 429 backoff to the caller's wall-clock
+  // deadline. Under the context-surfacing hook's Promise.race the abandoned embed
+  // promise otherwise keeps its fetch + retry sleeps running; AbortSignal.timeout
+  // actually cancels them, so a slow/rate-limited embed can no longer outlive the
+  // hook budget.
+  let signal: AbortSignal | undefined;
+  if (deadlineMs !== undefined) {
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0) return null; // deadline already elapsed — skip the embed entirely
+    signal = AbortSignal.timeout(remaining);
+  }
+  const result = await llm.embed(formattedText, { model, isQuery, signal });
+  if (!result?.embedding) return null;
+  return { embedding: result.embedding, model: result.model };
 }
 
 /**
@@ -3807,19 +3959,24 @@ export async function rerank(query: string, documents: { file: string; text: str
   // Cap parallelism at 4 to prevent VRAM exhaustion
   if (uncachedDocs.length > 0) {
     const rerankUrl = Bun.env.CLAWMEM_RERANK_URL;
+    const rerankApiKey = Bun.env.CLAWMEM_RERANK_API_KEY;
     let scored = false;
 
     // Try remote GPU reranker first
     // Truncate to ~400 chars per doc to fit within server's 512-token context
     // (query + document must fit in one pair; ~2 chars/token for mixed content)
     if (rerankUrl) {
+      // Independent of the embed/LLM keys — the rerank endpoint may be a different
+      // authenticated host. Sent as Authorization: Bearer when CLAWMEM_RERANK_API_KEY is set.
+      const rerankHeaders: Record<string, string> = { "Content-Type": "application/json" };
+      if (rerankApiKey) rerankHeaders["Authorization"] = `Bearer ${rerankApiKey}`;
       try {
         // Process in batches of 4 to prevent VRAM exhaustion
         for (let i = 0; i < uncachedDocs.length; i += 4) {
           const batch = uncachedDocs.slice(i, i + 4);
           const resp = await fetch(`${rerankUrl}/v1/rerank`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: rerankHeaders,
             body: JSON.stringify({
               query: rerankQuery,
               documents: batch.map(d => d.text.slice(0, 400)),