@mnemoverse/mcp-memory-server 0.9.0 → 0.10.0

package/dist/index.js

@@ -12,6 +12,11 @@ import { SERVER_INSTRUCTIONS, buildReadEmptyResponse } from "./teaching.js";
 import { classifyRooms, futureSinceNote, probeReadScope, readScopeNote, scopeLabel, } from "./scope.js";
 import { readRequestBody, recentRequestBody, writeRequestBody, searchedScope, } from "./requests.js";
 import { exactLiteral, formatDomainList, roomNamePhrase, withDomainEscapeLegend, } from "./names.js";
+// Every non-2xx becomes an instruction to the calling model instead of a raw
+// wire echo — see the header of src/errors.ts for why, and for what each status
+// actually means in this engine. So does a 2xx whose body this client cannot
+// parse, which is a third case and not a variant of either of the other two.
+import { ApiError, NetworkError, UnreadableBodyError } from "./errors.js";
 /**
  * What we know about the scope this read actually covered — a VALUE rather
  * than a sentence-or-empty-string. Costs one GET (rooms or stats, chosen by
@@ -58,19 +63,121 @@ function probeScope(searched) {
 // `node_modules/@mnemoverse/mcp-memory-server/dist/` after an npm install.
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
-const API_URL = process.env.MNEMOVERSE_API_URL || "https://core.mnemoverse.com/api/v1";
+/** Where the key goes when the user names no host. Referenced by the base-URL
+ *  refusal below, which has to tell them what to set it back to. */
+const DEFAULT_API_URL = "https://core.mnemoverse.com/api/v1";
+const API_URL = process.env.MNEMOVERSE_API_URL || DEFAULT_API_URL;
 const API_KEY = process.env.MNEMOVERSE_API_KEY || "";
 // Hard cap on tool result size — required by Claude Connectors Directory
 // (https://support.claude.com/en/articles/12922490-remote-mcp-server-submission-guide).
 // Approximate token count = chars / 4. Cap at 24,000 tokens to leave headroom under the 25K limit.
 const MAX_RESULT_CHARS = 24_000 * 4;
-// The API key is validated lazily — inside apiFetch, on the first tool call —
-// rather than at startup. This lets the server START WITHOUT a key so that
-// `tools/list` and other introspection work key-free. MCP directories and
-// registries (e.g. Glama) boot the server to enumerate and score its tools,
-// and clients may browse capabilities before sign-in; a startup exit on a
-// missing key blocks all of that. A tool *invocation* without a key returns a
-// clear, actionable error instead (see apiFetch).
+/**
+ * Is `MNEMOVERSE_API_URL` an address this client may attach the API key to —
+ * and if not, what does the user have to change (#99, CWE-319)?
+ *
+ * `apiFetch` attaches `X-Api-Key` to whatever this variable holds. Until this
+ * check existed, a base URL spelled `http://` — a typo, a copied tunnel address,
+ * a misread doc — put a live `mk_live_` key in cleartext on every tool call, on
+ * every hop between the user and that host, with nothing anywhere saying so.
+ * The key is the whole account: it reads and writes that user's memory.
+ *
+ * THREE HOSTS ARE EXEMPT, AND ONLY AS LITERAL HOSTNAMES. `http://localhost`,
+ * `http://127.0.0.1` and `http://[::1]` are legitimate — a self-hosted engine,
+ * this repo's own test harness — and a guard that demanded https unconditionally
+ * would break them. The comparison is against `URL.hostname`, NOT a prefix or
+ * suffix of the raw string, because `http://localhost.evil.example` passes a
+ * prefix test and `http://evil.localhost` passes a suffix test while both
+ * resolve to somebody else's server. The exemption is also scheme-bound —
+ * `ftp://localhost` is refused — since "aimed at loopback" is not by itself a
+ * reason to trust a transport.
+ *
+ * THE IPv6 LITERAL CARRIES ITS BRACKETS. `new URL("http://[::1]:8100")` reports
+ * `hostname` as `"[::1]"` — brackets included, not `"::1"` — so that is what the
+ * comparison holds, and test/base-url-guard.test.ts pins both spellings a user
+ * can type: the parser compresses `[0:0:0:0:0:0:0:1]` to `[::1]` before this
+ * function sees it, so one literal covers the long form too.
+ *
+ * WHAT IS STILL REFUSED, AND ON PURPOSE. `host.docker.internal` is NOT loopback
+ * and is not exempt: it resolves through the container's resolver to an address
+ * on the host network, so the packet — and the key — leaves the container before
+ * anything knows where it lands. "Aimed at my own machine" is a claim about
+ * intent; the exemption is about the wire. `[::ffff:127.0.0.1]` is refused for
+ * a smaller reason: it does reach 127.0.0.1, but it is a fourth spelling of an
+ * address that already has three legal ones, and widening an exemption that
+ * protects a live key is a decision, not a convenience.
+ *
+ * RETURNS A STRING RATHER THAN THROWING, and is called at import rather than
+ * on each request, because a throw at import would take the server down before
+ * `tools/list` — the one thing that is documented to work without any config at
+ * all (registries boot this server to enumerate its tools). The refusal has to
+ * land where the keyless refusal lands: inside a tool CALL.
+ *
+ * THE MESSAGE NEVER QUOTES THE URL, only its scheme. src/errors.ts keeps the
+ * base URL out of every message it builds on the stated grounds that the base
+ * can carry credentials — `http://user:pass@host` is exactly the case this guard
+ * fires on, so the one message whose subject IS the base URL is also the one
+ * most likely to leak it into a model's context and a client's logs. A scheme
+ * is safe to interpolate for a second reason: the URL parser restricts it to
+ * `[a-z0-9+.-]`, so it cannot carry a newline and open its own paragraph in
+ * this file's instruction voice.
+ */
+function refuseInsecureBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return {
+            toolCall: "Mnemoverse: this tool did not run, because MNEMOVERSE_API_URL is not " +
+                "a URL this client can parse — so it cannot tell whether sending the " +
+                "API key to it would expose the key, and it will not guess. Nothing " +
+                "was sent. This is the user's configuration: their key, their network " +
+                "and the service are all fine. Tell them to set MNEMOVERSE_API_URL to " +
+                "a complete https:// URL including the scheme and the path — the " +
+                `default is ${DEFAULT_API_URL} — or to unset it and use that default. ` +
+                "A local engine is the one exception and must be addressed as " +
+                "http://localhost, http://127.0.0.1 or http://[::1]. Do not retry " +
+                "until it is changed; every memory tool will fail the same way " +
+                "until then.",
+            startupLog: "Mnemoverse: startup key check SKIPPED, and nothing was sent — " +
+                "MNEMOVERSE_API_URL is not a URL this server can parse, so it cannot " +
+                "tell whether sending your API key over it would expose it. Set it to " +
+                `a complete https:// URL such as ${DEFAULT_API_URL}, or unset it to ` +
+                "use that default. Every memory tool will fail until it is changed.",
+        };
+    }
+    const loopback = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        // Brackets included: that is what `URL.hostname` reports for an IPv6 host.
+        url.hostname === "[::1]";
+    if (url.protocol === "https:" || (url.protocol === "http:" && loopback)) {
+        return undefined;
+    }
+    return {
+        toolCall: "Mnemoverse: this tool did not run, because MNEMOVERSE_API_URL does not " +
+            `address the API over https — its scheme is ${url.protocol}// — and ` +
+            "sending the API key to it would put a live mk_live_ key on the wire in " +
+            "cleartext, readable by anything on the path. Nothing was sent: this " +
+            "client refuses the call instead. This is the user's configuration, not " +
+            "a fault of the key, the network or the service. Tell them to change " +
+            "MNEMOVERSE_API_URL to the https:// form of the same host — the default " +
+            `is ${DEFAULT_API_URL} — or, if they are deliberately running the ` +
+            "engine on their own machine, to address it as http://localhost, " +
+            "http://127.0.0.1 or http://[::1] — the only three plain-http hosts " +
+            "this client accepts. Do not retry until it is changed; every memory " +
+            "tool will fail the same way until then.",
+        startupLog: "Mnemoverse: startup key check SKIPPED, and nothing was sent — " +
+            `MNEMOVERSE_API_URL has the scheme ${url.protocol}// rather than ` +
+            "https://, and this server will not put your API key on the wire in " +
+            `cleartext. Set it to ${DEFAULT_API_URL}, or to http://localhost, ` +
+            "http://127.0.0.1 or http://[::1] if you run the engine yourself. " +
+            "Every memory tool will fail until it is changed.",
+    };
+}
+/** The verdict on this process's base URL, computed once. `undefined` means the
+ *  key may go out; anything else is what each surface says instead. */
+const BASE_URL_REFUSAL = refuseInsecureBaseUrl(API_URL);
 /**
  * Fetch from the Mnemoverse core API with authentication.
  *
@@ -82,31 +189,127 @@ const MAX_RESULT_CHARS = 24_000 * 4;
  * handlers may switch to 204 in the future even though today they return
  * a JSON body.
  *
- * @throws Error with message `Mnemoverse API error {status}: {body}` on non-2xx.
+ * @throws {@link ApiError} on non-2xx — whose message is the agent-facing
+ * explanation from src/errors.ts, with the raw body kept after it. The MCP SDK
+ * turns a thrown Error into `{isError: true, content: [{type: "text", text:
+ * error.message}]}`, so this message IS what the calling model reads; that is
+ * why it is written as instructions rather than as a wire dump.
  */
 async function apiFetch(path, options = {}) {
+    const method = (options.method ?? "GET").toUpperCase();
     if (!API_KEY) {
-        throw new Error("MNEMOVERSE_API_KEY is required for this operation. Get a free key at " +
-            "https://console.mnemoverse.com and set it in your MCP client config.");
+        // The one failure that needs no request to diagnose — and the only one
+        // where the fix is "set the variable" rather than "replace its value".
+        // Kept distinct from the 401 sentence for exactly that reason.
+        throw new Error("Mnemoverse: no API key is configured, so this tool cannot run. Tell the " +
+            "user to set MNEMOVERSE_API_KEY in their MCP client config — a free key " +
+            "takes about 30 seconds at https://console.mnemoverse.com/dashboard/keys " +
+            "and starts with mk_live_. Do not retry until it is set; every memory " +
+            "tool will fail the same way until then.");
+    }
+    if (BASE_URL_REFUSAL !== undefined) {
+        // Alongside the key check, and after it: with no key configured there is
+        // nothing to expose, and "set the variable" is the more useful first thing
+        // to tell someone who has set neither. Both are decided from CONFIGURATION
+        // alone, which is why both belong here rather than in a diagnosis of the
+        // response — a guard that fired after fetch would print the right sentence
+        // about a key it had already put on the wire.
+        throw new Error(BASE_URL_REFUSAL.toolCall);
+    }
+    let res;
+    try {
+        res = await fetch(`${API_URL}${path}`, {
+            ...options,
+            // AFTER the spread, so no call site can opt out of it. `fetch` defaults to
+            // "follow", and Node re-sends request headers to the redirect target: the
+            // WHATWG rules strip Authorization, Cookie and Proxy-Authorization when
+            // the origin changes and say nothing about a custom header, so
+            // `X-Api-Key` rides along to whoever answered (#99, CWE-200). This API
+            // serves one stable base path and never redirects legitimately, so the
+            // only traffic this refuses is an exfiltration path. The resulting
+            // rejection is named by explainNetworkFailure rather than left to look
+            // like a dead host.
+            redirect: "error",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Api-Key": API_KEY,
+                ...(options.headers || {}),
+            },
+        });
+    }
+    catch (cause) {
+        // `TypeError: fetch failed` is what a model used to read here, which is as
+        // uninstructive as the raw 401 body this change is about. Every existing
+        // caller that swallows a failure (the scope probes, the empty-read stats
+        // call) catches without inspecting the type, so wrapping changes nothing
+        // for them — it only changes what surfaces when nobody catches.
+        throw new NetworkError(method, path, cause);
     }
-    const res = await fetch(`${API_URL}${path}`, {
-        ...options,
-        headers: {
-            "Content-Type": "application/json",
-            "X-Api-Key": API_KEY,
-            ...(options.headers || {}),
-        },
-    });
     if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`Mnemoverse API error ${res.status}: ${text}`);
+        // `fetch()` resolves once HEADERS arrive; a connection reset during the
+        // body read rejects HERE, not in the catch above, and used to surface as
+        // a raw undici TypeError (Copilot, #93).
+        //
+        // It is NOT the same failure as the catch above, and calling it one threw
+        // the status away: a 502 whose body died mid-stream was reported as "the
+        // memory service could not be reached at all… before any HTTP response
+        // came back", about a response whose status we are holding. The status is
+        // the most actionable thing this failure has, so it goes in the sentence.
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (cause) {
+            throw new UnreadableBodyError({ status: res.status, method, path, cause });
+        }
+        throw new ApiError({
+            status: res.status,
+            body: text,
+            method,
+            path,
+            // Only the rate-limit middleware sets it, and only on the 429 that
+            // waiting actually clears — so its PRESENCE is evidence, not decoration.
+            retryAfter: res.headers.get("retry-after"),
+        });
     }
     // 204 No Content or empty body — return an empty object cast as T so
     // call sites using optional chaining still work without crashing.
     if (res.status === 204 || res.headers.get("content-length") === "0") {
         return {};
     }
-    return (await res.json());
+    // A 2xx WHOSE BODY THIS CLIENT CANNOT READ. Read the text first and parse it
+    // second, rather than `res.json()`, for one reason: `res.json()` consumes the
+    // stream, so when it throws there is nothing left to quote — and the bytes
+    // are the evidence. A captive portal's sign-in page, an SPA shell served with
+    // 200 text/html, a MITM proxy's notice, or a JSON body that stopped mid-write
+    // all land here, and the first line of any of them identifies the culprit.
+    //
+    // Both throws used to be NetworkError, which asserts that NOTHING answered —
+    // "could not be reached at all… before any HTTP response came back… a
+    // connectivity or DNS problem" — while a 200 sat in this very function's
+    // hand, and the Raw detail below it quoted a SyntaxError out of the body it
+    // had just called nonexistent. Sending a user to debug wifi while a portal
+    // answers every request is the confident wrong cause src/errors.ts exists to
+    // remove. A real `fetch()` rejection above keeps that wording; this does not.
+    let body;
+    try {
+        body = await res.text();
+    }
+    catch (cause) {
+        throw new UnreadableBodyError({ status: res.status, method, path, cause });
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        throw new UnreadableBodyError({
+            status: res.status,
+            method,
+            path,
+            bodyPreview: body,
+            cause,
+        });
+    }
 }
 /**
  * Truncate a result string to MAX_RESULT_CHARS, appending a notice if truncated.
@@ -137,7 +340,7 @@ moreHint = "Use a more specific query to see all results.") {
     return `${truncated}\n\n[…truncated to fit the 25K token limit. ${moreHint}]`;
 }
 /**
- * A 200 whose body does not carry the array core always sends for a listing.
+ * A 2xx whose body does not carry what core always sends for this operation.
  *
  * Reading such a body as an EMPTY list is the substitution this release exists
  * to remove: `Array.isArray(x) ? x : []` turned "this client could not read
@@ -149,8 +352,19 @@ moreHint = "Use a more specific query to see all results.") {
  * is NOT ("a list of your rooms"), and the absence it is NOT evidence of
  * ("you have none") — so every consumer states its own boundary while the
  * sentence stays one sentence everywhere (truth F13, 2026-08-08).
+ *
+ * NOT ONLY LISTS any more: memory_write was the last surface still reading
+ * a missing field as a stated one — `if (r?.stored)`, whose else-branch was an
+ * unconditional "NOT STORED — nothing was saved" plus a mechanism nobody sent.
+ * It is the same class of claim about a different shape, so it gets the same
+ * sentence, and the name no longer says "List".
+ *
+ * `extra` exists for the write surface alone: a list that could not be read
+ * leaves the caller merely uninformed, whereas a WRITE that could not be read
+ * leaves an operation whose outcome is unknown, and the caller must be told not
+ * to report either outcome to the user.
  */
-function unreadableListReply(subject, notA, absence) {
+function unreadableAnswerReply(subject, notA, absence, extra = "") {
     return {
         content: [
             {
@@ -162,7 +376,7 @@ function unreadableListReply(subject, notA, absence) {
                 // unrecognised body (truth re-verification, 2026-08-09). Pinned in
                 // test/handlers.test.ts.
                 text: `${subject} came back in a shape this client does not recognise — so this ` +
-                    `is not ${notA}, and it is not evidence that ${absence}. Retry; ` +
+                    `is not ${notA}, and it is not evidence that ${absence}.${extra} Retry; ` +
                     `if it persists, whatever answered this call — the memory service, a ` +
                     `gateway or proxy in front of it, or the endpoint a mis-set ` +
                     `MNEMOVERSE_API_URL points at — is answering in a shape this client ` +
@@ -221,6 +435,29 @@ export const server = new McpServer({
 function isRoomDomain(domain) {
     return typeof domain === "string" && domain.startsWith("xroom:");
 }
+/**
+ * The three outcomes this client will ever print a WRITE promise about for a
+ * room membership. Core grants exactly two scopes — "read" and "read_write"
+ * (rooms_routes.py `_VALID_SCOPES`) — and refuses a read-only member's
+ * memory_write with a 403 "Read-only membership cannot write to this room"
+ * (src/errors.ts). Anything else on the wire (missing field, a Copilot-shaped
+ * partial body) is UNSPECIFIED: the server did not say what memory_write would
+ * do for this membership, so this client does not guess either — it is treated
+ * like "read" for the purpose of NOT promising write, but is not told it is
+ * read-only, because that is also a claim the response did not make.
+ *
+ * Bug hunt (pre-0.9.2, P2): memory_join_room's usage sentence and
+ * memory_list_rooms's per-row tail both used to print "use domain=... [on
+ * memory_write / memory_read] to read and write" unconditionally — true for a
+ * read_write membership, false for a read-only one.
+ */
+function roomScopeVerdict(scope) {
+    if (scope === "read_write")
+        return "read_write";
+    if (scope === "read")
+        return "read";
+    return "unspecified";
+}
 // --- Tool: memory_write ---
 server.registerTool("memory_write", {
     description: "Store a long-term memory that persists across sessions AND across every AI tool the user has connected to Mnemoverse (Claude, ChatGPT, Cursor, VS Code) — write once, recall everywhere. Call this PROACTIVELY the moment the user states a preference, makes a decision, or you learn a durable fact (people, roles, project setup, a lesson). Don't wait to be asked. Never store passwords, API keys, payment data, MFA codes, government IDs, or health records; skip transient chatter that only matters this turn. Behavior: an importance gate may filter low-value writes, so the result tells you whether the memory was stored or filtered. Write `content` as a self-contained statement that still makes sense when recalled out of context.",
@@ -237,7 +474,12 @@ server.registerTool("memory_write", {
         domain: z
             .string()
             .optional()
-            .describe("Namespace to organize memories (e.g. 'engineering', 'user:alice', 'project:acme')"),
+            .describe("Namespace to organize memories (e.g. 'engineering', 'user:alice', 'project:acme')." +
+            " Matched byte-for-byte — a leading space, a different case, or an invisible" +
+            " character opens a SEPARATE, permanent store, so reuse an exact name from" +
+            " memory_stats rather than retyping one. To write into a shared room, pass its" +
+            " address here instead (e.g. 'xroom:room_01ABC'). Find room addresses with" +
+            " memory_list_rooms."),
     },
     annotations: {
         title: "Store Memory",
@@ -276,6 +518,29 @@ server.registerTool("memory_write", {
         method: "POST",
         body: JSON.stringify(writeRequestBody({ content, concepts, domain })),
     });
+    // `stored` MUST BE A BOOLEAN before either verdict below may be printed.
+    //
+    // This was the last surface reading a MISSING field as a field that said
+    // false. `if (r?.stored)` sent every body that did not say `true` to the
+    // else-branch, whose first four words are "NOT STORED — nothing was saved"
+    // and whose last sentence explains WHY: "Writes are gated on how much a
+    // memory adds… so a near-duplicate is refused." So a 204, an empty `{}`, a
+    // proxy or gateway answering `{"ok":true}`, and a mis-set
+    // MNEMOVERSE_API_URL all produced an absence claim about the user's memory
+    // AND a fabricated mechanism for it — two statements, neither with any
+    // evidence behind it. The write is also the surface where being wrong costs
+    // most: a caller told "nothing was saved" re-words and retries, or drops
+    // the fact, and the atom that may in fact be sitting in the store is not
+    // what the user is told about.
+    //
+    // The four LIST surfaces have had this guard since 0.8.1 (truth F13); the
+    // write did not. The test for `boolean` and not for presence is deliberate:
+    // `{"stored":"yes"}` is not core speaking either.
+    if (typeof r?.stored !== "boolean") {
+        return unreadableAnswerReply("The write result", "confirmation that the memory was stored", "it was refused", " Whether the content reached memory is unknown from here — report the" +
+            " outcome of the RETRY, not of this call, and do not tell the user it" +
+            " was saved or that it was rejected.");
+    }
     // "unknown", not 0.00, when the server didn't send a score — the same rule
     // memory_stats got in this release. A live surface exists that answers
     // {"stored":false} with no reason and no score; printing "0.00" there
@@ -292,7 +557,9 @@ server.registerTool("memory_write", {
     const reasonQuote = r?.reason
         ? (exactLiteral(r.reason, 400)?.literal ?? "(too long to quote exactly)")
         : "";
-    if (r?.stored) {
+    // Narrowed to `true` by the guard above, so this is now the server's stated
+    // verdict rather than "the body was not falsy".
+    if (r.stored) {
         return {
             content: [
                 {
@@ -468,7 +735,7 @@ server.registerTool("memory_read", {
     // rooms, one level up from the probes (truth F13, 2026-08-08).
     const items = r?.items;
     if (!Array.isArray(items)) {
-        return unreadableListReply("The search result", "a list of matches", "nothing matched");
+        return unreadableAnswerReply("The search result", "a list of matches", "nothing matched");
     }
     if (items.length === 0 && (since || until || exclude_author)) {
         // A bounded/filtered read that finds nothing is NOT a bad query —
@@ -576,13 +843,72 @@ server.registerTool("memory_read", {
     };
 });
 // --- Tool: memory_list_recent ---
+/**
+ * How big ONE feed page may get, and how the handler stays under it (#104).
+ *
+ * THE INCIDENT. `memory_list_recent(domain: "xroom:…", limit: 40, cursor: …)`
+ * over a shared room of long archival entries produced a single tool result of
+ * 72,648 characters. Claude Code refused to inline it and spilled it to a file;
+ * a client without that fallback loses the page. MAX_RESULT_CHARS did not fire,
+ * and could not have: 72,648 is comfortably under 96,000. That number is
+ * `24,000 tokens × 4 chars/token`, and the 4 is an average over ordinary prose —
+ * archival room entries carry ids, code, punctuation and non-ASCII, which
+ * tokenize far worse. A cap derived from an optimistic ratio is not a promise
+ * about a client's real limit.
+ *
+ * WHY `limit` COULD NOT SOLVE IT. `limit` bounds the COUNT. Whether a count is
+ * safe depends entirely on how long the entries happen to be — 1,500–4,000+
+ * chars each in coordination rooms, against a 10,000-char write cap — and the
+ * caller cannot know that before asking. Too high explodes; too low costs
+ * dozens of round trips for the same catch-up.
+ *
+ * WHAT THIS IS. A page is assembled from small sub-requests and stops BEFORE
+ * the budget is exceeded, returning the server cursor of the last FULLY
+ * accepted sub-batch. The cursor is per-batch, which is why the batch is small:
+ * it is the granularity at which the page can end without losing or repeating
+ * an entry. Nothing is dropped silently — an entry that exceeds the budget on
+ * its own is returned whole, as a page of one, because per-entry truncation
+ * needs a fetch-one-by-id verb this server does not have (#104, suggestion 2).
+ *
+ * THE NUMBER IS DELIBERATELY CONSERVATIVE AND DELIBERATELY LOCAL. 40,000 is
+ * roughly half of what already failed in production; the true boundary of any
+ * given client is unmeasured, and calibrating it is follow-up work. It does NOT
+ * touch MAX_RESULT_CHARS, which is shared with memory_read and every other
+ * surface and remains the final backstop after this budget has done its work.
+ */
+const LIST_PAGE_CHAR_BUDGET = 40_000;
+/**
+ * Entries per sub-request. Small enough that the budget can end a page at a
+ * useful granularity, large enough that an ordinary short-entry feed still
+ * costs one or two round trips (the default `limit` of 20 costs two).
+ */
+const LIST_PAGE_CHUNK = 10;
+/**
+ * A ceiling on sub-requests per call — the loop's own stop condition is the
+ * budget, the caller's `limit`, or the end of the feed, and this fires only if
+ * a server answers in a way none of those three catch. `limit: 100` needs ten,
+ * plus a few for narrowing an over-budget batch.
+ */
+const LIST_PAGE_MAX_REQUESTS = 16;
+/**
+ * Appended when the page stopped because a LATER sub-request failed. Chunking
+ * multiplies the requests per call and therefore the chance one of them fails
+ * mid-page; discarding the entries already in hand would make this change a
+ * regression for exactly the long-entry rooms it exists for. Saying nothing
+ * would be worse — a short page with a valid cursor is indistinguishable from
+ * a page the budget ended, which is the could-not-fetch/does-not-exist
+ * collision this codebase keeps closing.
+ */
+const LIST_PAGE_EARLY_STOP_NOTE = "\n\n(This page stopped early — the request for the next batch of older " +
+    "entries did not come back usable, so this page holds fewer entries than " +
+    "asked for. The cursor above is unaffected: continue from it.)";
 server.registerTool("memory_list_recent", {
-    description: "List the NEWEST memories first — no search query needed. Semantic search answers 'what do I know about X'; this answers 'what happened lately': resuming work after a break, catching up on a shared room ('any new messages?'), or reviewing what was saved recently. Pass `since` (your last-seen time) to get only what's new, and page through older entries with the returned cursor. Complete by construction WITHIN ONE SCOPE — nothing is skipped there, unlike a semantic search. To catch up on a shared room you MUST pass its address as `domain`: rooms are separate stores and an unscoped call never covers them.",
+    description: "List the NEWEST memories first — no search query needed. Semantic search answers 'what do I know about X'; this answers 'what happened lately': resuming work after a break, catching up on a shared room ('any new messages?'), or reviewing what was saved recently. Pass `since` (your last-seen time) to get only what's new, and page through older entries with the returned cursor. Complete by construction WITHIN ONE SCOPE — nothing is skipped there, unlike a semantic search. A page is also bounded by SIZE, so a page of long entries comes back shorter than `limit` and hands you a cursor for the rest — nothing is dropped, and following the cursor is how you get it. To catch up on a shared room you MUST pass its address as `domain`: rooms are separate stores and an unscoped call never covers them.",
     inputSchema: {
         domain: z
             .string()
             .optional()
-            .describe("Restrict to one domain. REQUIRED to read a shared room — pass its address ('xroom:room_01ABC'), because rooms are separate stores that an unscoped feed does NOT cover. Omit only when you mean your own domains. Room addresses come from memory_list_rooms."),
+            .describe("Restrict to one domain. REQUIRED to read a shared room — pass its address ('xroom:room_01ABC'), because rooms are separate stores that an unscoped feed does NOT cover. Omit only when you mean your own domains. Room addresses come from memory_list_rooms. Room entries are often long — a room feed usually reaches its size budget after a handful of them, so expect to page (see `limit`)."),
         since: z
             .string()
             .optional()
@@ -602,7 +928,7 @@ server.registerTool("memory_list_recent", {
             .min(1)
             .max(100)
             .optional()
-            .describe("Page size (default: 20). Newest first."),
+            .describe("Most entries per page (default: 20). Newest first. ⚠️ A CEILING, not a promise: the page is ALSO bounded by size, so a page of long entries stops early and returns a cursor for the rest. In rooms whose entries run long, ask for 5–10 — a large `limit` there buys nothing the size budget will not take back, and costs round trips."),
         cursor: z
             .string()
             .max(512)
@@ -620,50 +946,151 @@ server.registerTool("memory_list_recent", {
     // ONE value for the request and for every decision about it — see the note
     // at the top of memory_read.
     const searched = searchedScope(domain);
-    let r;
-    try {
-        r = await apiFetch("/memory/recent", {
-            method: "POST",
-            body: JSON.stringify(recentRequestBody({ domain, since, until, exclude_author, limit, cursor })),
-        });
-    }
-    catch (e) {
-        // Graceful degradation while the server side rolls out: a 404 with no
-        // error `code` in the body is what an undeployed /memory/recent looks
-        // like, so degrade to a usable alternative instead of surfacing a raw
-        // HTTP error.
+    // The caller's `limit` is a CEILING on the item count. The page also has a
+    // character budget (LIST_PAGE_CHAR_BUDGET), and whichever binds first ends
+    // the page — which is why this is a loop over small sub-requests rather
+    // than one request for `limit` entries followed by a cap that arrives too
+    // late to do anything but truncate.
+    const ceiling = limit || 20;
+    const accepted = [];
+    // The server cursor of the last FULLY accepted sub-batch: the only value
+    // that can be handed back without losing or repeating an entry, since a
+    // cursor names a batch boundary and nothing finer.
+    let acceptedCursor;
+    // Where the next sub-request continues from — the caller's cursor first,
+    // the server's thereafter. Resending the caller's would replay page one.
+    let position = cursor || undefined;
+    let ask = Math.min(LIST_PAGE_CHUNK, ceiling);
+    let stoppedEarly = false;
+    for (let attempt = 0; attempt < LIST_PAGE_MAX_REQUESTS; attempt++) {
+        let r;
+        try {
+            r = await apiFetch("/memory/recent", {
+                method: "POST",
+                body: JSON.stringify(recentRequestBody({
+                    domain,
+                    since,
+                    until,
+                    exclude_author,
+                    limit: ask,
+                    cursor: position,
+                })),
+            });
+        }
+        catch (e) {
+            // A failure with entries already in hand ends the page instead of the
+            // call: the caller keeps what was fetched plus a cursor that still
+            // continues correctly, and the appended note says the page was cut
+            // short by a failed request rather than by the budget. With nothing
+            // accepted there is no page to return, so the error surfaces exactly
+            // as it did before chunking.
+            if (accepted.length > 0) {
+                stoppedEarly = true;
+                break;
+            }
+            // Graceful degradation while the server side rolls out: a 404 with no
+            // error `code` in the body is what an undeployed /memory/recent looks
+            // like, so degrade to a usable alternative instead of surfacing a raw
+            // HTTP error.
+            //
+            // NAMED FOR WHAT IT TESTS. This was `endpointAbsent`, which asserted a
+            // deployment fact the check cannot establish: every engine 404 carries a
+            // `code`, so a real room-404 is excluded, but a gateway, a proxy or a
+            // wrong MNEMOVERSE_API_URL produces the same bare 404 and is
+            // indistinguishable from here. The MESSAGE below still states the
+            // deployment cause outright, which is more than this boolean knows —
+            // listed in CHANGELOG's "Known and NOT fixed here" rather than papered
+            // over with a hedge.
+            //
+            // NOW READ FROM STRUCTURED FIELDS. It used to be
+            // `e.message.startsWith("Mnemoverse API error 404:")` plus a substring
+            // hunt for `"code"` in the same string — a behavioural branch keyed to the
+            // exact prefix of a user-facing sentence. Rewording that sentence, which
+            // is precisely what src/errors.ts does, would have flipped this branch
+            // silently: every per-request 404 would have degraded into "the service
+            // does not support the feed yet". `ApiError.isBare404` asks the parsed
+            // envelope instead, so the prose and the branch can no longer collide.
+            const bare404 = e instanceof ApiError && e.isBare404;
+            if (bare404) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "The memory service does not support the recent-entries feed yet. " +
+                                "Use memory_read with order_by: 'recency' as an approximation.",
+                        },
+                    ],
+                };
+            }
+            throw e;
+        }
+        // Same guard as memory_read: a 200 without an items array is UNREADABLE,
+        // not empty — and the feed's empty heads below are precisely the absence
+        // claims that must not be derived from it (truth F13, 2026-08-08). Mid
+        // page it is treated like a failed sub-request, for the same reason.
+        const batch = r?.items;
+        if (!Array.isArray(batch)) {
+            if (accepted.length > 0) {
+                stoppedEarly = true;
+                break;
+            }
+            return unreadableAnswerReply("The recent-entries feed", "an empty feed", "there is nothing to list");
+        }
+        const next = r?.next_cursor;
+        // Measured on the TEXT THAT WOULD SHIP, rendered by the same function
+        // that renders the answer — an estimate from item lengths would drift
+        // from the renderer the first time a line gained a field. The early-stop
+        // note's length is reserved up front: it is appended only when a LATER
+        // sub-request fails, which cannot be known while this batch is being
+        // sized, so every page keeps room for it (CodeRabbit, PR #108).
+        const fits = formatRecentPage(accepted.concat(batch), next).length <=
+            LIST_PAGE_CHAR_BUDGET - LIST_PAGE_EARLY_STOP_NOTE.length;
+        if (fits) {
+            accepted.push(...batch);
+            acceptedCursor = next;
+            position = typeof next === "string" && next ? next : undefined;
+            // No cursor: the feed ended, and the page says so. No entries: the
+            // server is not advancing, so continuing would spend requests on the
+            // same nothing. Ceiling reached: the caller's count is spent.
+            if (!position || batch.length === 0 || accepted.length >= ceiling)
+                break;
+            ask = Math.min(LIST_PAGE_CHUNK, ceiling - accepted.length);
+            continue;
+        }
+        // Over budget. With entries already accepted, THIS is the ordinary stop:
+        // keep the batches that fit and hand back the cursor of the last one.
+        if (accepted.length > 0)
+            break;
+        // Nothing accepted yet, so this one batch is over budget by itself and
+        // the page cannot be empty — something must be returned.
         //
-        // NAMED FOR WHAT IT TESTS. This was `endpointAbsent`, which asserted a
-        // deployment fact the check cannot establish: every engine 404 carries a
-        // `code`, so a real room-404 is excluded, but a gateway, a proxy or a
-        // wrong MNEMOVERSE_API_URL produces the same bare 404 and is
-        // indistinguishable from here. The MESSAGE below still states the
-        // deployment cause outright, which is more than this boolean knows —
-        // listed in CHANGELOG's "Known and NOT fixed here" rather than papered
-        // over with a hedge.
-        const bare404 = e instanceof Error &&
-            e.message.startsWith("Mnemoverse API error 404:") &&
-            !e.message.includes('"code"');
-        if (bare404) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "The memory service does not support the recent-entries feed yet. " +
-                            "Use memory_read with order_by: 'recency' as an approximation.",
-                    },
-                ],
-            };
+        // `batch.length > ask` means the server ignored `limit`; asking again,
+        // smaller, would be a wasted round trip against a deployment that is not
+        // listening, and MAX_RESULT_CHARS is the backstop for it. A batch of one
+        // is the entry that exceeds the budget alone: it ships whole, because
+        // dropping it is silent loss and truncating it needs a fetch-by-id verb
+        // that does not exist yet (#104).
+        //
+        // KNOWN EDGE, inherited rather than introduced (CodeRabbit, PR #108):
+        // when a limit-ignoring server's batch ships whole and capResult then
+        // truncates the tail, the printed cursor points past entries the reader
+        // never saw. 0.9.1 had the identical hazard (one request, the server's
+        // cursor, the same cap). The alternatives are worse lies: slicing to
+        // `ask` keeps the server's cursor and SKIPS the sliced entries silently;
+        // rejecting the batch outright answers a working feed with "unreadable".
+        // A contract-violating server is the precondition; the real fix is
+        // fetch-by-id (#104 follow-up), not a guess here.
+        const narrower = Math.max(1, Math.min(Math.floor(ask / 2), batch.length - 1));
+        if (batch.length <= 1 || batch.length > ask || narrower >= ask) {
+            accepted.push(...batch);
+            acceptedCursor = next;
+            break;
         }
-        throw e;
-    }
-    // Same guard as memory_read: a 200 without an items array is UNREADABLE,
-    // not empty — and the feed's empty heads below are precisely the absence
-    // claims that must not be derived from it (truth F13, 2026-08-08).
-    const items = r?.items;
-    if (!Array.isArray(items)) {
-        return unreadableListReply("The recent-entries feed", "an empty feed", "there is nothing to list");
+        // Re-ask the SAME position for fewer entries. `narrower < batch.length`
+        // by construction, so the ask strictly shrinks and the loop converges.
+        ask = narrower;
     }
+    const items = accepted;
     if (items.length === 0) {
         // THE SENTENCE ITSELF carries the scope — and it is selected by EVERY
         // filter that narrowed the window, not by `since` alone.
@@ -731,14 +1158,45 @@ server.registerTool("memory_list_recent", {
                 // 2026-08-08). Same order as memory_read's result page, same
                 // automatic drop: a cap that removed every escaped name removes the
                 // reason for the legend too.
-                text: withDomainEscapeLegend(capResult(formatRecentPage(items, r?.next_cursor), "Lower `limit` or add a `domain` for smaller pages."), ...items.map((it) => it?.domain)),
+                //
+                // The cursor is the last ACCEPTED batch's, never the newest one
+                // seen: a batch that did not fit the budget was not returned, so
+                // pointing past it would skip every entry in it.
+                text: withDomainEscapeLegend(capResult(formatRecentPage(items, acceptedCursor) +
+                    (stoppedEarly ? LIST_PAGE_EARLY_STOP_NOTE : ""), 
+                // Still true, and now only reachable when ONE entry is larger
+                // than the whole budget — the case `limit` cannot fix and the
+                // global cap has to.
+                "Lower `limit` or add a `domain` for smaller pages."), ...items.map((it) => it?.domain)),
             },
         ],
     };
 });
 // --- Tool: memory_feedback ---
+/**
+ * Why ids can miss, listed once and used by both branches that need it — the
+ * total miss (`updated_count: 0`) and the partial one (a count short of the
+ * ids sent). They are the same event at two scales, and when the sentence
+ * lived inline in the zero branch only, the partial case got no explanation at
+ * all.
+ *
+ * No frequency claim. "Most often that means…" was a statistic we do not have
+ * (review, 2026-08-08); the causes are listed as possibilities, with the one
+ * the caller cannot otherwise guess first because it is invisible from the
+ * tool surface — this tool takes no `domain`, so a room atom is unreachable
+ * from it by construction.
+ */
+const FEEDBACK_MISS_CAUSES = "Possible causes: the ids came from a shared room (this tool takes no domain " +
+    "argument and cannot reach room atoms, so rating them is a no-op); the memory " +
+    "was deleted; or the id came from somewhere other than a memory_read result.";
 server.registerTool("memory_feedback", {
-    description: "Report whether memories returned by memory_read were actually helpful. This is a learning signal, not a log: positive feedback raises a memory's ranking so it surfaces faster next time (across all of the user's tools), negative feedback lets it fade. Call it right after you act on (or reject) recalled memories, passing the ids from the memory_read results. NOTE: this reaches your own domains only — it takes no domain argument, so rating a memory that lives in a shared room silently does nothing.",
+    description: 
+    // "negative feedback lets it fade" was withdrawn as false by 0.9.1
+    // (#95) — and survived here, in the sentence every connected model
+    // reads. Nothing time-decays and nothing is auto-deleted: a downvoted
+    // memory is OUT-RANKED, and deletion has been administrative-only since
+    // 0.9.0. The replacement is the wording that release put on the README.
+    "Report whether memories returned by memory_read were actually helpful. This is a learning signal, not a log: positive feedback raises a memory's ranking so it surfaces faster next time (across all of the user's tools), negative feedback lowers it so other memories out-rank it — nothing is erased and nothing decays with time. Call it right after you act on (or reject) recalled memories, passing the ids from the memory_read results. NOTE: this reaches your own domains only — it takes no domain argument, so rating a memory that lives in a shared room silently does nothing.",
     inputSchema: {
         atom_ids: z
             .array(z.string())
@@ -766,7 +1224,67 @@ server.registerTool("memory_feedback", {
         method: "POST",
         body: JSON.stringify({ atom_ids, outcome }),
     });
-    const count = r?.updated_count ?? 0;
+    // A FIELD THE SERVER DID NOT SEND IS UNKNOWN, NOT ZERO — the rule
+    // memory_stats already applies with `num()`, broken here by
+    // `r?.updated_count ?? 0` in three directions at once:
+    //
+    //   1. A 200 with the field absent, an explicit null, and a 204 (which
+    //      apiFetch turns into `{}`) all became 0, and 0 prints "No feedback
+    //      was recorded" plus three causes for it — an absence claim read out
+    //      of a body that carried no claim. Under core's async path the
+    //      rating may well have been applied while the ack said nothing.
+    //   2. A string "0" is not 0, so `??` passed it straight through and the
+    //      ±1 branches printed "The service reports 0 memories updated — they
+    //      should surface sooner next time": two clauses contradicting each
+    //      other in one sentence.
+    //   3. Nothing rejected a negative: "reports -2 memories updated".
+    //
+    // So: usable means a non-negative integer. Anything else is UNKNOWN and
+    // gets its own sentence, which diagnoses nothing — the causes of a miss
+    // belong to a reported zero, not to a number we never received.
+    const reported = r?.updated_count;
+    const count = typeof reported === "number" && Number.isInteger(reported) && reported >= 0
+        ? reported
+        : undefined;
+    // Direction is echoed for every outcome, including the ones with no count
+    // to report: the same four words for +1 and -1 gave a caller no evidence
+    // the loop did anything, which is why nobody calls it twice.
+    const sent = outcome > 0
+        ? `Rating sent: +${outcome} (helpful).`
+        : outcome < 0
+            ? `Rating sent: ${outcome} (unhelpful).`
+            : "Rating sent: 0.";
+    // Zero has no effect clause to offer — promising "this shifts how they
+    // rank" for outcome 0 would be a claim we cannot make (dogfooding saw a
+    // neutral rating move a score UP by about five points, CodeRabbit #65) —
+    // so it offers the one thing that is actionable instead.
+    //
+    // WHAT 0 ACTUALLY DOES, restated against core#493 (merged 2026-08-13). The
+    // valence step used to be `sign(outcome) * |prediction error|`, so outcome
+    // 0 took the POSITIVE branch and pushed valence UP — which is what
+    // dogfooding saw, and what the previous version of this comment recorded.
+    // That is no longer true: core now uses the SIGNED error,
+    // `pe = outcome - valence` (memory_engine.py:5167-5169), so a 0 against a
+    // positive valence moves it DOWN, toward neutral. Either way 0 is not a
+    // no-op and the line must not imply one — but the old explanation is now
+    // backwards, and it ships verbatim inside dist/index.js, so it cannot be
+    // left to rot in a comment.
+    const pickADirection = outcome === 0
+        ? " Use +1 (helpful) or -1 (harmful/wrong) to express a clear direction."
+        : "";
+    if (count === undefined) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${sent} The service accepted the call but did not report how many ` +
+                        `memories it updated, so whether any changed is unknown from here. ` +
+                        `That is not evidence of a failure — do not re-send the same rating ` +
+                        `on the strength of it.` + pickADirection,
+                },
+            ],
+        };
+    }
     // "Feedback recorded for 0 memories." is one character away from the
     // success line and reads like one. But the DIAGNOSIS matters as much as
     // the fact: an earlier version of this branch blamed deletion, which is
@@ -783,32 +1301,16 @@ server.registerTool("memory_feedback", {
             content: [
                 {
                     type: "text",
-                    text: 
-                    // No frequency claim. "Most often that means…" was a statistic
-                    // we do not have (review, 2026-08-08); the causes are listed as
-                    // possibilities, with the one the caller cannot otherwise guess
-                    // first because it is invisible from the tool surface.
-                    "No feedback was recorded — none of those ids matched a memory in your own " +
-                        "domains. Possible causes: the ids came from a shared room (this tool takes " +
-                        "no domain argument and cannot reach room atoms, so rating them is a no-op); " +
-                        "the memory was deleted; or the id came from somewhere other than a " +
-                        "memory_read result.",
+                    text: "No feedback was recorded — none of those ids matched a memory in your own " +
+                        `domains. ${FEEDBACK_MISS_CAUSES}`,
                 },
             ],
         };
     }
-    // Echo the DIRECTION, not just the count: the same four words for +1 and
-    // -1 gave a caller no evidence the loop did anything, which is why nobody
-    // calls it twice.
-    //
-    // The effect clause is per-direction. Promising "this shifts how they
-    // rank" for outcome 0 would be a claim we cannot make — dogfooding saw a
-    // neutral rating move a score UP by about five points, so neither "no
-    // change" nor "ranks higher" is safe to assert (CodeRabbit, #65).
     // WHOSE NUMBER THIS IS (#68). `updated_count` is the count of memories the
     // service says it touched — and that is true only while core runs
     // `feedback_async = False`. Under async it returns the number of ids
-    // SUBMITTED, not applied (core schemas.py:689-695, memory_engine.py:4490),
+    // SUBMITTED, not applied (core schemas.py:826-838, memory_engine.py:4898-4902),
     // and nothing in the response says which mode ran. A server-side config
     // flip would therefore turn a confident sentence here false on every
     // installed client, silently. So the number is reported as the SERVICE'S
@@ -817,27 +1319,50 @@ server.registerTool("memory_feedback", {
     // (mnemoverse-mcp-remote#38); one number, one degree of confidence,
     // whichever surface a model reaches it through.
     const noun = `${count} memor${count === 1 ? "y" : "ies"}`;
-    const text = outcome > 0
-        ? `Rating sent: +${outcome} (helpful). The service reports ${noun} updated — they should surface sooner next time.`
+    const effect = outcome > 0
+        ? " — they should surface sooner next time."
         : outcome < 0
-            ? `Rating sent: ${outcome} (unhelpful). The service reports ${noun} updated — they should fade.`
-            // Zero claims only what is knowable from here: the rating was sent,
-            // the service reported a count, and ±1 send a clear signal.
-            //
-            // WHAT 0 ACTUALLY DOES, restated against core#493 (merged
-            // 2026-08-13). The valence step used to be
-            // `sign(outcome) * |prediction error|`, so outcome 0 took the
-            // POSITIVE branch and pushed valence UP — which is what dogfooding
-            // saw, and what the previous version of this comment recorded. That
-            // is no longer true: core now uses the SIGNED error,
-            // `pe = outcome - valence` (memory_engine.py:4986-4988), so a 0
-            // against a positive valence moves it DOWN, toward neutral. Either
-            // way 0 is not a no-op and the line must not imply one — but the old
-            // explanation is now backwards, and it ships verbatim inside
-            // dist/index.js, so it cannot be left to rot in a comment.
-            : `Rating sent: 0. The service reports ${noun} updated. Use +1 (helpful) or -1 (harmful/wrong) to express a clear direction.`;
+            // No fade. 0.9.1 (#95) withdrew "lets it fade" as false — nothing
+            // time-decays, nothing is auto-deleted, and deletion has been
+            // administrative-only since 0.9.0 — and this line kept promising it
+            // after the release that deleted the claim from the README.
+            ? " — they should rank lower next time. Out-ranked, not erased: nothing is deleted and nothing decays with time."
+            : ".";
+    // WHAT THE COUNT IS NOT: a guarantee that every id landed. `atom_ids.length`
+    // was never compared with it, so five ids and `updated_count: 2` printed
+    // the unqualified success line and three silent misses — the typical shape
+    // of the room case, where half the ids came off a room read this tool
+    // cannot reach. A SHORTFALL can only come from core's sync path (the async
+    // ack is exactly `len(atom_ids)`, memory_engine.py:4898-4902), where the
+    // number is the authoritative count of atoms that existed — so the same
+    // causes as the zero branch apply, at a smaller scale, and the string is
+    // shared so the two cannot drift apart.
+    //
+    // An EXCESS is not a shape core produces at all (sync counts one per id
+    // that resolved, async counts the ids). But MNEMOVERSE_API_URL points
+    // wherever it is pointed, and "reports 9 memories updated" for one id
+    // would otherwise read as nine of the caller's memories rated. Say what it
+    // cannot be rather than pass it off as a per-id result.
+    const idsSent = `${atom_ids.length} id${atom_ids.length === 1 ? "" : "s"} you sent`;
+    const mismatch = count < atom_ids.length
+        ? ` That is fewer than the ${idsSent}: ${atom_ids.length - count} of them ` +
+            `matched nothing in your own domains. ${FEEDBACK_MISS_CAUSES}`
+        : count > atom_ids.length
+            ? ` That is more than the ${idsSent}, so it cannot be a per-id result — ` +
+                `read it as the service's own tally, not as how many of your memories ` +
+                `were rated.`
+            : "";
     return {
-        content: [{ type: "text", text }],
+        content: [
+            {
+                type: "text",
+                // Order: what was sent, what the service reported, what that means
+                // for the ids — then the advice. Putting `pickADirection` before the
+                // mismatch clause interrupted the report with a suggestion and
+                // resumed it afterwards.
+                text: `${sent} The service reports ${noun} updated${effect}${mismatch}${pickADirection}`,
+            },
+        ],
     };
 });
 // --- Tool: memory_stats ---
@@ -874,6 +1399,15 @@ server.registerTool("memory_stats", {
     // zero-width character are all visible, Cyrillic stays Cyrillic, and two
     // different names can no longer print as one. Assembly lives in
     // src/names.ts, where it is unit-tested against those exact inputs.
+    //
+    // The assembly also BOUNDS the list (MAX_DOMAIN_LIST_CHARS), which is what
+    // makes this handler respect the 25K-token cap every other surface already
+    // respected. The line is linear in the number of stores and nothing bounded
+    // it: 4,000 domains rendered past 100,000 characters — deterministically,
+    // with no hostile input involved. Bounding the LIST rather than leaning on
+    // capResult alone is the point: capResult truncates from the END, so the
+    // wall of names would have taken the average-quality line and the rooms
+    // reminder down with it, leaving the answer nothing but names.
     const domains = formatDomainList(r?.domains);
     const text = [
         `Memories: ${num(r?.total_atoms)} (${num(r?.episodes)} episodes, ${num(r?.prototypes)} prototypes)`,
@@ -900,7 +1434,18 @@ server.registerTool("memory_stats", {
                 // arrives over the wire, and spreading a non-iterable object would
                 // throw here — turning a malformed payload into a dead tool instead
                 // of the "none reported" it degrades to two lines up.
-                text: withDomainEscapeLegend(text, ...(Array.isArray(r?.domains) ? r.domains : [])),
+                //
+                // capResult is the second belt, not the mechanism: the domain list is
+                // already bounded above, so this only fires if some future line grows
+                // unboundedly. It stays because this was the ONE tool result with no
+                // cap at all, and "every surface is capped" is worth being an
+                // invariant rather than an argument about which surfaces can grow.
+                // Its hint names a control this no-input tool actually has — none —
+                // rather than the read tool's "use a more specific query".
+                //
+                // Legend AFTER the cap, as everywhere else: it must describe the names
+                // that SURVIVED, and it is appended at the end, where the cap cuts.
+                text: withDomainEscapeLegend(capResult(text, "The domain list was truncated — some domain names are not shown."), ...(Array.isArray(r?.domains) ? r.domains : [])),
             },
         ],
     };
@@ -1011,7 +1556,7 @@ server.registerTool("memory_invite_to_room", {
 });
 // --- Tool: memory_join_room ---
 server.registerTool("memory_join_room", {
-    description: "Join a shared memory room using an invite code (starts with 'mnvr_'). Use when the user pastes an invite code or says something like 'join room with code ...'. After joining, use the returned address as the `domain` on memory_write/memory_read to read and write the shared room.",
+    description: "Join a shared memory room using an invite code (starts with 'mnvr_'). Use when the user pastes an invite code or says something like 'join room with code ...'. After joining, use the returned address as the `domain` on memory_read to read the shared room — the result tells you what you may do with it: memory_write to that address is only allowed when your membership scope is read_write; a read-only membership has that write refused; and when the server does not report a scope, whether memory_write would succeed is stated as unknown rather than promised either way.",
     inputSchema: {
         code: z.string().min(1).max(200).describe("The invite code (mnvr_...)."),
     },
@@ -1040,9 +1585,18 @@ server.registerTool("memory_join_room", {
         ? `You're already a member of ${roomName}.`
         : `Joined ${roomName} (${scope}).`;
     // Don't print broken `domain=""` guidance if no address came back (Copilot).
-    const usage = address
-        ? `Use it: pass domain="${address}" on memory_write / memory_read to read and write the shared room.`
-        : `The server did not return a room address — retry, or check that your API key is set.`;
+    // The write half of this sentence is scope-gated (roomScopeVerdict, above
+    // isRoomDomain): a "read" invite gets told memory_write will be refused
+    // rather than offered it, and a scope the response did not report at all
+    // gets no promise about write either way.
+    const verdict = roomScopeVerdict(r?.scope);
+    const usage = !address
+        ? `The server did not return a room address — retry, or check that your API key is set.`
+        : verdict === "read_write"
+            ? `Use it: pass domain="${address}" on memory_write / memory_read to read and write the shared room.`
+            : verdict === "read"
+                ? `Use it: pass domain="${address}" on memory_read to read it; this membership is read-only, so memory_write to that address will be refused.`
+                : `Use it: pass domain="${address}" on memory_read to read it — the server did not report this membership's write access, so whether memory_write to that address would succeed is unknown.`;
     return {
         content: [
             {
@@ -1055,7 +1609,7 @@ server.registerTool("memory_join_room", {
 });
 // --- Tool: memory_list_rooms ---
 server.registerTool("memory_list_rooms", {
-    description: "List the shared memory rooms you can use — the ones you OWN plus the ones you've JOINED — each with the address to pass as `domain` on memory_write / memory_read. Use this to RE-FIND a room in a new session (e.g. 'what rooms do I have?', 'resume the room with Olya') instead of having to create or re-join it.",
+    description: "List the shared memory rooms you can use — the ones you OWN plus the ones you've JOINED — each with the address to pass as `domain` on memory_read, and on memory_write too where your membership scope is read_write; a read-only membership has that write refused. Use this to RE-FIND a room in a new session (e.g. 'what rooms do I have?', 'resume the room with Olya') instead of having to create or re-join it.",
     inputSchema: {},
     annotations: {
         title: "List rooms",
@@ -1076,7 +1630,7 @@ server.registerTool("memory_list_rooms", {
         // Byte-identical to the inline wording this replaces — the builder is
         // shared so the four list surfaces answer the unreadable case with one
         // sentence, not four drifting ones.
-        return unreadableListReply("The room list", "a list of your rooms", "you have none");
+        return unreadableAnswerReply("The room list", "a list of your rooms", "you have none");
     }
     if (rooms.state === "none") {
         return {
@@ -1109,13 +1663,24 @@ server.registerTool("memory_list_rooms", {
         // src/scope.ts), so that clause was an instruction to make a call that
         // cannot succeed. The address stays visible — it is the room's identity —
         // but the line says what a read against it will do.
+        //
+        // For a live room, the write half is scope-gated the same way
+        // memory_join_room's usage sentence is (roomScopeVerdict, near
+        // isRoomDomain): this used to say "use domain=..." with no operation
+        // named, which read as an unqualified read+write invitation even for a
+        // "read" member — false, since core refuses that member's memory_write.
+        const verdict = roomScopeVerdict(scope);
         const tail = r?.archived
             ? address
                 ? ` [archived] — address ${address}, but every read is refused while it is archived`
                 : ` [archived] — every read is refused while it is archived`
-            : address
-                ? ` — use domain="${address}"`
-                : "";
+            : !address
+                ? ""
+                : verdict === "read_write"
+                    ? ` — use domain="${address}" to read and write it`
+                    : verdict === "read"
+                        ? ` — use domain="${address}" on memory_read only; this membership is read-only, so memory_write to it will be refused`
+                        : ` — use domain="${address}" on memory_read; this membership's write access was not reported`;
         return `- ${name} (${role}${scope ? `, ${scope}` : ""})${tail}`;
     });
     const text = `Your shared rooms (${list.length}):\n${lines.join("\n")}`;
@@ -1151,7 +1716,7 @@ server.registerTool("vault_list", {
     // 2026-08-08). A genuinely empty array keeps the absence claim below.
     const list = r?.secrets;
     if (!Array.isArray(list)) {
-        return unreadableListReply("The secret list", "a list of your Vault secrets", "none are stored");
+        return unreadableAnswerReply("The secret list", "a list of your Vault secrets", "none are stored");
     }
     if (list.length === 0) {
         return {
@@ -1237,10 +1802,33 @@ server.registerTool("vault_list", {
 function probeApiKeyInBackground() {
     if (!API_KEY)
         return;
+    if (BASE_URL_REFUSAL !== undefined) {
+        // THE SECOND CREDENTIAL-BEARING CALL SITE (#99). This probe predates
+        // apiFetch's base-URL guard and calls `fetch` directly, so the guard does
+        // not reach it — and this one fires on every server START, before any tool
+        // is called. Left alone, a user whose MNEMOVERSE_API_URL is spelled
+        // `http://` would leak the key by launching their editor, and the tool-call
+        // guard would then dutifully refuse to leak the key it had already leaked.
+        //
+        // Saying nothing is not an option either: a silent server whose every tool
+        // then fails is the exact invisible failure mode this probe was added to
+        // end. So it reports the skip on stderr — where MCP clients surface
+        // connection logs — in the user's own register.
+        console.error(BASE_URL_REFUSAL.startupLog);
+        return;
+    }
     void (async () => {
         try {
             const res = await fetch(`${API_URL}/memory/stats`, {
                 headers: { "X-Api-Key": API_KEY },
+                // Same reason as apiFetch: following a redirect re-sends this header to
+                // the new host (#99, CWE-200), and this request carries the key just as
+                // a tool call does. The rejection lands in the catch below with every
+                // other probe failure — deliberately, since the probe is fire-and-forget
+                // and must never take the server down. Nothing is lost by the silence:
+                // the same redirect meets the first real tool call, where
+                // explainNetworkFailure names it in full.
+                redirect: "error",
                 signal: AbortSignal.timeout(10_000),
             });
             // Drain the body so the connection returns to the pool immediately —