Mnemoverse Memory｜AI Agent 托管长期记忆 MCP 服务器

access：来源确认 · connect with an OAuth sign-in on the hosted endpoint `https://mcp.mnemoverse.com/mcp`, or run this package locally with an API key

project_type：来源确认 · **Hosted long-term memory for AI agents over MCP.**

# Mnemoverse Memory

**Hosted long-term memory for AI agents over MCP.** Two calls cover the basics: `memory_write` saves a memory, and `memory_read` finds it again by a natural-language query. Pass `domain: "user:<id>"` on both to keep each user's memories apart (a namespace inside your account, not a permission boundary). Rating a recalled memory as helpful or misleading re-ranks what comes back next (`memory_feedback`).

**Free plan, no credit card:** 1,000 queries a day (reads, writes and feedback combined), 10,000 atoms of storage, 60 requests a minute. Plans and limits: [mnemoverse.com/pricing](https://mnemoverse.com/pricing)

**Using ChatGPT?** [Install the published Mnemoverse Memory plugin](https://chatgpt.com/plugins/plugin_asdk_app_6ada598cec7c81918b22105edfafcb33), then complete browser sign-in. Follow the [ChatGPT guide](https://mnemoverse.com/docs/api/chatgpt) to verify the connection; no local package or custom MCP setup is needed for this route.

**Other clients:** connect with an OAuth sign-in on the hosted endpoint `https://mcp.mnemoverse.com/mcp`, or run this package locally with an API key. Setup for Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop (formerly Windsurf), Zed, JetBrains, Cline and Gemini CLI is below. Steps for other hosts: [mnemoverse.com/docs/api/install-by-host](https://mnemoverse.com/docs/api/install-by-host)

Shared rooms (beta) let several agents work from one memory.

`@mnemoverse/mcp-memory-server` is the MIT-licensed MCP server for the hosted Mnemoverse memory engine.

**Official sources only:** this repository, the npm package `@mnemoverse/mcp-memory-server`, and the `.mcpb` attached to this repository's [GitHub Releases](https://github.com/mnemoverse/mcp-memory-server/releases). A copy of this README elsewhere with its own "Download" button is not ours: please don't run it, and report it to us at support@mnemoverse.com.

[![npm version](https://img.shields.io/npm/v/@mnemoverse/mcp-memory-server.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server)
[![npm downloads](https://img.shields.io/npm/dm/@mnemoverse/mcp-memory-server.svg?color=blue&label=downloads)](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-0ea5e9)](https://registry.modelcontextprotocol.io/v0/servers?search=mnemoverse)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![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)

## What is Mnemoverse Memory?

Mnemoverse is a hosted memory engine for AI agents, reached over the Model Context Protocol. It 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 OAuth sign-in on the hosted endpoint, or an API key in a local config.

**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, each new session reads them again, and a committed file travels with its repository; but a file reaches only the tools that look for its name, so a rule written for Claude Code is not there in a ChatGPT chat. 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 rating a recalled memory as helpful or misleading re-ranks what comes back next. 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.

> ⭐ If Mnemoverse saves you from re-explaining context to your agents, [star the repo](https://github.com/mnemoverse/mcp-memory-server). It helps other builders find it.

## Quick Start

Create a free account at [console.mnemoverse.com](https://console.mnemoverse.com/sign-up?utm_source=readme&utm_medium=readme&utm_campaign=mcp-memory-server) (no credit card). Every setup in this section connects to the hosted server `https://mcp.mnemoverse.com/mcp` and signs you in through the browser, so there is no key to copy. To run this package on your machine with an API key instead, see [Local package with an API key](#local-package-with-an-api-key).

### 1. Connect your AI tool

<!-- INSTALL_SNIPPETS_START — generated from src/configs/source.json. Run `npm run generate:configs` to refresh. Do not edit by hand. -->

**Claude Code** — the hosted server, with a browser sign-in. No API key, nothing to install:

```bash
claude mcp add --scope user --transport http mnemoverse https://mcp.mnemoverse.com/mcp
```

Then start Claude Code, run `/mcp`, select `mnemoverse` and choose **Authenticate**. If the command ran inside a Claude Code session (yours, or Claude ran it for you), that session does not load the new server: exit and start `claude` again first.

**Cursor** — click to add the hosted server. Cursor signs you in through the browser, so there is no key to paste:

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=mnemoverse&config=eyJ1cmwiOiJodHRwczovL21jcC5tbmVtb3ZlcnNlLmNvbS9tY3AifQ==)

The button writes `{"url": "https://mcp.mnemoverse.com/mcp"}` under `mnemoverse` in `~/.cursor/mcp.json`, the global config that covers every project. Then click **Connect** next to `mnemoverse` in Cursor's MCP settings (**Customize** in the sidebar; **Cursor Settings → Tools & MCPs** in Cursor 3.21.16) and approve in the browser. Cursor runs the sign-in and keeps the token itself.

**Any MCP client** — a client that adds a remote server by URL and runs the MCP sign-in (OAuth) itself takes `https://mcp.mnemoverse.com/mcp`. Any other client takes the entry below: [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a separate open-source bridge, runs through `npx` (Node.js 20.18.1 or later), forwards to the same URL and opens the same browser sign-in on first start. Neither way needs a key:

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.mnemoverse.com/mcp"
      ]
    }
  }
}
```

The bridge keeps its sign-ins in `~/.mcp-auth`. If a sign-in gets stuck, its README says to delete that folder and restart the client.


<!-- INSTALL_SNIPPETS_END -->

<details>
<summary><b>Setup per client</b> — VS Code, Claude Desktop, Cline, Devin Desktop (formerly Windsurf), Zed, JetBrains</summary>

<!-- MORE_CLIENTS_START — generated from src/configs/source.json. Run `npm run generate:configs` to refresh. Do not edit by hand. -->

**VS Code** — the [VS Code extension](https://github.com/mnemoverse/mnemoverse-vscode) signs in through the browser, with no key to paste: install it and run **Mnemoverse: Sign In**. Without the extension, add the hosted server to `.vscode/mcp.json` (VS Code 1.102 or later; VS Code uses `servers`, not `mcpServers`). VS Code opens the browser sign-in on first use, and the entry holds no key, so the file is safe to commit:

```json
{
  "servers": {
    "mnemoverse": {
      "type": "http",
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}
```

**Claude Desktop** — add the hosted server as a custom connector: **Customize → Connectors**, then **+** and **Add custom connector**, paste `https://mcp.mnemoverse.com/mcp` and sign in when the browser opens. The connector also works on claude.ai and in the Claude mobile apps; free Claude plans allow one custom connector. To use `claude_desktop_config.json` instead, add the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which runs through `npx` (Node.js 20.18.1 or later), and restart Claude Desktop; the bridge opens the same browser sign-in:

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.mnemoverse.com/mcp"
      ]
    }
  }
}
```

**Cline** — in the Cline panel, open **MCP Servers**, then the **Remote Servers** tab. Enter `mnemoverse` as the server name and `https://mcp.mnemoverse.com/mcp` as the URL, choose **Streamable HTTP**, click **Add Server**, then click **Authenticate** on the server's row and sign in in the browser. The same entry by hand, in `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "mnemoverse": {
      "type": "streamableHttp",
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}
```

Keep `"type": "streamableHttp"`: without it Cline uses the older SSE transport.

**Devin Desktop (formerly Windsurf)** — add the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which runs through `npx` (Node.js 20.18.1 or later), to `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows) and restart Devin Desktop; the bridge opens the browser sign-in on first start:

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.mnemoverse.com/mcp"
      ]
    }
  }
}
```

Devin also documents a remote entry with only `"url"` and its own sign-in; that sign-in has not been tested with Mnemoverse yet.

**Zed** — add the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which runs through `npx` (Node.js 20.18.1 or later), to `~/.config/zed/settings.json` (Zed uses `context_servers`); the bridge opens the browser sign-in on first start:

```json
{
  "context_servers": {
    "mnemoverse": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.mnemoverse.com/mcp"
      ]
    }
  }
}
```

Zed also accepts the URL itself (`"url": "https://mcp.mnemoverse.com/mcp"`) and runs its own sign-in; that route has not been tested with Mnemoverse yet.

**JetBrains** (AI Assistant) — *Settings → Tools → AI Assistant → Model Context Protocol (MCP)*, then paste the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which runs through `npx` (Node.js 20.18.1 or later); the bridge opens the browser sign-in on first start:

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.mnemoverse.com/mcp"
      ]
    }
  }
}
```


<!-- MORE_CLIENTS_END -->

</details>

**Gemini CLI**: `gemini extensions install https://github.com/mnemoverse/gemini-extension` connects the same hosted server. **ChatGPT**: [install the published plugin](https://chatgpt.com/plugins/plugin_asdk_app_6ada598cec7c81918b22105edfafcb33) and follow the [ChatGPT guide](https://mnemoverse.com/docs/api/chatgpt); [custom MCP setup](https://mnemoverse.com/docs/api/chatgpt-custom-mcp) remains a separate advanced alternative. Steps for more hosts: [mnemoverse.com/docs/api/install-by-host](https://mnemoverse.com/docs/api/install-by-host)

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

### 2. Try it — 30 seconds to verify it works

First ask the agent to call `memory_stats` and inspect the actual response. A successful result confirms read access, including an empty account. Visible tools alone do not. If you only wanted to connect memory, you can stop here; writing has not been tested.

For a save-and-recall test you want to run, choose a harmless true fact, then ask the agent to save it with `memory_write` in a domain such as `setup-check`. Check the tool result before treating the fact as saved. `NOT STORED` or `stored: false` means no new memory was saved: keep the returned reason, do not assume it was a duplicate, and do not retry writes blindly.

After a successful write, open a **new chat / new session** and ask the agent to call `memory_read` for that fact in the same domain.

Verify that the actual `memory_read` result contains your fact. An answer without the tool result does not prove persistence. If writing succeeded but read-back failed, saving is confirmed and verification remains incomplete.

If a call fails, keep the actual error. Check that the client was fully restarted and that browser sign-in finished (in Claude Code, `/mcp`; in Cursor, **Connect** next to `mnemoverse`). With the [local package](#local-package-with-an-api-key), check the key privately in the client configuration; do not paste it into chat or troubleshooting output. An existing matching memory found after a refused write is not a newly saved test fact.

> ⭐ If the second session remembered, [star the repo](https://github.com/mnemoverse/mcp-memory-server). It helps other builders find it.

### 3. 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](https://mnemoverse.com/docs/api/agent-memory) explains where they go and how to confirm the tools work first.

## Local package with an API key

This package also runs on your machine as a local MCP server (stdio, Node.js 18 or later) that authenticates with an API key. Use it when a client cannot complete a browser sign-in, for unattended runs, or when you would rather manage a key yourself. It reaches the same memory as the hosted server.

### 1. Get a free API key

Sign up at [console.mnemoverse.com](https://console.mnemoverse.com/sign-up?utm_source=readme&utm_medium=readme&utm_campaign=mcp-memory-server) (no credit card) and create a key.

**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:
```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:
```powershell
$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.

**The hosted server accepts the key too.** A client that can send a fixed header needs no local package: point it at `https://mcp.mnemoverse.com/mcp` with the header `Authorization: Bearer <API_KEY>` ([details](https://mnemoverse.com/docs/api/remote-mcp-server#with-an-api-key-instead-of-the-sign-in)).

### 2. Add it to your client

Where a client has a user-level config, the entry below goes there, so the key is written **once, covering every project**. Avoid a per-project config file for a key: it lives inside the repository and can be committed with it. The local entry and the hosted one share the name `mnemoverse`, so use one or the other in a client, not both.

<details>
<summary><b>Config per client</b> — Claude Code, Cursor, VS Code, Claude Desktop, Cline, Devin Desktop (formerly Windsurf), Zed, JetBrains</summary>

<!-- LOCAL_KEY_SNIPPETS_START — generated from src/configs/source.json. Run `npm run generate:configs` to refresh. Do not edit by hand. -->

**Claude Code** — put your own key in place of `mk_live_YOUR_KEY`:

```bash
claude mcp add mnemoverse --scope 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:

```powershell
claude mcp add mnemoverse --scope 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** — add the JSON below to `~/.cursor/mcp.json`, the global config that covers every project, merging it with any servers already there, and put your own key in place of `mk_live_YOUR_KEY`. 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.

```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"
      }
    }
  }
}
```

**VS Code** — add to `.vscode/mcp.json` (VS Code uses `servers`, not `mcpServers`). Never put a literal `mk_live_` key in that file: it is committed with the repository. The `inputs` entry below prompts for the key instead; VS Code masks what you type and keeps it in its own secret storage, not in the file. VS Code's non-interactive Agent Host mode does not start a server that prompts for inputs, so for unattended use there, leave out the `inputs` entry and the `MNEMOVERSE_API_KEY` line, and set `MNEMOVERSE_API_KEY` in the environment of the process that launches VS Code:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "mnemoverse-api-key",
      "description": "Mnemoverse API key (starts with mk_live_), for this local package only: the hosted server https://mcp.mnemoverse.com/mcp signs in with OAuth and takes no key. 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"
      }
    }
  }
}
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```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"
      }
    }
  }
}
```

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

```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"
      }
    }
  }
}
```

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

```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"
      }
    }
  }
}
```

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

```json
{
  "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:

```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"
      }
    }
  }
}
```

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

<!-- LOCAL_KEY_SNIPPETS_END -->

</details>

Restart the client after editing its config, then run the two-session check from step 2 of the Quick Start.

## 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 a recalled memory as helpful or misleading, which re-ranks what comes back next |
| `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; and `memory_read` and `memory_list_recent`, which carry an optional
  `rooms_not_searched` field (the shared rooms an unscoped call did not
  search) that the connector's schemas do not declare yet.
- **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 unfiltered registrations of this package at 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.

Every `inputSchema` and `outputSchema` is JSON Schema 2020-12, the dialect MCP
assumes when a schema names none, and names none (#189).

The list above is the current surface: eleven tools, each declaring all four hints.
The hosted connector at `mcp.mnemoverse.com/mcp` registers tools from this package
at the version it pins, then applies its own host profile. For ChatGPT that profile
withholds `vault_list`; it is a connector-layer filter, not a configurable tool
list in this package. Compare the same package version and host profile when
checking parity; see [tool availability by host](https://mnemoverse.com/docs/api/tool-availability).
The package's unfiltered list is published as
[`tools.json`](./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 [Local package with an API key](#local-package-with-an-api-key), 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 rating a recalled memory as helpful or misleading re-ranks what comes back next, 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

One account works across all tools, whether a tool signs in through the browser or uses an API key. 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

The local package reads two environment variables. The hosted server needs neither: it signs you in through the browser.

| 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](https://arxiv.org/abs/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**

- [Documentation](https://mnemoverse.com/docs/api/mcp-server)
- [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 (account and API keys)](https://console.mnemoverse.com/sign-up?utm_source=readme&utm_medium=readme&utm_campaign=mcp-memory-server)

**Background reading**

- [Memory MCP servers compared](https://mnemoverse.com/docs/library/memory-mcp-servers-compared) — thirteen shipping options, with pricing and registry presence
- [How to choose a memory MCP server](https://mnemoverse.com/docs/library/memory-mcp) — the five questions that narrow the field
- [What AI agent memory is](https://mnemoverse.com/docs/library/ai-agent-memory) — the category explained
- [Is this a vector database?](https://mnemoverse.com/docs/library/not-a-vector-database) — what makes a memory layer different
- [Shared memory for multi-agent systems](https://mnemoverse.com/docs/library/shared-memory-for-multi-agent-systems) — how Rooms work and when to use them

**Other ways to install it**

The same memory, packaged for hosts that prefer a plugin or an extension over an MCP config block. How each one connects and authenticates differs, so the line below says which is which rather than claiming one flow for all of them.

- [Claude Code plugin](https://github.com/mnemoverse/claude-plugin) — remote endpoint over MCP with an OAuth sign-in, no key to paste. Bundles the `agent-memory-discipline` skill
  ```
  claude plugin marketplace add mnemoverse/claude-plugin
  claude plugin install mnemoverse@mnemoverse
  ```
- [Cursor plugin](https://github.com/mnemoverse/cursor-plugin) — same remote endpoint, same sign-in
- [Gemini CLI extension](https://github.com/mnemoverse/gemini-extension) — same remote endpoint. `gemini extensions install https://github.com/mnemoverse/gemini-extension`
- VS Code extension ([VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Mnemoverse.mnemoverse-vscode), [Open VSX](https://open-vsx.org/extension/mnemoverse/mnemoverse-vscode), [source](https://github.com/mnemoverse/mnemoverse-vscode)) — signs in through the browser, with pasting a key kept as a fallback command
- Desktop extension: `manifest.json` in this repository is an MCPB manifest. This one is different from the four above: it runs the server as a local `node` process and reads `MNEMOVERSE_API_KEY` from the extension settings rather than calling the hosted endpoint. The packaged `.mcpb` ships with each release

**Standing rules, separate from this server**

- [agent-memory-discipline](https://github.com/mnemoverse/agent-memory-discipline) — when an agent should recall before acting and save afterward. CC0, backend-neutral, works against any memory store rather than this one. It carries its own [marketplace manifest](https://github.com/mnemoverse/agent-memory-discipline/blob/main/.claude-plugin/marketplace.json) under `.claude-plugin/`.
- [awesome-agent-memory](https://github.com/mnemoverse/awesome-agent-memory) — a curated index of the category, CC0, including the servers this one competes with

**Project**

- [GitHub](https://github.com/mnemoverse/mcp-memory-server)
- [Releases](https://github.com/mnemoverse/mcp-memory-server/releases)
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=mnemoverse)
- [Contributing](CONTRIBUTING.md)

## Privacy Policy

This server sends to the Mnemoverse API (`core.mnemoverse.com`), authenticated with your API key, what a tool call carries — and nothing else it can see. It does **not** read your AI client's conversation history, your local files, or anything you don't pass to a `memory_*` / `vault_*` tool. Stored memories live under your account; Mnemoverse never sells them and never shares them on its own. The one sharing path is the one you create yourself: inviting someone to a shared room grants their assistant access to that room's memories, bounded by the invite's scope.

What each tool sends:

| Tool | Data sent |
|---|---|
| `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 `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` |
| `memory_graph` | the `seeds`, plus any of `depth`, `domain`, `min_weight`, `limit` you pass |
| `memory_stats` / `memory_list_rooms` / `vault_list` | no request body — authenticated GETs |

One thing goes out that you did not explicitly request: since 0.8.1, when a search or feed comes back empty, the server sends one or two authenticated read-only GET probes (`/memory/rooms` and/or `/memory/stats`) so the empty answer can say what it did not cover. Since 0.16.0 a search or feed without `domain` that does return results also sends one, to `/memory/rooms`, so the answer can name the shared rooms it did not search. The probes carry your API key and nothing else, change no stored state, and are disclosed in the [CHANGELOG](CHANGELOG.md).

| | |
|---|---|
| **Privacy Policy** | <https://mnemoverse.com/docs/legal/privacy-policy> |
| **Retention & deletion** | correct a wrong or stale memory by writing a fresh one; an individual personal memory can be deleted through the REST API; deletion is not exposed through this MCP server |
| **Contact** | hello@mnemoverse.com |

## License

[MIT](LICENSE) © Mnemoverse

托管路径需兼容 MCP 客户端与 OAuth 登录；本地包需 Node.js 18+ 和 API Key，仍连接托管记忆引擎；mcp-remote 桥接需 Node.js 20.18.1+。README 免费方案为每日1000次查询、10000 atoms、每分钟60次请求，实际额度和费用以官方为准。服务部署地域、国内连通性与模型协作效果待核验。