@mnemoverse/mcp-memory-server 0.11.0 → 0.12.1

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;