@mnemoverse/mcp-memory-server 0.11.0 → 0.12.0

package/README.md

@@ -325,28 +325,50 @@ saw and diff it against what the server serves today, by version.
   not have one; once declared, that schema's fields are add-only under this
   same rule. Where this server's output schema deliberately differs from the
   hosted connector's, the CHANGELOG entry says so; today that is
+  `memory_id` in every output schema, a plain string here and a
+  GUID-validated string there (this package's ids are opaque);
   `memory_list_recent`'s `next_cursor`, optional here (absent when the
   service sent a continuation token this client will not pass on) and
-  required there.
+  required there; `memory_stats`, which carries five optional fields
+  (`episodes`, `prototypes`, `hebbian_edges`, `avg_valence`,
+  `avg_importance`) the connector's schema does not declare; the room
+  tools (`memory_create_room`, `memory_invite_to_room`, `memory_join_room`,
+  `memory_list_rooms`), where several fields the connector marks required
+  are optional here (`name`, `scope`, `already_member`, and the invite's
+  `code`, `scope`, `room_address` and `expires_at`), because a value core
+  did not send is an honest outcome here rather than a placeholder; and
+  `memory_list_rooms` and `vault_list`, which drop a row with no usable
+  identity (`room_id`, `address`, `role`; `alias`, `context`) from the data,
+  reported once on stderr, instead of emitting empty strings into required
+  fields.
 - **Removing or renaming a tool or a tool's input parameter, or dropping or
   renaming a declared annotation field,** is announced one MINOR ahead: the
   tool (or parameter) stays, its description says
   `deprecated since x.y, removed in x.z`, and the change lands only in the
   announced version, with its CHANGELOG line. A renamed parameter is accepted
   under both names until then (0.11: `memory_feedback`'s `atom_ids` became
-  `memory_ids`). A rename is announced by naming
+  `memory_ids`; its removal, first announced for 0.12, lands in 0.13, since
+  0.12 shipped sooner than that announcement assumed). A rename is announced by naming
   both the old and the new name; the version pair alone does not say what a
   client should look for. Because a MINOR may add a field but not remove one, a
   renamed annotation field is declared under both names until the announced
   version.
 - Any difference between two servers of the same version is a bug. Report it
-  with both `tools/list` outputs.
+  with both `tools/list` outputs. One exception, by configuration: a server
+  built on the `/shared` entry point may ask for its own noun in the three
+  descriptions that name the server (`wording.serverNoun`, below), which
+  changes those three description strings and nothing else; tool names,
+  input and output schemas and annotations never vary by configuration.
 
-The list above is the 0.11 surface: ten tools, each declaring all four hints.
+The list above is the 0.12 surface: ten tools, each declaring all four hints.
 The hosted connector at `mcp.mnemoverse.com/mcp` serves the same ten.
 
 **If the hosted connector stops answering in a session.** A client can keep showing the connector as connected while every call in that session fails with "not connected". Reconnecting it on claude.ai does not revive a session that is already stuck; reconnect from inside the session instead (in Claude Code, `/mcp`, then sign in again). Meanwhile this local server, set up with an API key from the same account as in the Quick Start, reaches the same memory and does not depend on that session's sign-in.
 
+### Building a second MCP server on this package
+
+`@mnemoverse/mcp-memory-server/shared` is the entry point another server registers these same tools from, instead of keeping its own copy (ADR-025, mnemoverse-core). It exports `registerMemoryTools`/`registerMemoryPrompts`/`registerMemoryResources`, the three typed error classes (`ApiError`, `NetworkError`, `UnreadableBodyError`), `MAX_RESULT_CHARS`/`capResult`, and two optional dependencies a hosted deployment injects to speak in its own voice: `wording` (its own server noun and error vocabulary, including an OAuth mode under which no 401 or 403 explanation names an API key) and `writeAuthor` (vouching for the end user behind a write). See [`docs/shared.md`](./docs/shared.md) for the full contract.
+
 ## Use cases
 
 The pattern that pays off first is cross-tool continuity: a decision made while pairing in Claude Code is there when you open Cursor an hour later, and the preference you stated in VS Code holds in a ChatGPT session that evening. Teams use shared rooms the same way — one place where an agent's lessons about a codebase accumulate instead of being re-taught per seat. And because recall re-ranks from feedback, the memories that keep proving useful surface first, which matters once a store grows past what anyone curates by hand.

package/dist/errors.d.ts

@@ -76,6 +76,41 @@
  *  outright, see `validatedKeysUrl` below, but this constant stays the
  *  fallback for both). */
 export declare const KEYS_URL = "https://console.mnemoverse.com/dashboard/keys";
+/**
+ * How a server that registers these tools wants its failures worded (STEP4-2,
+ * STEP4-3, owner decisions 2026-09-24). Every field is optional, and every
+ * field's absence means exactly what this file already does today: the
+ * whole point is that a consumer supplying no `wording` at all gets
+ * byte-identical text to before this type existed.
+ *
+ *  - `serverNoun`: what the three tool descriptions that name themselves
+ *    call this deployment ("this server" vs "this connector"). Read by
+ *    src/tools.ts at registration time; ignored by this module.
+ *  - `auth`: which credential the CALLER holds, not which one core issued.
+ *    "api-key" (default) keeps every existing MNEMOVERSE_API_KEY-flavoured
+ *    sentence. "oauth" is for a server whose user never sees an API key at
+ *    all (a hosted connector minting a key on their behalf): no 401/403
+ *    explanation under this mode names MNEMOVERSE_API_KEY, an env var, an
+ *    MCP config file, or the keys console; each says what an OAuth user can
+ *    actually do instead (reconnect, sign in again, check the plan, wait
+ *    for the retry window).
+ *  - `keysUrl`: replaces {@link KEYS_URL} wherever the api-key vocabulary
+ *    prints a console URL, for a deployment whose key-management page is
+ *    not console.mnemoverse.com. Has no effect under `auth: "oauth"`, which
+ *    prints no console URL at all.
+ *  - `rawDetail`: whether the wire body's raw tail (STEP4-3; e.g. `Raw
+ *    detail — Mnemoverse API error 401 on …`) is appended after the
+ *    guidance. Defaults to `true`, unchanged from every release before this
+ *    one. Held in reserve for a deployment whose core-side error envelopes
+ *    are found to echo request content back in `details`: set to `false`
+ *    only once that check finds something to hide.
+ */
+export interface Wording {
+    serverNoun?: "this server" | "this connector";
+    auth?: "api-key" | "oauth";
+    keysUrl?: string;
+    rawDetail?: boolean;
+}
 /** Everything known about one failed call, at the moment it failed. */
 export interface ApiFailure {
     /** HTTP status. */
@@ -146,12 +181,16 @@ export declare function parseErrorEnvelope(body: string): ErrorEnvelope;
 export declare function retryAfterSeconds(header: string | null | undefined): number | undefined;
 /**
  * The agent-facing explanation for one failed call, with the raw body kept
- * after it.
+ * after it (unless `wording.rawDetail === false`, STEP4-3).
  *
  * Total by construction: every status reaches a sentence, and the fallback says
  * that it has no specific guidance instead of inventing some.
+ *
+ * `wording` (STEP4-2/3, owner 2026-09-24) is optional and, absent, resolves
+ * to exactly today's behaviour: every call site before this release passes
+ * none, so every existing pin stays byte-identical.
  */
-export declare function explainApiFailure(f: ApiFailure): string;
+export declare function explainApiFailure(f: ApiFailure, wording?: Wording): string;
 /**
  * The request never got an answer at all: DNS, connectivity, a host that does
  * not listen, or this client's own probe deadline firing.
@@ -172,7 +211,7 @@ export declare function explainApiFailure(f: ApiFailure): string;
  * that case now. Every sentence below asserts that nothing answered, so it may
  * only be reached when nothing did.
  */
-export declare function explainNetworkFailure(method: string, path: string, cause: unknown): string;
+export declare function explainNetworkFailure(method: string, path: string, cause: unknown, wording?: Wording): string;
 /** A 2xx-or-not response whose BODY this client could not turn into the JSON
  *  this API speaks. The status is known — a reply arrived — which is the whole
  *  difference between this and {@link ApiFailure} or a transport failure. */
@@ -212,7 +251,7 @@ export interface UnreadableBody {
  * say whether the operation ran, because a body it cannot read is no evidence
  * either way. That last clause matters most for a write.
  */
-export declare function explainUnreadableBody(f: UnreadableBody): string;
+export declare function explainUnreadableBody(f: UnreadableBody, wording?: Wording): string;
 /**
  * {@link explainUnreadableBody} as an error, so a caller can tell "a reply
  * arrived and was unreadable" from "no reply arrived" by TYPE rather than by
@@ -222,14 +261,25 @@ export declare class UnreadableBodyError extends Error {
     readonly status: number;
     readonly method: string;
     readonly path: string;
-    constructor(f: UnreadableBody);
+    /** The bytes that failed to parse, when they were read at all. Kept so
+     *  {@link withWording} re-renders the same arm of the explanation. */
+    readonly bodyPreview: string | undefined;
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainUnreadableBody}. */
+    constructor(f: UnreadableBody, wording?: Wording);
+    /** The same failure, explained under `wording`: see {@link ApiError.withWording}. */
+    withWording(wording: Wording | undefined): UnreadableBodyError;
 }
 /** {@link explainNetworkFailure} as an error, so `instanceof` can tell a
  *  transport failure from an HTTP one without reading either message. */
 export declare class NetworkError extends Error {
     readonly method: string;
     readonly path: string;
-    constructor(method: string, path: string, cause: unknown);
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainNetworkFailure}. */
+    constructor(method: string, path: string, cause: unknown, wording?: Wording);
+    /** The same failure, explained under `wording`: see {@link ApiError.withWording}. */
+    withWording(wording: Wording | undefined): NetworkError;
 }
 /**
  * A failed API call, as an ERROR OBJECT rather than a parsed string.
@@ -249,7 +299,22 @@ export declare class ApiError extends Error {
     readonly path: string;
     /** The engine's envelope, already parsed — so a caller never re-parses. */
     readonly envelope: ErrorEnvelope;
-    constructor(f: ApiFailure);
+    /** The `Retry-After` header as it arrived, when the response carried one.
+     *  Kept so {@link withWording} re-renders a 429 with its retry sentence. */
+    readonly retryAfter: string | null | undefined;
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainApiFailure}. */
+    constructor(f: ApiFailure, wording?: Wording);
+    /**
+     * The same failure, explained under `wording`: a new instance of this
+     * class whose message is what the constructor would have produced with
+     * that `wording`, every field and {@link isBare404} unchanged. The message
+     * is a pure function of the failure and the wording, so re-rendering an
+     * instance under the wording it was built with gives the same text back.
+     * This is how `MemoryToolDeps.wording` reaches an error the consumer's
+     * `apiFetch` built without it: see {@link rewordFailure}.
+     */
+    withWording(wording: Wording | undefined): ApiError;
     /**
      * A 404 the ENGINE did not answer: silence, or the router's literal
      * defaults. This is what a path the deployment does not serve looks like
@@ -269,3 +334,21 @@ export declare class ApiError extends Error {
      */
     get isBare404(): boolean;
 }
+/**
+ * Re-explain one of this module's three errors under `wording`; hand
+ * anything else back untouched.
+ *
+ * This is how `MemoryToolDeps.wording` reaches the error text (STEP4-2): a
+ * consumer's `apiFetch` constructs `ApiError`, `NetworkError` and
+ * `UnreadableBodyError` however it likes, and `registerMemoryTools` passes
+ * every rejection through here with the `wording` it was given, so the
+ * consumer states its wording once, on `deps`, and the constructors need no
+ * second copy. Re-rendering is idempotent (see {@link ApiError.withWording}),
+ * so an `apiFetch` that does pass the same `wording` to the constructors
+ * gets the same text either way; one that passed a different wording gets
+ * `deps.wording`, the one source of truth for this registration. A
+ * rejection that is none of the three classes (a plain `Error`, an
+ * `McpError`) is returned as is: it carries no wording to apply, and its
+ * identity may matter to whoever threw it.
+ */
+export declare function rewordFailure(e: unknown, wording: Wording | undefined): unknown;

package/dist/errors.js

@@ -89,6 +89,19 @@ const USAGE_URL = "https://console.mnemoverse.com/dashboard/usage";
  *  module is imported BY index.ts, so reading the value from there would be a
  *  cycle. Change one, grep for the other. */
 const DEFAULT_API_URL = "https://core.mnemoverse.com/api/v1";
+/** Defaults applied field-by-field, with a `typeof`/literal guard on each:
+ *  `wording` crosses a public package boundary a caller controls only at
+ *  compile time, so a malformed value at runtime degrades to the default
+ *  instead of propagating (e.g. into a template literal, or a `Wording`
+ *  field silently taking a fifth value no branch here checks for). */
+function resolveWording(w) {
+    return {
+        serverNoun: w?.serverNoun === "this connector" ? "this connector" : "this server",
+        auth: w?.auth === "oauth" ? "oauth" : "api-key",
+        keysUrl: typeof w?.keysUrl === "string" && w.keysUrl !== "" ? w.keysUrl : KEYS_URL,
+        rawDetail: typeof w?.rawDetail === "boolean" ? w.rawDetail : true,
+    };
+}
 /**
  * Is `details.keys_url` safe to put in front of a user?
  *
@@ -232,16 +245,42 @@ function has(message, needle) {
  * "caller org not identified" for the same reason that clause runs first at
  * all (a valid key must never be told to replace itself), and still before
  * the substring guess, since a named reason needs no guessing.
+ *
+ * UNDER `wording.auth === "oauth"` (STEP4-2, owner, 2026-09-24) none of the
+ * above applies: the caller never held an API key at all, so `reason` (a
+ * diagnosis of WHICH key problem this is) and every key-flavoured branch
+ * below would be a wrong cause stated confidently. "Caller org not
+ * identified" is the one exception: it is about tenant identification, not
+ * about a key, and can fire under either credential type, so it is checked
+ * first regardless of `auth`, worded for whichever credential the caller
+ * actually holds. Every other 401 collapses to one OAuth-flavoured sentence:
+ * reconnect or sign in again, because that is the one thing an OAuth user
+ * can actually do about a 401, and naming a wrong one of five key reasons
+ * would be worse than naming none.
  */
-function explain401(env) {
+function explain401(env, wording) {
     const m = env.message;
     if (has(m, "caller org not identified")) {
-        return ("Mnemoverse: this deployment could not identify a tenant account for " +
-            "this request (401). The API key itself was not rejected — do NOT " +
-            "tell the user to replace it. Room and shared-memory operations need " +
-            "the multi-tenant backend, which a self-hosted or static-auth " +
-            "deployment does not have. Quote the detail below, and do not retry " +
-            "the same call against this deployment.");
+        return wording.auth === "oauth"
+            ? "Mnemoverse: this deployment could not identify a tenant account for " +
+                "this request (401). The caller's sign-in itself was not rejected " +
+                "— do NOT tell the user to reconnect over this. Room and " +
+                "shared-memory operations need the multi-tenant backend, which a " +
+                "self-hosted or static-auth deployment does not have. Quote the " +
+                "detail below, and do not retry the same call against this " +
+                "deployment."
+            : "Mnemoverse: this deployment could not identify a tenant account for " +
+                "this request (401). The API key itself was not rejected — do NOT " +
+                "tell the user to replace it. Room and shared-memory operations need " +
+                "the multi-tenant backend, which a self-hosted or static-auth " +
+                "deployment does not have. Quote the detail below, and do not retry " +
+                "the same call against this deployment.";
+    }
+    if (wording.auth === "oauth") {
+        return ("Mnemoverse: the user's sign-in was rejected (401). There is no " +
+            "credential for them to edit — tell them to disconnect and " +
+            "reconnect the app, or sign in again, to refresh their session. Do " +
+            "not retry until they do.");
     }
     // `details.reason` (an engine change not yet released as of this
     // one): the engine's own diagnosis of WHICH key problem this is, five
@@ -254,7 +293,7 @@ function explain401(env) {
     // for byte: `reason` is additive, never a replacement for a message this
     // parser cannot yet interpret.
     if (env.reason !== undefined) {
-        const keysUrl = env.keysUrl ?? KEYS_URL;
+        const keysUrl = env.keysUrl ?? wording.keysUrl;
         switch (env.reason) {
             case "placeholder_key":
                 return ("Mnemoverse: your API key was rejected (401). The engine itself " +
@@ -309,7 +348,7 @@ function explain401(env) {
             "MNEMOVERSE_API_KEY is not valid — if it still reads a docs " +
             'placeholder such as "mk_live_YOUR_KEY" or "mk_live_USER_KEY" (any ' +
             "value they did not create at the console themselves) it must be " +
-            `replaced with a real key from ${KEYS_URL}. Do not retry until they ` +
+            `replaced with a real key from ${wording.keysUrl}. Do not retry until they ` +
             "replace it.");
     }
     if (m !== undefined || env.code !== undefined) {
@@ -326,33 +365,48 @@ function explain401(env) {
         "client cannot tell WHO refused. Quote the detail below and check the " +
         "path to the API first.");
 }
-/** 403: when the ENGINE refused, the key was accepted and then the request
- *  was refused — name WHICH refusal, from the engine's own message, and never
- *  blame the key. But that first clause is only known when the engine actually
- *  spoke: a proxy, a WAF or a tunnel also answers 403, in HTML, and asserting
- *  "the key identified the account fine" about a response the engine may never
- *  have seen is exactly the confident wrong cause this module exists to avoid. */
-function explain403(env) {
+/** 403: when the ENGINE refused, the credential was accepted and then the
+ *  request was refused — name WHICH refusal, from the engine's own message,
+ *  and never blame the credential. But that first clause is only known when
+ *  the engine actually spoke: a proxy, a WAF or a tunnel also answers 403, in
+ *  HTML, and asserting "the credential identified the account fine" about a
+ *  response the engine may never have seen is exactly the confident wrong
+ *  cause this module exists to avoid.
+ *
+ *  Under `wording.auth === "oauth"` every noun for the credential changes
+ *  and nothing else does: the clause naming it as innocent ("The API key" /
+ *  "Your sign-in"), the holder the room-permission causes speak about ("This
+ *  key" / "This account", since an OAuth user holds no key and membership is
+ *  the account's), and the one word the opaque-403 branch declines to blame
+ *  ("the key" / "the sign-in"). Review round 2 on the wording slice: the
+ *  first cut changed only the innocent clause and left "This key is not an
+ *  active member" in the same sentence that had just told an OAuth user
+ *  their sign-in was fine. */
+function explain403(env, wording) {
+    const oauth = wording.auth === "oauth";
     if (saidNothing(env)) {
+        const blamed = oauth ? "the sign-in" : "the key";
         return ("Mnemoverse: this request was refused (403) by something that did not " +
             "speak this API's error language — the body carries neither of the two " +
             "shapes the engine produces. That points at a proxy, a gateway, or a " +
             "MNEMOVERSE_API_URL aimed somewhere unexpected, and the engine may never " +
-            "have seen the request — so do not blame the key and do not blame room " +
+            `have seen the request — so do not blame ${blamed} and do not blame room ` +
             "permissions: this client cannot tell WHO refused it. Quote the detail " +
             "below to the user, and do not retry until the path to the API is explained.");
     }
+    const holder = oauth ? "This account" : "This key";
+    const holderLc = oauth ? "this account" : "this key";
     const m = env.message;
     const cause = has(m, "archiv")
         ? "The room you addressed is archived. An archived room refuses every read " +
             "and every write, for its owner as much as for a member, and this client " +
             "has no operation that reopens one."
         : has(m, "not an active member") || has(m, "member of this room")
-            ? "This key is not an active member of the room you addressed. Ask the " +
+            ? `${holder} is not an active member of the room you addressed. Ask the ` +
                 "room's owner for an invite; memory_list_rooms shows the rooms it can " +
                 "already reach."
             : has(m, "read-only")
-                ? "This key's membership in that room is read-only — it can read the " +
+                ? `${holder}'s membership in that room is read-only — it can read the ` +
                     "room but not write to it. Ask the room's owner for write access."
                 : has(m, "invalid room address")
                     ? 'The room address was not in the form the engine accepts ' +
@@ -360,12 +414,13 @@ function explain403(env) {
                         "rather than composing one."
                     : has(m, "own this room")
                         ? "That room belongs to another account, and only its owner can do " +
-                            "this. memory_list_rooms shows which rooms this key owns."
-                        : "Something about this request is not permitted for this key — " +
+                            `this. memory_list_rooms shows which rooms ${holderLc} owns.`
+                        : `Something about this request is not permitted for ${holderLc} — ` +
                             "most often the room it addressed. Check memory_list_rooms, and " +
                             "if nothing there explains it, tell the user exactly what was " +
                             "refused instead of guessing.";
-    return ("Mnemoverse: this request was refused (403). The API key is NOT the problem " +
+    const subject = oauth ? "Your sign-in" : "The API key";
+    return (`Mnemoverse: this request was refused (403). ${subject} is NOT the problem ` +
         "— it identified the account fine, and this was a permission decision. " +
         `${cause} Do not retry the same call: it will be refused again.`);
 }
@@ -444,15 +499,20 @@ function explain404(f, env) {
 }
 /** 429: three causes, opposite advice. The envelope's `retryable` is the
  *  discriminator, because it is the only thing the engine states outright. */
-function explain429(f, env) {
+function explain429(f, env, wording) {
     const secs = retryAfterSeconds(f.retryAfter);
     const wait = secs === undefined ? "about a minute" : `${secs} seconds`;
     if (env.retryable === true) {
+        // The one 429 sentence that names the credential holder (Sigma, review
+        // round 2 on the wording slice): "this key" for an API-key caller, "this
+        // account" for an OAuth user who holds no key. The other two branches
+        // speak about the account and the plan already.
+        const holder = wording.auth === "oauth" ? "this account" : "this key";
         return ("Mnemoverse: rate-limited (429). This is the per-minute request limit and " +
             `it clears by itself. Wait ${wait}, then make AT MOST ONE more attempt — ` +
             "do not retry in a loop and do not fan out into more calls, which is what " +
             "turns a one-minute limit into a sustained one. If the retry also fails, " +
-            "stop and tell the user this key is hitting its rate limit.");
+            `stop and tell the user ${holder} is hitting its rate limit.`);
     }
     if (env.retryable === false) {
         return ("Mnemoverse: refused for quota, not for speed (429). Waiting will NOT " +
@@ -467,25 +527,30 @@ function explain429(f, env) {
 }
 /**
  * The agent-facing explanation for one failed call, with the raw body kept
- * after it.
+ * after it (unless `wording.rawDetail === false`, STEP4-3).
  *
  * Total by construction: every status reaches a sentence, and the fallback says
  * that it has no specific guidance instead of inventing some.
+ *
+ * `wording` (STEP4-2/3, owner 2026-09-24) is optional and, absent, resolves
+ * to exactly today's behaviour: every call site before this release passes
+ * none, so every existing pin stays byte-identical.
  */
-export function explainApiFailure(f) {
+export function explainApiFailure(f, wording) {
+    const resolved = resolveWording(wording);
     const env = parseErrorEnvelope(f.body);
     let guidance;
     if (f.status === 401) {
-        guidance = explain401(env);
+        guidance = explain401(env, resolved);
     }
     else if (f.status === 403) {
-        guidance = explain403(env);
+        guidance = explain403(env, resolved);
     }
     else if (f.status === 404) {
         guidance = explain404(f, env);
     }
     else if (f.status === 429) {
-        guidance = explain429(f, env);
+        guidance = explain429(f, env, resolved);
     }
     else if (f.status === 400 || f.status === 422) {
         guidance =
@@ -511,7 +576,7 @@ export function explainApiFailure(f) {
                 "specific guidance for that status. Do not invent a cause for the user — " +
                 "quote the detail below. One retry is acceptable; a loop is not.";
     }
-    return `${guidance}\n\n${rawDetail(f)}`;
+    return resolved.rawDetail ? `${guidance}\n\n${rawDetail(f)}` : guidance;
 }
 /**
  * A server-controlled string, made safe to quote inside model-facing text.
@@ -594,12 +659,13 @@ function refusedRedirect(cause) {
  * that case now. Every sentence below asserts that nothing answered, so it may
  * only be reached when nothing did.
  */
-export function explainNetworkFailure(method, path, cause) {
+export function explainNetworkFailure(method, path, cause, wording) {
+    const resolved = resolveWording(wording);
     const name = cause instanceof Error ? cause.name : "";
     const timedOut = name === "TimeoutError" || name === "AbortError";
     const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
     if (refusedRedirect(cause)) {
-        return (`Mnemoverse: ${method} ${path} was answered with a REDIRECT, and this ` +
+        const head = `Mnemoverse: ${method} ${path} was answered with a REDIRECT, and this ` +
             "client refused to follow it — so the API key was never sent to whatever " +
             "the redirect pointed at. That refusal is the whole point: following a " +
             "redirect re-sends the request headers to the new host, which hands a " +
@@ -610,7 +676,10 @@ export function explainNetworkFailure(method, path, cause) {
             "network: the request arrived somewhere and was answered. Tell the user " +
             "to check MNEMOVERSE_API_URL and point it straight at the API (the " +
             `default is ${DEFAULT_API_URL}). Do not retry: the same address will ` +
-            `redirect again.\n\n${rawTransportDetail(method, path, detail)}`);
+            "redirect again.";
+        return resolved.rawDetail
+            ? `${head}\n\n${rawTransportDetail(method, path, detail)}`
+            : head;
     }
     const head = timedOut
         ? `Mnemoverse: the memory service did not answer ${method} ${path} in time.`
@@ -620,11 +689,11 @@ export function explainNetworkFailure(method, path, cause) {
         ? "The service may just be slow right now."
         : "That is a connectivity or DNS problem, or MNEMOVERSE_API_URL pointing at " +
             "a host that does not answer.";
-    return (`${head} ${cause_} This is NOT a rejected API key and NOT a quota — no ` +
+    const body = `${head} ${cause_} This is NOT a rejected API key and NOT a quota — no ` +
         "reply arrived to say anything about either, so do not send the user to " +
         "check their key. One retry is reasonable. If that also fails, tell the " +
-        "user memory is unreachable and carry on without it rather than retrying.\n\n" +
-        rawTransportDetail(method, path, detail));
+        "user memory is unreachable and carry on without it rather than retrying.";
+    return resolved.rawDetail ? `${body}\n\n${rawTransportDetail(method, path, detail)}` : body;
 }
 /** The debugging half of a transport failure, in one place so the redirect
  *  branch and the generic one cannot drift into two spellings of it. */
@@ -657,7 +726,8 @@ const MAX_PREVIEW_CHARS = 200;
  * say whether the operation ran, because a body it cannot read is no evidence
  * either way. That last clause matters most for a write.
  */
-export function explainUnreadableBody(f) {
+export function explainUnreadableBody(f, wording) {
+    const resolved = resolveWording(wording);
     // TWO ARMS, because the two failures have different causes and the wrong one
     // is a wrong instruction. A body that PARSED WRONG is a foreign answer — a
     // portal, a proxy, a base URL aimed elsewhere. A body that stopped ARRIVING
@@ -680,10 +750,11 @@ export function explainUnreadableBody(f) {
             `nothing about the user's key. One retry is reasonable; if it ` +
             `repeats, tell the user the reply is arriving incomplete and quote ` +
             `the detail below, status included.`;
-    return (`Mnemoverse: something answered HTTP ${f.status} for ${f.method} ` +
+    const head = `Mnemoverse: something answered HTTP ${f.status} for ${f.method} ` +
         `${f.path}, but ${body} Whether the operation itself ran is unknown ` +
         `either way — if this was a write, treat it as neither saved nor ` +
-        `refused.\n\n${rawUnreadableDetail(f)}`);
+        "refused.";
+    return resolved.rawDetail ? `${head}\n\n${rawUnreadableDetail(f)}` : head;
 }
 /** The debugging half for an unreadable body: what stopped the read, and the
  *  first bytes of what arrived — through the same inert filter as
@@ -708,12 +779,25 @@ export class UnreadableBodyError extends Error {
     status;
     method;
     path;
-    constructor(f) {
-        super(explainUnreadableBody(f), { cause: f.cause });
+    /** The bytes that failed to parse, when they were read at all. Kept so
+     *  {@link withWording} re-renders the same arm of the explanation. */
+    bodyPreview;
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainUnreadableBody}. */
+    constructor(f, wording) {
+        super(explainUnreadableBody(f, wording), { cause: f.cause });
         this.name = "UnreadableBodyError";
         this.status = f.status;
         this.method = f.method;
         this.path = f.path;
+        this.bodyPreview = f.bodyPreview;
+    }
+    /** The same failure, explained under `wording`: see {@link ApiError.withWording}. */
+    withWording(wording) {
+        const f = { status: this.status, method: this.method, path: this.path, cause: this.cause };
+        if (this.bodyPreview !== undefined)
+            f.bodyPreview = this.bodyPreview;
+        return new UnreadableBodyError(f, wording);
     }
 }
 /**
@@ -744,12 +828,18 @@ function explain409(f) {
 export class NetworkError extends Error {
     method;
     path;
-    constructor(method, path, cause) {
-        super(explainNetworkFailure(method, path, cause), { cause });
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainNetworkFailure}. */
+    constructor(method, path, cause, wording) {
+        super(explainNetworkFailure(method, path, cause, wording), { cause });
         this.name = "NetworkError";
         this.method = method;
         this.path = path;
     }
+    /** The same failure, explained under `wording`: see {@link ApiError.withWording}. */
+    withWording(wording) {
+        return new NetworkError(this.method, this.path, this.cause, wording);
+    }
 }
 /**
  * A failed API call, as an ERROR OBJECT rather than a parsed string.
@@ -769,15 +859,36 @@ export class ApiError extends Error {
     path;
     /** The engine's envelope, already parsed — so a caller never re-parses. */
     envelope;
-    constructor(f) {
-        super(explainApiFailure(f));
+    /** The `Retry-After` header as it arrived, when the response carried one.
+     *  Kept so {@link withWording} re-renders a 429 with its retry sentence. */
+    retryAfter;
+    /** `wording` (STEP4-2/3): optional, and absent (every call site before this
+     *  release) reproduces today's message exactly: see {@link explainApiFailure}. */
+    constructor(f, wording) {
+        super(explainApiFailure(f, wording));
         this.name = "ApiError";
         this.status = f.status;
         this.body = f.body;
         this.method = f.method;
         this.path = f.path;
+        this.retryAfter = f.retryAfter;
         this.envelope = parseErrorEnvelope(f.body);
     }
+    /**
+     * The same failure, explained under `wording`: a new instance of this
+     * class whose message is what the constructor would have produced with
+     * that `wording`, every field and {@link isBare404} unchanged. The message
+     * is a pure function of the failure and the wording, so re-rendering an
+     * instance under the wording it was built with gives the same text back.
+     * This is how `MemoryToolDeps.wording` reaches an error the consumer's
+     * `apiFetch` built without it: see {@link rewordFailure}.
+     */
+    withWording(wording) {
+        const f = { status: this.status, body: this.body, method: this.method, path: this.path };
+        if (this.retryAfter !== undefined)
+            f.retryAfter = this.retryAfter;
+        return new ApiError(f, wording);
+    }
     /**
      * A 404 the ENGINE did not answer: silence, or the router's literal
      * defaults. This is what a path the deployment does not serve looks like
@@ -799,4 +910,27 @@ export class ApiError extends Error {
         return this.status === 404 && engineSilentOn404(this.envelope);
     }
 }
+/**
+ * Re-explain one of this module's three errors under `wording`; hand
+ * anything else back untouched.
+ *
+ * This is how `MemoryToolDeps.wording` reaches the error text (STEP4-2): a
+ * consumer's `apiFetch` constructs `ApiError`, `NetworkError` and
+ * `UnreadableBodyError` however it likes, and `registerMemoryTools` passes
+ * every rejection through here with the `wording` it was given, so the
+ * consumer states its wording once, on `deps`, and the constructors need no
+ * second copy. Re-rendering is idempotent (see {@link ApiError.withWording}),
+ * so an `apiFetch` that does pass the same `wording` to the constructors
+ * gets the same text either way; one that passed a different wording gets
+ * `deps.wording`, the one source of truth for this registration. A
+ * rejection that is none of the three classes (a plain `Error`, an
+ * `McpError`) is returned as is: it carries no wording to apply, and its
+ * identity may matter to whoever threw it.
+ */
+export function rewordFailure(e, wording) {
+    if (e instanceof ApiError || e instanceof NetworkError || e instanceof UnreadableBodyError) {
+        return e.withWording(wording);
+    }
+    return e;
+}
 //# sourceMappingURL=errors.js.map