clawmem 0.17.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.17.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/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 {
@@ -210,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.
@@ -307,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) {

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/llm.ts

@@ -327,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
@@ -401,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;
@@ -436,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);
@@ -944,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;
@@ -1167,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,
       });
@@ -1485,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.
@@ -3448,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, deadlineMs);
-  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.
@@ -3560,7 +3639,7 @@ export async function searchVec(db: Database, query: string, model: string, limi
 // Embeddings
 // =============================================================================
 
-async function getEmbedding(text: string, model: string, isQuery: boolean, deadlineMs?: number): 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);
@@ -3576,7 +3655,8 @@ async function getEmbedding(text: string, model: string, isQuery: boolean, deadl
     signal = AbortSignal.timeout(remaining);
   }
   const result = await llm.embed(formattedText, { model, isQuery, signal });
-  return result?.embedding || null;
+  if (!result?.embedding) return null;
+  return { embedding: result.embedding, model: result.model };
 }
 
 /**
@@ -3879,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)),