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. 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.

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 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. 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 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.

⭐ If Mnemoverse saves you from re-explaining context to your agents, star the repo. It helps other builders find it.

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 (no credit card), then connect the hosted endpoint.

Claude Code:

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:

{ "mcpServers": { "mnemoverse": { "url": "https://mcp.mnemoverse.com/mcp" } } }

Claude Desktop, Devin Desktop (formerly Windsurf), VS Code and ChatGPT: Remote MCP setup. 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 — 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.

macOS, Linux, Git Bash:

printf 'Mnemoverse API key: '; read -rs KEY; echo
printf 'X-Api-Key: %s\n' "$KEY" | curl -s -H @- https://core.mnemoverse.com/api/v1/memory/stats; unset KEY

Windows PowerShell 5.1 and PowerShell 7:

$k = [Net.NetworkCredential]::new('', (Read-Host 'Mnemoverse API key' -AsSecureString)).Password
try { (Invoke-WebRequest https://core.mnemoverse.com/api/v1/memory/stats -Headers @{ 'X-Api-Key' = $k } -UseBasicParsing).Content }
catch { if ($_.ErrorDetails.Message) { $_.ErrorDetails.Message } else { (New-Object IO.StreamReader($_.Exception.Response.GetResponseStream())).ReadToEnd() } }; Remove-Variable k

The output contains	What it means
JSON that includes "total_atoms"	The key works.
"reason":"placeholder_key"	That is the example key from these docs. Create a real one at the console.
"reason":"malformed_key"	Not the shape of a key: cut short in the paste, wrapped in quotes, or a different token entirely.
"reason":"invalid_key"	The shape is right and no such key exists. Copy it again from the console.
"reason":"revoked_key"	The key was revoked and will not work again. Create a new one.
"reason":"missing_key"	No key reached the API: what you entered was empty.

In the JSON, reason sits inside the details object (details.reason), next to details.keys_url, the console page where keys are created.

2. Connect to your AI tool

The two canonical setups, Claude Code and Cursor. Each writes the key once, at user scope, covering every project. Avoid a per-project config file for this: it lives inside the repository and can be committed with it, and a key belongs outside:

Claude Code — add via CLI:

claude mcp add mnemoverse -s user \
  -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY \
  -e MNEMOVERSE_API_URL=https://core.mnemoverse.com/api/v1 \
  -- npx -y @mnemoverse/mcp-memory-server@latest

On Windows (PowerShell), paste the same command as one line — PowerShell does not read the \ line continuations:

claude mcp add mnemoverse -s user -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -e MNEMOVERSE_API_URL=https://core.mnemoverse.com/api/v1 -- npx -y @mnemoverse/mcp-memory-server@latest

Cursor — click to install, or add the JSON below to ~/.cursor/mcp.json, the global config that covers every project. Do not put it in a project-level .cursor/mcp.json: that file lives inside the repository and is committed with it unless you exclude it, and this config holds your key.

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. 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.

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

VS Code — the VS Code extension signs in through the browser and needs no key; that's the default path. In VS Code's non-interactive Agent Host mode, servers that prompt for inputs like this one are not started; for unattended use there, put the key in the environment of the process that launches VS Code instead. To wire the MCP server directly instead, add this to .vscode/mcp.json (note: VS Code uses servers, not mcpServers). Never put a literal mk_live_ key in that file — it's committed with the repo. The inputs entry below prompts for the key instead: VS Code masks what you type and stores it in its own secret storage, not in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mnemoverse-api-key",
      "description": "Mnemoverse API key (starts with mk_live_). Optional to install and inspect — the server starts and lists its tools without a key; every actual tool call requires one. Get one free in ~30s at https://console.mnemoverse.com",
      "password": true
    }
  ],
  "servers": {
    "mnemoverse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "${input:mnemoverse-api-key}",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

Devin Desktop (formerly Windsurf) — add to ~/.config/devin/mcp_config.json:

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

More MCP clients — same server, different config file:

Zed — add to ~/.config/zed/settings.json (Zed uses context_servers, and "source": "custom" is required):

{
  "context_servers": {
    "mnemoverse": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

JetBrains (AI Assistant) — Settings → Tools → AI Assistant → Model Context Protocol (MCP), then paste:

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

Cline — MCP Servers → Configure (or edit cline_mcp_settings.json). Cline reads env values literally, so paste your real key — not a ${VAR} reference:

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

Why @latest? Bare npx @mnemoverse/mcp-memory-server is cached indefinitely by npm and stops re-checking the registry. The @latest suffix forces a metadata lookup on every Claude Code / Cursor / VS Code session start (~100-300ms), so you always pick up new releases.

⚠️ Restart your AI client after editing the config. MCP servers are only picked up on client startup.

3. Try it — 30 seconds to verify it works

Paste this in your AI chat:

"Remember that my favourite TypeScript framework is Hono, and please call memory_write to save it."

Your agent should call memory_write and confirm the memory was stored.

Then open a new chat / new session (this is the whole point — memory survives restarts), and ask:

"What's my favourite TypeScript framework?"

Your agent should call memory_read, find the entry, and answer "Hono". If it does — you're wired up. Write whatever you want next.

If it doesn't remember: check that the client was fully restarted and the config has your real mk_live_... key, not the placeholder.

⭐ If the second session remembered, star the repo. It helps other builders find it.

4. Make it a habit

The test above works because you asked the agent to call the tool. In normal work it will not, unless it has a standing instruction that says when to read memory and when to save. The setup_memory prompt writes those rules for Claude Code, Claude, Cursor or Codex, and Make Your Agent Use Memory explains where they go and how to confirm the tools work first.

Tools

Tool	What it does
memory_write	Store a memory — insight, preference, lesson learned
memory_read	Search memories by natural language query (optional recency ordering, time bounds, author exclusion)
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_create_room	Create a shared memory room; its address works as a domain on write/read
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
memory_graph	Read the association edges around given concepts — weight, outcome valence, co-activation count
vault_list	List Vault secrets by alias and purpose — the secret value is never returned

Prompts

Four named prompts for clients that show MCP prompts as commands (Claude Code as /mcp__mnemoverse__<name>). None of them calls the API itself: three ask the model to use the tools above, and setup_memory hands you rules for your own agent.

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
setup_memory	optional host: claude-code, claude-ai, cursor or codex	Memory rules for CLAUDE.md, AGENTS.md, Cursor rules or your chat preferences, and where they go, so your assistant checks and saves memory without being reminded

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 saw and diff it against what the server serves today, by version.

• Within a PATCH (x.y.Z): tool names, argument schemas and the annotations object of every tool (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) do not change. Only text may: descriptions 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. 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 renamed parameter is accepted under both names until then (0.11 renamed memory_feedback's atom_ids to memory_ids; the old name was removed in 0.13, as announced after 0.12 shipped sooner than the first 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. 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 current surface: eleven tools, each declaring all four hints. The hosted connector at mcp.mnemoverse.com/mcp serves the same surface, registered from this package at the version it pins. The list itself is published as tools.json, generated from the built server (name, title, description and annotations per tool); the test suite and the release workflow fail when it does not list what the server registers, and the .mcpb manifest's tool list is derived from it.

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 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.

Concrete things worth writing:

• User preferences: "I use dark mode", "I prefer Tailwind over CSS modules"
• Project context: "This project uses PostgreSQL + Prisma", "Deploy to Railway"
• Lessons learned: "Always run tests before push on this repo"
• Decisions made: "We chose REST over GraphQL because of caching simplicity"
• People & roles: "Alice is the designer, Bob owns the API"
• Past mistakes: "Don't deploy on Fridays — learned this the hard way"

Universal Memory

The same API key works across all tools. Write a memory in Claude Code — read it in Cursor. Learn something in VS Code — your GPT Custom Action knows it too.

                    ┌── Claude Code (this MCP server)
                    ├── Cursor (this MCP server)
   Mnemoverse API ──├── VS Code (this MCP server)
   (one memory)     ├── GPT (Custom Actions)
                    ├── Python SDK (pip install mnemoverse)
                    └── REST API (curl)

Configuration

Env Variable	Required	Default
MNEMOVERSE_API_KEY	For every tool call — the server starts and lists its tools without one	—
MNEMOVERSE_API_URL	No	https://core.mnemoverse.com/api/v1

Research behind it

The retrieval model is published: arXiv:2603.08965, accepted at the GRAAI workshop at IEEE WCCI 2026 — it establishes the abstraction-discovery method the memory model builds on. No benchmark figures appear in this README, ours or anyone's: numbers will come with a reproducible run to stand behind, not before.

Links

Setup and reference