@mnemoverse/mcp-memory-server 0.9.0 → 0.10.0

package/README.md

@@ -7,7 +7,7 @@
 [![Research: SLoD arXiv](https://img.shields.io/badge/Research-arXiv%3A2603.08965-b31b1b)](https://arxiv.org/abs/2603.08965)
 [![Glama quality](https://glama.ai/mcp/servers/mnemoverse/mcp-memory-server/badges/score.svg)](https://glama.ai/mcp/servers/mnemoverse/mcp-memory-server)
 
-Hosted memory for AI agents that learns which facts matter. Feedback reranks recall — a Rescorla-Wagner update on the prediction error, not a similarity score — so what helped rises and what misled sinks, and recall favors recent memories (an exponential recency boost with a ~30-day half-life). The engine also ships consolidation (HDBSCAN clustering, with Von Restorff protection so distinctive memories survive compression). One API key works across Claude, Cursor, VS Code, ChatGPT, and any MCP client.
+Hosted memory for AI agents that learns which facts matter. Feedback re-ranks recall — a Rescorla-Wagner update on the prediction error, not a similarity score — so what helped rises and what misled sinks, with a bounded recency tie-breaker for fresh memories. The engine also ships consolidation (HDBSCAN clustering, with Von Restorff protection so distinctive memories survive compression). One API key works across Claude, Cursor, VS Code, ChatGPT, and any MCP client.
 
 Memory that persists across sessions, projects, and tools — and improves with use. Hosted, so there's no infrastructure to run, and not locked to a single cloud.
 

package/dist/errors.d.ts

@@ -0,0 +1,235 @@
+/**
+ * What a failed API call TELLS THE AGENT TO DO.
+ *
+ * WHY THIS MODULE EXISTS. Until now every non-2xx became one sentence:
+ *
+ *     Mnemoverse API error 401: {"code":"UNAUTHORIZED","message":"Invalid or
+ *     revoked API key.","requestId":null,"retryable":false,"details":null}
+ *
+ * The `isError` flag and the status code were right; the TEXT was a raw echo of
+ * a wire body. Verified against production with a real `tools/call`
+ * (2026-08-16): with a bad key, `memory_write` returns exactly that. The reader
+ * of a tool result is a MODEL, and that string gives a model nothing to act on,
+ * so the two things it actually does are relay "error 401" to the user or guess
+ * — and the cheapest guess is "the network is down", which sends the user to
+ * debug a working network while a placeholder key sits in their config.
+ *
+ * Every message here therefore answers three questions in order: what happened,
+ * WHOSE problem it is, and what to do next — including, explicitly, whether to
+ * retry. "Do not retry" is not decoration: an agent that loops on a 429 turns
+ * one rate-limit into a sustained one, and an agent that loops on a 401 burns a
+ * conversation on a key that will never start working.
+ *
+ * THE RAW BODY IS NEVER DROPPED. It is appended after the guidance, still
+ * carrying the literal `Mnemoverse API error <status>` that this repo's tests
+ * and anyone's grep already look for. Making the text kind to an agent must not
+ * make it useless to a human debugging at 3am.
+ *
+ * WHAT THE STATUS CODES ACTUALLY MEAN HERE, verified by reading the engine
+ * (mnemoverse-core `src/mnemo/api/`, 2026-08-16) rather than assumed from HTTP
+ * folklore. The distinctions below are the entire point of this file:
+ *
+ *   401  auth.py — "Invalid or revoked API key." / "Missing API key." The key.
+ *   403  routes.py, rooms_routes.py, auth.py — "Room is archived", "Not an
+ *        active member of this room", "Read-only membership cannot write to
+ *        this room", "Invalid room address", "You do not own this room", plus
+ *        the OIDC scope rules. NOT a bad key: the caller was identified and
+ *        then refused. Telling the user to replace a working key over a 403
+ *        would be a new, more confident lie than the raw echo was.
+ *   404  A room that does not exist for this key — or, when the body says
+ *        nothing at all, a path the deployment does not serve. A DOMAIN never
+ *        404s: an empty domain reads as empty, so "your domain is missing" is
+ *        the wrong guess and is named as wrong below.
+ *   429  THREE different causes with opposite advice. rate_limit.py returns
+ *        `retryable: true` with a `Retry-After` header (waiting works);
+ *        usage.py (daily quota) and subscription_guard.py (atom limit, payment
+ *        past due) return `retryable: false` (waiting does NOT work — the
+ *        account needs an upgrade or a new day). A blanket "wait and retry"
+ *        would be wrong for two of the three.
+ *   5xx  auth.py returns 503 `retryable: true` when its DB pool is gone. Ours,
+ *        not theirs.
+ *
+ * A 2xx CAN FAIL TOO, and gets the same treatment for the same reason. A reply
+ * whose body this client cannot parse is not a status at all, so none of the
+ * sentences above fit it — and it used to borrow the TRANSPORT sentence, which
+ * asserts that nothing answered. `explainUnreadableBody` at the bottom of this
+ * file owns that case now; the distinction it protects is "a reply arrived and
+ * was unreadable" versus "no reply arrived", which have opposite fixes.
+ *
+ * RELATION TO THE STARTUP PROBE (src/index.ts, `probeApiKeyInBackground`, added
+ * in 0.8.4). That probe treats 401 and 403 alike, and is right to: it calls
+ * `GET /memory/stats`, which addresses no room, so a 403 there can only come
+ * from the auth layer. On a TOOL CALL the same status usually comes from a room
+ * the caller named, which is why the two surfaces diverge on 403 and must not be
+ * "unified" by a later reader. They agree where it matters: same `Mnemoverse:`
+ * opener, same `MNEMOVERSE_API_KEY` variable name, same console origin.
+ */
+/** Everything known about one failed call, at the moment it failed. */
+export interface ApiFailure {
+    /** HTTP status. */
+    status: number;
+    /** Response body, verbatim and unparsed. */
+    body: string;
+    /** Uppercase HTTP verb. */
+    method: string;
+    /** Path below the API base, e.g. "/memory/write". Deliberately NOT the full
+     *  URL: the base can carry credentials, and the path alone is what identifies
+     *  the operation. */
+    path: string;
+    /** `Retry-After` header when the response carried one. */
+    retryAfter?: string | null;
+}
+/**
+ * The engine's error envelope, as much of it as survived parsing.
+ *
+ * Every field is optional because a non-2xx does not have to come from the
+ * engine at all: a proxy, a tunnel, or a wrong `MNEMOVERSE_API_URL` answers with
+ * HTML, plain text or nothing. A missing field means "the body did not say",
+ * never a default — inventing `retryable: false` for an unparseable body would
+ * put a retry decision on evidence that does not exist.
+ */
+export interface ErrorEnvelope {
+    code?: string;
+    message?: string;
+    retryable?: boolean;
+}
+/**
+ * Read the engine's envelope out of a response body.
+ *
+ * Two shapes are accepted because core produces both: its own middleware writes
+ * `{code, message, retryable, details}` at the top level, while anything raised
+ * as a FastAPI `HTTPException` arrives wrapped as `{"detail": …}` — where the
+ * detail is sometimes a string and sometimes the envelope again. The feed's
+ * 404-vs-404 test in this repo pins the nested form, so both are real.
+ */
+export declare function parseErrorEnvelope(body: string): ErrorEnvelope;
+/** `Retry-After` as whole seconds, when it is a plain number. The HTTP-date
+ *  form is legal too, and is deliberately NOT parsed: an unparsed header
+ *  degrades into "wait a moment", which is honest, whereas a misparsed date
+ *  would print a confident and wrong number of seconds. */
+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.
+ *
+ * Total by construction: every status reaches a sentence, and the fallback says
+ * that it has no specific guidance instead of inventing some.
+ */
+export declare function explainApiFailure(f: ApiFailure): 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.
+ *
+ * Included even though the brief was about HTTP statuses, because it is the
+ * OTHER half of the same defect and the two are easy to confuse. The 401
+ * message above tells an agent not to blame the network; this is the case where
+ * the network genuinely IS the answer, and `TypeError: fetch failed` — which is
+ * all a model saw before — is no more actionable than the raw 401 body was.
+ *
+ * A timeout is named separately because the advice differs in one word: an
+ * unreachable host is unlikely to become reachable in three seconds, whereas a
+ * request that ran out of time may well succeed on a second try.
+ *
+ * NARROWED to `fetch()` itself rejecting. Reading the BODY of a response that
+ * did arrive used to land here too, so a 200 carrying a sign-in page printed
+ * "no HTTP response came back" — see {@link explainUnreadableBody}, which owns
+ * 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;
+/** 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. */
+export interface UnreadableBody {
+    /** HTTP status, as it actually arrived. */
+    status: number;
+    /** Uppercase HTTP verb. */
+    method: string;
+    /** Path below the API base. Never the full URL — the base can carry
+     *  credentials, and the path alone identifies the operation. */
+    path: string;
+    /** The bytes that failed to parse, when they were read at all. Absent when
+     *  the body READ itself failed, which is a different sentence below. */
+    bodyPreview?: string;
+    /** The SyntaxError, TypeError or abort that stopped the read. */
+    cause: unknown;
+}
+/**
+ * A reply ARRIVED and could not be read — which is not a dead network.
+ *
+ * WHY THIS IS SEPARATE FROM {@link explainNetworkFailure}. Both failures used
+ * to throw the same NetworkError, so `JSON.parse` choking on a 200 printed
+ * "the memory service could not be reached at all — POST /memory/read failed
+ * before any HTTP response came back… That is a connectivity or DNS problem".
+ * Against a captive portal, a MITM proxy, an SPA that serves its shell with a
+ * 200, or a body that stops mid-stream, every clause of that is false: a reply
+ * came, with a status, and the Raw detail underneath it quoted a SyntaxError
+ * out of the body it had just called nonexistent.
+ *
+ * The cost is the same one this module exists to remove — a confident wrong
+ * cause. "Connectivity or DNS" sends the user to debug working wifi while a
+ * portal or a mis-set MNEMOVERSE_API_URL answers every request with a page.
+ *
+ * WHAT THIS MESSAGE MAY CLAIM. Only what the status proves: something answered,
+ * and its answer is not this API's JSON. It does NOT name who answered — this
+ * client cannot tell the engine from a gateway in front of it — and it does NOT
+ * 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;
+/**
+ * {@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
+ * matching a sentence — the same reason {@link ApiError} carries fields.
+ */
+export declare class UnreadableBodyError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(f: UnreadableBody);
+}
+/** {@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);
+}
+/**
+ * A failed API call, as an ERROR OBJECT rather than a parsed string.
+ *
+ * The status and the body are fields because a caller that needs to branch on
+ * them must not do it by matching the message. `memory_list_recent` used to
+ * decide between "the endpoint is not deployed" and "this room does not exist"
+ * with `message.startsWith("Mnemoverse API error 404:")`, which coupled a
+ * behavioural branch to the exact prefix of a user-facing sentence — so
+ * improving the sentence, which is this change, would have silently flipped
+ * that branch. Structured fields make the wording free to change.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly method: string;
+    readonly path: string;
+    /** The engine's envelope, already parsed — so a caller never re-parses. */
+    readonly envelope: ErrorEnvelope;
+    constructor(f: ApiFailure);
+    /**
+     * 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
+     * — the first version of this predicate tested silence alone, mistook the
+     * real framework body `{"detail":"Not Found"}` for an engine answer, and
+     * un-fired the feed's degrade branch for the exact rollout case it exists
+     * for (panel, #93).
+     *
+     * NAMED FOR WHAT IT TESTS, not for what it implies: a gateway, a proxy or a
+     * wrong MNEMOVERSE_API_URL can produce the same shapes and is
+     * indistinguishable from here. Known, accepted edge: a foreign API whose
+     * 404 nests its error under a key this parser does not read
+     * (`{"error":{…}}`) also reads as bare, so the feed degrades to its
+     * not-supported notice instead of surfacing the foreign body — bounded
+     * harm, since against a wrong base URL the very next call fails with the
+     * instructive no-envelope wording.
+     */
+    get isBare404(): boolean;
+}