@mnemoverse/mcp-memory-server 0.10.2 → 0.11.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,11 +319,22 @@ 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_list_recent`'s `next_cursor`, optional here (absent when the
+  service sent a continuation token this client will not pass on) and
+  required there.
+- **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`). 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
@@ -300,9 +342,11 @@ saw and diff it against what the server serves today, by version.
 - Any difference between two servers of the same version is a bug. Report it
   with both `tools/list` outputs.
 
-The list above is the 0.10 surface: ten tools, each declaring all four hints.
+The list above is the 0.11 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.
+
 ## 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 +392,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 +439,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/index.d.ts

@@ -1,24 +1,3 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * Two renderers, and which one a value gets is a decision, not a style choice.
- *
- * `safeInline` (src/render.ts) SANITISES an untrusted display string for inline
- * rendering in tool output that a DIFFERENT principal's LLM will read (CN-032
- * anti-injection): strip to a conservative charset, collapse whitespace, cap
- * the length. The treatment `formatAuthorTag` applies to a server-stamped
- * author, and the defensive second pass the machine-shaped room fields
- * (address, room_id, role, scope — all charset-validated or enum-shaped in
- * core) get here. It is lossy on purpose, and everything it still renders is a
- * value the reader looks at and never has to retype or compare.
- *
- * `exactLiteral` / `domainPhrase` / `roomNamePhrase` (src/names.ts) print a
- * value as a JSON string literal, or refuse to print it. Domain names because
- * the engine matches them byte-for-byte, so the reader must be able to send
- * the exact bytes back. Room NAMES (0.8.1) because the sanitiser did not make
- * them harmless so much as it made them WRONG: "проект" echoed back as `""` on
- * create, "Zoë" as "Zo" inside quotes that claim to be the name. The literal
- * is one line with quotes, backslashes and invisibles escaped, so it is as
- * injection-safe as the sanitised spelling was — without the renaming.
- */
 export declare const server: McpServer;