@mnemoverse/mcp-memory-server 0.10.2 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Mnemoverse Memory
 
-**Persistent memory for AI agents over MCP.** Tell it a recalled memory helped or misled, and it re-ranks what comes back next. One key across Claude Code, Cursor, VS Code and ChatGPT.
+**Persistent memory for AI agents over MCP.** Tell it a recalled memory helped or misled, and it re-ranks what comes back next. Shared rooms let several agents work from one memory. One key or OAuth across Claude Code, Cursor, VS Code and ChatGPT.
 
 `@mnemoverse/mcp-memory-server` is the MIT-licensed MCP server for the hosted Mnemoverse memory engine.
 
@@ -13,13 +13,13 @@
 
 ## What is Mnemoverse Memory?
 
-Mnemoverse is a hosted memory engine for AI agents, reached over the Model Context Protocol. Mnemoverse stores what your agents learn — decisions, preferences, lessons — and returns it in any connected tool, so one memory follows you across Claude Code, Cursor, VS Code and ChatGPT with a single API key. Mnemoverse re-ranks recall from outcomes: report that a recalled memory helped and a Rescorla-Wagner update on the prediction error raises it, report that it misled and it sinks — a different mechanism from similarity scoring, usable alongside it.
+Mnemoverse is a hosted memory engine for AI agents, reached over the Model Context Protocol. Mnemoverse stores what your agents learn — decisions, preferences, lessons — and returns it in any connected tool, so one memory follows you across Claude Code, Cursor, VS Code and ChatGPT with one account: an API key in a local config, or an OAuth sign-in on the hosted endpoint. Mnemoverse re-ranks recall from outcomes: report that a recalled memory helped and a Rescorla-Wagner update on the prediction error raises it, report that it misled and it sinks — a different mechanism from similarity scoring, usable alongside it.
 
-**What is open source here, and what is not.** This repository, the MCP server, is MIT, and so is the Python SDK. The memory engine they talk to is a hosted service with a free tier; there is no self-hosted build of the engine.
+**What is open source here, and what is not.** This repository, the MCP server, is MIT, and so is the Python SDK. The memory engine they talk to is a hosted service with a free tier. Self-hosting the engine is available on Enterprise plans by agreement, when security or compliance requirements call for it; by default we run it for you.
 
 ## How it compares
 
-Most agent memory today lives in one of three places. Per-tool instruction files — `CLAUDE.md`, `.cursorrules`, `AGENTS.md` — are versioned and readable, but each copy belongs to one repo and one tool, and nothing follows you to the next window. A vector store behind RAG retrieves by similarity, and similarity never changes because advice helped or misled. Local-first memory servers win on privacy and latency, and ask you to run and update the infrastructure yourself. Mnemoverse is the managed, cross-tool option in that landscape: nothing to deploy, one key everywhere, and ranking that moves with reported outcomes. If you need memory inside your own perimeter, a local-first server is the better choice — this one is hosted by design.
+Most agent memory today lives in one of three places. Per-tool instruction files — `CLAUDE.md`, `.cursorrules`, `AGENTS.md` — are versioned and readable, but each copy belongs to one repo and one tool, and nothing follows you to the next window. A vector store behind RAG retrieves by similarity, and similarity never changes because advice helped or misled. Local-first memory servers win on privacy and latency, and ask you to run and update the infrastructure yourself. Mnemoverse is the managed, cross-tool option in that landscape: nothing to deploy, one account everywhere, and ranking that moves with reported outcomes. If you need memory inside your own perimeter, a local-first server is the better choice; this one is hosted by default, with Enterprise self-hosting by agreement.
 
 The consolidation stage of the engine — HDBSCAN clustering with Von Restorff protection, so distinctive memories are not absorbed into the average — is designed in and currently switched off on the hosted service; our docs say so rather than hide it.
 
@@ -27,9 +27,26 @@ The consolidation stage of the engine — HDBSCAN clustering with Von Restorff p
 
 ## Quick Start
 
+### No key: the hosted endpoint
+
+If your client signs in over OAuth, you do not need a key at all. Create a free account at [console.mnemoverse.com](https://console.mnemoverse.com/sign-up?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server) (no credit card), then connect the hosted endpoint.
+
+Claude Code:
+```bash
+claude mcp add -s user --transport http mnemoverse https://mcp.mnemoverse.com/mcp
+```
+Then run `/mcp` in a session, select `mnemoverse` and choose **Authenticate**.
+
+Cursor, in `.cursor/mcp.json`:
+```json
+{ "mcpServers": { "mnemoverse": { "url": "https://mcp.mnemoverse.com/mcp" } } }
+```
+
+Claude Desktop, Windsurf, VS Code and ChatGPT: [Remote MCP setup](https://mnemoverse.com/docs/api/remote-mcp-server). The local server below is the other path: it runs on your machine and reads an API key.
+
 ### 1. Get a free API key
 
-Sign up at [console.mnemoverse.com](https://console.mnemoverse.com?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server) — takes 30 seconds, no credit card.
+Sign up at [console.mnemoverse.com](https://console.mnemoverse.com/sign-up?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server) — takes 30 seconds, no credit card.
 
 **Check the key before you put it in a config.** Both forms ask for the key at a masked prompt and never pass it as a command argument, so it lands neither in your shell history nor in the process list.
 
@@ -82,7 +99,7 @@ claude mcp add mnemoverse -s user -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -e MNEM
 
 [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=mnemoverse&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtbmVtb3ZlcnNlL21jcC1tZW1vcnktc2VydmVyQGxhdGVzdCJdLCJlbnYiOnsiTU5FTU9WRVJTRV9BUElfS0VZIjoibWtfbGl2ZV9ZT1VSX0tFWSIsIk1ORU1PVkVSU0VfQVBJX1VSTCI6Imh0dHBzOi8vY29yZS5tbmVtb3ZlcnNlLmNvbS9hcGkvdjEifX0%3D)
 
-The install button carries the placeholder key `mk_live_YOUR_KEY`, not yours, so the shortest path is to skip the button: add the JSON below to `~/.cursor/mcp.json`, merging it with any servers already there, and put your own key in place. Get one at [console.mnemoverse.com](https://console.mnemoverse.com?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server). If you did click the button, edit the same key in the `mcp.json` it wrote; Cursor keeps MCP environment values in that file, not in a settings form. Until the key is real the server starts and lists its tools, but every tool call is refused.
+The install button carries the placeholder key `mk_live_YOUR_KEY`, not yours, so the shortest path is to skip the button: add the JSON below to `~/.cursor/mcp.json`, merging it with any servers already there, and put your own key in place. Get one at [console.mnemoverse.com](https://console.mnemoverse.com/sign-up?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server). If you did click the button, edit the same key in the `mcp.json` it wrote; Cursor keeps MCP environment values in that file, not in a settings form. Until the key is real the server starts and lists its tools, but every tool call is refused.
 
 ```json
 {
@@ -272,11 +289,25 @@ If it doesn't remember: check that the client was fully restarted and the config
 | `memory_feedback` | Rate memories as helpful or not (improves future recall) |
 | `memory_stats` | Check how many memories stored, which domains exist |
 | `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_invite_to_room` | Mint an invite (code + link) for a room you own; single-use unless `max_uses` allows more |
 | `memory_join_room` | Join a shared room with an invite code (`mnvr_...`) |
 | `memory_list_rooms` | List rooms you own or joined, with each room's address to use as `domain` |
 | `vault_list` | List Vault secrets by alias and purpose — the secret value is never returned |
 
+### Prompts
+
+Three named shortcuts for clients that show MCP prompts as commands (Claude Code as `/mcp__mnemoverse__<name>`). Each one only asks the model to use the tools above; none of them calls the API itself.
+
+| Prompt | Arguments | What it asks for |
+|------|------|-------------|
+| `recall` | `topic` | Search memory for a topic with `memory_read` and summarize only what comes back |
+| `save_insight` | `insight`, optional `domain` | Store an insight with `memory_write` and confirm what was stored |
+| `what_do_you_know` | `subject` | A briefing from `memory_read` that flags what is not stored |
+
+### Resources
+
+`memory://item/{memory_id}` opens one saved memory by its id (the `id:` line of a `memory_read` result) for clients that attach MCP resources. It returns the memory's `memory_id`, `content` and `domain` as JSON. It reads your own store only: a memory read from a shared room cannot be opened by id.
+
 ### Tool surface stability
 
 `tools/list` is frozen per released version, so a client can save the list it
@@ -288,21 +319,56 @@ saw and diff it against what the server serves today, by version.
   and what a tool returns, as the CHANGELOG rules state.
 - **Within a MINOR** (x.Y.0): tools and annotation fields may be added, never
   removed or renamed, and no declared annotation field disappears or flips
-  silently. Every addition has a line in the CHANGELOG under that version.
-- **Removing or renaming a tool, or dropping or renaming a declared annotation
-  field,** is announced one MINOR ahead: the tool stays, its description says
+  silently. Every addition has a line in the CHANGELOG under that version. A
+  MINOR may also add an output schema (`outputSchema`, with
+  `structuredContent` returned alongside the same text) to a tool that did
+  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; `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 rename is announced by naming
+  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`; 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.10 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.
@@ -348,7 +414,7 @@ The retrieval model is published: [arXiv:2603.08965](https://arxiv.org/abs/2603.
 - [Cursor](https://mnemoverse.com/docs/api/cursor) · [VS Code](https://mnemoverse.com/docs/api/vs-code) · [Claude Code](https://mnemoverse.com/docs/api/claude) · [ChatGPT](https://mnemoverse.com/docs/api/chatgpt)
 - [Python SDK](https://mnemoverse.com/docs/api/python-sdk)
 - [API Reference](https://mnemoverse.com/docs/api/reference)
-- [Console (get API key)](https://console.mnemoverse.com?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server)
+- [Console (get API key)](https://console.mnemoverse.com/sign-up?utm_source=npm&utm_medium=readme&utm_campaign=mcp-memory-server)
 
 **Background reading**
 
@@ -395,7 +461,7 @@ What each tool sends:
 | `memory_write` | the `content`, `concepts`, and `domain` you pass |
 | `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_feedback` | the `memory_ids` being rated (sent to the API as `atom_ids`), the `outcome` score, and the `domain` when you pass one (a shared room's address) |
 | `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` |

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;