@mnemoverse/mcp-memory-server 0.8.4 → 0.9.1

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.
 
@@ -203,8 +203,6 @@ If it doesn't remember: check that the client was fully restarted and the config
 | `memory_list_recent` | List newest memories first — no query; `since`/`until` bounds (inclusive) + cursor paging |
 | `memory_feedback` | Rate memories as helpful or not (improves future recall) |
 | `memory_stats` | Check how many memories stored, which domains exist |
-| `memory_delete` | Permanently delete a single memory by `atom_id` |
-| `memory_delete_domain` | Wipe an entire domain (requires `confirm: true` safety interlock) |
 | `memory_create_room` | Create a shared memory room; its address works as a `domain` on write/read |
 | `memory_invite_to_room` | Mint a one-time invite (code + link) for a room you own |
 | `memory_join_room` | Join a shared room with an invite code (`mnvr_...`) |
@@ -277,7 +275,6 @@ What each tool sends:
 | `memory_read` | the `query`, plus any filters: `domain`, `since`/`until`, `exclude_author`, `top_k`, `order_by` |
 | `memory_list_recent` | the feed filters: `domain`, `since`/`until`, `exclude_author`, `limit`, `cursor` |
 | `memory_feedback` | the `atom_ids` being rated and the `outcome` score |
-| `memory_delete` / `memory_delete_domain` | the `atom_id` / `domain` being deleted |
 | `memory_create_room` | the room `name` and `description` |
 | `memory_invite_to_room` | the `room_id`, invite `scope`, and expiry |
 | `memory_join_room` | the invite `code` |
@@ -288,7 +285,7 @@ One thing goes out that you did not explicitly request: since 0.8.1, when a sear
 | | |
 |---|---|
 | **Privacy Policy** | <https://mnemoverse.com/privacy> |
-| **Retention & deletion** | delete one memory with `memory_delete`, or an entire namespace with `memory_delete_domain` |
+| **Retention & deletion** | correct a wrong or stale memory by writing a fresh one; deletion is an administrative operation on the REST API, not exposed through this MCP server |
 | **Contact** | hello@mnemoverse.com |
 
 ## License

package/dist/errors.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function explainNetworkFailure(method: string, path: string, cause: unknown): string;
+/** {@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;
+}