MnemoverseDocs

Appearance

Quick Setup ​

For AI Agents

Machine-readable docs (plain text, no auth):

Claude chat sandbox blocks most domains except github.com — use the GitHub link.

Set up Mnemoverse persistent memory in your AI tool. Pick your tool below.

What You Need ​

Two setup paths exist for Mnemoverse memory. Pick one:

  • Path A — Local MCP server (works today). You run @mnemoverse/mcp-memory-server over stdio inside the host tool, authenticated either with a mk_live_* API key from the console, or — in VS Code and its forks — keylessly via the Mnemoverse extension's browser sign-in (no key to paste). This is the path documented below in Step 1.
  • Path B — Remote MCP server + one-click OAuth (live). The host tool connects to https://mcp.mnemoverse.com/mcp over streamable HTTP and authorises via OAuth 2.1 + PKCE against auth.mnemoverse.com/api/auth — no API key copy-paste. The endpoint and its OAuth discovery chain are deployed and serving; one-click connector listings in client directories are rolling out. See the Remote MCP Server page, with per-client configs in Step 1B.

If you do not know which path you want: pick A. It works today, and you can move to B without losing memories — same account, same atoms. (The two paths are near-identical; the remote surface omits the two delete tools — see Available Tools.)

Authentication at a glance ​

The same memory, four ways to authenticate — pick by your tool:

MethodWhat you pasteWorks inSetup
Local package + API keya mk_live_ keyevery MCP client, scripts, CIStep 1
Keyless editor sign-innothing (browser sign-in)VS Code & its forks (Cursor, Windsurf)Editors
Remote OAuth connectornothing (browser sign-in)any compliant MCP clientRemote MCP Server · Step 1B
ChatGPT Custom GPTa mk_live_ keyChatGPTChatGPT

All four resolve to the same account and the same atoms — write with one, recall with another. The API-key methods need a free key from console.mnemoverse.com; the browser methods just need an account.

What you need for either path:

  1. Path A: a Mnemoverse API key (starts with mk_live_). If the user hasn't provided one, tell them to get a free key at console.mnemoverse.com. Path B: a Mnemoverse account at console.mnemoverse.com — no manual key needed; OAuth grants the token.
  2. Know which tool you are running in (see below).

Step 1: Detect Your Environment ​

Determine which AI tool you are running in, then follow the matching setup. This section covers Path A (local stdio — works today). For Path B (one-click OAuth — live) see Step 1B.

Claude Code ​

Run this command:

bash
claude mcp add mnemoverse \
  -e MNEMOVERSE_API_KEY=mk_live_USER_KEY \
  -- npx -y @mnemoverse/mcp-memory-server@latest

Replace mk_live_USER_KEY with the actual key. Done after this command succeeds.

Cursor ​

Create the file .cursor/mcp.json in the project root:

json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Tell the user to restart Cursor after you create this file.

VS Code ​

The easiest path for VS Code (and Cursor / Windsurf / VSCodium) is the keyless Mnemoverse Memory extension: install it and click Sign In — no API key to paste. The manual .vscode/mcp.json below is the alternative (it needs an API key).

Create the file .vscode/mcp.json in the project root:

json
{
  "servers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Tell the user to restart VS Code after you create this file.

Claude Desktop ​

Tell the user to add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Claude Desktop requires manual config edit and restart.

Windsurf ​

Create or edit ~/.codeium/windsurf/mcp_config.json:

json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Tell the user to restart Windsurf after you create this file.

ChatGPT (Custom GPT) ​

You cannot self-configure inside ChatGPT. Tell the user to follow the manual setup guide: ChatGPT Integration. For the forthcoming Apps-SDK / connector path (one-click OAuth in the consumer ChatGPT app), see Step 1B — ChatGPT.

Other Tools ​

If the tool supports MCP, use the Cursor config format (it is the most common). If the tool does not support MCP, use the REST API directly:

bash
# Write a memory
curl -X POST https://core.mnemoverse.com/api/v1/memory/write \
  -H "X-Api-Key: mk_live_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test memory", "concepts": ["test"]}'

# Read memories
curl -X POST https://core.mnemoverse.com/api/v1/memory/read \
  -H "X-Api-Key: mk_live_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "top_k": 5}'

Step 1B: One-click OAuth Connect ​

Live — connector listings rolling out

The remote MCP endpoint at https://mcp.mnemoverse.com/mcp and its OAuth discovery chain (auth.mnemoverse.com/api/auth) are deployed and serving. One-click connector entries in client directories (Anthropic Connectors, ChatGPT App Directory) are still rolling out — until your client lists Mnemoverse, use the static config below or Path A. The canonical host is published in data/facts.json under mcp.remote.endpoint.

How the connect actually works: the host tool POSTs to https://mcp.mnemoverse.com/mcp (a GET returns 404 — the challenge is POST-only), gets a 401 + WWW-Authenticate: Bearer challenge, walks the OAuth discovery chain to auth.mnemoverse.com/api/auth, opens the consent screen (scopes: openid profile email memory:read memory:write offline_access), and stores the access + refresh tokens locally. No API key is ever copied; the host tool is the OAuth client. Compliant clients self-register via Dynamic Client Registration (RFC 7591) at the authorization server; DCR is host-allowlisted — see which clients can sign in for the current list. A client whose redirect host is not on the allowlist uses the static config below instead. Section 11 of the Privacy Policy describes the data flow end-to-end.

Claude Code (remote) ​

The agent self-configures with:

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

The first tool call triggers the OAuth flow in the user's browser; the user grants the scopes and the token is stored by Claude Code. No -e MNEMOVERSE_API_KEY needed.

Claude Desktop (remote) ​

Tell the user to open Settings → Connectors → Add custom connector and paste https://mcp.mnemoverse.com/mcp as the URL. Claude Desktop drives the OAuth flow on first use. No JSON config file edit needed for the remote path.

Cursor (remote) ​

Create .cursor/mcp.json in the project root:

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

Cursor detects the HTTP URL, walks the OAuth discovery chain, and opens the consent screen in the user's default browser on first use. Tell the user to restart Cursor after creating this file.

VS Code (remote) ​

Create .vscode/mcp.json in the project root:

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

The "type": "http" field is what tells VS Code to use the streamable-HTTP transport with OAuth discovery; without it, VS Code defaults to stdio and the install fails. Tell the user to restart VS Code after creating this file.

ChatGPT (Apps SDK) ​

You cannot self-configure inside ChatGPT. Tell the user to:

  1. Sign in to ChatGPT.
  2. Open Settings → Connectors → Browse and search for Mnemoverse Memory.
  3. Click Connect, complete the OAuth login at auth.mnemoverse.com, and grant the requested scopes.

The connector is gated on the ChatGPT App Directory review queue and on Eduard publishing the connector under the mnemoverse-org account; until then, the entry does not appear in Browse. For the legacy Custom GPT (OpenAPI Actions) path, see ChatGPT Integration.

Windsurf (remote) ​

Create or edit ~/.codeium/windsurf/mcp_config.json:

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

Windsurf walks the OAuth discovery chain on first use. Tell the user to restart Windsurf after creating this file.

Other Tools (remote) ​

If the host tool supports remote MCP servers (streamable HTTP + OAuth 2.1), point it at https://mcp.mnemoverse.com/mcp. The OAuth discovery chain follows RFC 9728 (protected resource metadata) and OIDC for the authorization server — anything compliant connects without per-tool hand-tuning.

Distribution Channels ​

Mnemoverse memory ships across the MCP ecosystem. The single source of truth for the channel registry (Official MCP Registry, Smithery, PulseMCP, mcp.so, awesome-mcp-servers, Glama, Anthropic Connectors Directory, ChatGPT App Directory) lives in mnemoverse-distribution/channels/distribution-channels-2026.md. The currently-listed clients on the home page and in data/facts.json under clients.mcp reflect that registry.

As remote connector listings roll out across channels, each surfaces the OAuth-connect entry alongside the existing API-key entry, so users on either path land on the same memory store.

Step 2: Verify ​

After setup, test by writing and reading a memory:

  1. Store: "Remember that this is a test memory for setup verification"
  2. Read: "What test memories do I have?"

If the read returns the test memory, setup is complete.

Step 3: Tell the User ​

Confirm to the user:

  • Memory is configured and working
  • Memories persist across sessions
  • Same memories are accessible from any tool signed in to the same account (API key or OAuth)
  • You will proactively remember preferences, decisions, and lessons

Available Tools After Setup ​

ToolWhat it doesPath A (local)Path B (remote)
memory_readSearch memories by natural language query✓✓
memory_writeStore a preference, decision, or lesson✓✓
memory_statsCheck how many memories are stored✓✓
memory_feedbackReport if a memory was helpful (+1) or wrong (-1)✓✓
memory_deleteForget one memory by atom_id✓—
memory_delete_domainWipe all memories in a domain (requires confirm: true)✓—
memory_create_roomBeta — create a shared cross-account memory room✓✓
memory_invite_to_roomBeta — mint a share code (mnvr_...); single-use on Path A, configurable use limit on Path B✓✓
memory_join_roomBeta — redeem a share code to join a room✓✓
memory_list_roomsBeta — list rooms you own or joined, with their domain addresses✓✓

The first six rows are the core memory tools: Path A (local stdio) exposes all six; Path B (remote OAuth) exposes four of them — the two delete tools are deliberately excluded from the remote surface (forget-not-delete; ADR-012), so a connected agent cannot destructively wipe a domain over the network. The last four rows are the Beta shared-room tools (memory_create_room, memory_invite_to_room, memory_join_room, memory_list_rooms): they are non-destructive, so they ship on both paths — see Join a shared room below. Per-tool annotations (readOnlyHint / destructiveHint / idempotentHint) are otherwise consistent across both transports.

Join a shared room (Beta) ​

Beta — shared rooms

A room is a memory pool shared across separate Mnemoverse accounts. Members address it by putting xroom:<room_id> in the domain field of memory_write / memory_read — no new endpoint, and no separate tool call to read or write it. Creating a room, inviting, and joining ship as three tools on both paths (Path A local and Path B remote); the feature is in beta. The Rooms page is the full reference for the address format, the two membership scopes (read / read_write), billing (usage is billed to the caller who makes the request, never the room owner), and the error envelope.

Three tools drive the flow — memory_create_room, memory_invite_to_room, and memory_join_room.

Owner — create a room and mint an invite:

  1. memory_create_room({ name }) returns the room's room_id (shape room_<ulid>) and its address (xroom:<room_id>).
  2. memory_invite_to_room({ room_id, scope }) mints a share code (mnvr_...) plus a ready-to-forward share_message. scope is read or read_write (default read_write) and is baked into the code at mint — the invitee gets exactly that role. Both paths default to one redemption and a 7-day expiry. Path A's local tool always mints a single-use code and accepts expires_in_days; Path B's remote tool also accepts max_uses when the owner intentionally needs more than one redemption.
  3. Forward the share_message — it carries the code and a join link — to whoever you're adding, over any channel.

Joiner — redeem the code, then use the room:

  1. Their agent calls memory_join_room({ code }) with the mnvr_... code. The joiner's identity comes from their own auth, not the code — the code only carries the room and the role. Joining returns the room's address (xroom:<room_id>).
  2. From then on, the joiner reads and writes the shared pool by passing domain: "xroom:<room_id>" on memory_write / memory_read — the same two tools you already use, with one extra field.

Self-installing invite

The invite is designed to set itself up. The recipient can paste the share_message straight to their own assistant. If that assistant isn't connected to Mnemoverse yet, it first follows Step 1B to add the Mnemoverse remote connector — no account needed up front; the first OAuth sign-in creates one — and then calls memory_join_room with the code. One paste, and the recipient's agent is in the room.

Being in a room does not change the memory habit: an agent won't reach for room memory unless told to. Point it at the room's domain in your project instructions, and set the general recall-and-save rule from Make Your Agent Use Memory.