@cerefox/memory 1.14.2 → 1.14.3

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.1.0
+  version: 4.2.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -697,7 +697,10 @@ paths:
                     Response size budget in bytes (server hard ceiling 200000).
                     Whole results are dropped (never truncated mid-document) until
                     the budget is met; the response sets `truncated: true` when this
-                    happens. Advanced; leave unset for the default.
+                    happens. One exception: when nothing fits at all, a single
+                    content-free header is returned even if it exceeds the budget,
+                    because an empty results array would read as "nothing was found"
+                    (see degraded). Advanced; leave unset for the default.
                 author:
                   type: string
                   description: >
@@ -713,9 +716,11 @@ paths:
             chunk_count, total_chars, best_score, is_partial.
             matched is how many results the query found, before the byte budget.
             When degraded is true, everything that matched was larger than max_bytes, so the
-            items carry NO full_content — they name what exists so you can re-ask with a
-            larger max_bytes or fetch one document. An empty results array with degraded
-            true is never "nothing was found"; results is empty only when matched is 0.
+            items carry NO content of any kind — they name what exists so you can re-ask with
+            a larger max_bytes or fetch one document. That header list is itself capped to
+            max_bytes, so it may be a SUBSET of matched (at least one item is always
+            returned). Read matched, never results.length, to know how much the query found:
+            "nothing was found" is matched == 0.
             is_partial is true when the document exceeded the small-to-big threshold — in that
             case full_content contains matched chunks plus their neighbours rather than the
             complete document, and total_chars still reflects the full document size.
@@ -1130,7 +1135,7 @@ If the same content was already ingested (SHA-256 hash match), returns `"skipped
 | `mode` | string | `"docs"` | `"docs"` = full document results (recommended) |
 | `alpha` | number | 0.7 | Semantic weight (0 = FTS only, 1 = semantic only) |
 | `min_score` | number | 0.5 | Minimum cosine similarity threshold |
-| `max_bytes` | number | 200000 | Response size budget in bytes. Results are dropped whole (never truncated mid-document) once the budget is reached. The response includes `truncated: true` and `response_bytes` when the limit was hit. See "Response size limit" below. |
+| `max_bytes` | number | 200000 | Response size budget in bytes. Results are dropped whole (never truncated mid-document) once the budget is reached. The response includes `truncated: true` and `response_bytes` when the limit was hit. When nothing fits, `degraded: true` and a content-free header list come back instead of an empty `results` — always at least one item, even if it exceeds the budget. See "Response size limit" below. |
 
 **Response envelope fields:**
 

package/docs/guides/response-limits.md

@@ -30,13 +30,35 @@ agent's context window matters. Callers always choose whether to apply a limit.
 
 ## How limits are applied
 
-Truncation is always **whole-document**: results are dropped in full once adding the next
-document would exceed the budget. Cerefox never cuts a document mid-content.
+Truncation is always **whole-document**: a result is returned in full or not at all.
+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.
 
 When truncation occurs:
-- The local MCP server appends `[Results truncated at N bytes — ...]` to the response text.
+- The MCP tool appends a footer naming what was held back:
+  `[3 of 12 result(s) shown; 9 did not fit max_bytes=8000: Plan › Rollout (chunk 4) [id: …] and 8 more. Raise max_bytes, narrow the query, or lower match_count.]`
 - The Edge Function includes `"truncated": true` and `"response_bytes": N` in the JSON response.
 
+**The reply as a whole stays inside the budget**, footer and warnings included:
+they are measured in the same rendered bytes the caller receives (v1.14.3).
+When the budget is tight the framing gives way before the results do.
+
+**When nothing fits at all** — the smallest matching document is larger than
+the whole budget — the reply is NOT "no results found", which an agent acts on
+as "this knowledge does not exist". It is a header list naming what matched,
+its size and its id, prefixed with a warning and the remedy. The same case on
+the Edge Function sets `"degraded": true`, returns items with no content, and
+reports `"matched"`: read that, not `results.length`, to know what the query
+found. A reply may exceed `max_bytes` only by the framing that cannot be dropped
+without misleading you: the notice that results were held back, or the
+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.
+
 ---
 
 ## The server ceiling — agents can request less, never more

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.14.2",
+  "version": "1.14.3",
   "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",
@@ -39,12 +39,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@hono/node-server": "^2.0.12",
+    "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@supabase/supabase-js": "^2.45.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
-    "hono": "^4.12.34",
+    "hono": "^4.13.7",
     "mammoth": "^1.9.0",
     "ora": "^9.4.0",
     "picocolors": "^1.0.0",