npm - @cerefox/memory - Versions diffs - 1.0.2 → 1.0.4 - Mend

@cerefox/memory 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/AGENT_QUICK_REFERENCE.md +2 -1
package/dist/bin/cerefox.js +120 -44
package/dist/frontend/assets/{index-CLD16BC4.js → index-Csj-6UHY.js} +2 -2
package/dist/frontend/assets/{index-CLD16BC4.js.map → index-Csj-6UHY.js.map} +1 -1
package/dist/frontend/index.html +1 -1
package/dist/server-assets/_shared/ef-meta/index.ts +11 -1
package/dist/server-assets/_shared/mcp-tools/_utils.ts +15 -0
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +2 -2
package/dist/server-assets/_shared/mcp-tools/search.ts +47 -2
package/dist/server-assets/db/rpcs.sql +188 -26
package/dist/server-assets/db/schema.sql +1 -1
package/docs/guides/configuration.md +9 -0
package/package.json +1 -1

package/dist/frontend/index.html CHANGED Viewed

@@ -15,7 +15,7 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
     />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-CLD16BC4.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-Csj-6UHY.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-Asx5wD7g.css">
   </head>
   <body>

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

@@ -18,7 +18,17 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
-export const EF_VERSION = "1.0.2";
+export const EF_VERSION = "1.0.4";
+/**
+ * The most recent version whose EF-side SOURCE actually changed (#127).
+ * `EF_VERSION` bumps unconditionally at stable cuts (so stable deployments
+ * never display a pre-release label), which means a version delta no longer
+ * implies the deployed behaviour differs. This constant is bumped by
+ * `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.4";
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

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

@@ -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/get-help-content.ts CHANGED Viewed

@@ -11,12 +11,12 @@
  * docs/specs/polish-and-distribution-design.md §10d.
  */
-export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --expected-content-hash \"<hash>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
+export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --expected-content-hash \"<hash>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
 /** Sections keyed by their H2 heading text (lower-cased for matching). */
 export const HELP_SECTIONS: Record<string, string> = {
   "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
-  "Essential Rules": "## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
+  "Essential Rules": "## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
   "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.",
   "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```",
   "Catch-Up Workflow": "## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```",

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

@@ -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,
     };
   }
@@ -132,16 +142,24 @@ async function handler(
     doc_title?: string;
     full_content?: string;
     best_score?: number;
+    score?: number;
     is_partial?: boolean;
     chunk_count?: number;
     total_chars?: number;
     content_hash?: string;
+    below_confidence?: boolean;
   }>;
+  // 28I: nothing cleared the relevance threshold, so the server returned its
+  // best-effort top candidates flagged below_confidence instead of an empty
+  // set (which agents misread as "this knowledge does not exist").
+  const belowConfidence = rows.length > 0 && rows.every((r) => r.below_confidence === true);
   const parts: string[] = rows.map((row) => {
     const title = row.doc_title ?? "Untitled";
     const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
-    const score = row.best_score != null ? ` (score: ${row.best_score.toFixed(3)})` : "";
+    const rawScore = row.best_score ?? row.score;
+    const score = rawScore != null ? ` (score: ${rawScore.toFixed(3)})` : "";
     const partial = row.is_partial
       ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
       : "";
@@ -151,6 +169,12 @@ async function handler(
   });
   let output = parts.join("\n\n---\n\n");
+  if (belowConfidence) {
+    output =
+      `⚠ No results cleared the confidence threshold. Showing the closest ${rows.length} ` +
+      `candidate(s) with scores — judge relevance yourself; a low score means weak signal, ` +
+      `not necessarily absent knowledge.\n\n` + output;
+  }
   if (truncated) {
     output +=
       `\n\n[Results truncated at ${usedBytes} bytes. Use a more specific query or a smaller match_count to see more.]`;
@@ -181,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 CHANGED Viewed

@@ -63,6 +63,19 @@ DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID,
 DROP FUNCTION IF EXISTS cerefox_reconstruct_doc(UUID);
 DROP FUNCTION IF EXISTS cerefox_get_document(UUID, UUID);
+-- Iteration 28I (v1.0.3, search recall): below_confidence BOOLEAN added to the
+-- return types of cerefox_hybrid_search and cerefox_search_docs (never-silently-
+-- empty fallback). Drop the pre-change signatures first.
+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,
@@ -90,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,
@@ -106,7 +126,11 @@ RETURNS TABLE (
     doc_project_ids UUID[],
     doc_project_names TEXT[],
     doc_metadata    JSONB,
-    version_count   INT
+    version_count   INT,
+    -- 28I: TRUE on every row of a below-confidence fallback response — nothing
+    -- cleared the pass-filter, so these are the best-effort top candidates for
+    -- the caller to judge (scores included). FALSE on all normal results.
+    below_confidence BOOLEAN
 )
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -120,15 +144,81 @@ DECLARE
     -- websearch operators (phrase, OR, NOT); semantic ranking is the soft-match
     -- layer for "broadly related". If operator support is ever needed, gate it
     -- behind an opt-in flag rather than changing the default.
-    query_fts tsquery := plainto_tsquery('english', p_query_text);
+    --
+    -- 28I progressive relaxation: AND-first, OR-fallback. The AND query stays
+    -- the primary match (byte-identical behavior whenever it matches anything),
+    -- but when it matches ZERO chunks (under the same project/metadata filters),
+    -- we retry with an OR-composition of the same tokens: one absent term then
+    -- no longer vetoes the terms that DO occur, and ts_rank_cd naturally ranks
+    -- chunks matching more terms higher. Multi-term evidence accumulates
+    -- instead of vetoing.
+    query_fts_and tsquery := plainto_tsquery('english', p_query_text);
+    query_fts_or  tsquery := NULL;
+    query_fts     tsquery;
+    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, 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 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.
+    IF numnode(query_fts_and) > 0 THEN
+        SELECT EXISTS (
+            SELECT 1
+            FROM cerefox_chunks c
+            JOIN cerefox_documents d ON c.document_id = d.id
+            WHERE c.version_id IS NULL
+              AND d.deleted_at IS NULL
+              AND c.fts @@ query_fts_and
+              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
+                  ))
+              AND (p_metadata_filter IS NULL OR d.metadata @> p_metadata_filter)
+        ) INTO and_matches;
+    END IF;
+    query_fts := CASE WHEN and_matches THEN query_fts_and
+                      ELSE COALESCE(query_fts_or, query_fts_and) END;
     RETURN QUERY
     WITH
         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
@@ -175,15 +265,27 @@ 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
-        )
+        ),
+        -- 28I: pass-filter as a flag rather than a WHERE, so we can fall back.
+        -- FTS matches pass through unconditionally: the @@ operator is a hard
+        -- gate and guarantees the query terms appear in the chunk. Vector-only
+        -- results (no FTS match) are filtered by the cosine threshold.
+        flagged AS (
+            SELECT *,
+                   (combined.has_fts_match OR combined.vec_score >= p_min_score) AS passes
+            FROM combined
+        ),
+        any_pass AS (SELECT bool_or(fl.passes) AS ok FROM flagged fl)
     SELECT
         c.id            AS chunk_id,
         c.document_id,
@@ -202,16 +304,22 @@ BEGIN
               WHERE dp.document_id = d.id) AS doc_project_names,
         d.metadata      AS doc_metadata,
         (SELECT COUNT(*)::INT FROM cerefox_document_versions dv
-         WHERE dv.document_id = d.id) AS version_count
-    FROM combined cm
+         WHERE dv.document_id = d.id) AS version_count,
+        -- 28I: when NOTHING clears the pass-filter, return the top candidates
+        -- anyway, flagged — an empty response reads to agent callers as "this
+        -- knowledge does not exist", the most expensive wrong conclusion a
+        -- memory layer can produce. "Truly nothing" (no candidates at all)
+        -- still returns zero rows.
+        NOT ap.ok       AS below_confidence
+    FROM flagged cm
+    CROSS JOIN any_pass ap
     JOIN cerefox_chunks   c ON c.id = cm.id
     JOIN cerefox_documents d ON c.document_id = d.id
-    -- FTS matches pass through unconditionally: the @@ operator is a hard gate
-    -- and guarantees the query terms appear in the chunk.
-    -- Vector-only results (no FTS match) are filtered by the cosine threshold.
-    WHERE cm.has_fts_match OR cm.vec_score >= p_min_score
+    WHERE cm.passes OR NOT ap.ok
     ORDER BY cm.score DESC
-    LIMIT p_match_count;
+    LIMIT (SELECT CASE WHEN ap2.ok THEN p_match_count
+                       ELSE LEAST(p_match_count, 3) END
+           FROM any_pass ap2);
 END;
 $$;
@@ -222,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,
@@ -245,9 +356,48 @@ SECURITY DEFINER
 SET search_path = public, pg_catalog
 AS $$
 DECLARE
-    -- plainto_tsquery: see rationale comment in cerefox_hybrid_search above.
-    query_fts tsquery := plainto_tsquery('english', p_query_text);
+    -- plainto_tsquery + 28I AND-first/OR-fallback: see the rationale comments
+    -- in cerefox_hybrid_search above.
+    query_fts_and tsquery := plainto_tsquery('english', p_query_text);
+    query_fts_or  tsquery := NULL;
+    query_fts     tsquery;
+    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 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 (
+            SELECT 1
+            FROM cerefox_chunks c
+            JOIN cerefox_documents d ON c.document_id = d.id
+            WHERE c.version_id IS NULL
+              AND d.deleted_at IS NULL
+              AND c.fts @@ query_fts_and
+              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
+                  ))
+              AND (p_metadata_filter IS NULL OR d.metadata @> p_metadata_filter)
+        ) INTO and_matches;
+    END IF;
+    query_fts := CASE WHEN and_matches THEN query_fts_and
+                      ELSE COALESCE(query_fts_or, query_fts_and) END;
     RETURN QUERY
     SELECT
         c.id            AS chunk_id,
@@ -273,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
@@ -583,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,
@@ -602,7 +758,10 @@ RETURNS TABLE (
     is_partial               BOOL,
     -- Optimistic-concurrency token (iter-32): the document's current
     -- content_hash, to pass back as expected_content_hash on update.
-    content_hash             TEXT
+    content_hash             TEXT,
+    -- 28I: TRUE when this is a below-confidence fallback response (nothing
+    -- cleared the hybrid pass-filter). See cerefox_hybrid_search.
+    below_confidence         BOOLEAN
 )
 LANGUAGE sql
 SECURITY DEFINER
@@ -620,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 (
@@ -635,6 +795,7 @@ AS $$
             cr.doc_project_ids,
             cr.doc_project_names,
             cr.version_count,
+            cr.below_confidence,
             d.updated_at       AS doc_updated_at,
             d.content_hash
         FROM chunk_results cr
@@ -720,7 +881,8 @@ AS $$
         td.doc_updated_at,
         td.version_count,
         ac.is_partial,
-        td.content_hash
+        td.content_hash,
+        td.below_confidence
     FROM top_docs td
     JOIN doc_sizes ds ON ds.document_id = td.document_id
     JOIN all_content ac ON ac.document_id = td.document_id
@@ -1776,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.8.2'::TEXT;
+    SELECT '0.9.1'::TEXT;
 $$;
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

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

@@ -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.8.2
+-- @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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.0.2",
+  "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",