@cerefox/memory 1.0.3 → 1.0.4

package/dist/bin/cerefox.js

@@ -7184,7 +7184,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.0.3";
+var PKG_VERSION = "1.0.4";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -25225,6 +25225,13 @@ function getMinSearchScore() {
   const n = Number.parseFloat(raw);
   return Number.isNaN(n) || n < 0 || n > 1 ? fallback : n;
 }
+function getMinTermCoverage() {
+  const raw = globalThis.process?.env?.CEREFOX_MIN_TERM_COVERAGE;
+  if (raw === undefined || raw === "")
+    return;
+  const n = Number.parseFloat(raw);
+  return Number.isNaN(n) || n < 0 || n > 1 ? undefined : n;
+}
 function applyByteBudget(rows, maxBytes) {
   const accepted = [];
   let usedBytes = 0;
@@ -55572,6 +55579,8 @@ async function handler9(supabase, args, ctx) {
   const mode = args.mode ?? "docs";
   const alpha = args.alpha ?? 0.7;
   const min_score = args.min_score ?? getMinSearchScore();
+  const min_term_coverage = args.min_term_coverage ?? getMinTermCoverage();
+  const coverageParam = min_term_coverage !== undefined ? { p_min_term_coverage: min_term_coverage } : {};
   const metadata_filter = args.metadata_filter ?? null;
   const requested_max_bytes = args.max_bytes;
   const ceiling = getMaxResponseBytes();
@@ -55603,7 +55612,8 @@ async function handler9(supabase, args, ctx) {
       p_query_text: query,
       p_match_count: match_count,
       p_project_id: projectId,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   } else if (mode === "hybrid") {
     rpcName = "cerefox_hybrid_search";
@@ -55615,7 +55625,8 @@ async function handler9(supabase, args, ctx) {
       p_use_upgrade: false,
       p_project_id: projectId,
       p_min_score: min_score,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   } else {
     rpcName = "cerefox_search_docs";
@@ -55626,7 +55637,8 @@ async function handler9(supabase, args, ctx) {
       p_alpha: alpha,
       p_project_id: projectId,
       p_min_score: min_score,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   }
   const { data, error: error2 } = await supabase.rpc(rpcName, rpcParams);
@@ -55699,6 +55711,23 @@ var init_search = __esm(() => {
           description: 'Optional JSONB containment filter. Only documents whose metadata contains ALL specified key-value pairs are returned. Example: {"type": "decision", "status": "active"}. Call cerefox_list_metadata_keys first to discover available keys and values. Omit to search all documents.',
           additionalProperties: { type: "string" }
         },
+        mode: {
+          type: "string",
+          enum: ["docs", "hybrid", "fts", "semantic"],
+          description: "Search mode (default: docs — full reconstructed documents). hybrid: ranked chunks; fts: keyword-only (no embedding); semantic: vector-only."
+        },
+        alpha: {
+          type: "number",
+          description: "Hybrid fusion weight 0–1 (default 0.7): 1 = pure semantic, 0 = pure keyword."
+        },
+        min_score: {
+          type: "number",
+          description: "Minimum cosine similarity for vector-side results (default: server-configured, 0.5 OpenAI / 0.6 local embedder)."
+        },
+        min_term_coverage: {
+          type: "number",
+          description: "Keyword OR-fallback confidence bar 0–1 (default 0.5): fraction of the query's meaningful terms a result must match to count as a confident hit; weaker matches return flagged below-confidence. 0 = any matching term. Needs schema ≥ 0.9.1."
+        },
         max_bytes: {
           type: "integer",
           description: "Optional response size budget in bytes. Results are dropped whole until the budget is satisfied; a truncated flag is set when results are dropped. Defaults to the server maximum (200000). Pass a smaller value if your context window is limited. Values above the server maximum are silently capped."
@@ -69032,10 +69061,29 @@ init_cli_core();
 
 // src/cli/commands/backup.ts
 init_cli_core();
-init_client();
 import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join2, resolve } from "node:path";
+
+// ../../_shared/db-client/paginate.ts
+async function fetchAllPages(makeQuery, batchSize = 200) {
+  const results = [];
+  let offset = 0;
+  for (;; ) {
+    const { data, error } = await makeQuery(offset, offset + batchSize - 1);
+    if (error)
+      throw new Error(error.message ?? JSON.stringify(error));
+    const page = data ?? [];
+    results.push(...page);
+    if (page.length < batchSize)
+      break;
+    offset += batchSize;
+  }
+  return results;
+}
+
+// src/cli/commands/backup.ts
+init_client();
 function expandHome(path) {
   if (path === "~")
     return homedir2();
@@ -69056,21 +69104,25 @@ async function action(options) {
   const filename = `cerefox-${stamp}${options.label ? "-" + options.label : ""}.json`;
   const dest = join2(outDir, filename);
   const client = getClient();
-  const { data: docsData, error: docsErr } = await client.raw.from("cerefox_documents").select("id, title, content_hash, source, metadata, total_chars, chunk_count, " + "review_status, created_at, updated_at, deleted_at").is("deleted_at", null).order("created_at", { ascending: true });
-  if (docsErr)
-    throw systemError(`Document fetch failed: ${docsErr.message}`);
-  const docs = docsData ?? [];
+  let docs;
+  try {
+    docs = await fetchAllPages((from, to) => client.raw.from("cerefox_documents").select("id, title, content_hash, source, metadata, total_chars, chunk_count, " + "review_status, created_at, updated_at, deleted_at").is("deleted_at", null).order("created_at", { ascending: true }).order("id", { ascending: true }).range(from, to));
+  } catch (err) {
+    throw systemError(`Document fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
   let chunkTotal = 0;
   const enriched = [];
   for (let i = 0;i < docs.length; i++) {
     const doc = docs[i];
     const docId = doc.id;
-    const { data: chunks, error: chunkErr } = await client.raw.from("cerefox_chunks").select("*").eq("document_id", docId).is("version_id", null).order("chunk_index", { ascending: true });
-    if (chunkErr) {
-      throw systemError(`Chunk fetch failed for ${docId}: ${chunkErr.message}`);
+    let chunks;
+    try {
+      chunks = await fetchAllPages((from, to) => client.raw.from("cerefox_chunks").select("*").eq("document_id", docId).is("version_id", null).order("chunk_index", { ascending: true }).range(from, to));
+    } catch (err) {
+      throw systemError(`Chunk fetch failed for ${docId}: ${err instanceof Error ? err.message : String(err)}`);
     }
-    chunkTotal += (chunks ?? []).length;
-    enriched.push({ ...doc, chunks: chunks ?? [] });
+    chunkTotal += chunks.length;
+    enriched.push({ ...doc, chunks });
     if (process.stdout.isTTY) {
       process.stderr.write(`\r  Dumping documents: ${i + 1}/${docs.length} (${chunkTotal} chunks so far)…`);
     }
@@ -74948,8 +75000,8 @@ import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.0.3";
-var EF_LAST_CHANGED = "1.0.3";
+var EF_VERSION = "1.0.4";
+var EF_LAST_CHANGED = "1.0.4";
 
 // src/cli/util/checks.ts
 init_config();
@@ -77239,18 +77291,22 @@ async function action27(options) {
   }
   const reindexAll = Boolean(options.all);
   const dryRun = Boolean(options.dryRun);
-  let query = supabase.from("cerefox_chunks").select("id, document_id, content, embedder_primary, cerefox_documents(title)").is("version_id", null);
-  if (options.documentId) {
-    query = query.eq("document_id", options.documentId);
-  }
   const targetModel = activeEmbedderName();
-  if (!reindexAll) {
-    query = query.neq("embedder_primary", targetModel);
+  let chunks;
+  try {
+    chunks = await fetchAllPages((from, to) => {
+      let query = supabase.from("cerefox_chunks").select("id, document_id, content, embedder_primary, cerefox_documents(title)").is("version_id", null);
+      if (options.documentId) {
+        query = query.eq("document_id", options.documentId);
+      }
+      if (!reindexAll) {
+        query = query.neq("embedder_primary", targetModel);
+      }
+      return query.order("id", { ascending: true }).range(from, to);
+    }, 1000);
+  } catch (err) {
+    throw systemError(`Failed to list chunks: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const { data, error: error3 } = await query;
-  if (error3)
-    throw systemError(`Failed to list chunks: ${error3.message}`);
-  const chunks = data ?? [];
   if (chunks.length === 0) {
     println(c.dim("(nothing to reindex)"));
     return;
@@ -77420,6 +77476,8 @@ async function action29(query, options) {
   const matchCount = parsePositiveInt(options.matchCount, "--match-count", 5);
   const alpha = parseFloat01(options.alpha, "--alpha", 0.7);
   const minScore = parseFloat01(options.minScore, "--min-score", getMinSearchScore());
+  const envCoverage = getMinTermCoverage();
+  const coverageParam = options.minTermCoverage !== undefined ? { p_min_term_coverage: parseFloat01(options.minTermCoverage, "--min-term-coverage", envCoverage ?? 0.5) } : envCoverage !== undefined ? { p_min_term_coverage: envCoverage } : {};
   const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", getMaxResponseBytes());
   const mode = options.mode ?? "docs";
   if (!["docs", "hybrid", "fts"].includes(mode)) {
@@ -77450,7 +77508,8 @@ async function action29(query, options) {
       p_query_text: query,
       p_match_count: matchCount,
       p_project_id: projectId,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   } else if (mode === "hybrid") {
     rpcName = "cerefox_hybrid_search";
@@ -77462,7 +77521,8 @@ async function action29(query, options) {
       p_use_upgrade: false,
       p_project_id: projectId,
       p_min_score: minScore,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   } else {
     rpcName = "cerefox_search_docs";
@@ -77473,7 +77533,8 @@ async function action29(query, options) {
       p_alpha: alpha,
       p_project_id: projectId,
       p_min_score: minScore,
-      ...metaFilterParam
+      ...metaFilterParam,
+      ...coverageParam
     };
   }
   const results = await client.rpc(rpcName, rpcParams);
@@ -77572,7 +77633,7 @@ async function action29(query, options) {
   }
 }
 function registerSearch(program2) {
-  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action29);
+  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--min-term-coverage <float>", "OR-fallback keyword matches must cover at least this fraction of the query's meaningful terms to count as confident hits (default: CEREFOX_MIN_TERM_COVERAGE; else the server default 0.5; needs schema ≥ 0.9.1).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action29);
 }
 
 // src/cli/commands/self-update.ts
@@ -81444,10 +81505,8 @@ async function getProjectDocCounts(ctx, projectIds) {
   if (projectIds.length === 0)
     return { active, deleted };
   try {
-    const { data, error: error3 } = await ctx.supabase.from("cerefox_document_projects").select("project_id, cerefox_documents(deleted_at)").in("project_id", projectIds);
-    if (error3)
-      throw error3;
-    for (const row of data ?? []) {
+    const rows = await fetchAllPages((from, to) => ctx.supabase.from("cerefox_document_projects").select("project_id, cerefox_documents(deleted_at)").in("project_id", projectIds).order("document_id", { ascending: true }).order("project_id", { ascending: true }).range(from, to));
+    for (const row of rows) {
       const pid = row.project_id;
       if (!(pid in active))
         continue;
@@ -81491,16 +81550,13 @@ async function getRecentDocAuthors(ctx, docIds) {
   return out;
 }
 async function countDocumentsForProject(ctx, projectId) {
-  const { data, error: error3 } = await ctx.supabase.from("cerefox_document_projects").select("document_id, cerefox_documents(deleted_at)").eq("project_id", projectId);
+  const { count, error: error3 } = await ctx.supabase.from("cerefox_document_projects").select("document_id, cerefox_documents!inner(deleted_at)", {
+    count: "exact",
+    head: true
+  }).eq("project_id", projectId).is("cerefox_documents.deleted_at", null);
   if (error3)
     throw error3;
-  let n = 0;
-  for (const row of data ?? []) {
-    if (row.cerefox_documents && row.cerefox_documents.deleted_at === null) {
-      n += 1;
-    }
-  }
-  return n;
+  return count ?? 0;
 }
 function dashboardDocFromRow(row, projectIds) {
   return {

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.0.3";
+export const EF_VERSION = "1.0.4";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -28,7 +28,7 @@ export const EF_VERSION = "1.0.3";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.0.3";
+export const EF_LAST_CHANGED = "1.0.4";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/_utils.ts

@@ -68,6 +68,21 @@ export function getMinSearchScore(): number {
   return Number.isNaN(n) || n < 0 || n > 1 ? fallback : n;
 }
 
+/**
+ * CEREFOX_MIN_TERM_COVERAGE (v1.0.4): user-configurable default for the
+ * OR-fallback term-coverage gate. Returns undefined when unset/invalid —
+ * callers then OMIT p_min_term_coverage from the RPC call, deferring to the
+ * server default (0.5) and staying compatible with pre-0.9.1 servers
+ * (an unknown named argument fails the PostgREST function match).
+ */
+export function getMinTermCoverage(): number | undefined {
+  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.CEREFOX_MIN_TERM_COVERAGE;
+  if (raw === undefined || raw === "") return undefined;
+  const n = Number.parseFloat(raw);
+  return Number.isNaN(n) || n < 0 || n > 1 ? undefined : n;
+}
+
 export function applyByteBudget(
   rows: unknown[],
   maxBytes: number,

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -18,7 +18,8 @@
 import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding, resolveEmbedderKind } from "../embeddings/index.ts";
-import { applyByteBudget, getMaxResponseBytes, getMinSearchScore, logUsage } from "./_utils.ts";
+import { applyByteBudget, getMaxResponseBytes, getMinSearchScore,
+  getMinTermCoverage, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 
@@ -33,6 +34,12 @@ async function handler(
   const mode = (args.mode as string | undefined) ?? "docs";
   const alpha = (args.alpha as number | undefined) ?? 0.7;
   const min_score = (args.min_score as number | undefined) ?? getMinSearchScore();
+  // v1.0.4: coverage gate default from CEREFOX_MIN_TERM_COVERAGE; only sent
+  // when configured (see getMinTermCoverage — keeps pre-0.9.1 servers working).
+  const min_term_coverage =
+    (args.min_term_coverage as number | undefined) ?? getMinTermCoverage();
+  const coverageParam =
+    min_term_coverage !== undefined ? { p_min_term_coverage: min_term_coverage } : {};
   const metadata_filter =
     (args.metadata_filter as Record<string, string> | null | undefined) ?? null;
   const requested_max_bytes = args.max_bytes as number | undefined;
@@ -84,6 +91,7 @@ async function handler(
       p_match_count: match_count,
       p_project_id: projectId,
       ...metaFilterParam,
+      ...coverageParam,
     };
   } else if (mode === "hybrid") {
     rpcName = "cerefox_hybrid_search";
@@ -96,6 +104,7 @@ async function handler(
       p_project_id: projectId,
       p_min_score: min_score,
       ...metaFilterParam,
+      ...coverageParam,
     };
   } else {
     rpcName = "cerefox_search_docs";
@@ -107,6 +116,7 @@ async function handler(
       p_project_id: projectId,
       p_min_score: min_score,
       ...metaFilterParam,
+      ...coverageParam,
     };
   }
 
@@ -195,6 +205,27 @@ export const searchTool: ToolDefinition = {
           'Optional JSONB containment filter. Only documents whose metadata contains ALL specified key-value pairs are returned. Example: {"type": "decision", "status": "active"}. Call cerefox_list_metadata_keys first to discover available keys and values. Omit to search all documents.',
         additionalProperties: { type: "string" },
       },
+      mode: {
+        type: "string",
+        enum: ["docs", "hybrid", "fts", "semantic"],
+        description:
+          "Search mode (default: docs — full reconstructed documents). hybrid: ranked chunks; fts: keyword-only (no embedding); semantic: vector-only.",
+      },
+      alpha: {
+        type: "number",
+        description:
+          "Hybrid fusion weight 0–1 (default 0.7): 1 = pure semantic, 0 = pure keyword.",
+      },
+      min_score: {
+        type: "number",
+        description:
+          "Minimum cosine similarity for vector-side results (default: server-configured, 0.5 OpenAI / 0.6 local embedder).",
+      },
+      min_term_coverage: {
+        type: "number",
+        description:
+          "Keyword OR-fallback confidence bar 0–1 (default 0.5): fraction of the query's meaningful terms a result must match to count as a confident hit; weaker matches return flagged below-confidence. 0 = any matching term. Needs schema ≥ 0.9.1.",
+      },
       max_bytes: {
         type: "integer",
         description:

package/dist/server-assets/db/rpcs.sql

@@ -69,6 +69,13 @@ DROP FUNCTION IF EXISTS cerefox_get_document(UUID, UUID);
 DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOOLEAN, UUID, FLOAT, JSONB);
 DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB);
 
+-- Iteration 28I follow-up (v1.0.4, term-coverage gate): p_min_term_coverage
+-- added to the search RPC signatures (new arg count = new function; the old
+-- overloads must go or PostgREST calls become ambiguous).
+DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOOLEAN, UUID, FLOAT, JSONB);
+DROP FUNCTION IF EXISTS cerefox_fts_search(TEXT, INT, UUID, JSONB);
+DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB);
+
 -- ── Shared return type note ────────────────────────────────────────────────────
 -- All chunk-level search RPCs return the same shape for consistency:
 --   chunk_id, document_id, chunk_index, title, content, heading_path,
@@ -96,7 +103,14 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     p_use_upgrade     BOOLEAN DEFAULT FALSE,
     p_project_id      UUID    DEFAULT NULL,
     p_min_score       FLOAT   DEFAULT 0.0,
-    p_metadata_filter JSONB   DEFAULT NULL
+    p_metadata_filter JSONB   DEFAULT NULL,
+    -- 28I follow-up (v1.0.4): in OR-fallback mode, the unconditional FTS pass
+    -- requires at least this fraction of the query's meaningful (non-stopword,
+    -- deduplicated) terms to match the chunk. Under AND semantics a match
+    -- meant 100% of terms — the pass this gate generalizes. Chunks below the
+    -- bar can still pass via the vector threshold, else they are
+    -- below-confidence material. 0 restores the pre-gate OR behavior.
+    p_min_term_coverage FLOAT DEFAULT 0.5
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -144,18 +158,26 @@ DECLARE
     tok           TEXT;
     tok_q         tsquery;
     and_matches   BOOLEAN := FALSE;
+    -- v1.0.4 coverage gate: the per-token queries (deduplicated by normalized
+    -- lexeme text, so "run running" counts once) and their count.
+    tok_queries   tsquery[] := '{}';
+    seen_tokens   TEXT[]    := '{}';
+    total_tokens  INT;
     candidate_count INT := p_match_count * 5;
 BEGIN
     -- Build the OR-composed query: plainto each whitespace token (so tokens get
     -- the same normalization/stemming as the AND path), skip stopword-only
-    -- tokens, fold with the tsquery OR operator (||).
+    -- tokens, dedupe by normalized form, fold with the tsquery OR operator (||).
     FOR tok IN SELECT unnest(regexp_split_to_array(trim(p_query_text), '\s+')) LOOP
         tok_q := plainto_tsquery('english', tok);
-        IF numnode(tok_q) > 0 THEN
+        IF numnode(tok_q) > 0 AND NOT (tok_q::TEXT = ANY(seen_tokens)) THEN
+            seen_tokens := seen_tokens || tok_q::TEXT;
+            tok_queries := tok_queries || tok_q;
             query_fts_or := CASE WHEN query_fts_or IS NULL
                                  THEN tok_q ELSE query_fts_or || tok_q END;
         END IF;
     END LOOP;
+    total_tokens := COALESCE(array_length(tok_queries, 1), 0);
 
     -- Does the strict AND query match anything at all (under the caller's
     -- filters)? Cheap probe against the partial FTS index.
@@ -183,7 +205,20 @@ BEGIN
         fts_results AS (
             SELECT
                 c.id,
-                ts_rank_cd(c.fts, query_fts)::FLOAT AS fts_score
+                ts_rank_cd(c.fts, query_fts)::FLOAT AS fts_score,
+                -- v1.0.4 coverage gate: in AND mode a match means 100% of the
+                -- query's terms are present, so the unconditional pass is
+                -- earned by construction. In OR-fallback mode, earn it only
+                -- when at least p_min_term_coverage of the meaningful terms
+                -- match this chunk; weaker matches keep contributing their
+                -- fts_score to the fusion but must pass via the vector
+                -- threshold (or surface as below-confidence candidates).
+                CASE
+                    WHEN and_matches OR total_tokens = 0 THEN TRUE
+                    ELSE (SELECT COUNT(*) FROM unnest(tok_queries) tq
+                          WHERE c.fts @@ tq)::FLOAT
+                         >= p_min_term_coverage * total_tokens
+                END AS coverage_ok
             FROM cerefox_chunks c
             JOIN cerefox_documents d ON c.document_id = d.id
             WHERE c.version_id IS NULL
@@ -230,12 +265,14 @@ BEGIN
                     (1.0 - p_alpha) * COALESCE(f.fts_score, 0.0)
                 ) AS score,
                 COALESCE(v.vec_score, 0.0) AS vec_score,
-                -- TRUE when the chunk matched the @@ FTS operator.
-                -- We use this flag rather than vec_score to decide whether a chunk
-                -- passes the threshold, because in small corpora every chunk appears
-                -- in vec_results (LIMIT candidate_count covers all rows), so
-                -- vec_score is never NULL even for FTS-only matches.
-                f.id IS NOT NULL AS has_fts_match
+                -- TRUE when the chunk matched the @@ FTS operator WITH enough
+                -- term coverage to earn the unconditional pass (v1.0.4; always
+                -- true for AND-mode matches). We use this flag rather than
+                -- vec_score to decide whether a chunk passes the threshold,
+                -- because in small corpora every chunk appears in vec_results
+                -- (LIMIT candidate_count covers all rows), so vec_score is
+                -- never NULL even for FTS-only matches.
+                (f.id IS NOT NULL AND f.coverage_ok) AS has_fts_match
             FROM fts_results f
             FULL OUTER JOIN vec_results v ON f.id = v.id
         ),
@@ -293,7 +330,10 @@ CREATE OR REPLACE FUNCTION cerefox_fts_search(
     p_query_text      TEXT,
     p_match_count     INT  DEFAULT 10,
     p_project_id      UUID DEFAULT NULL,
-    p_metadata_filter JSONB DEFAULT NULL
+    p_metadata_filter JSONB DEFAULT NULL,
+    -- v1.0.4: see cerefox_hybrid_search. In OR-fallback mode results must
+    -- match at least this fraction of the query's meaningful terms.
+    p_min_term_coverage FLOAT DEFAULT 0.5
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -324,14 +364,20 @@ DECLARE
     tok           TEXT;
     tok_q         tsquery;
     and_matches   BOOLEAN := FALSE;
+    tok_queries   tsquery[] := '{}';
+    seen_tokens   TEXT[]    := '{}';
+    total_tokens  INT;
 BEGIN
     FOR tok IN SELECT unnest(regexp_split_to_array(trim(p_query_text), '\s+')) LOOP
         tok_q := plainto_tsquery('english', tok);
-        IF numnode(tok_q) > 0 THEN
+        IF numnode(tok_q) > 0 AND NOT (tok_q::TEXT = ANY(seen_tokens)) THEN
+            seen_tokens := seen_tokens || tok_q::TEXT;
+            tok_queries := tok_queries || tok_q;
             query_fts_or := CASE WHEN query_fts_or IS NULL
                                  THEN tok_q ELSE query_fts_or || tok_q END;
         END IF;
     END LOOP;
+    total_tokens := COALESCE(array_length(tok_queries, 1), 0);
 
     IF numnode(query_fts_and) > 0 THEN
         SELECT EXISTS (
@@ -377,6 +423,11 @@ BEGIN
     WHERE c.version_id IS NULL
               AND d.deleted_at IS NULL
       AND c.fts @@ query_fts
+      -- v1.0.4 coverage gate (OR-fallback mode only): pure keyword search
+      -- returns only chunks matching enough of the query's terms.
+      AND (and_matches OR total_tokens = 0
+           OR (SELECT COUNT(*) FROM unnest(tok_queries) tq
+               WHERE c.fts @@ tq)::FLOAT >= p_min_term_coverage * total_tokens)
       AND (p_project_id IS NULL OR EXISTS (
               SELECT 1 FROM cerefox_document_projects dp
               WHERE dp.document_id = d.id AND dp.project_id = p_project_id
@@ -687,7 +738,8 @@ CREATE OR REPLACE FUNCTION cerefox_search_docs(
     p_min_score              FLOAT DEFAULT 0.0,
     p_small_to_big_threshold INT   DEFAULT 20000,
     p_context_window         INT   DEFAULT 1,
-    p_metadata_filter        JSONB DEFAULT NULL
+    p_metadata_filter        JSONB DEFAULT NULL,
+    p_min_term_coverage      FLOAT DEFAULT 0.5
 )
 RETURNS TABLE (
     document_id              UUID,
@@ -727,7 +779,8 @@ AS $$
             p_use_upgrade     := FALSE,
             p_project_id      := p_project_id,
             p_min_score       := p_min_score,
-            p_metadata_filter := p_metadata_filter
+            p_metadata_filter := p_metadata_filter,
+            p_min_term_coverage := p_min_term_coverage
         )
     ),
     best_per_doc AS (
@@ -1885,7 +1938,7 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
-    SELECT '0.9.0'::TEXT;
+    SELECT '0.9.1'::TEXT;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.9.0
+-- @version: 0.9.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —

package/docs/guides/configuration.md

@@ -117,10 +117,19 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 
 ## Retrieval
 
+> **Which paths read these?** Client-side tunables in this section are read
+> from *your* `.env` by the **CLI**, the **local MCP server**, and `cerefox
+> web`. The **remote MCP / Edge Function path** runs on Supabase and does not
+> see your `.env` — it uses the server defaults unless the caller passes the
+> per-call parameter (e.g. `min_score`, `min_term_coverage` on
+> `cerefox_search`). Setting them as Supabase **Function secrets** may also
+> work but is not a tested configuration.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CEREFOX_MAX_RESPONSE_BYTES` | `200000` | Maximum bytes in a single search response (local MCP path). See explanation below. |
 | `CEREFOX_MIN_SEARCH_SCORE` | `0.50` (`0.60` with the local embedder) | Minimum cosine similarity for hybrid and semantic search results (0.0–1.0). The default is embedder-aware: nomic scores unrelated text higher than OpenAI, so `CEREFOX_EMBEDDER=local` raises the floor to 0.60. In **hybrid search**, chunks that matched the FTS keyword operator (`@@`) always pass through regardless of their vector score — the threshold only filters vector-only results. In **semantic search**, all results are filtered. The pure **FTS search** mode is unaffected. Increase for stricter precision; decrease for wider recall. |
+| `CEREFOX_MIN_TERM_COVERAGE` | *(unset — server default `0.5`)* | Confidence bar for the keyword OR-fallback (v1.0.4, schema ≥ 0.9.1): when a strict all-terms match fails and search relaxes to any-term matching, a result counts as a confident hit only if it matches at least this fraction of the query's meaningful terms; weaker matches surface as below-confidence candidates. `0` restores pre-gate behavior (any matching term passes); `1` requires every term. Per-call override: `cerefox search --min-term-coverage`. Leave unset against pre-0.9.1 servers. |
 | `CEREFOX_EMBED_MAX_INPUT_CHARS` | `20000` | Safety cap on the characters sent to the embedding model per input. The full chunk content is always stored and reconstructed untouched; only the embedding uses the (rare) truncated prefix, so an oversized chunk can never fail an ingest. |
 | `CEREFOX_MODELS_DIR` | `~/.cerefox/models` (in-container: inside the data volume) | Where the local embedder caches downloaded model weights (Cerefox Local; `CEREFOX_EMBEDDER=local`). |
 | `CEREFOX_ONNX_BATCH` | `4` | Texts per local-embedder inference call. Peak memory scales with this; the small default keeps ingest/reindex safe on small Docker VMs. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",