@cerefox/memory 1.14.3 → 1.14.4

package/dist/bin/cerefox.js

@@ -7400,7 +7400,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 });
 
 // src/meta.ts
-var PKG_VERSION = "1.14.3";
+var PKG_VERSION = "1.14.4";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -23317,6 +23317,14 @@ function logUsage(supabase, params) {
     p_extra: params.extra ?? {}
   })).catch(() => {});
 }
+function resolveByteBudget(requested, ceiling) {
+  if (requested === null || requested === undefined || requested === "")
+    return ceiling;
+  const n = Math.floor(Number(requested));
+  if (!Number.isFinite(n))
+    return ceiling;
+  return Math.min(Math.max(n, 1), ceiling);
+}
 var MAX_RESPONSE_BYTES = 200000, DEFAULT_MIN_SEARCH_SCORE = 0.5, DEFAULT_MIN_SEARCH_SCORE_LOCAL = 0.6, DEFAULT_SEARCH_ALPHA = 0.7;
 var init__utils = __esm(() => {
   init_audit_ops();
@@ -25759,7 +25767,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.14.3", CEREFOX_VERSION = "1.14.3", EF_LAST_CHANGED = "1.14.3";
+var EF_VERSION = "1.14.4", CEREFOX_VERSION = "1.14.4", EF_LAST_CHANGED = "1.14.4";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -56411,8 +56419,7 @@ async function handler10(supabase, args, ctx) {
       throw new Error(`Project not found: ${project_name}`);
   }
   const ceiling = getMaxResponseBytes();
-  const requestedBytes = Math.floor(Number(requested_max_bytes));
-  const max_bytes = include_content ? Math.min(Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling, ceiling) : null;
+  const max_bytes = include_content ? resolveByteBudget(requested_max_bytes, ceiling) : null;
   const params = {
     p_metadata_filter: metadata_filter ?? {},
     p_project_id: projectId,
@@ -56465,7 +56472,13 @@ ${lines.join(`
     log(0);
     return "No documents match the given criteria.";
   }
-  log(rows.length);
+  let matched = rows.length;
+  if (include_content && max_bytes !== null && rows.length < limit) {
+    const { data: headers, error: probeError } = await supabase.rpc("cerefox_metadata_search", { ...params, p_include_content: false, p_max_bytes: null });
+    if (!probeError)
+      matched = Math.max(rows.length, (headers ?? []).length);
+  }
+  log(matched, matched > rows.length ? { returned: rows.length, truncated: true } : undefined);
   const showReview = await reviewWorkflowEnabled(supabase);
   const parts = rows.map((row) => {
     const projects = row.project_names?.length ? ` | projects: ${row.project_names.join(", ")}` : "";
@@ -56481,6 +56494,16 @@ ${row.content}`;
     }
     return header;
   });
+  if (matched > rows.length) {
+    const held = matched - rows.length;
+    return `${parts.join(`
+
+---
+
+`)}
+
+` + `[${rows.length} of ${matched} document(s) shown; ${held} did not fit ` + `max_bytes=${max_bytes}. Raise max_bytes, lower limit, or use ` + `include_content: false to list them all.]`;
+  }
   return parts.join(`
 
 ---
@@ -56612,8 +56635,7 @@ async function handler11(supabase, args, ctx) {
   const metadata_filter = args.metadata_filter ?? null;
   const requested_max_bytes = args.max_bytes;
   const ceiling = getMaxResponseBytes();
-  const requestedBytes = Math.floor(Number(requested_max_bytes));
-  const max_bytes = Math.min(Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling, ceiling);
+  const max_bytes = resolveByteBudget(requested_max_bytes, ceiling);
   if (metadata_filter !== null && metadata_filter !== undefined && (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))) {
     throw new McpInvalidParams("metadata_filter must be a JSON object or null");
   }
@@ -80608,10 +80630,28 @@ async function action28(options) {
   };
   if (options.includeContent)
     params.p_max_bytes = maxBytes;
-  const rows = await client.rpc("cerefox_metadata_search", params);
+  let rows = await client.rpc("cerefox_metadata_search", params);
   if (rows === null) {
     throw systemError("cerefox_metadata_search: RPC returned no data.");
   }
+  let heldBack = 0;
+  if (options.includeContent && rows.length < limit) {
+    const all = await client.rpc("cerefox_metadata_search", {
+      ...params,
+      p_include_content: false,
+      p_max_bytes: null
+    });
+    if (all !== null && all.length > rows.length) {
+      const withContent = new Map(rows.map((r) => [r.document_id, r]));
+      heldBack = all.length - rows.length;
+      const merged = all.map((h) => withContent.get(h.document_id) ?? { ...h, content: null });
+      const seen = new Set(merged.map((r) => r.document_id));
+      for (const r of rows)
+        if (!seen.has(r.document_id))
+          merged.push(r);
+      rows = merged;
+    }
+  }
   const requestor = resolveRequestor(options.author ?? options.requestor);
   client.raw.rpc("cerefox_log_usage", {
     p_operation: "metadata_search",
@@ -80633,6 +80673,10 @@ async function action28(options) {
     println("No documents match the metadata filter.");
     return;
   }
+  if (heldBack > 0) {
+    println(c.dim(`(${rows.length - heldBack} of ${rows.length} document(s) have content here; ` + `${heldBack} did not fit --max-bytes ${maxBytes} and are listed without it)`));
+    println("");
+  }
   for (const row of rows) {
     const projects = row.project_names?.length ? ` | projects: ${row.project_names.join(", ")}` : "";
     const meta = Object.entries(row.doc_metadata ?? {}).map(([k, v]) => `${k}=${v}`).join(", ");
@@ -81171,7 +81215,7 @@ async function action32(query, options) {
     const rowBytes = Buffer.byteLength(JSON.stringify(row), "utf8");
     if (usedBytes + rowBytes > maxBytes && accepted.length > 0) {
       truncated = true;
-      break;
+      continue;
     }
     accepted.push(row);
     usedBytes += rowBytes;
@@ -81252,7 +81296,8 @@ async function action32(query, options) {
     }
   }
   if (truncated) {
-    println(c.dim(`(results truncated at ${usedBytes} bytes; use --max-bytes to raise)`));
+    const held = results.length - accepted.length;
+    println(c.dim(`(${accepted.length} of ${results.length} result(s) shown; ${held} did not fit ` + `${usedBytes} bytes used of --max-bytes ${maxBytes} — raise it to see the rest)`));
   }
 }
 function registerSearch(program) {

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.14.3";
+export const EF_VERSION = "1.14.4";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.14.3";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.14.3";
+export const CEREFOX_VERSION = "1.14.4";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.14.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.14.3";
+export const EF_LAST_CHANGED = "1.14.4";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

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

@@ -147,25 +147,32 @@ export function applyByteBudget(
   maxBytes: number,
 ): { accepted: unknown[]; dropped: unknown[]; truncated: boolean; usedBytes: number } {
   const accepted: unknown[] = [];
+  const dropped: unknown[] = [];
   let usedBytes = 0;
   let truncated = false;
-  let cut = rows.length;
 
-  for (const [i, row] of rows.entries()) {
+  for (const row of rows) {
     const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
+    // Skipped, not the end of the list (#266, #268). This used to `break`, so
+    // one oversized top hit suppressed every smaller result behind it: the
+    // Edge Function answered with an empty `accepted`, flipped to the degraded
+    // shape and stripped content from results 2 and 3 that would have fitted
+    // comfortably. The MCP tool has skipped since #266; this is the same rule
+    // reaching the surface GPT Actions and direct HTTP callers use.
     if (usedBytes + rowBytes > maxBytes) {
       truncated = true;
-      cut = i;
-      break;
+      dropped.push(row);
+      continue;
     }
     accepted.push(row);
     usedBytes += rowBytes;
   }
 
   // What did not fit, so a caller can say so instead of reporting nothing
-  // (#254): a first row larger than the budget empties `accepted` entirely,
+  // (#254): every row larger than the budget lands here — they are no longer
+  // a contiguous tail, because the scan no longer stops at the first one —
   // and "no results" is the one answer an agent acts on irreversibly.
-  return { accepted, dropped: rows.slice(cut), truncated, usedBytes };
+  return { accepted, dropped, truncated, usedBytes };
 }
 
 import type { AccessPath } from "./types.ts";
@@ -293,3 +300,28 @@ export function logUsage(supabase: MCPSupabaseClient, params: LogUsageParams): v
     }),
   ).catch(() => {});
 }
+
+/**
+ * Resolve a caller-supplied byte budget against the server ceiling.
+ *
+ * One implementation, because this arithmetic was written out by hand on four
+ * surfaces and each hand-written copy was wrong in its own way (#267, #268):
+ *
+ * - **Non-numeric means unset, not unbounded.** `Math.min("lots", CEILING)` is
+ *   `NaN`; `NaN` compares false against every `>` check and serialises to JSON
+ *   `null`, and `p_max_bytes NULL` means NO limit in Postgres. So the one
+ *   parameter that exists to bound a reply, handed a word, removed the bound.
+ * - **`null` and `undefined` mean unset too.** `Number(null)` is `0`, which is
+ *   finite, so a clamp to `>= 1` turned an explicitly-null budget into a
+ *   ONE-BYTE budget — a client that serialises optional fields as `null` asked
+ *   for content and got none.
+ * - **A real number of zero or less means "almost nothing", and is honoured.**
+ *   Falling back to the ceiling there would hand a caller whose allowance had
+ *   run out the largest possible reply.
+ */
+export function resolveByteBudget(requested: unknown, ceiling: number): number {
+  if (requested === null || requested === undefined || requested === "") return ceiling;
+  const n = Math.floor(Number(requested));
+  if (!Number.isFinite(n)) return ceiling;
+  return Math.min(Math.max(n, 1), ceiling);
+}

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

@@ -7,7 +7,7 @@
 
 import type { MCPSupabaseClient } from "./types.ts";
 
-import { getMaxResponseBytes, logUsage } from "./_utils.ts";
+import { getMaxResponseBytes, logUsage, resolveByteBudget } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { reviewWorkflowEnabled } from "./feature-flags.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
@@ -51,20 +51,14 @@ async function handler(
     if (!projectId) throw new Error(`Project not found: ${project_name}`);
   }
 
-  // Enforce byte ceiling for content mode.
-  //
-  // Sanitised first: a non-numeric `max_bytes` became `NaN`, which reaches the
-  // RPC as JSON null, and `p_max_bytes NULL` means NO limit — so one word
-  // instead of a number returned every matching document's full content, with
-  // the in-process guard below disabled too (#267). Same hole as the search
-  // tool's, in the sibling that shares its transport.
+  // Enforce byte ceiling for content mode, via the one shared resolver every
+  // budget-taking surface uses (#268). It was written out by hand here and on
+  // three other surfaces, and each copy was wrong differently: a non-numeric
+  // value became `NaN` and disabled the limit entirely (#267), and an explicit
+  // `null` coerced to 0 and became a ONE-BYTE budget.
   const ceiling = getMaxResponseBytes();
-  const requestedBytes = Math.floor(Number(requested_max_bytes));
   const max_bytes = include_content
-    ? Math.min(
-        Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling,
-        ceiling,
-      )
+    ? resolveByteBudget(requested_max_bytes, ceiling)
     : null;
 
   const params: Record<string, unknown> = {
@@ -166,7 +160,33 @@ async function handler(
     log(0);
     return "No documents match the given criteria.";
   }
-  log(rows.length);
+  // How many documents actually matched, as opposed to how many the budget
+  // let through (#268). The RPC applies `p_max_bytes` by stopping at the first
+  // row that does not fit, so a short list has two indistinguishable causes:
+  // fewer documents matched, or the budget cut the list. Only the caller's
+  // side knows which, and only after asking — so ask, with the same
+  // content-free probe the empty branch above uses.
+  //
+  // Cost, stated honestly: this is a second RPC round-trip, and it fires
+  // whenever a content-bearing search returns less than a full page — which is
+  // the COMMON case, not a rare one, since `limit` defaults to 10. A full page
+  // and a budget-free call both skip it, but nothing else does. The RPC gives
+  // no "there was more" signal, and the alternative to asking is guessing:
+  // a short list is indistinguishable from a cut list from here, and guessing
+  // wrong is the bug (#268). Worth revisiting if the RPC ever returns a total.
+  let matched = rows.length;
+  if (include_content && max_bytes !== null && rows.length < limit) {
+    const { data: headers, error: probeError } = await supabase.rpc(
+      "cerefox_metadata_search",
+      { ...params, p_include_content: false, p_max_bytes: null },
+    );
+    // A failed probe must not invent a count. supabase-js resolves with
+    // `{ data: null, error }` rather than throwing (#261), so read the error:
+    // leaving `matched` at `rows.length` states only what is known.
+    if (!probeError) matched = Math.max(rows.length, ((headers ?? []) as unknown[]).length);
+  }
+
+  log(matched, matched > rows.length ? { returned: rows.length, truncated: true } : undefined);
 
   // The review status is a column of a feature that may be off (#241); when
   // it is, an agent should not see "approved" and wonder what it means.
@@ -194,6 +214,19 @@ async function handler(
     return header;
   });
 
+  // Never hold results back silently (#268). A caller who receives 1 of 5 and
+  // is told nothing believes they saw everything — the same failure as a false
+  // empty, in a quieter form. This notice is framing that is never dropped.
+  if (matched > rows.length) {
+    const held = matched - rows.length;
+    return (
+      `${parts.join("\n\n---\n\n")}\n\n` +
+      `[${rows.length} of ${matched} document(s) shown; ${held} did not fit ` +
+      `max_bytes=${max_bytes}. Raise max_bytes, lower limit, or use ` +
+      `include_content: false to list them all.]`
+    );
+  }
+
   return parts.join("\n\n---\n\n");
 }
 

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

@@ -19,7 +19,7 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding, resolveEmbedderKind } from "../embeddings/index.ts";
 import { getConfiguredMinSearchScore, getConfiguredSearchAlpha,
-  getMaxResponseBytes, getMinTermCoverage, logUsage } from "./_utils.ts";
+  getMaxResponseBytes, getMinTermCoverage, logUsage , resolveByteBudget } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
@@ -214,11 +214,7 @@ async function handler(
   // falling back to the ceiling there would hand a caller whose remaining
   // allowance ran out the largest possible reply (#267). Only a missing or
   // non-numeric value defaults to the ceiling.
-  const requestedBytes = Math.floor(Number(requested_max_bytes));
-  const max_bytes = Math.min(
-    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling,
-    ceiling,
-  );
+  const max_bytes = resolveByteBudget(requested_max_bytes, ceiling);
 
   if (
     metadata_filter !== null &&

package/dist/server-assets/supabase/functions/cerefox-metadata-search/index.ts

@@ -4,6 +4,7 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
 import { reviewWorkflowEnabled } from "../../../_shared/mcp-tools/feature-flags.ts";
+import { resolveByteBudget } from "../../../_shared/mcp-tools/_utils.ts";
 
 /**
  * cerefox-metadata-search -- Supabase Edge Function
@@ -103,8 +104,12 @@ Deno.serve(async (req: Request): Promise<Response> => {
     const include_content = body.include_content ?? false;
     const requested_max_bytes = body.max_bytes;
 
+    // One implementation of this arithmetic, shared with every other surface
+    // that takes a budget (#268): non-numeric and null both mean "unset" and
+    // fall back to the ceiling, while a real number of zero or less is
+    // honoured as "almost no budget".
     const max_bytes = include_content
-      ? Math.min(requested_max_bytes ?? MAX_BYTES, MAX_BYTES)
+      ? resolveByteBudget(requested_max_bytes, MAX_BYTES)
       : null;
 
     const supabaseUrl = Deno.env.get("SUPABASE_URL")!;
@@ -154,18 +159,90 @@ Deno.serve(async (req: Request): Promise<Response> => {
       });
     }
 
-    // Fire-and-forget usage logging
+    let rows = (data ?? []) as Array<Record<string, unknown>>;
+
+    // Never answer with a shorter list than what matched (#268).
+    //
+    // The RPC applies `p_max_bytes` server-side by stopping at the first row
+    // whose content does not fit, so this list has two indistinguishable
+    // causes: fewer documents matched, or the budget cut it short. When the
+    // first row is the oversized one the array comes back EMPTY, and a caller
+    // reads `[]` as "this knowledge does not exist" and stops looking — the
+    // false negative #254 exists to prevent, reached here through a sibling
+    // that never got the guard.
+    //
+    // The response shape stays a bare array, because Custom GPTs are
+    // configured against it: every matching document is listed, and only
+    // CONTENT is negotiable. Rows the budget could not afford come back
+    // content-free and marked, so `results.length` is always the true count
+    // and nothing is held back silently.
+    //
+    // Cost: a second RPC round-trip whenever a content-bearing search returns
+    // less than a full page, which is the common case rather than a rare one.
+    // The RPC signals no total, so the only alternative to asking is guessing
+    // whether a short list was cut — and guessing wrong is the bug.
+    if (include_content && max_bytes !== null && rows.length < limit) {
+      const { data: headerData, error: probeError } = await supabase.rpc(
+        "cerefox_metadata_search",
+        { ...params, p_include_content: false, p_max_bytes: null },
+      );
+      // supabase-js RESOLVES with `{ data: null, error }` for PostgREST and
+      // network failures rather than throwing, so a probe failure must be read
+      // from the error, not inferred from an empty list — reading it as "no
+      // documents" is the very false empty this branch prevents (#261).
+      if (probeError && rows.length === 0) {
+        // Falling through here would ship exactly the false empty this block
+        // exists to prevent — `200 []`, which a caller reads as "no such
+        // knowledge". An error is the honest answer: it says the question was
+        // not resolved, rather than answering it wrongly.
+        return new Response(
+          JSON.stringify({
+            error:
+              `Nothing fit max_bytes=${max_bytes} with include_content, and the follow-up ` +
+              `query that lists what matched failed: ${probeError.message}. This is NOT a ` +
+              `confirmed empty result — retry with a larger max_bytes, or include_content: false.`,
+          }),
+          { status: 502, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
+        );
+      }
+      if (!probeError) {
+        const headers = (headerData ?? []) as Array<Record<string, unknown>>;
+        if (headers.length > rows.length) {
+          const withContent = new Map(rows.map((r) => [r.document_id as string, r]));
+          // The probe carries the full, correctly ordered match set; the
+          // content-bearing rows are folded into it by id so ordering is the
+          // RPC's, not an artefact of which rows happened to fit.
+          const merged = headers.map(
+            (h) => withContent.get(h.document_id as string) ?? { ...h, content_omitted: true },
+          );
+          // Two queries, two chances to disagree: the RPC orders by
+          // `updated_at DESC` with no tiebreaker under a LIMIT, and a
+          // concurrent write between the calls shifts the window. Anything the
+          // content query returned that the probe did not is APPENDED rather
+          // than dropped — losing a document we already hold, while fixing a
+          // bug about losing documents, would be its own joke.
+          const seen = new Set(merged.map((r) => r.document_id as string));
+          for (const r of rows) {
+            if (!seen.has(r.document_id as string)) merged.push(r);
+          }
+          rows = merged;
+        }
+      }
+    }
+
+    // Fire-and-forget usage logging. Counts what MATCHED, not what the budget
+    // allowed through: a budget-wiped search logging `0` misreports the store
+    // as empty in analytics (#259).
     Promise.resolve(supabase.rpc("cerefox_log_usage", {
       p_operation: "metadata_search",
       p_access_path: "edge-function",
       p_requestor: identityValue ?? null,
       p_query_text: JSON.stringify(metadata_filter),
-      p_result_count: (data ?? []).length,
+      p_result_count: rows.length,
       p_project_id: project_id,
     })).catch(() => {});
 
     // Presentation only: the same shared reader every other surface uses.
-    const rows = (data ?? []) as Array<Record<string, unknown>>;
     const showReview = await reviewWorkflowEnabled(supabase);
     const out = showReview
       ? rows

package/dist/server-assets/supabase/functions/cerefox-search/index.ts

@@ -5,7 +5,7 @@ import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
 // One implementation of the byte budget, shared with the MCP tools (#254).
-import { applyByteBudget } from "../../../_shared/mcp-tools/_utils.ts";
+import { applyByteBudget, resolveByteBudget } from "../../../_shared/mcp-tools/_utils.ts";
 
 /**
  * cerefox-search — Supabase Edge Function
@@ -219,11 +219,7 @@ Deno.serve(async (req: Request) => {
   // check, so a non-numeric value bypassed the ceiling entirely (#266).
   // A number of 0 or less still means "almost no budget"; only a missing or
   // non-numeric value falls back to the ceiling (#267).
-  const requestedBytes = Math.floor(Number(requested_max_bytes));
-  const max_bytes = Math.min(
-    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : MAX_BYTES,
-    MAX_BYTES,
-  );
+  const max_bytes = resolveByteBudget(requested_max_bytes, MAX_BYTES);
   // Clamp match_count to [1, MAX_MATCH_COUNT] (bounds query work; see MAX_MATCH_COUNT).
   const match_count = Math.min(Math.max(1, Math.floor(Number(raw_match_count)) || 5), MAX_MATCH_COUNT);
 

package/docs/guides/connect-agents.md

@@ -638,7 +638,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 4.2.0
+  version: 4.3.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -1051,8 +1051,10 @@ paths:
                   type: integer
                   default: 200000
                   description: >
-                    Response size budget in bytes when include_content is true
-                    (whole results dropped to fit). Advanced; leave unset for the default.
+                    Response size budget in bytes when include_content is true.
+                    Content is dropped whole, never truncated mid-document, and a
+                    document whose content is dropped is still listed with
+                    content_omitted: true. Advanced; leave unset for the default.
                 author:
                   type: string
                   description: >
@@ -1067,6 +1069,12 @@ paths:
                version_count, content_hash, content }], plus review_status
             only while the store's review workflow is on (the key is absent
             when it is off).
+            The array lists EVERY matching document, so its length is the true
+            match count. When include_content is true and max_bytes cannot
+            carry a document's text, that document is still listed, with its
+            content omitted and "content_omitted": true set on the item — the
+            list is never silently shortened, and an empty array always means
+            nothing matched.
             content_hash is the concurrency token — pass it back as
             expected_content_hash when updating via ingestNote.
 ```

package/docs/guides/response-limits.md

@@ -8,11 +8,18 @@ explains how response size limits work and how to tune them.
 
 ## The key principle: opt-in limits, never truncate the web UI
 
-The web UI and CLI never truncate results. They have no size limit — the browser or terminal
-can handle arbitrarily large responses and there is no LLM context window to worry about.
+The web UI never truncates results. It has no size limit — the browser can handle
+arbitrarily large responses and there is no LLM context window to worry about.
 
-Limits are **opt-in per call**, used only on the MCP and Edge Function paths where an AI
-agent's context window matters. Callers always choose whether to apply a limit.
+Limits apply on the MCP, Edge Function **and CLI** paths. On MCP and the Edge Functions
+they exist because an AI agent's context window matters; the CLI applies the same default
+so that one setting (`CEREFOX_MAX_RESPONSE_BYTES`) governs every non-browser path, and
+raises or lowers it per call with `--max-bytes`.
+
+> **Changed in v0.10.2.** The CLI originally returned everything, like the web UI. It now
+> honours `CEREFOX_MAX_RESPONSE_BYTES` (200 000 default) and prints
+> `(results truncated at N bytes; use --max-bytes to raise)` when results are dropped.
+> This guide described the pre-v0.10.2 behaviour until v1.14.4.
 
 ---
 
@@ -21,7 +28,7 @@ agent's context window matters. Callers always choose whether to apply a limit.
 | Path | Limit behaviour |
 |------|----------------|
 | Web UI (`/search`) | **No limit** — all results returned |
-| CLI (`cerefox search`) | **No limit** — all results returned |
+| CLI (`cerefox search`) | Defaults to `CEREFOX_MAX_RESPONSE_BYTES` (200 000); raise or lower per call with `--max-bytes`. Announces truncation. |
 | Local MCP server (`cerefox mcp`) | Defaults to `CEREFOX_MAX_RESPONSE_BYTES` (200 000); agent can request less |
 | Edge Function (`cerefox-search`) | Defaults to 200 000 bytes; agent can request less via `max_bytes` body param |
 | Remote MCP (`cerefox-mcp` Edge Function) | Defaults to 200 000 bytes; agent can request less via `max_bytes` tool param |
@@ -35,8 +42,10 @@ Cerefox never cuts a document mid-content.
 
 A result that does not fit is **skipped**, not treated as the end of the list, so the
 returned set is not necessarily the top N by rank: one oversized document ranked first
-does not hide the smaller results behind it (v1.14.3). Anything skipped is named in the
-footer, so what is missing is always visible.
+does not hide the smaller results behind it (v1.14.3 on the MCP tool; v1.14.4 on the
+`cerefox-search` Edge Function and the CLI, which both still stopped at the first
+oversized row). Anything skipped is named in the footer, so what is missing is always
+visible.
 
 When truncation occurs:
 - The MCP tool appends a footer naming what was held back:
@@ -59,6 +68,30 @@ below-confidence advisory. Both are a few dozen bytes, and neither is ever
 traded for content. Returning 1 of 5 results without saying so, or presenting
 weak candidates as confident ones, would be worse than a small overrun.
 
+### Metadata search follows the same rules (v1.14.4)
+
+`cerefox_metadata_search` and the `cerefox-metadata-search` Edge Function apply
+`max_bytes` only when `include_content: true`, and the budget is applied by the
+database, which stops at the first document whose content does not fit. That
+made two silent failures possible until v1.14.4, and both are now closed:
+
+- **The reply is never empty when documents matched.** If the first document is
+  the oversized one, the budget used to empty the result set — the MCP tool
+  returned "No documents match", the Edge Function returned `[]`. Both now say
+  what matched: the tool with a warning and a header list, the Edge Function by
+  listing every matching document with content omitted.
+- **Documents are never held back silently.** The MCP tool appends
+  `[2 of 7 document(s) shown; 5 did not fit max_bytes=20000. …]`. The Edge
+  Function keeps its array shape and lists **every** matching document, marking
+  the ones whose content did not fit with `"content_omitted": true` — so
+  `results.length` is always the true match count and only content is dropped.
+
+`max_bytes` is resolved the same way on every path: `null`, absent, empty or
+non-numeric all mean **unset** and fall back to the server ceiling, and none of
+them disables the limit. A real number of zero or less means "almost no
+budget" and is honoured as such — a caller whose allowance has run out is not
+handed the largest possible reply.
+
 ---
 
 ## The server ceiling — agents can request less, never more
@@ -164,7 +197,7 @@ threshold (it is a SQL DEFAULT in `rpcs.sql`, changed via `cerefox server deploy
 | Question | Answer |
 |----------|--------|
 | Does the web UI truncate results? | No — unlimited |
-| Does the CLI truncate results? | No — unlimited |
+| Does the CLI truncate results? | Yes — at `CEREFOX_MAX_RESPONSE_BYTES`, or `--max-bytes`. It says so when it does. |
 | What is the default MCP response limit? | 200 000 bytes |
 | Can an agent request a smaller limit? | Yes — `max_bytes` tool parameter |
 | Can an agent exceed the server ceiling? | No — always capped |

package/package.json

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