@mnemoverse/mcp-memory-server 0.10.2 → 0.12.0

package/dist/tools.js

@@ -0,0 +1,2437 @@
+/**
+ * The ten memory tools, as one function any MCP server can register.
+ *
+ * ADR-025 (mnemoverse-core): this package defines the MCP surface, and every
+ * server that exposes Mnemoverse memory over MCP registers the SAME tools from
+ * here instead of keeping its own copy. The stdio server in src/index.ts is one
+ * such server; the hosted connector (mnemoverse-mcp-remote) is the other.
+ *
+ * What differs between servers is only how a request reaches the API: which
+ * credential it carries, where it goes, and how a transport failure is worded.
+ * That is `MemoryToolDeps.apiFetch`. Nothing in this file reads configuration
+ * or the environment.
+ */
+import { z } from "zod";
+import { CURSOR_RE, formatReadItem, formatRecentPage, rawAuthorName, safeInline, structuredItem, } from "./render.js";
+// `NO_MATCH_MESSAGE` is no longer imported here: this file used to pick between
+// it and buildReadEmptyResponse by testing a note string for truthiness, which
+// is how "we could not check" came to be spelled like "the store is there".
+// Assembling the whole answer belongs in one place — src/teaching.ts.
+import { buildReadEmptyResponse } from "./teaching.js";
+import { classifyRooms, futureSinceNote, probeReadScope, readScopeNote, scopeLabel, } from "./scope.js";
+import { readRequestBody, recentRequestBody, writeRequestBody, searchedScope, } from "./requests.js";
+import { exactLiteral, formatDomainList, MAX_DOMAIN_LITERAL, MAX_DOMAIN_TAG_LITERAL, roomNamePhrase, structuredText, withDomainEscapeLegend, withEscapeLegendAt, } from "./names.js";
+import { ApiError, rewordFailure } from "./errors.js";
+// Field limits, generated from core's contract (src/limits.ts, ADR-025).
+import { CORE_LIMITS } from "./limits.js";
+// For the invite's `expires_at` (S8, structured-output plan): the same
+// UTC-instant reader src/render.ts uses for a memory's `created_at`.
+import { utcInstant } from "./time.js";
+/**
+ * `deps.apiFetch` with `deps.wording` applied to what it throws (STEP4-2):
+ * every rejection passes through {@link rewordFailure}, so an `ApiError`,
+ * `NetworkError` or `UnreadableBodyError` the consumer built with no
+ * `wording` (or with a different one) reaches the model explained under the
+ * wording this registration was given. Results and every other rejection
+ * pass through untouched. Installed only when `wording` is supplied at all:
+ * the stdio server supplies none, and its `apiFetch` is used exactly as
+ * before.
+ */
+export function wordedApiFetch(inner, wording) {
+    return async (path, options) => {
+        try {
+            return await inner(path, options);
+        }
+        catch (e) {
+            throw rewordFailure(e, wording);
+        }
+    };
+}
+// 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.
+//
+// Exported (re-exported from ./shared, ADR-025) so a future editor does not
+// move or rename it without checking there: it is now the one cap both this
+// server and, from step 4 of the structured-output plan, the hosted connector
+// apply to a tool result's text. `structuredContent` is NOT capped (OD-11,
+// 2026-09-23); this bound is text-only.
+export const MAX_RESULT_CHARS = 24_000 * 4;
+/**
+ * Truncate a result string to MAX_RESULT_CHARS, appending a notice if truncated.
+ * Required by Claude Connectors Directory submission policy.
+ *
+ * Defensive against splitting UTF-16 surrogate pairs: if the character right
+ * before the cut point is a high surrogate (U+D800–U+DBFF), drop it so the
+ * result stays well-formed. Otherwise an emoji or non-BMP character at the
+ * boundary can produce a lone surrogate and corrupt downstream JSON encoding.
+ *
+ * Exported (re-exported from ./shared) so a consumer applying MAX_RESULT_CHARS
+ * to its own tool results does not have to re-implement this code-point-safe
+ * truncation as a plain `slice`, which can cut a surrogate pair.
+ */
+export function capResult(text, 
+// The default recommends ONLY the control that works. A previous draft also
+// said "or smaller top_k" — but top_k is not a hard cap (association
+// expansion can return more, the relevance floor fewer; the same query at
+// 1/5/20 returned 6/7/4 items), which this release's own top_k description
+// already admits. One surface must not recommend the knob another refutes.
+moreHint = "Use a more specific query to see all results.") {
+    if (text.length <= MAX_RESULT_CHARS)
+        return text;
+    // `moreHint` lets no-input tools (the discovery lists) give accurate truncation
+    // guidance instead of the read-tool default (which points at a query control a
+    // repeated no-arg call cannot use). Existing callers keep the default message.
+    //
+    // The reserve for the notice is 200 characters, as it always was, so every
+    // existing truncated result keeps its exact cut; a hint longer than that
+    // reserve (a consumer of the /shared export may pass any sentence) widens
+    // the reserve to the suffix's own length instead of pushing the result over
+    // the cap, and a hint is bounded at MAX_HINT_CODE_POINTS so the suffix can
+    // never be the whole budget (review round 2 on the export, CodeRabbit).
+    const hint = [...moreHint].slice(0, MAX_HINT_CODE_POINTS).join("");
+    const suffix = `\n\n[…truncated to fit the 25K token limit. ${hint}]`;
+    const reserve = Math.max(200, suffix.length);
+    let truncated = text.slice(0, MAX_RESULT_CHARS - reserve);
+    const lastCode = truncated.charCodeAt(truncated.length - 1);
+    if (lastCode >= 0xd800 && lastCode <= 0xdbff) {
+        truncated = truncated.slice(0, -1);
+    }
+    return `${truncated}${suffix}`;
+}
+/** The longest `moreHint` capResult will print; the rest is cut, so the suffix
+ * cannot take the whole result budget. 1,000 code points is ten times the
+ * longest hint this package passes. */
+const MAX_HINT_CODE_POINTS = 1_000;
+/**
+ * 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
+ * the response" into "there is nothing there" — an absence claim on zero
+ * evidence. `classifyRooms` (src/scope.ts) and the stats domains guard closed
+ * it for rooms and domains; this builder is the same answer for the remaining
+ * list surfaces (search results, the feed, the vault), phrased the way the
+ * room list already phrases it. The three parts are the subject, what the body
+ * 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.
+ *
+ * Carries `isError: true`, not a text-only success. Once a tool declares an
+ * `outputSchema`, the SDK's `validateToolOutput` (see the comment on
+ * `structured()` below) rejects a non-error result that has no
+ * `structuredContent`, and there is no honest `structuredContent` for "this
+ * client could not read the body": an empty shape such as `{items: []}` would
+ * make exactly the absence claim this sentence exists to avoid. `isError` is
+ * the one shape the SDK exempts from that check, so it is the shape this
+ * reply must take (pinned against the installed SDK in
+ * test/structured-output.test.ts).
+ */
+function unreadableAnswerReply(subject, notA, absence, extra = "") {
+    return {
+        content: [
+            {
+                type: "text",
+                text: unreadableAnswerText(subject, notA, absence, extra),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * The sentence behind {@link unreadableAnswerReply}, exported so the memory
+ * resource (src/resources.ts) says the same thing about an unreadable answer
+ * rather than keeping its own copy.
+ *
+ * The tail attributes the unreadable 200 to "whatever answered this call", not
+ * to "the memory service" — this client cannot establish WHO answered: a
+ * gateway, a proxy, or the endpoint a mis-set MNEMOVERSE_API_URL points at
+ * produces the same 200 with an unrecognised body (truth re-verification,
+ * 2026-08-09). Pinned in test/handlers.test.ts.
+ */
+export function unreadableAnswerText(subject, notA, absence, extra = "") {
+    return (`${subject} came back in a shape this client does not recognise — so this ` +
+        `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 ` +
+        `cannot read.`);
+}
+/**
+ * A success result carrying both a text block and `structuredContent`, which
+ * is what a tool with a declared `outputSchema` must return, or the SDK
+ * itself rejects the call. `validateToolOutput` in the installed SDK
+ * (node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:185-207)
+ * turns a non-error, text-only result into an `isError` "Output validation
+ * error: … has an output schema but no structured content was provided", the
+ * moment a tool declares that schema, even though the same text alone was a
+ * fine answer the day before the schema was added. Pinned against that
+ * installed SDK in test/structured-output.test.ts.
+ *
+ * Deliberately dumb: it does not call `capResult` or `withDomainEscapeLegend`
+ * itself. Every tool already measures and caps its own text with a per-tool
+ * hint and applies the legend after the cap (see memory_read below), so a
+ * helper that capped again would double-truncate; callers pass `text`
+ * already finished.
+ */
+export function structured(text, data) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: data,
+    };
+}
+/**
+ * Two renderers, and which one a value gets is a decision, not a style choice.
+ *
+ * `safeInline` (src/render.ts) SANITISES an untrusted display string for inline
+ * rendering in tool output that a DIFFERENT principal's LLM will read (CN-032
+ * anti-injection): strip to a conservative charset, collapse whitespace, cap
+ * the length. The treatment `formatAuthorTag` applies to a server-stamped
+ * author, and the defensive second pass the machine-shaped room fields
+ * (address, room_id, role, scope — all charset-validated or enum-shaped in
+ * core) get here. It is lossy on purpose, and everything it still renders is a
+ * value the reader looks at and never has to retype or compare.
+ *
+ * `exactLiteral` / `domainPhrase` / `roomNamePhrase` (src/names.ts) print a
+ * value as a JSON string literal, or refuse to print it. Domain names because
+ * the engine matches them byte-for-byte, so the reader must be able to send
+ * the exact bytes back. Room NAMES (0.8.1) because the sanitiser did not make
+ * them harmless so much as it made them WRONG: "проект" echoed back as `""` on
+ * create, "Zoë" as "Zo" inside quotes that claim to be the name. The literal
+ * is one line with quotes, backslashes and invisibles escaped, so it is as
+ * injection-safe as the sanitised spelling was — without the renaming.
+ */
+/**
+ * True for a shared-room address (`xroom:<room_id>`).
+ *
+ * Mirrors core's own predicate (`memory_engine._is_room_domain`), which is a
+ * plain prefix test — deliberately, so a padded or otherwise non-canonical
+ * address does NOT normalise into a room. Byte-for-byte, no trimming: this
+ * file's write handler documents at length why trimming a domain here once
+ * nearly wrote into a room visible to other accounts.
+ *
+ * Used only to choose which TRUE sentence to print about a refusal. It never
+ * changes what is sent, so a wrong answer here misinforms and cannot misroute.
+ */
+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";
+}
+/**
+ * How long a HONESTY PROBE may take before the answer goes out without it (#73).
+ *
+ * The probes are a courtesy: they let a zero-result answer say what it did NOT
+ * cover. They are not the answer. Without a deadline they inherit undici's
+ * default (~300s), so one slow engine endpoint turns an empty read — which
+ * 0.8.0 answered instantly, having probed nothing — into a multi-minute stall.
+ * `probeReadScope` already treats a failed probe as "unknown" and says so, so
+ * an abort degrades into the honest fallback rather than an error.
+ *
+ * 4s is chosen against measured production latency: `/memory/read` averaged
+ * 1,330 ms with a 10.2 s maximum (core observability, 2026-08), and these two
+ * are cheaper GETs. Long enough not to fire on a normal slow day, short enough
+ * that a hung endpoint costs seconds instead of minutes.
+ */
+const PROBE_TIMEOUT_MS = 4000;
+/**
+ * The memory-item shape shared by memory_read's `outputSchema` and
+ * memory_list_recent's (S5, structured-output plan): copied from the
+ * connector's `memoryItemOutput` (mnemoverse-mcp-remote, src/tools/index.ts),
+ * field for field and description for description, with the SAME ONE
+ * deliberate difference memory_write's outputSchema already carries:
+ * `memory_id` here is `z.string()`, not `z.guid()` (decision OD-7, owner,
+ * 2026-09-22). This package's ids are opaque strings, and nothing in the
+ * contract promises they are UUIDs; a guid validator would turn any future
+ * id-format change into a whole-page "Output validation error" instead of a
+ * value this client simply could not shape-check further.
+ *
+ * A raw shape, not a `z.object(...)`, so both tools can build their own
+ * object around it (`z.object(MEMORY_ITEM_OUTPUT)`) without importing a
+ * schema instance neither owns, so memory_read's emitted JSON schema
+ * stays byte-identical to what it was before this constant existed
+ * (test/read-structured.test.ts pins it unchanged).
+ */
+const MEMORY_ITEM_OUTPUT = {
+    memory_id: z.string().describe("Identifier needed to rate or manage this saved memory."),
+    content: z.string().describe("Stored memory content."),
+    domain: z.string().describe("User-defined memory namespace or domain."),
+    created_at: z
+        .string()
+        .optional()
+        .describe("UTC creation instant, ISO-8601; absent on legacy memories without a timestamp."),
+    author: z
+        .string()
+        .optional()
+        .describe("Sanitized AGENT identity of the writer (never the human principal) — attribution in shared rooms."),
+};
+/**
+ * Register the ten memory tools on `server`. Call once per server instance.
+ * `deps.apiFetch` is the only way the tools reach the API.
+ */
+export function registerMemoryTools(server, deps) {
+    const { wording, writeAuthor } = deps;
+    // STEP4-2: `wording` reaches the error text here, on every rejection, not
+    // in the consumer's constructors. See wordedApiFetch.
+    const apiFetch = wording === undefined ? deps.apiFetch : wordedApiFetch(deps.apiFetch, wording);
+    // Read once, defensively: `wording` crosses a public package boundary a
+    // caller controls only at compile time (STEP4-2, owner 2026-09-24). A
+    // strict-equality check rather than a truthiness check, so any value other
+    // than the one literal "this connector" (including a typo, a boolean, or
+    // a stale value from a future third option) falls back to the default
+    // rather than being printed. Defaults to today's wording exactly, so a
+    // server that supplies no `wording` at all gets byte-identical descriptions.
+    const serverNoun = wording?.serverNoun === "this connector" ? "this connector" : "this server";
+    // Same value, sentence-initial capitalisation, for the one description that
+    // opens a second sentence with it rather than sitting mid-clause.
+    const serverNounCap = serverNoun === "this connector" ? "This connector" : "This server";
+    // ANNOTATIONS, decided once for every server that registers these tools
+    // (owner, 2026-09-21; the stdio server and the hosted connector had answered
+    // both opposite ways):
+    //  - openWorldHint is false on all ten. Every tool works on the user's own
+    //    memory store and reaches nothing else; that the store sits behind an API
+    //    does not make it an open world.
+    //  - destructiveHint is true only for a tool that deletes. None of these ten
+    //    does. Rating a memory moves its ranking signals and never alters or
+    //    erases what was saved (see memory_feedback).
+    /**
+     * 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
+     * the scope) and runs on zero-result paths only — but it is not that path's
+     * only probe: the plain unscoped empty read also hands buildReadEmptyResponse
+     * a stats call for the first-contact greeting, so that answer makes two
+     * probes where 0.8.0 made one, and the scoped/filtered answers make one where
+     * 0.8.0 made none. Disclosed in the 0.8.1 CHANGELOG entry.
+     *
+     * This replaces `domainMissNote`, whose `catch { return ""; }` made three
+     * different states share one spelling: the store is there and the query missed,
+     * the room is there and the query missed, and the probe failed. The caller then
+     * read that string as a boolean, so "we could not check" was rendered exactly
+     * like "the store exists" — the collision this release is about, at the point
+     * where the whole scoped path converges. The states are now arms of a union
+     * (src/scope.ts) and every consumer must answer for each of them.
+     *
+     * The probe routing lives in src/scope.ts: a room address is checked against the
+     * ROOM list and a domain against `/memory/stats`, because stats never contains a
+     * room address (CodeRabbit #65). `searched` is the RAW value that went over the
+     * wire, so the diagnosis can never describe a different store than the request.
+     */
+    function probeScope(searched) {
+        return probeReadScope(searched, () => apiFetch("/memory/stats", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) }), () => apiFetch("/memory/rooms", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) }), safeInline);
+    }
+    // --- 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.",
+        inputSchema: {
+            content: z
+                .string()
+                .min(CORE_LIMITS.writeContent.minLength)
+                .max(CORE_LIMITS.writeContent.maxLength)
+                .describe("The memory to store as a self-contained statement, e.g. 'User prefers TypeScript strict mode' or 'Decided to deploy the API on Cloudflare Workers (2026-06)'."),
+            concepts: z
+                .array(z.string())
+                .max(CORE_LIMITS.writeConcepts.maxItems)
+                .optional()
+                .describe("Key concepts for linking related memories (e.g. ['deploy', 'friday', 'staging'])"),
+            // The only domain the contract bounds is this one: core's write
+            // schema caps it at 100 characters, and a longer one is refused there.
+            // Read, list_recent and feedback have no limit in the contract, so
+            // none is invented for them here (src/limits.ts, ADR-025).
+            domain: z
+                .string()
+                .max(CORE_LIMITS.domain.maxLength)
+                .optional()
+                .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."),
+        },
+        // Copied from the connector's `memoryWriteOutput` (mnemoverse-mcp-remote,
+        // src/tools/index.ts), field for field and description for description,
+        // except that `reason`'s description also states the 400-character cap and
+        // the normalised-to-empty case (the connector's text promises exact
+        // preservation while capping the same way; review, 2026-09-23), and with ONE
+        // deliberate difference in a validator: `memory_id` here is `z.string()`, not
+        // `z.guid()` (decision OD-7, owner, 2026-09-22). This package's ids are
+        // opaque strings, and nothing in the contract promises they are UUIDs;
+        // a guid validator would turn any future id-format change into a
+        // whole-page "Output validation error" instead of a value this client
+        // simply could not shape-check further.
+        outputSchema: {
+            stored: z
+                .boolean()
+                .describe("Whether the memory passed the novelty gate and was stored."),
+            memory_id: z
+                .string()
+                .nullable()
+                .describe("Identifier of the stored memory, or null when it was not stored."),
+            reason: z
+                .string()
+                .optional()
+                .describe("The memory service's own explanation of this outcome, quoted as sent — when stored is false this is the ONLY statement of WHY, e.g. \"Below importance threshold (0.047 < 0.1)\". Ordinary text is preserved exactly; only control, bidi, zero-width, and repeated-whitespace characters are normalized before display, and the value is capped at 400 characters. Absent when the service sent no explanation, or when nothing remains after that normalization."),
+            importance: z
+                .number()
+                .optional()
+                .describe("Novelty score for this write (0-1): how much it adds over the nearest memories already saved in the same domain. A first-generation metric UNDER ACTIVE DEVELOPMENT and known to be unreliable — the same content has measured ~0.08 in Russian against ~0.55 in English, so it under-reads non-English text. It is not a verdict on whether the memory was worth keeping. Absent when the service sent no score."),
+        },
+        annotations: {
+            title: "Store Memory",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ content, concepts, domain }) => {
+        // NO NORMALISATION HERE — deliberately, after a review found two ways it
+        // breaks (2026-08-08). Trimming looked like an obvious win: domain names
+        // are matched byte-for-byte in core, so " engineering" opens a permanent
+        // second store beside "engineering". But:
+        //
+        //   1. Core REJECTS a non-canonical room address on purpose — 400
+        //      "Non-canonical room address", so a write "can't be mis-routed and
+        //      tagged with a spoofed xroom domain" in its own words. Trimming
+        //      " xroom:room_01ABC" normalises past that guard, and the atom lands
+        //      in the ROOM's store, visible to every member. Content that never
+        //      left the caller in 0.8.0 would leave the account in 0.8.1. The
+        //      address in that shape is one our own output hands the model.
+        //   2. For a caller who has been padding a domain for months, trimming
+        //      silently relocates new writes and orphans the old corpus, and (at
+        //      the time this was written) memory_delete_domain did NOT trim, so
+        //      the same client could no longer even name the shard it created —
+        //      that tool was withdrawn to an administrative REST-only operation
+        //      on 2026-08-20, so this specific consequence no longer applies, but
+        //      the orphaned-corpus risk from silently relocating writes does.
+        //
+        // Both are behaviour changes, so they do not belong in a patch whose
+        // whole claim is that it only changes wording. Normalisation, if it ever
+        // returns, needs room addresses deliberately EXEMPT and zero-width
+        // characters handled (JS trim() does not strip them — verified, contrary
+        // to what an earlier comment here asserted).
+        //
+        // `writeAuthor` (STEP4-5): called once, here, only for this one write,
+        // never for a read or a probe. `typeof` first, not a shape check: this
+        // dependency crosses a public package boundary a caller controls only
+        // at compile time, so a runtime value that is not an object (a string,
+        // a number, `null`) is treated the same as "no author", rather than
+        // reaching JSON.stringify as a field core would then have to reject.
+        // Whatever IS an object is sent exactly as returned: no field-level
+        // normalisation here, because core re-normalises server-side (see
+        // {@link WriteAuthor}), and this package cannot know the sixth field a
+        // future core release adds any better than core's own validator does.
+        const authorRaw = writeAuthor?.();
+        const author = typeof authorRaw === "object" && authorRaw !== null ? authorRaw : undefined;
+        const r = await apiFetch("/memory/write", {
+            method: "POST",
+            body: JSON.stringify(writeRequestBody({ content, concepts, domain }, author)),
+        });
+        // `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
+        // fabricates the gate's verdict (review, 2026-08-08).
+        // A non-finite number is no score either: JSON can carry `1e400`, which
+        // parses as Infinity, passes a `typeof` check, prints as "Infinity" and
+        // fails the output schema (zod rejects non-finite numbers), so the whole
+        // reply would turn into an SDK validation error (review, 2026-09-23).
+        const importance = typeof r?.importance === "number" && Number.isFinite(r.importance)
+            ? r.importance.toFixed(2)
+            : "unknown";
+        // `Server reason:` is a VERBATIM label, and safeInline made it a lie on
+        // every occurrence: core's only rejection reason is
+        // "Below importance threshold (0.412 < 0.500)", whose parentheses and `<`
+        // are outside the sanitiser's charset — so the relay read "Below importance
+        // threshold 0.412 0.500", with the comparison operator and both delimiters
+        // deleted and the two numbers left unlabelled and order-only. Quoted
+        // exactly instead (src/names.ts). If it will not fit, say THAT rather than
+        // drop the clause: omitting it would report a server that gave no reason.
+        const reasonQuote = r?.reason
+            ? (exactLiteral(r.reason, 400)?.literal ?? "(too long to quote exactly)")
+            : "";
+        // Structured twins of the two text-only values above, for
+        // `structuredContent`: the raw number instead of the two-decimal
+        // string, and the control/bidi/zero-width-normalised text (src/names.ts
+        // `structuredText`) instead of the quoted JSON literal `reasonQuote`
+        // uses, since a `structuredContent` consumer reads `reason` as a plain
+        // string field, not a literal it must decode. Computed once and used on
+        // BOTH verdict branches below, since core can send either on a stored
+        // write too. Core's `superseded` array (the ids this write replaced) is
+        // deliberately not carried in this slice.
+        const reasonStructured = structuredText(r.reason, 400);
+        const importanceStructured = typeof r.importance === "number" && Number.isFinite(r.importance)
+            ? r.importance
+            : undefined;
+        const optionalStructured = {
+            ...(reasonStructured === undefined ? {} : { reason: reasonStructured }),
+            ...(importanceStructured === undefined ? {} : { importance: importanceStructured }),
+        };
+        // 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) {
+            // core's WriteResponseSchema carries `atom_id` on every stored write,
+            // so a `stored: true` body without one is not core's answer: the
+            // same class of unreadable 2xx the guard above catches for a missing
+            // `stored`, just discovered one field later. `structuredContent`
+            // needs `memory_id` to be a string (the declared outputSchema), and
+            // there is no honest value to put there for a write whose own result
+            // does not say what was stored.
+            if (typeof r.atom_id !== "string") {
+                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.");
+            }
+            return structured(`Stored (importance: ${importance}). ID: ${r.atom_id}`, {
+                stored: true,
+                memory_id: r.atom_id,
+                ...optionalStructured,
+            });
+        }
+        // NOT STORED. The old wording ("Filtered — …") named the mechanism but
+        // never the outcome, so a caller could read it as a soft success and move
+        // on. In dogfooding this ate a CORRECTION to a wrong fact: the stale
+        // version stayed as the only record, and looked more authoritative for
+        // having no competitor (2026-08-07).
+        //
+        // The ADVICE was wrong until 2026-08-08, and wrong in a way that made
+        // things worse. It told the caller to rewrite the content as a cleaner
+        // factual statement — but the gate scores GEOMETRIC NOVELTY against the
+        // nearest existing atom in the same domain, not phrasing or factuality.
+        // "Below importance threshold" means TOO SIMILAR TO SOMETHING ALREADY
+        // STORED. A rewrite of the same fact therefore produces a near-identical
+        // embedding, scores the same or lower, and is rejected again — and the old
+        // text ended with "write it again", so a compliant agent looped. It was
+        // anti-correlated with the mechanism in exactly the case it was written
+        // for: a correction, which is by nature similar to what it corrects.
+        // WHAT IS CONDITIONAL HERE, stated exactly, because a previous
+        // version of this comment claimed more than the code does.
+        //
+        // Conditional: the SERVER'S VERDICT and the SCORE. `Server reason:`
+        // is printed only when `reason` came back, and `Novelty score` only
+        // when a numeric `importance` did — a live surface answers
+        // `{"stored":false}` with neither, and quoting a verdict nobody sent
+        // would be a claim on zero evidence.
+        //
+        // Unconditional: the MECHANISM sentence below, and it is not derived
+        // from this response. It is a statement about core: `/memory/write`
+        // refuses for exactly one reason — the importance gate, scoring
+        // geometric novelty against the nearest existing atom in the same
+        // domain, with "Below importance threshold (x < y)" as its only text
+        // (two branches in memory_engine, one reason). The BATCH endpoint has
+        // other failure paths; this client does not call it. So for any
+        // rejection this client can receive, that sentence is true whether or
+        // not the server bothered to say why. The earlier comment here read
+        // "the cause is named only when the server named it", which describes
+        // a draft that did not carry this sentence at all.
+        //
+        // NOT PRESENT AT ALL: a prediction about the retry. "Rewording will
+        // score the same or lower" was asserted as fact and is probably
+        // BACKWARDS — novelty decreases with similarity to the blocking
+        // memory, so a reworded sentence is usually LESS similar and scores
+        // HIGHER. And delete-then-write advice an earlier draft carried was
+        // impossible for a room write even when memory_delete still existed:
+        // the blocker is a room atom, which that tool could not touch either
+        // (reviews, 2026-08-08). Deletion is administrative-only now
+        // (2026-08-20), so this message never suggests it at all.
+        return structured(`NOT STORED — nothing was saved.` +
+            (reasonQuote ? ` Server reason: ${reasonQuote}.` : ``) +
+            (importance === "unknown"
+                ? ``
+                : ` Novelty score ${importance}. That score is a first-generation` +
+                    ` metric under active development and known to be unreliable —` +
+                    ` identical content has measured ~0.08 in Russian against ~0.55 in` +
+                    ` English — so read it as a rough hint about similarity, not as a` +
+                    ` judgement of whether this memory was worth keeping.`) +
+            (isRoomDomain(domain)
+                ? // ROOM RULE (core#482, 2026-08-13). A room is a message bus:
+                    // the second agent's job is to receive a restatement of what
+                    // the first was told, so a briefing or a status summary STORES
+                    // here. Only a write the embedder cannot distinguish from one
+                    // already present is refused. Telling a caller to "write the
+                    // delta" in a room would be advice against the room's purpose.
+                    ` Restatements are allowed in rooms — this one was refused only` +
+                        ` because it is indistinguishable by embedding from a message` +
+                        ` already there. Similarity is judged on roughly the first 500` +
+                        ` tokens, so a long message that OPENS like an earlier one can` +
+                        ` land here even when its body differs: lead with what is new.`
+                : ` Writes are gated on how much a memory adds over what is already in the` +
+                    ` same domain, so a near-duplicate is refused. If the point is genuinely` +
+                    ` new, write what is DIFFERENT rather than restating the whole fact.`), 
+        // `memory_id` is a literal null on a refusal, per the field's own
+        // description ("null when it was not stored"); the connector's refusal
+        // fixtures carry `atom_id: null` as well. The connector forwards
+        // `res.atom_id` on both verdicts; this package does not forward an id
+        // for a write that was not stored, since a refusal carrying one would
+        // be a body this client cannot vouch for.
+        { stored: false, memory_id: null, ...optionalStructured });
+    });
+    // --- Tool: memory_read ---
+    server.registerTool("memory_read", {
+        description: "Search your long-term memory before answering anything that may have come up before — user preferences, past decisions, project setup, people, or earlier context. This memory is shared: it persists across sessions and across every AI tool the user has connected (Claude, ChatGPT, Cursor, VS Code). ALWAYS check here first when you're unsure whether you already know something; no need to call it for general world knowledge you already hold. Returns matches ranked by relevance (or newest-first with order_by: 'recency'); each result carries an id you can pass to memory_feedback. A wrong or stale memory is corrected by writing a fresh one with memory_write, not by deleting it.",
+        inputSchema: {
+            query: z
+                .string()
+                .min(CORE_LIMITS.readQuery.minLength)
+                .max(CORE_LIMITS.readQuery.maxLength)
+                .describe("Natural-language description of what you're looking for, e.g. 'database choice for the API' or 'user's preferred testing framework'."),
+            top_k: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.readTopK.minimum)
+                .max(CORE_LIMITS.readTopK.maximum)
+                .optional()
+                .describe(`Requested number of results (default: 5, what ${serverNoun} asks for when you omit it; the engine's own default of 10 never applies, because the field is always sent). ⚠️ Not a hard cap: association expansion can return MORE than this, and the relevance floor can return fewer — raising it does not reliably widen the result set. For a complete, exactly-bounded listing use memory_list_recent instead.`),
+            domain: z
+                .string()
+                .optional()
+                .describe("Restrict the search to one domain namespace (e.g. 'project:acme'). Omitting it searches your OWN domains — it does NOT include shared rooms, which are separate stores: to search a room, pass its address here (e.g. 'xroom:room_01ABC'). Find room addresses with memory_list_rooms."),
+            order_by: z
+                .enum(["relevance", "recency"])
+                .optional()
+                .describe("'relevance' (default) = ranking order. 'recency' = the matched " +
+                "set re-sorted newest-first. For a complete newest-first feed " +
+                "with no search at all, use memory_list_recent instead."),
+            since: z
+                .string()
+                .max(40)
+                .optional()
+                .describe("Only memories created at/after this ISO-8601 instant (naive = " +
+                "UTC) — e.g. your last-seen watermark in a shared room."),
+            until: z
+                .string()
+                .max(40)
+                .optional()
+                .describe("Only memories created at/before this ISO-8601 instant."),
+            exclude_author: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("Drop memories written by this author PRINCIPAL — the server-side " +
+                "identity. ⚠️ NOT USABLE FROM HERE YET: the principal is not shown " +
+                "in these results, so there is no value you can obtain through " +
+                "this tool, and a guess like 'me' silently matches nothing and " +
+                "filters nothing. Only pass it if your system knows the exact " +
+                "principal from elsewhere (e.g. the REST API). A self-exclusion " +
+                "shortcut is planned."),
+        },
+        // Item shape is MEMORY_ITEM_OUTPUT (above), shared with
+        // memory_list_recent's outputSchema as of S5; see that constant's
+        // comment for provenance and the OD-7 id-type note.
+        outputSchema: {
+            items: z
+                .array(z.object(MEMORY_ITEM_OUTPUT))
+                .describe("Matching memories, ordered per order_by."),
+        },
+        annotations: {
+            title: "Search Memories",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ query, top_k, domain, order_by, since, until, exclude_author }) => {
+        // ONE value, used for the request AND for every decision about it.
+        //
+        // A previous draft sent the raw string but decided the wording from a
+        // TRIMMED copy, and the two disagreed in the release's own founding case:
+        // a read on " engineering" searched the padded store (correct) while the
+        // diagnosis checked "engineering", found it, and stayed silent — so the
+        // one note that would have said "a stray space makes a different store"
+        // was suppressed exactly when a stray space had made a different store.
+        // For a whitespace-only domain it went the other way and claimed the
+        // search had covered the caller's own domains when it had covered none
+        // (reviews, 2026-08-08).
+        //
+        // `|| undefined` is what 0.8.0 sent and must stay: core filters on
+        // `domain is not None`, not on truthiness, so passing "" through would
+        // become `WHERE domain = ''` — a store that cannot exist — turning a
+        // search of every domain into a guaranteed miss. That is data movement,
+        // not wording, and it does not belong in a patch.
+        const searched = searchedScope(domain);
+        const r = await apiFetch("/memory/read", {
+            method: "POST",
+            body: JSON.stringify(readRequestBody({ query, top_k, domain, order_by, since, until, exclude_author })),
+        });
+        // `items` must be a REAL array before anything below may speak. Core's
+        // read response always carries one on a 200, so a body without it is not
+        // core's answer — and the old `Array.isArray(r?.items) ? r.items : []`
+        // fed exactly that body to the entire zero-result machinery: head
+        // sentence, scope probe, diagnosis. An absence claim derived from a body
+        // this client could not read — the substitution classifyRooms removed for
+        // rooms, one level up from the probes (truth F13, 2026-08-08).
+        const items = r?.items;
+        if (!Array.isArray(items)) {
+            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 —
+            // the truthful answer is "nothing new for these filters" (the feed's
+            // filtered head uses the same sentence; no stats probe, no broaden
+            // hint). Unscoped, it also has to name the rooms it never looked in.
+            const scopeNote = readScopeNote(await probeScope(searched));
+            // The scope is IN the sentence, not appended after it. This branch
+            // was already the honest one in 0.8.0 — it names its filters — and
+            // it is the model the feed's copy now follows.
+            //
+            // The legend wraps the WHOLE message and is added at most once:
+            // `scopeNote` may itself have named a store (a case-twin), and one
+            // explanation of the escaping per answer is the point of it.
+            return structured(withDomainEscapeLegend(`Nothing in ${scopeLabel(searched)} matches within the given time/author filters.` +
+                futureSinceNote(since, Date.now()) +
+                scopeNote, searched), { items: [] });
+        }
+        if (items.length === 0) {
+            // Zero results. The scope is probed FIRST and the whole answer is then
+            // assembled from that ONE value in src/teaching.ts — head sentence and
+            // disclosure together, per state.
+            //
+            // ORDER MATTERS and is now structural: whether the caller has rooms we
+            // could not search decides whether the first-contact greeting is even
+            // true, so the room knowledge is an INPUT to the answer rather than a flag
+            // consulted beside it. `total_atoms` counts the personal org only, so a
+            // joiner with three full rooms and no personal writes would otherwise be
+            // told "nothing has been saved yet" and contradicted by the note right
+            // underneath (review, 2026-08-08).
+            //
+            // Nothing is appended here any more. While the head came from teaching.ts
+            // and the tail was concatenated at this line, the two could disagree — a
+            // head promising "that is not the whole picture:" with an empty tail after
+            // it was a live bug for an account whose only room was archived.
+            const scope = await probeScope(searched);
+            const text = await buildReadEmptyResponse(
+            // THE THIRD PROBE, and the one the first pass at #73 missed. An
+            // UNSCOPED empty read takes this path: probeScope only fetches the
+            // room list (scope.ts: `if (!searched) return { kind: "own-domains" }`),
+            // and the stats call for the first-contact greeting is issued here.
+            // Deadlining only the two inside probeScope left the commonest empty
+            // read of all still able to hang for undici's ~300s default — the exact
+            // symptom #73 names.
+            () => apiFetch("/memory/stats", {
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            }), scope);
+            // NO legend wrapper here, on purpose — `withDomainEscapeLegend(
+            // text, searched)` stood on this line and was dead code that
+            // looked load-bearing (tests-lens F9, 2026-08-08): every arm of
+            // buildReadEmptyResponse either names no store at all (fixed
+            // sentences), or names it inside a note that appends its own
+            // legend (the case-twin diagnosis, src/scope.ts) — and the
+            // unscoped path passes `searched === undefined`, which can never
+            // need one. So there was no input on which the wrapper fired.
+            // Pinned by "the plain-empty read is legended by its notes" in
+            // test/handlers.test.ts.
+            return structured(text, { items: [] });
+        }
+        // Every item must carry the three fields core's MemoryItemSchema always
+        // sends before this handler may render OR structure it: `atom_id`,
+        // `content` and `domain`. A body with items but missing one of those on
+        // any entry is not core's answer to memory_read, the same "unreadable
+        // 2xx" class the guard above catches one level up, discovered one field
+        // later. `structuredItem` (src/render.ts) needs all three to build a
+        // schema-honest structuredContent item, and there is no honest value to
+        // put in a required field this response did not send.
+        if (items.some((it) => typeof it?.atom_id !== "string" ||
+            typeof it?.content !== "string" ||
+            typeof it?.domain !== "string")) {
+            return unreadableAnswerReply("The search result", "a list of matches", "nothing matched");
+        }
+        // Rendering lives in src/render.ts (testable): each line carries the
+        // CN-001 author tag, the created_at date (#404 R1 — a reader cannot
+        // reason about recency it cannot see) and the full atom id (the tool
+        // description always promised ids for memory_feedback/memory_delete;
+        // the old render never delivered them, making both uncallable from
+        // read results).
+        const lines = items.map((item, i) => formatReadItem(item, i));
+        // `?? 0` prints a FABRICATED `(0ms)` when the server sent no timing — the
+        // same class as "Associations: 0" for an unknown count, which memory_stats
+        // fixed in this release. Untouched here and recorded in CHANGELOG's "Known
+        // and NOT fixed here" with the other three.
+        const searchMs = (r?.search_time_ms ?? 0).toFixed(0);
+        const text = lines.join("\n\n") + `\n\n(${searchMs}ms)`;
+        // Each line's `@"domain"` tag is an exact literal; the legend that
+        // explains an escape belongs to the answer, not to twenty tags.
+        //
+        // Legend AFTER the cap, never before. capResult truncates from the
+        // END, and the legend is appended at the end — so applied first it
+        // was the first thing the cap ate, on exactly the pages long enough
+        // to need both: a hundred escaped tags left with nothing saying that
+        // \u00a0 is ONE character, not six (truth F6, 2026-08-08). Applied
+        // to the CAPPED text the legend survives; and since it fires only
+        // when an escaped literal is still on the page, a cap that removed
+        // every escaped name drops the legend with it.
+        //
+        // `structuredContent` carries every item, uncapped (OD-11): the cap
+        // and its legend are TEXT-side concerns, and `structuredItem`
+        // (src/render.ts) is deliberately not run through either.
+        //
+        // Author names are candidates too, not just domains (I66-1..I66-3,
+        // issue #66): the text tag now quotes every author name through the
+        // same `exactLiteral` the `@domain` tag uses, so an escaped one needs
+        // the same "these are JSON string literals" legend an escaped domain
+        // already gets. `rawAuthorName` is the SAME raw value `formatAuthorTag`
+        // quoted, so this recomputation finds the same literal that is
+        // actually on the page.
+        return structured(withEscapeLegendAt(MAX_DOMAIN_TAG_LITERAL, capResult(text), ...items.map((it) => it?.domain), ...items.map((it) => rawAuthorName(it?.provenance))), { items: items.map(structuredItem) });
+    });
+    // --- 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. 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. 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()
+                .describe("Only entries created at/after this ISO-8601 instant (naive = UTC) — your novelty watermark."),
+            until: z
+                .string()
+                .optional()
+                .describe("Only entries created at/before this ISO-8601 instant (inclusive). Pair with `since` to read a closed window — 'what happened on Monday' — instead of paging back from now."),
+            exclude_author: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("Drop entries written by this author PRINCIPAL. ⚠️ NOT USABLE FROM HERE YET — the principal is never shown in these results, so there is no value you can get through this tool; a guess like 'me' filters nothing, silently. Same caveat as on memory_read."),
+            limit: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.recentLimit.minimum)
+                .max(CORE_LIMITS.recentLimit.maximum)
+                .optional()
+                .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(CORE_LIMITS.recentCursor.maxLength)
+                .optional()
+                .describe("Opaque cursor from a previous page's 'More older entries exist' line — continues the listing without skips or duplicates."),
+        },
+        // Item shape is MEMORY_ITEM_OUTPUT, shared with memory_read's
+        // outputSchema (S5, structured-output plan; see that constant's
+        // comment). `next_cursor` copies the connector's own field, same name
+        // and meaning (mnemoverse-mcp-remote `memoryListRecentOutput`), but
+        // this package derives it differently, because it pages through
+        // several core requests per call instead of one; see the comment on
+        // `acceptedCursor` where the value is produced, below.
+        outputSchema: {
+            items: z
+                .array(z.object(MEMORY_ITEM_OUTPUT))
+                .describe("Entries newest-first (creation time descending)."),
+            // Optional, unlike the connector's required field (decision OD-12,
+            // 2026-09-23): the key is ABSENT when the service sent a continuation
+            // token this client will not pass on (CN-032 shape gate, the same one
+            // the text applies), because null would claim the listing is complete.
+            next_cursor: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("Pass back as cursor for the next (older) page; null = listing complete. Absent when the service sent a continuation token this client will not pass on; the text then says the token could not be displayed."),
+        },
+        annotations: {
+            title: "List Recent Memories",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ domain, since, until, exclude_author, limit, cursor }) => {
+        // ONE value for the request and for every decision about it — see the note
+        // at the top of memory_read.
+        const searched = searchedScope(domain);
+        // 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) {
+                    // OD-9 (owner, 2026-09-23): this reply is now `isError`, not a
+                    // silent success. Once this tool declares an outputSchema (S5),
+                    // the SDK's own `validateToolOutput` (see the comment on
+                    // `structured()` above) rejects a non-error result with no
+                    // `structuredContent`, and there is no honest structuredContent
+                    // to give it: `{items: [], next_cursor: null}` would be a
+                    // schema-valid EMPTY PAGE, exactly the absence claim about the
+                    // feed this sentence exists to avoid making. `isError` is the one
+                    // shape the SDK exempts from that check, so it is the shape this
+                    // reply takes now. The sentence itself is unchanged.
+                    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.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                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);
+                // An EMPTY cursor ends the feed for the page as well as for this loop.
+                // The loop below already stops on it (`position` is undefined), but
+                // the raw "" went to formatRecentPage, which reads only null as the
+                // end, so a finished feed printed "More entries exist but the
+                // continuation token could not be displayed" (CodeRabbit, #144).
+                // Only "" is normalised: any other non-null value still reaches the
+                // renderer, which says entries exist but refuses to print the token.
+                acceptedCursor = next === "" ? null : next;
+                // The same gate the two surfaces apply (CURSOR_RE, src/render.ts):
+                // a token this client will not print or carry is not passed back
+                // to the service either, so paging stops here and the page says
+                // the token could not be displayed (Copilot, #159).
+                position =
+                    typeof next === "string" && next && CURSOR_RE.test(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.
+            //
+            // `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 === "" ? null : next; // same end-of-feed rule as above
+                break;
+            }
+            // 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;
+        // Every ACCEPTED item must carry the three fields core's
+        // MemoryItemSchema always sends before this handler may render OR
+        // structure it: `atom_id`, `content` and `domain`; same guard as
+        // memory_read's (S4), added here for S5. A body with items but missing
+        // one of those on any entry is not core's answer, the same "unreadable
+        // 2xx" class the batch guard above catches one request earlier;
+        // `structuredItem` (src/render.ts) needs all three to build a
+        // schema-honest structuredContent item, and there is no honest value to
+        // put in a required field a batch did not send. Trivially satisfied
+        // when `items` is empty, so this runs before the zero-length branch
+        // rather than only inside the non-empty one.
+        if (items.some((it) => typeof it?.atom_id !== "string" ||
+            typeof it?.content !== "string" ||
+            typeof it?.domain !== "string")) {
+            return unreadableAnswerReply("The recent-entries feed", "an empty feed", "there is nothing to list");
+        }
+        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.
+            //
+            // Two prior shapes of this branch were wrong the same way. In 0.8.0 it
+            // printed "Nothing new since your watermark." with no scope in it — the
+            // sentence src/scope.ts was written to eliminate. The first fix put the
+            // scope into the clause but kept choosing BETWEEN the two heads by
+            // looking at `since` only, so {until} alone and {exclude_author} alone
+            // fell to "No memories in ${where} yet." — an emptiness claim about a
+            // store holding a thousand atoms outside the window — and {since, until}
+            // kept the watermark phrasing, which pretends the read reached the
+            // present when `until` stopped it years short (review, 2026-08-08).
+            //
+            // Four heads, one rule: the emptiness claim ("yet") is allowed only
+            // when NOTHING narrowed the window; the watermark phrasing only when
+            // `since` was the whole narrowing; any other filter combination gets the
+            // sentence memory_read's filtered branch uses — the filters are named as
+            // what bounded the result, and nothing is claimed beyond them.
+            //
+            // A `cursor` outranks all three. It is not a filter over the store — it
+            // is a POSITION in a listing whose earlier pages the caller has already
+            // read, so every other head is false here: "No memories in ${where}
+            // yet." is an absence claim about a store the caller has just SEEN
+            // entries from, and the watermark phrasing pretends a continuation that
+            // stopped mid-listing was a clean catch-up. The engine hands out a
+            // cursor only when more entries existed at that moment, so an empty
+            // continued page means the listing moved under the caller — entries
+            // removed between page fetches — and the head speaks about the
+            // continuation only, never about what the store holds (follow-up to the
+            // head-selection fix, 2026-08-08). Decided by the same truthiness the
+            // request used: an empty-string cursor never reaches the wire
+            // (src/requests.ts), so it may not pick the sentence either.
+            const scopeNote = readScopeNote(await probeScope(searched));
+            const where = scopeLabel(searched);
+            const head = cursor
+                ? `Nothing further in ${where} past this cursor — entries may have been ` +
+                    `removed since the previous page was fetched.` +
+                    (since || until || exclude_author
+                        ? ` The given time/author filters still bounded this page.`
+                        : ``)
+                : since && !until && !exclude_author
+                    ? `Nothing new in ${where} since your watermark.`
+                    : since || until || exclude_author
+                        ? `Nothing in ${where} matches within the given time/author filters.`
+                        : `No memories in ${where} yet.`;
+            // `structuredContent.next_cursor` is unconditionally null on this
+            // branch: none of the four heads above ever prints a NEW cursor to
+            // continue from (a `cursor` in the args is the caller's OWN, already
+            // spent; the others are absence claims over the whole scope), so
+            // there is no cursor value the text could be said to agree with.
+            return structured(withDomainEscapeLegend(head + futureSinceNote(since, Date.now()) + scopeNote, searched), { items: [], next_cursor: null });
+        }
+        return structured(
+        // The page body comes from src/render.ts; the escape legend is
+        // applied HERE, to the CAPPED text. formatRecentPage used to append
+        // it itself, which put it before capResult, and capResult truncates
+        // from the end, so the one sentence explaining the escapes was the
+        // first casualty on every page long enough to be capped (truth F6,
+        // 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.
+        //
+        // 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.
+        //
+        // Author names are candidates too, not just domains: same reasoning
+        // as memory_read's call site above (I66-1..I66-3, issue #66).
+        withEscapeLegendAt(MAX_DOMAIN_TAG_LITERAL, 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), ...items.map((it) => rawAuthorName(it?.provenance))), {
+            items: items.map(structuredItem),
+            // Same field name and meaning as the connector's `next_cursor`
+            // (mnemoverse-mcp-remote `memoryListRecentOutput`): the cursor a
+            // client can safely pass back to continue, null when the feed is
+            // finished. DIFFERENT derivation, because this package pages
+            // through several core requests per call (LIST_PAGE_CHAR_BUDGET)
+            // instead of one: it is `acceptedCursor`, the cursor of the last
+            // FULLY accepted batch (set above, same value `formatRecentPage`
+            // just printed), not core's newest-seen cursor: a batch that did
+            // not fit the budget is absent from `items` too, so pointing past
+            // it would both skip entries and contradict the page just shown.
+            // `acceptedCursor` is normalised to null in the loop already
+            // (`next === "" ? null : next`) before it ever reaches here. One
+            // more gate, the same one the text applies (CURSOR_RE, src/render.ts):
+            // a token of a shape this client will not pass on is withheld from
+            // the data too, and the key is then ABSENT, not null, since null
+            // would claim the listing is complete (decision OD-12, 2026-09-23;
+            // the schema marks the field optional for exactly this case).
+            // `typeof` first: the wire value is declared a string but a number
+            // would pass the regex by coercion and then fail the schema.
+            ...(acceptedCursor == null
+                ? { next_cursor: null }
+                : typeof acceptedCursor === "string" && CURSOR_RE.test(acceptedCursor)
+                    ? { next_cursor: acceptedCursor }
+                    : {}),
+        });
+    });
+    // --- 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. A room memory lives in the room's
+     * own store, and a rating reaches it only when that room's address is the
+     * `domain` (core routes the rating by it, routes.py `feedback` →
+     * `_resolve_target_org`). Until 0.11 this tool had no `domain` at all, so a
+     * room memory could not be rated from here; now the miss is a wrong or
+     * missing address, and the text says which store was searched.
+     */
+    const feedbackMissCauses = (domain) => isRoomDomain(domain)
+        ? "Possible causes: the ids did not come from that room (your own memories " +
+            "are rated without a domain, and another room's only with its own address); " +
+            "the memory was deleted; or the id came from somewhere other than a " +
+            "memory_read result."
+        : "Possible causes: the ids came from a shared room, which is reached only " +
+            "when domain is that room's address; the memory was deleted; or the id came " +
+            "from somewhere other than a memory_read result.";
+    const feedbackScope = (domain) => isRoomDomain(domain) ? "in that room" : "in your own domains";
+    server.registerTool("memory_feedback", {
+        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 as memory_ids. For memories read from a shared room, also pass that room's address as domain; your own memories need no domain. A read-only room member cannot rate the room's memories.",
+        // `memory_ids` is the name (2026-09-21): the tool rates memories, which
+        // is what every result is (an atom is the engine's word for its smallest
+        // unit), and the hosted connector already names the parameter so. Both
+        // fields are optional in the schema only so the handler can refuse the
+        // two ways a call can get this wrong with a sentence instead of a
+        // validation dump. Neither carries a format or a count cap: the engine
+        // validates the ids and sets no maximum, and ADR-025 keeps such checks
+        // with the engine rather than copying them here.
+        inputSchema: {
+            memory_ids: z
+                .array(z.string())
+                .min(1)
+                .optional()
+                .describe("Required: IDs of the memories to rate, the `id:` line of each memory_read result. (Optional in this schema only while the deprecated atom_ids is still accepted in its place.)"),
+            atom_ids: z
+                .array(z.string())
+                .min(1)
+                .optional()
+                .describe("Deprecated since 0.11, removed in 0.13: atom_ids is the old name of memory_ids, still accepted on its own until then. Pass memory_ids instead."),
+            outcome: z
+                .number()
+                .min(CORE_LIMITS.feedbackOutcome.minimum)
+                .max(CORE_LIMITS.feedbackOutcome.maximum)
+                .describe("How helpful was this? 1.0 = very helpful, 0 = neutral, -1.0 = harmful/wrong"),
+            // Added in 0.11 (owner, 2026-09-22). Core has always accepted it and
+            // routes the rating to the room's store when it is an xroom address,
+            // refusing a non-member, an archived room and a read-only member with
+            // a 403 that explain403 names. Any other value changes nothing: the
+            // rating goes to the caller's own store, as it does without one. No
+            // format or length check here (ADR-025). The value is sent untouched,
+            // like every other domain this package passes on, except that an
+            // empty string counts as none (searchedScope, as on memory_read).
+            domain: z
+                .string()
+                .optional()
+                .describe("Only for memories read from a shared room: that room's address (xroom:...), exactly as you read it. Omit it for your own memories, which are rated by id alone."),
+        },
+        // Copied from the connector's `memoryFeedbackOutput` (mnemoverse-mcp-remote,
+        // src/tools/index.ts), field for field and description for description,
+        // with one noun changed: the connector's `coactivation_edges` text says
+        // "This connector does not send query_concepts"; here it says "This
+        // server", since the fact holds for this tool's own request body (the
+        // POST above carries only atom_ids, outcome and domain) and the noun was
+        // wrong for a local stdio server. `updated_count` is required, matching both the connector's
+        // schema and core's FeedbackResponseSchema (decision OD-8, owner,
+        // 2026-09-23): a body without a usable count is not core's answer. See
+        // the unknown-count branch below, which is `isError` for exactly that
+        // reason, since there is no honest default to declare for it here.
+        outputSchema: {
+            updated_count: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("How many memories the service reports it applied the rating to. Processed synchronously this is the real count of memories that existed and were updated; processed asynchronously it is a best-effort ACCEPTED-count estimate — the number of IDs submitted — and the authoritative number is not known until the background worker runs. Zero means no submitted ID matched in the service's resolved request scope."),
+            avg_valence: z
+                .number()
+                .optional()
+                .describe("Average valence of the rated memories after the update. Reported as 0 in an asynchronous acknowledgement, where the real value is computed later — a 0 here is therefore not evidence of a neutral outcome."),
+            coactivation_edges: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe(`Number of feedback-driven query/result concept co-activation edges changed by the service. This is separate from ordinary Hebbian strengthening among a memory's own concepts. ${serverNounCap} does not send query_concepts, so live calls through this tool report 0; asynchronous acknowledgements also report 0.`),
+        },
+        annotations: {
+            title: "Rate Memory Helpfulness",
+            readOnlyHint: false,
+            // NOT destructive (owner, 2026-09-21: "only deletion is destructive;
+            // rating is a good action"). A rating moves the memory's valence and
+            // the weights of its associations, which decide how it ranks; the
+            // saved text, its concepts and its domain are untouched, and later
+            // ratings keep moving those scores. Until 0.11 this said true, citing
+            // the spec's "destructive update" to stored state. A client that asks
+            // for confirmation on destructive tools would then have asked before
+            // every rating, taxing the one signal the ranking learns from. The
+            // engine still replaces the previous scores on each rating; keeping
+            // every rating so any one can be undone is planned there, and the
+            // 0.11 CHANGELOG entry says so until it ships.
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ memory_ids, atom_ids: legacyIds, outcome, domain }) => {
+        // Both names at once is ambiguous (which list did the caller mean?), so
+        // it is refused rather than resolved by a silent preference.
+        if (memory_ids !== undefined && legacyIds !== undefined) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "Pass the ids as memory_ids only. atom_ids is its old name, still " +
+                            "accepted on its own, but both at once is ambiguous. Nothing was rated.",
+                    },
+                ],
+            };
+        }
+        const atom_ids = memory_ids ?? legacyIds;
+        if (atom_ids === undefined) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "memory_feedback needs memory_ids: the ids from the memory_read results " +
+                            "you are rating. Nothing was rated.",
+                    },
+                ],
+            };
+        }
+        // `atom_ids` below is the ENGINE's field name for the same list; the
+        // wire contract is unchanged. `domain` goes through `searchedScope`, as
+        // on memory_read and memory_list_recent: an empty string counts as no
+        // domain and is not sent, so a call without one is byte-identical to one
+        // from before 0.11 and core applies its own default. Any other value is
+        // sent untouched.
+        const scope = searchedScope(domain);
+        const r = await apiFetch("/memory/feedback", {
+            method: "POST",
+            body: JSON.stringify(scope === undefined ? { atom_ids, outcome } : { atom_ids, outcome, domain: scope }),
+        });
+        // 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 = 
+        // isSafeInteger, not isInteger: the output schema is z.number().int(),
+        // and zod 4 rejects an integer above 2^53 - 1, so such a count would
+        // turn the whole reply into an SDK validation error (review, 2026-09-23).
+        typeof reported === "number" && Number.isSafeInteger(reported) && reported >= 0
+            ? reported
+            : undefined;
+        // Structured twin of the text's average-valence clause built further
+        // below (`the service reports their average valence is now …`): the
+        // RAW number, not the two-decimal string. Computed here, ahead of that
+        // clause, because it is also carried on the count===0 branch just
+        // below, which returns before the later clause exists. Same rule as
+        // the text: a value that is not a finite number is unknown and absent
+        // from structuredContent, never defaulted to 0.
+        const avgValenceRaw = r?.avg_valence;
+        const avgValenceStructured = typeof avgValenceRaw === "number" && Number.isFinite(avgValenceRaw)
+            ? avgValenceRaw
+            : undefined;
+        // Structured twin of `coactivation_edges`, left out of the TEXT below
+        // for the reason the comment on `valence` gives (this tool sends no
+        // query_concepts, so the number is always 0 here and a sentence about
+        // it would report nothing) but not out of structuredContent, where the
+        // connector's schema carries it as a genuine data field, on every
+        // path, the count===0 one included (review, 2026-09-23). Forwarded
+        // only when it is a non-negative integer, the shape the schema itself
+        // requires, so a value core could never send in that shape is simply
+        // absent here rather than turning this whole reply into an SDK
+        // "Output validation error".
+        const coactivationRaw = r?.coactivation_edges;
+        const coactivationEdges = typeof coactivationRaw === "number" &&
+            Number.isSafeInteger(coactivationRaw) &&
+            coactivationRaw >= 0
+            ? coactivationRaw
+            : 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) {
+            // OD-8 (owner, 2026-09-23): this reply is now `isError`, not a
+            // silent non-error text. Once this tool declares an outputSchema
+            // (S6), the SDK's own `validateToolOutput` (see the comment on
+            // `structured()` above) rejects a non-error result with no
+            // `structuredContent`, and `updated_count` is REQUIRED in that
+            // schema (matching core's own FeedbackResponseSchema), so there is
+            // no honest value to put there for a body that sent none. `isError`
+            // is the one shape the SDK exempts from that check, so it is the
+            // shape this reply takes now. The sentence itself is unchanged,
+            // "do not re-send the same rating" included.
+            return {
+                isError: true,
+                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
+        // usually the wrong cause (review, 2026-08-08).
+        //
+        // Core resolves the feedback org from `domain`, defaulting to the
+        // caller's own store. So the ordinary way to get zero is to rate atoms
+        // that live somewhere else: read a room, take the ids off the `id:`
+        // lines, rate them without the room's address (or with another room's),
+        // and every one silently misses. The atoms exist, the ids are valid, and
+        // telling the caller they were deleted sends them to look for a problem
+        // that isn't there. Before 0.11 there was no `domain` to pass at all.
+        if (count === 0) {
+            return structured("No feedback was recorded — none of those ids matched a memory " +
+                `${feedbackScope(scope)}. ${feedbackMissCauses(scope)}`, {
+                updated_count: 0,
+                ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
+                ...(coactivationEdges === undefined ? {} : { coactivation_edges: coactivationEdges }),
+            });
+        }
+        // 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: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
+        // report rather than asserted as an outcome this client verified. The
+        // hosted connector took the same correction on 2026-08-13
+        // (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 effect = outcome > 0
+            ? " — they should surface sooner next time."
+            : outcome < 0
+                // 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 read of a room this
+        // call did not address. 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 ${feedbackScope(scope)}. ${feedbackMissCauses(scope)}`
+            : 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.`
+                : "";
+        // AVERAGE VALENCE, which core returns and this tool dropped until 0.11
+        // (the hosted connector already passed it on). It is the mean valence of
+        // the memories the rating reached, AFTER the rating: the one number that
+        // shows the rating moved something. Same degree of confidence as the
+        // count, and the same rule: a value that is not a finite number is
+        // unknown and prints nothing, never 0. Core's async mode acks with 0
+        // before the worker runs (memory_engine.py `feedback` docstring), which
+        // is why this is the service's report too; in production every rating
+        // observed so far took the synchronous path (the asynchronous
+        // acknowledgement is reachable but was not seen in the checked window).
+        //
+        // coactivation_edges is left out of the text on purpose: core links
+        // concepts only when the request carries query_concepts, which this tool
+        // does not send, so the number is always 0 here and a sentence about it
+        // would report nothing.
+        //
+        // toFixed keeps the sign of a value that rounds to zero: (-0.001) prints
+        // "-0.00", which reads as a negative valence. Shown as "0.00" instead
+        // (CodeRabbit on #146).
+        const avg = r?.avg_valence;
+        const valence = typeof avg === "number" && Number.isFinite(avg)
+            ? ` The service reports their average valence is now ${avg.toFixed(2).replace(/^-0\.00$/, "0.00")} (on a scale from -1 to 1).`
+            : "";
+        // 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.
+        return structured(`${sent} The service reports ${noun} updated${effect}${valence}${mismatch}${pickADirection}`, {
+            updated_count: count,
+            ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
+            ...(coactivationEdges === undefined ? {} : { coactivation_edges: coactivationEdges }),
+        });
+    });
+    // --- Tool: memory_stats ---
+    server.registerTool("memory_stats", {
+        description: "Get an overview of the stored memory: total count, episodes vs consolidated prototypes, number of learned associations, the list of domains, and average quality scores. This memory is shared across all AI tools the user has connected to Mnemoverse. Use it to orient yourself, to confirm the exact domain name before writing to it, or when the user asks what you remember. Read-only — changes nothing.",
+        inputSchema: {},
+        // `memory_count` and `domains` are copied from the connector's
+        // `memoryStatsOutput` (mnemoverse-mcp-remote, src/tools/index.ts), field
+        // for field and description for description, under the CONNECTOR's
+        // naming rather than core's (`total_atoms`): the same structured
+        // consumer can read both servers, and a data field spelled differently
+        // between them would defeat the point of one shared shape (decision Q3,
+        // owner, 2026-09-23). Both are required, matching the connector: a body
+        // without a usable value for either is not core's answer (see the guard
+        // in the handler below). The other five fields are this package's own
+        // addition, the rest of what this tool's own text already reports,
+        // each optional, present only when core sent a usable number for it.
+        outputSchema: {
+            memory_count: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Number of saved memories."),
+            domains: z.array(z.string()).describe("User-defined memory domains."),
+            episodes: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of episodic (not yet consolidated) memories."),
+            prototypes: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of consolidated prototype memories."),
+            hebbian_edges: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of Hebbian concept-to-concept links, learned from concepts that occur together as memories are stored and used."),
+            avg_valence: z
+                .number()
+                .optional()
+                .describe("Average valence of stored memories: how well recalls turned out, on a scale from -1 to 1."),
+            avg_importance: z
+                .number()
+                .optional()
+                .describe("Average importance of stored memories, on a scale from 0 to 1."),
+        },
+        annotations: {
+            title: "Memory Statistics",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const r = await apiFetch("/memory/stats");
+        // REQUIRED-FIELD GUARD (OD-8 precedent, owner, 2026-09-23): `memory_count`
+        // and `domains` are REQUIRED in the outputSchema above, matching the
+        // connector's own `memoryStatsOutput`, so a body without a usable
+        // `total_atoms` (a non-negative safe integer) or without an ARRAY
+        // `domains` is not core's answer and there is no honest
+        // structuredContent to build for it. Before this schema existed, both
+        // degraded silently into this tool's own "unknown" numbers / "none
+        // reported" domains text; now they are `isError`, the same shape every
+        // other unreadable-answer reply in this file takes. isSafeInteger, not
+        // isInteger, for the same reason memory_feedback's count check gives:
+        // the schema is z.number().int(), and zod 4 rejects an integer above
+        // 2^53 - 1.
+        const totalAtomsRaw = r?.total_atoms;
+        const memoryCount = typeof totalAtomsRaw === "number" &&
+            Number.isSafeInteger(totalAtomsRaw) &&
+            totalAtomsRaw >= 0
+            ? totalAtomsRaw
+            : undefined;
+        const domainsRaw = r?.domains;
+        if (memoryCount === undefined || !Array.isArray(domainsRaw)) {
+            return unreadableAnswerReply("The stats answer", "the memory store's statistics", "the store is empty");
+        }
+        // A field the server did not send is UNKNOWN, not zero. Rendering it as
+        // "0" is the same class of lie as an empty search claiming emptiness:
+        // "Associations: 0" reads as "this memory has learned nothing", which is
+        // a strong and possibly false statement about the product itself.
+        const num = (v) => (typeof v === "number" ? String(v) : "unknown");
+        const dec = (v) => (typeof v === "number" ? v.toFixed(2) : "unknown");
+        // THE surface this tool's own description sends the reader to, to
+        // confirm the exact domain name before writing to it — so it has to be
+        // able to answer that. (Until 2026-08-20 memory_delete_domain also sent
+        // readers here for the same reason, before deletion was withdrawn to an
+        // administrative REST-only operation; see CHANGELOG.)
+        //
+        // Quoting was tried, then withdrawn as a fix that wasn't one: safeInline
+        // collapses and trims whitespace BEFORE the quotes go on, so " engineering"
+        // and "engineering" printed identically and the list read like a tool bug.
+        // The conclusion drawn then — "revealing whitespace needs escaping rather
+        // than quoting" — was right; this is that escaping. Each name is a JSON
+        // string literal, so a leading space, a no-break space, a newline and a
+        // 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)`,
+            // The gloss names the real mechanism. Core's `hebbian_edges` counts
+            // concept-concept edges (api/schemas.py: "Number of Hebbian
+            // concept-concept edges"), and every path that learns one links two
+            // CONCEPTS: `strengthen` walks pairs within one atom's concept list at
+            // write time and again on feedback, `co_activate` links query concepts
+            // to result concepts on use. An earlier gloss said "links between
+            // memories that get used together" — wrong unit (memories, not
+            // concepts) and wrong trigger (an edge records co-occurrence, not two
+            // memories being used together).
+            `Associations: ${num(r?.hebbian_edges)} Hebbian edges — concept-to-concept links learned from concepts that occur together as memories are stored and used`,
+            `Domains: ${domains}`,
+            `Avg quality: valence ${dec(r?.avg_valence)} (how well recalls turned out, -1..1), importance ${dec(r?.avg_importance)} (0..1)`,
+            "",
+            "Counts cover your own domains. Shared rooms are separate stores and are not included — see memory_list_rooms.",
+        ].join("\n");
+        // STRUCTURED TWIN of the optional numeric fields, following the same
+        // rule memory_feedback's does: a value core did not send, or sent in a
+        // shape the schema could not hold, is absent from structuredContent,
+        // never defaulted to 0. Int fields use isSafeInteger for the reason the
+        // guard above gives (the schema is z.number().int(), and zod 4 rejects
+        // an integer above 2^53 - 1); the two averages use isFinite, so an
+        // Infinity smuggled through a raw body (e.g. avg_valence: 1e400) never
+        // reaches a structured consumer as data. The TEXT above keeps printing
+        // whatever num()/dec() print for the same malformed value, and that
+        // text/data divergence is disclosed in the CHANGELOG, as S5 disclosed
+        // its cursor semantics.
+        const safeIntOrUndefined = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+        const finiteOrUndefined = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+        const episodesStructured = safeIntOrUndefined(r?.episodes);
+        const prototypesStructured = safeIntOrUndefined(r?.prototypes);
+        const hebbianEdgesStructured = safeIntOrUndefined(r?.hebbian_edges);
+        const avgValenceStructured = finiteOrUndefined(r?.avg_valence);
+        const avgImportanceStructured = finiteOrUndefined(r?.avg_importance);
+        // DOMAINS FOR structuredContent: FILTERED, not an error and not zeroed
+        // (decisions S7-1/S7-2, owner, 2026-09-23). A non-string element is
+        // dropped rather than turning the whole reply into isError, and the
+        // TEXT above already counts it in formatDomainList's "not shown, cannot
+        // be printed exactly" clause, so the count is not silently lost, only
+        // moved off the surface a structured consumer reads. What a structured
+        // consumer would silently lose is the fact that anything was dropped at
+        // all, so the drop is also reported once on stderr, in this package's
+        // existing startup-diagnostic style ("Mnemoverse: ..." in src/index.ts),
+        // the operator's channel rather than the model's: putting this in the
+        // tool text would surface an implementation detail to the agent reading it.
+        const domainsStructured = domainsRaw.filter((d) => typeof d === "string");
+        const droppedDomains = domainsRaw.length - domainsStructured.length;
+        if (droppedDomains > 0) {
+            console.error(`Mnemoverse: memory_stats dropped ${droppedDomains} non-string domain ` +
+                `entr${droppedDomains === 1 ? "y" : "ies"} from structuredContent.domains ` +
+                `(still counted in the text's "not shown" total).`);
+        }
+        return structured(
+        // Array.isArray, not `?? []`: `domains` is typed as a string[] but
+        // 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.
+        //
+        // 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.
+        withDomainEscapeLegend(capResult(text, "The domain list was truncated — some domain names are not shown."), ...(Array.isArray(r?.domains) ? r.domains : [])), {
+            memory_count: memoryCount,
+            domains: domainsStructured,
+            ...(episodesStructured === undefined ? {} : { episodes: episodesStructured }),
+            ...(prototypesStructured === undefined ? {} : { prototypes: prototypesStructured }),
+            ...(hebbianEdgesStructured === undefined
+                ? {}
+                : { hebbian_edges: hebbianEdgesStructured }),
+            ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
+            ...(avgImportanceStructured === undefined
+                ? {}
+                : { avg_importance: avgImportanceStructured }),
+        });
+    });
+    // --- Tool: memory_create_room ---
+    //
+    // CORE'S `next_steps` IS NOT PRINTED, on purpose (checked 2026-09-22, step
+    // 3c). Core returns it on create and on join, and the closed
+    // mnemoverse-mcp-remote#29 proposed echoing it. It is written for REST
+    // callers ("POST /api/v1/memory/write ... mint an invite with POST
+    // .../invites"), which would steer a model toward calls it does not have;
+    // on join it tells every member to write, a read-only one included; and it
+    // carries the owner-chosen room name raw, which this file prints only
+    // through roomNamePhrase (CN-032). The usage lines below say the same
+    // things in MCP terms, scope-gated on join.
+    // OUTPUT SCHEMAS for the three room tools (S8, structured-output plan):
+    // `room_id`/`address`/`room_address`/`scope` copied from the connector's
+    // `roomCreatedOutput`/`roomInviteOutput`/`roomJoinedOutput`
+    // (mnemoverse-mcp-remote, src/tools/index.ts), field for field and
+    // description for description.
+    //
+    // OD-13 (owner, 2026-09-23): several fields the connector marks required
+    // are OPTIONAL here: `name` on create and join, `scope`/`already_member`
+    // on join, and `code`/`scope`/`room_address`/`expires_at` on invite. The
+    // connector's own core client types those fields as always-present; this
+    // package treats every wire value as untyped (the general rule this whole
+    // file follows) and already has a non-degraded THREE-state phrase for a
+    // room name core did not send (`roomNamePhrase`) and for a join whose
+    // scope core did not report (`roomScopeVerdict`'s "unspecified" arm), so
+    // "core sent no usable value for this field" is an existing, honestly
+    // representable outcome here, not an error, and the schema says so by
+    // making the field optional rather than forcing a fabricated placeholder
+    // into a field declared required.
+    //
+    // `join_url`/`share_message` on invite stay as today: at least one of the
+    // two must be usable or the call is `isError` (unchanged from before this
+    // schema existed), so `share_message` is the one guaranteed field, built
+    // from the SAME fallback the text already prints (share_message when core
+    // sent one, else join_url), and `join_url` itself is optional, present
+    // only when core actually returned a string for it.
+    // --- Tool: memory_create_room ---
+    server.registerTool("memory_create_room", {
+        description: "Create a SHARED memory room — a space OTHER people's assistants can read, and write too when their invite granted read_write (the default scope), across Claude/ChatGPT/Cursor. Use when the user wants to share context or collaborate with someone else (e.g. 'make a room for me and Olya'). Returns the room's address; pass that address as the `domain` on memory_write/memory_read to use it, and on memory_list_recent to catch up on what others added. To bring someone in, call memory_invite_to_room next.",
+        inputSchema: {
+            name: z
+                .string()
+                .min(CORE_LIMITS.roomName.minLength)
+                .max(CORE_LIMITS.roomName.maxLength)
+                .describe("Room name, unique within your account (e.g. 'me-and-olya')."),
+            description: z
+                .string()
+                .max(CORE_LIMITS.roomDescription.maxLength)
+                .optional()
+                .describe("Optional description of the room."),
+        },
+        outputSchema: {
+            room_id: z
+                .string()
+                .describe("The room's id (room_...); pass to memory_invite_to_room."),
+            address: z
+                .string()
+                .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
+            name: z.string().optional().describe("The room name as stored."),
+        },
+        annotations: {
+            title: "Create shared room",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ name, description }) => {
+        const r = await apiFetch("/memory/rooms", {
+            method: "POST",
+            body: JSON.stringify({ name, description }),
+        });
+        // The name is echoed back to the caller who CHOSE it, so it is printed
+        // exactly (src/names.ts): safeInline turned `memory_create_room({name:
+        // "проект"})` into `Created shared room ""` — an echo claiming the caller
+        // named their room the empty string.
+        const rawName = r?.name ?? name;
+        const roomName = roomNamePhrase(rawName);
+        const address = safeInline(r?.address);
+        const roomId = safeInline(r?.room_id);
+        // If core returned no usable id (empty body / sanitized away), don't print
+        // broken `domain=""` guidance — say so instead (Copilot).
+        //
+        // GATE (S8-1, owner, 2026-09-23): core's RoomCreatedSchema sends
+        // room_id alongside address on every create, so `roomId` now joins
+        // `address` in the condition that picks this branch: a body missing
+        // a usable one of either is not core's answer, the same class of
+        // unreadable 2xx this file already refuses rather than describes.
+        const text = address && roomId
+            ? `Created shared room ${roomName}. Address: ${address}\n` +
+                `Use it now: pass domain="${address}" on memory_write / memory_read, and on memory_list_recent to catch up on what others added.\n` +
+                (roomId
+                    ? `To add someone: call memory_invite_to_room with room_id="${roomId}".`
+                    : "")
+            : `Room ${roomName} was created but the server did not return a usable address — ` +
+                `retry, or check that your API key is set.`;
+        // Legend AFTER the cap (same rule as memory_read/memory_list_recent):
+        // capResult cuts from the end, so a legend applied first would be the
+        // first casualty; applied to the capped text it also drops itself when
+        // the cap removed the only escaped name.
+        const finalText = withDomainEscapeLegend(capResult(text), rawName);
+        // Same gate as the text above: no usable address or no usable room_id
+        // is not core's answer, and there is no honest structuredContent for
+        // it either. The existing degrade sentence is the whole reply now,
+        // with isError: true, instead of a 200-shaped "success" with nothing
+        // a caller can act on.
+        if (!address || !roomId) {
+            return {
+                content: [{ type: "text", text: finalText }],
+                isError: true,
+            };
+        }
+        // STRUCTURED `name` comes from the RESPONSE only, never from the
+        // request's `name` the text above falls back to: the schema says "as
+        // stored", and a body that omits `name` gives this client no evidence
+        // of what core stored, so the key is absent rather than an echo of the
+        // caller's own spelling dressed up as core's answer (Copilot, review
+        // round 2). The text keeps its fallback: it is written for the caller
+        // who chose the name and stays byte-identical.
+        const nameStructured = structuredText(r?.name, 200);
+        return structured(finalText, {
+            room_id: roomId,
+            address,
+            ...(nameStructured === undefined ? {} : { name: nameStructured }),
+        });
+    });
+    // --- Tool: memory_invite_to_room ---
+    server.registerTool("memory_invite_to_room", {
+        description: "Mint an invite for a room you own and get a ready-to-forward message. An invite is single-use by default; pass max_uses to let several people join with the same one. The user sends that message to the person they want to add (any messenger); the recipient opens the link or tells THEIR assistant the code to join. Use after memory_create_room, or whenever the user says 'invite <someone>' to an existing room.",
+        inputSchema: {
+            room_id: z
+                .string()
+                .min(1)
+                .max(100)
+                .describe("The room's id (room_...), from memory_create_room."),
+            scope: z
+                .enum(["read", "read_write"])
+                .optional()
+                .describe("Role the invitee gets — 'read' or 'read_write' (default read_write)."),
+            expires_in_days: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.inviteExpiresInDays.minimum)
+                .max(CORE_LIMITS.inviteExpiresInDays.maximum)
+                .optional()
+                .describe("Days until the invite expires (default 7)."),
+            // Added in 0.11 (step 3c; the hosted connector already had it). Core
+            // takes 1 to 1000, default 1. Both ends come from the contract now
+            // (src/limits.ts), so an engine that widens the range widens this
+            // parameter with it rather than being refused here.
+            max_uses: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.inviteMaxUses.minimum)
+                .max(CORE_LIMITS.inviteMaxUses.maximum)
+                .optional()
+                .describe("How many people may join with this invite (default 1, single-use)."),
+        },
+        outputSchema: {
+            share_message: z.string().describe("Ready-to-forward invite text."),
+            join_url: z.string().optional().describe("Landing URL the invitee can open to join."),
+            code: z
+                .string()
+                .optional()
+                .describe("The invite code (mnvr_...). Single-use by default, with a configurable use limit. Shown once."),
+            scope: z.string().optional().describe("Role the invitee will get."),
+            room_address: z
+                .string()
+                .optional()
+                .describe("The room's domain address (xroom:<id>)."),
+            expires_at: z.string().nullable().optional().describe("ISO 8601 expiry, or null."),
+        },
+        annotations: {
+            title: "Invite to room",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ room_id, scope, expires_in_days, max_uses }) => {
+        // JSON.stringify drops undefined keys, so a call without max_uses sends
+        // exactly the body it sent before 0.11 and core applies its default of 1.
+        const r = await apiFetch(`/memory/rooms/${encodeURIComponent(room_id)}/invites`, {
+            method: "POST",
+            body: JSON.stringify({ scope, expires_in_days, max_uses }),
+        });
+        // ONE selection feeds both surfaces (Copilot, review round 2): the
+        // message the text forwards is core's share_message when the body has
+        // one (its raw value, exactly as before this schema existed), else
+        // join_url, else the "(no message returned)" sentence.
+        const rawMessage = r?.share_message ?? r?.join_url;
+        const text = capResult(`Invite ready. Forward this message to the person you're inviting:\n\n` +
+            `${rawMessage ?? "(no message returned)"}`);
+        // Shown to the room OWNER (who minted it), not a foreign principal, so
+        // the core-generated share_message is fine as-is; capResult only bounds
+        // its length for the Connectors-Directory 25K cap. STRUCTURED
+        // `share_message` (S8-4, owner, 2026-09-23) is that SAME selected
+        // value, normalised through structuredText, so the data never carries
+        // a message the text did not show. A selected value that normalises to
+        // nothing (no share_message and no join_url, or a share_message that is
+        // empty, whitespace-only or not a string at all) is not this tool's
+        // success case any more: the text above is unchanged (the blank or the
+        // "(no message returned)" sentence, as before) and the reply is
+        // isError: true, since there is no honest
+        // structuredContent.share_message to pair it with.
+        const shareMessageStructured = structuredText(rawMessage, 800);
+        if (shareMessageStructured === undefined) {
+            return { content: [{ type: "text", text }], isError: true };
+        }
+        // `join_url` through safeInline with the connector's own cap of 400,
+        // as the connector does (mnemoverse-mcp-remote, memory_invite_to_room):
+        // core builds it as `<base>/<code>`, which safeInline's character class
+        // carries unchanged; anything else it would have to alter is not a URL
+        // this client should hand on as one. Absent when nothing remains.
+        const joinUrlSafe = safeInline(r?.join_url, 400);
+        const joinUrlStructured = joinUrlSafe === "" ? undefined : joinUrlSafe;
+        // The other machine fields the same way: safeInline returns "" for a
+        // non-string, an empty string and a string with nothing it may keep,
+        // and "" is not a usable code, scope or address, so the key is absent
+        // (CodeRabbit, review round 2). Present only when something remains.
+        const codeSafe = safeInline(r?.code);
+        const codeStructured = codeSafe === "" ? undefined : codeSafe;
+        const scopeSafe = safeInline(r?.scope);
+        const scopeStructured = scopeSafe === "" ? undefined : scopeSafe;
+        const roomAddressSafe = safeInline(r?.room_address);
+        const roomAddressStructured = roomAddressSafe === "" ? undefined : roomAddressSafe;
+        // `expires_at` through utcInstant's RETURN, the rule memory_read's
+        // `created_at` already follows (S4): a value that states its offset is
+        // carried exactly as sent, an offset-less one, which this package reads
+        // as UTC by contract, is re-emitted as the UTC ISO-8601 instant, so a
+        // structured consumer lands on the instant this client used rather than
+        // reading the naive string as local time (CodeRabbit, review round 2).
+        // `null` when core sent null; absent when the value does not parse.
+        const expiresAtStructured = r?.expires_at === null ? null : (utcInstant(r?.expires_at) ?? undefined);
+        return structured(text, {
+            share_message: shareMessageStructured,
+            ...(joinUrlStructured === undefined ? {} : { join_url: joinUrlStructured }),
+            ...(codeStructured === undefined ? {} : { code: codeStructured }),
+            ...(scopeStructured === undefined ? {} : { scope: scopeStructured }),
+            ...(roomAddressStructured === undefined ? {} : { room_address: roomAddressStructured }),
+            ...(expiresAtStructured === undefined ? {} : { expires_at: expiresAtStructured }),
+        });
+    });
+    // --- 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_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_...)."),
+        },
+        outputSchema: {
+            room_id: z.string().describe("The room's id (room_...)."),
+            address: z
+                .string()
+                .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
+            name: z.string().optional().describe("The room name."),
+            scope: z.string().optional().describe("Your role in the room ('read' | 'read_write')."),
+            already_member: z
+                .boolean()
+                .optional()
+                .describe("True if you were already a member (no-op join)."),
+            next_steps: z.string().describe("How to use the room now."),
+        },
+        annotations: {
+            title: "Join room",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ code }) => {
+        const r = await apiFetch("/memory/rooms/join", {
+            method: "POST",
+            body: JSON.stringify({ code }),
+        });
+        // The room name is OWNER-chosen and rendered into the JOINER's LLM context
+        // (CN-032) — and it is printed EXACTLY (src/names.ts): the literal is one
+        // line with quotes and invisibles escaped, so it cannot forge an
+        // instruction block, and "Zoë" stops being quoted as "Zo" in a sentence
+        // that presents it as the name. `scope` stays sanitised: server-shaped
+        // enum, display-only.
+        const roomName = roomNamePhrase(r?.name);
+        const scope = safeInline(r?.scope) || "member";
+        const address = safeInline(r?.address);
+        const roomId = safeInline(r?.room_id);
+        const prefix = r?.already_member
+            ? `You're already a member of ${roomName}.`
+            : `Joined ${roomName} (${scope}).`;
+        // Don't print broken `domain=""` guidance if no address came back (Copilot).
+        // 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.
+        //
+        // GATE (S8-2, mirrors create's S8-1, owner, 2026-09-23): core's
+        // JoinedRoomSchema sends room_id alongside address on every join, so
+        // `roomId` now joins `address` in the condition that picks this
+        // sentence: same wording as before (it still names only "address" -
+        // the caller cannot tell which of the two core actually omitted, and a
+        // second sentence for a case indistinguishable from this one would be
+        // a distinction this client cannot see either).
+        const verdict = roomScopeVerdict(r?.scope);
+        const usage = !address || !roomId
+            ? `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, and on memory_list_recent to catch up on what is new.`
+                : verdict === "read"
+                    ? `Use it: pass domain="${address}" on memory_read or memory_list_recent 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 or memory_list_recent to read it — the server did not report this membership's write access, so whether memory_write to that address would succeed is unknown.`;
+        // No usable address or room_id: the reply is the same text as before
+        // this schema existed (the prefix line plus the degrade sentence), now
+        // isError: true, since there is no honest structuredContent for a join
+        // whose room this client cannot address. The text stays byte-identical
+        // on purpose: whether this reply should stop saying "Joined" is a
+        // wording decision for the owner, not for this slice.
+        if (!address || !roomId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: withDomainEscapeLegend(capResult(`${prefix}\n${usage}`), r?.name),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const nameStructured = structuredText(r?.name, 200);
+        // STRUCTURED `next_steps` (S8-6, owner, 2026-09-23) is this SAME usage
+        // sentence, never core's own `next_steps`: that field points at REST
+        // endpoints and is deliberately not echoed (see the comment above
+        // memory_create_room). `?? usage` is a defensive fallback for the
+        // unreachable case where structuredText would normalise `usage` to
+        // nothing; it is built from safe, already-sanitised parts and never
+        // actually empties.
+        const nextStepsStructured = structuredText(usage, 500) ?? usage;
+        // `scope` absent when safeInline leaves nothing, as on invite.
+        const scopeSafe = safeInline(r?.scope);
+        const scopeStructured = scopeSafe === "" ? undefined : scopeSafe;
+        return structured(
+        // Legend after the cap, same ordering rule as everywhere else.
+        withDomainEscapeLegend(capResult(`${prefix}\n${usage}`), r?.name), {
+            room_id: roomId,
+            address,
+            ...(nameStructured === undefined ? {} : { name: nameStructured }),
+            ...(scopeStructured === undefined ? {} : { scope: scopeStructured }),
+            ...(typeof r?.already_member === "boolean"
+                ? { already_member: r.already_member }
+                : {}),
+            next_steps: nextStepsStructured,
+        });
+    });
+    // --- Tool: memory_list_rooms ---
+    // OUTPUT SCHEMA (S9, structured-output plan): `room_id`/`name`/`address`/
+    // `role`/`scope`/`archived` copied from the connector's `roomListOutput`
+    // (mnemoverse-mcp-remote, src/tools/index.ts), field for field and
+    // description for description.
+    //
+    // OD-14 (owner, 2026-09-23, S9-1): `name` is OPTIONAL here though the
+    // connector's own schema marks it a REQUIRED z.string(); so is `scope`, for
+    // the reason OD-13 gave on memory_join_room: the text already has a
+    // supported, non-degraded state for a membership whose write access core
+    // did not report ("this membership's write access was not reported"), and
+    // a required field would turn that state into an SDK "Output validation
+    // error" (review round 2). `structuredText`
+    // (src/names.ts) returns undefined for a genuinely empty or absent name, a
+    // real, already-tested case ("keeps '(unnamed room)' for a genuinely absent
+    // or empty name", test/handlers.test.ts), and forcing that through a
+    // REQUIRED field would make the SDK reject the WHOLE reply with "Output
+    // validation error" on an unnamed room, which is a supported, non-error
+    // outcome, not a malformed response. The alternative, falling back to the
+    // literal empty string, was rejected: the text would keep saying
+    // "(unnamed room)" while the data silently said `name: ""`, the same
+    // text/data lie the anti-fabrication rule this package already applies to
+    // every other optional field exists to prevent.
+    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_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: {},
+        outputSchema: {
+            rooms: z.array(z.object({
+                room_id: z.string().describe("The room's id (room_...)."),
+                name: z.string().optional().describe("The room name."),
+                address: z
+                    .string()
+                    .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
+                role: z.string().describe("'owner' or 'member'."),
+                scope: z.string().optional().describe("'read' or 'read_write'."),
+                archived: z.boolean().describe("True if archived (owned rooms only)."),
+            })),
+        },
+        annotations: {
+            title: "List rooms",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        // The same classifier the scope notes use, for the same reason: this handler
+        // did `Array.isArray(rooms) ? rooms : []` and then asserted "You have no
+        // shared rooms yet" — a claim about the account derived from a body it could
+        // not read. It is the third consumer of this payload and the third place the
+        // substitution was made; all three now go through one function that maps an
+        // unreadable body to `unknown`, never to `none`.
+        const rooms = classifyRooms(await apiFetch("/memory/rooms"), safeInline);
+        if (rooms.state === "unknown") {
+            // 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 unreadableAnswerReply("The room list", "a list of your rooms", "you have none");
+        }
+        if (rooms.state === "none") {
+            return structured("You have no shared rooms yet. Create one with memory_create_room, " +
+                "or join one with memory_join_room using an invite code.", { rooms: [] });
+        }
+        // ARCHIVED ROOMS ARE LISTED HERE, unlike in the scope note — this tool's job
+        // is the inventory, and the `[archived]` tag says which ones cannot be read.
+        const list = rooms.rooms;
+        // Room name is OWNER-chosen — printed EXACTLY (src/names.ts), like every
+        // other room-name surface as of 0.8.1: the sanitiser listed "проект" and
+        // "план" as two "(unnamed room)" entries and quoted "Zoë" as "Zo".
+        // address/role/scope are server-shaped and keep the defensive sanitiser.
+        const lines = list.map((r) => {
+            const name = roomNamePhrase(r?.name);
+            const roomId = safeInline(r?.room_id);
+            // Always surface the canonical address: fall back to xroom:<room_id> when the server
+            // omits `address`, so the domain guidance this tool promises is never silently dropped.
+            const address = safeInline(r?.address) || (roomId ? `xroom:${roomId}` : "");
+            const role = safeInline(r?.role);
+            const scope = safeInline(r?.scope);
+            // No "use domain=..." on an archived room: core refuses EVERY read of one
+            // with a 403, for owner and member alike (see the archived-only note in
+            // 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
+                    ? ""
+                    : 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")}`;
+        // Legend after the cap: this is the one room surface long enough to
+        // actually overflow, and the legend must describe the names that
+        // SURVIVED the cut, not the ones it removed.
+        const finalText = withDomainEscapeLegend(capResult(text, "The room list was truncated — some rooms are not shown."), ...list.map((r) => r?.name));
+        // STRUCTURED rows (S9-1/S9-3, owner, 2026-09-23): room_id/address/role/
+        // scope through the SAME safeInline sanitiser the text loop above
+        // already applies (address keeps the identical xroom:<room_id>
+        // fallback), archived through Boolean(). The name is withheld from the
+        // data in exactly the cases the text withholds it: roomNamePhrase
+        // prints "(room name cannot be printed exactly)" when exactLiteral
+        // refuses the JSON literal (longer than MAX_DOMAIN_LITERAL once quoted
+        // and escaped), so the same exactLiteral check decides whether `name`
+        // is present here, and the value carried is the structuredText
+        // normalisation of the raw name (control, bidi and zero-width
+        // characters out), never a truncated prefix presented as the name
+        // (review round 2: the two caps measure different things, a JSON
+        // literal and a code-point count, so reusing the number alone did not
+        // make the surfaces agree). Absent, never fabricated as "" or
+        // "(unnamed room)", for a room with no usable name (OD-14 above).
+        // One stated exception (review round 3): a name made only of the
+        // characters structuredText removes (whitespace, control, bidi,
+        // zero-width) is printed exactly in the text, as an escaped literal
+        // with the legend, but leaves nothing to carry as a plain data value;
+        // the data omits the key rather than carry "" (which would claim the
+        // name is empty) or the raw characters (which the data surface keeps
+        // out by rule). The same exception holds for every structuredText
+        // field on this surface.
+        //
+        // Core's RoomListItemSchema sends room_id, address and role on every
+        // row; a row whose room_id or role sanitises to nothing (or whose
+        // address cannot even be rebuilt from room_id) is not core's row and
+        // is dropped from the data rather than emitted with fabricated empty
+        // strings in required fields (review round 2). `scope` is optional
+        // (OD-14 above): absent from the data when the text says the write
+        // access was not reported. The text keeps its existing per-row
+        // degrade; the drop is counted and reported once on stderr, as
+        // vault_list and memory_stats report theirs.
+        const roomsStructured = [];
+        let droppedRooms = 0;
+        for (const r of list) {
+            const roomId = safeInline(r?.room_id);
+            const address = safeInline(r?.address) || (roomId ? `xroom:${roomId}` : "");
+            const role = safeInline(r?.role);
+            const scope = safeInline(r?.scope);
+            if (!roomId || !address || !role) {
+                droppedRooms += 1;
+                continue;
+            }
+            const nameStructured = typeof r?.name === "string" && exactLiteral(r.name, MAX_DOMAIN_LITERAL)
+                ? structuredText(r.name, MAX_DOMAIN_LITERAL)
+                : undefined;
+            roomsStructured.push({
+                room_id: roomId,
+                address,
+                role,
+                ...(scope ? { scope } : {}),
+                archived: Boolean(r?.archived),
+                ...(nameStructured === undefined ? {} : { name: nameStructured }),
+            });
+        }
+        if (droppedRooms > 0) {
+            console.error(`Mnemoverse: memory_list_rooms dropped ${droppedRooms} malformed room ` +
+                `row${droppedRooms === 1 ? "" : "s"} from structuredContent.rooms ` +
+                `(room_id, address or role missing or not usable; still shown in the text).`);
+        }
+        return structured(finalText, { rooms: roomsStructured });
+    });
+    // --- Tool: vault_list ---
+    // Core's CreateSecretRequest caps (mnemoverse-core src/mnemo/api/vault_routes.py):
+    // alias max_length 200, context max_length 10,000. Concepts carry no cap
+    // of their own there; 200 is the alias cap reused for a tag, not a new
+    // number. Not in src/limits.ts because the generator covers the memory
+    // routes, not the vault ones.
+    const VAULT_ALIAS_CAP = 200;
+    const VAULT_CONTEXT_CAP = 10_000;
+    const VAULT_CONCEPT_CAP = 200;
+    // OUTPUT SCHEMA (S9, structured-output plan): `alias`/`context`/`concepts`
+    // copied from the connector's `vaultListOutput` (mnemoverse-mcp-remote,
+    // src/tools/index.ts), field for field and description for description,
+    // all three REQUIRED, matching the connector exactly (unlike
+    // memory_list_rooms's `name`, above).
+    //
+    // OD-15 (owner, 2026-09-23, S9-2): a row whose `alias` or `context` is not
+    // a usable string is SKIPPED from `secrets` in structuredContent rather
+    // than turning the whole call into `isError`. The plan's original wording
+    // (isError on one bad row) directly reversed an existing, deliberately
+    // named test, "a broken alias is one anonymous row, not a dead tool"
+    // (test/handlers.test.ts), which the owner confirmed keeping as-is: the
+    // text already substitutes "(no alias)" for that ONE row and leaves every
+    // other row and the call itself untouched, so the data follows the same
+    // rule this package applies everywhere else, a value the text withholds
+    // must be withheld from the data too. Because both fields are REQUIRED
+    // here, exactly as in the connector, there is no honest partial row to
+    // emit for one that fails either check, including a row whose `context`
+    // (or `alias`) was never sent at all (`typeof undefined` is not
+    // `"string"`): this package does not fabricate `""` for a value it does
+    // not have, the same rule OD-14 above applies to a room name. The skip is
+    // reported once per call on stderr, in this package's existing
+    // startup-diagnostic style (src/index.ts's "Mnemoverse: ..." lines,
+    // mirroring memory_stats's S7 domain-drop diagnostic), because a
+    // structured consumer reading only `structuredContent.secrets` has no
+    // other way to learn the array is shorter than the count in the text's own
+    // header line.
+    //
+    // `concepts` is a brand-new field with no text-side precedent, nothing in
+    // this tool's text renders it. Core's SecretSummary sends it on every row,
+    // so a row without it, or with a value that is not an array of strings,
+    // is treated the same as a malformed alias/context and drops the row: no
+    // `[]` is fabricated for a value core did not send, and there is no honest
+    // subset of an unshaped value to keep.
+    //
+    // Free text on this surface (alias, context, each concept) goes through
+    // structuredText with core's own caps (alias 200, context 10,000, a
+    // concept 200; vault_routes.py CreateSecretRequest), the same normalisation
+    // the room name gets: a value that normalises to nothing (empty,
+    // whitespace-only, control characters only) is not usable, and the row is
+    // dropped rather than carried as "" (review round 2). The text prints its
+    // own safeInline reading of alias and context unchanged.
+    server.registerTool("vault_list", {
+        description: `List the secrets stored in your Mnemoverse Vault — by ALIAS and purpose only; the secret VALUE is never returned or shown to you, and no tool on ${serverNoun} returns it. Use this to check WHICH secrets the user has stored and under what alias (e.g. the user says 'do I have a GitHub token saved?'). Only YOUR account's secrets are listed.`,
+        inputSchema: {},
+        outputSchema: {
+            secrets: z.array(z.object({
+                alias: z
+                    .string()
+                    .describe("The secret's alias — the reference you use, never the value."),
+                context: z.string().describe("The secret's purpose/context — never the value."),
+                concepts: z.array(z.string()).describe("Concept tags."),
+            })),
+        },
+        annotations: {
+            title: "List vault secrets",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const r = await apiFetch("/vault/secrets");
+        // A 200 missing the `secrets` array used to print "No secrets are stored
+        // in your Vault yet." — an absence claim about the Vault derived from a
+        // body this client could not read. The family fix (classifyRooms, the
+        // domains guard) had stopped one tool short of here (truth F13,
+        // 2026-08-08). A genuinely empty array keeps the absence claim below.
+        const list = r?.secrets;
+        if (!Array.isArray(list)) {
+            return unreadableAnswerReply("The secret list", "a list of your Vault secrets", "none are stored");
+        }
+        if (list.length === 0) {
+            return structured("No secrets are stored in your Vault yet.", { secrets: [] });
+        }
+        const lines = list.map((s) => {
+            const alias = safeInline(s?.alias) || "(no alias)";
+            const context = safeInline(s?.context);
+            return context ? `- ${alias} — ${context}` : `- ${alias}`;
+        });
+        const text = `Your Vault secrets (${list.length}) — alias and purpose only, never the value:\n` +
+            lines.join("\n");
+        const finalText = capResult(text, "The secret list was truncated — some secrets are not shown.");
+        // STRUCTURED rows (S9-2, owner, 2026-09-23; see the OD-15 comment
+        // above): core's SecretSummary sends alias, context and concepts on
+        // every row, so a row is kept only when alias and context are strings
+        // and concepts is an array of strings; a row missing any of the three,
+        // or carrying one in another shape, is not core's row and is dropped
+        // from the data, never defaulted (no "" for a context, no [] for
+        // concepts). The call itself stands; the drop is counted and reported
+        // once on stderr.
+        const secretsStructured = [];
+        let droppedSecrets = 0;
+        for (const s of list) {
+            const alias = structuredText(s?.alias, VAULT_ALIAS_CAP);
+            const context = structuredText(s?.context, VAULT_CONTEXT_CAP);
+            const conceptsRaw = s?.concepts;
+            const concepts = Array.isArray(conceptsRaw)
+                ? conceptsRaw.map((c) => structuredText(c, VAULT_CONCEPT_CAP))
+                : undefined;
+            const conceptsOk = concepts !== undefined && concepts.every((c) => c !== undefined);
+            if (alias === undefined || context === undefined || !conceptsOk) {
+                droppedSecrets += 1;
+                continue;
+            }
+            secretsStructured.push({ alias, context, concepts: concepts });
+        }
+        if (droppedSecrets > 0) {
+            console.error(`Mnemoverse: vault_list dropped ${droppedSecrets} malformed secret ` +
+                `row${droppedSecrets === 1 ? "" : "s"} from structuredContent.secrets ` +
+                `(alias, context or concepts missing, empty or not in core's shape; ` +
+                `still shown in the text).`);
+        }
+        return structured(finalText, { secrets: secretsStructured });
+    });
+}
+//# sourceMappingURL=tools.js.map