MnemoverseDocs

Appearance

Claude Code ​

For AI Agents

Machine-readable docs: mnemoverse.com/docs/llms.txt

Give Claude persistent memory. One command — it never forgets again.

Claude Code — add via CLI:

bash
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:

powershell
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

That's it. Claude Code now has long-term memory across all sessions.

The command runs the server locally through npx, so it needs Node.js 18 or later on this machine. The OAuth connector below needs nothing installed. If claude mcp list shows the server as failed, see The server shows Failed to connect.

Get your API key at console.mnemoverse.com (free tier, no credit card).

Check the key before you add it. Check your API key asks the API whether it accepts the key, from bash or PowerShell, and names the cause if it does not.

Prefer no API key? Connect over one-click OAuth instead — the connector URL is https://mcp.mnemoverse.com/mcp. Add it with claude mcp add -s user --transport http mnemoverse https://mcp.mnemoverse.com/mcp. Adding it does not open the browser: start a Claude Code session, run /mcp, select mnemoverse and choose Authenticate to sign in (or run claude mcp login mnemoverse from your shell on Claude Code 2.1.186 or later). Nothing to paste.

Using the Claude apps, not the CLI?

Claude Desktop, claude.ai (web), and mobile set up differently — see Claude Desktop, Web & Mobile. To add the connector there in one click, use Connect to Claude. It opens the Add custom connector dialog on claude.ai with the name and URL filled in; review them, click Add, and sign in when the browser opens. Without the link: Customize → Connectors, then + and Add custom connector, and paste https://mcp.mnemoverse.com/mcp. Free plans allow one custom connector.

Try It ​

Claude may never recall what it saved — unless you tell it to

Without memory rules, Claude answers from its own context instead of checking Mnemoverse, so recall quietly goes unused. The server's tool descriptions say what each tool does, not when Claude should use it unasked. Add the memory rules to CLAUDE.md: run /mcp__mnemoverse__setup_memory and Claude shows them and offers to add them, or copy them from Make Your Agent Use Memory.

With that in place, the point is one memory across tools. In Claude Code:

"Remember: staging deploys go through make deploy-staging, never Railway directly."

Later, in Cursor or ChatGPT — a different tool, even days later:

"How do I deploy staging here?"

It recalls the rule, because the memory lives in Mnemoverse, not in any single tool. (A single-tool "it remembers" demo wouldn't prove much — the tool's own memory could do that; cross-tool recall is what needs Mnemoverse.)

If this setup saved you time, a GitHub star helps the next builder find it.

Tools ​

The MCP server registers 11 tools in total: the core memory tools below, the Beta shared-room tools (covered in their own section), and vault_list, which returns the names (aliases) of stored secrets — never the secret values themselves. The MCP Server page lists every tool.

memory_write — Store a memory ​

When Claude learns something worth keeping — a preference, a lesson, a decision — it stores it.

You: "I prefer Tailwind over CSS modules"
Claude: [calls memory_write]
    content: "User prefers Tailwind CSS over CSS modules for styling"
    concepts: ["tailwind", "css", "styling", "preferences"]
→ Stored (importance: 0.82)
NameTypeRequiredDescription
contentstringYesWhat to remember (1-10,000 chars)
conceptsstring[]NoKey concepts for linking memories (up to 256 items)
domainstringNoNamespace: "engineering", "user:alice"

memory_read — Recall memories ​

Before starting a task, Claude checks what it already knows.

You: "Set up the database"
Claude: [calls memory_read]
    query: "database setup preferences and history"
→ 1. Project uses PostgreSQL 15 + Prisma ORM (postgresql, prisma) @"engineering" · 2026-07-14 09:31Z
     id: 550e8400-e29b-41d4-a716-446655440000
  2. Always run migrations with --create-only first (migrations, prisma) @"lessons" [by "cursor"] · 2026-06-02 18:05Z
     id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
  3. DB hosted on Supabase, connection string in .env.local (supabase, env) · 2026-05-21 11:47Z
     id: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
NameTypeRequiredDescription
querystringYesNatural language search (1-5,000 chars)
top_kintegerNoRequested number of results (default: 5, max: 500). Not a hard cap: association expansion can return more, and the relevance floor can return fewer
domainstringNoFilter by namespace
order_bystringNo"relevance" (default) or "recency" — newest first
since / untilstringNoISO-8601 bounds on creation time (naive = UTC)
exclude_authorstringNoSkip entries whose author principal equals this value — the "only what others wrote" read in a room. It matches the principal, not the agent name shown in results, so an agent name will silently match nothing (max 200 chars)

memory_list_recent — Catch up on what's new ​

The newest memories first, no search query — for resuming after a break or checking a shared room for fresh entries.

You: "Anything new in the team room since yesterday?"
Claude: [calls memory_list_recent]
    domain: "xroom:acme-team"
    since: "2026-08-03T00:00:00Z"
→ 1. [2026-08-04 09:12Z] Staging moved to Fly.io — Railway config retired [by "bob/claude"]
  2. [2026-08-03 16:40Z] Design review moved to Thursdays [by "alice/cursor"]
  (end of feed — nothing older)
NameTypeRequiredDescription
domainstringNoOne domain (e.g. a room's xroom:... address); omit for all
sincestringNoOnly entries at/after this ISO-8601 instant — your "last seen" watermark
untilstringNoOnly entries at/before this instant. Pair with since for a closed window
exclude_authorstringNoSkip one author principal — same value and same caveat as on memory_read
limitintegerNoPage size (default: 20, max: 100)
cursorstringNoOpaque cursor from the previous page — continues without skips

memory_feedback — Rate memories ​

After using a memory, Claude reports whether it helped. Good memories surface faster next time.

Claude: [calls memory_feedback]
    memory_ids: ["550e8400-..."]
    outcome: 1.0  // Very helpful!
→ Rating sent: +1 (helpful). The service reports 1 memory updated — it should surface sooner next time.
NameTypeRequiredDescription
memory_idsstring[]YesMemory IDs from read results
outcomenumberYes-1.0 (harmful) to 1.0 (very helpful)
domainstringNoOnly for memories read from a shared room: that room's address (xroom:...). A read-only member cannot rate

memory_stats — Check status ​

Claude: [calls memory_stats]
→ Memories: 1,250 (500 episodes, 450 prototypes)
  Associations: 8,500 Hebbian edges
  Domains: engineering, user:alice, project:acme
  Avg quality: valence 0.65, importance 0.72

memory_graph — See what your memory has linked ​

Reads the association links around the concepts you name: which concepts your memory has connected, with each link's weight, outcome valence and co-activation count. Useful to inspect what the memory has learned, or to see why a recall pulled in a related concept. Read-only.

ParameterTypeRequiredDescription
seedsstring[]YesConcepts to center the graph on, 1-20 of them. An unknown concept adds no links; it is not an error
depthnumberNoHops from the seeds, 1 to 3, default 1. At depth 2 or 3 without min_weight, the engine keeps only links of weight 0.05 and up at every hop
domainstringNoA shared room's address (xroom:...) to read that room's graph instead of your own; any other value has no effect here
min_weightnumberNoOnly links at or above this weight; pass 0 to see every link at every depth
limitnumberNoMaximum links returned, 1 to 500, default 100

The reply lists the concepts, the links with their weight, valence, count and last update, and says when the list was cut at limit. The same read is available over the REST API as POST /memory/graph.

Shared rooms (Beta) ​

Beyond your private memory, Claude can share a memory pool with other people's assistants through a room. Four Beta tools — memory_create_room, memory_invite_to_room (which mints a share code, mnvr_..., single-use unless minted with max_uses), memory_join_room, and memory_list_rooms — let Claude spin up a room, invite someone, join one, and re-find the ones you already have: it returns each room's name and its xroom:<room_id> address, which is exactly the value to pass as domain on memory_write / memory_read. Both the local server and the hosted connector accept max_uses (1 to 1000). Members then read and write the shared pool by passing domain: "xroom:<room_id>" on memory_write / memory_read. See Join a shared room for the full owner-and-joiner flow.

What to Remember ​

CategoryExample
Preferences"User prefers dark mode", "Always use pnpm, not npm"
Project context"This repo uses PostgreSQL + Prisma", "Deploy target is Railway"
Lessons learned"Never deploy on Fridays", "Run tests before push"
Decisions"Chose REST over GraphQL for caching simplicity"
People"Alice owns the design system", "Bob reviews all API changes"
Patterns"Exponential backoff fixed timeout issues in this service"

Universal Memory ​

Same Mnemoverse account, same memories, in every tool. Claude and the editors connect with an API key or OAuth. ChatGPT's MCP connector signs in with OAuth instead of a key, while a Custom GPT uses an API key, so sign in with the Mnemoverse account your other tools use.

text
                    ┌── Claude Code ← you are here
                    ├── Claude Desktop / web / mobile
   Mnemoverse API ──├── Cursor / VS Code / Devin Desktop
   (one memory)     ├── ChatGPT
                    └── Python SDK / REST

Write a memory in Claude Code → ChatGPT reads it. Learn something in Cursor → Claude Code recalls it.

Configuration ​

VariableRequiredDefault
MNEMOVERSE_API_KEYYes—
MNEMOVERSE_API_URLNohttps://core.mnemoverse.com/api/v1

MNEMOVERSE_API_URL is the REST backend the local server talks to — it is not an MCP endpoint; never paste it into a connector-URL field. A remote MCP connector uses https://mcp.mnemoverse.com/mcp (Remote MCP Server).

Troubleshooting ​

The server shows Failed to connect ​

Check the status from your shell with claude mcp list, or with /mcp inside a session. If the local server shows ✘ Failed to connect or ✘ Connection error, work through these steps in order. Both statuses mean the server did not start.

  1. Wait and check again. Right after you add it, the first check can show ✘ Failed to connect while npx downloads the package. Run claude mcp list again after a moment. If the first download takes longer than the default 30-second startup limit, start Claude Code with a longer MCP_TIMEOUT, in milliseconds: MCP_TIMEOUT=60000 claude in bash, or $env:MCP_TIMEOUT = "60000"; claude in PowerShell.

  2. Read the error detail. Run claude mcp get mnemoverse. It prints the scope, the command Claude Code runs, and any error detail. ✘ Connection error never comes with detail, and Claude Code versions before 2.1.219 show only the bare ✘ Failed to connect status. In either case, go straight to the next step.

  3. Run the server command yourself. The same line parses in bash and PowerShell:

    bash
    npx -y @mnemoverse/mcp-memory-server@latest

    In PowerShell, if it fails with "running scripts is disabled on this system", the execution policy is blocking the npx.ps1 wrapper, not Node.js. Run npx.cmd -y @mnemoverse/mcp-memory-server@latest instead.

    If it starts and waits for input, the server works. Stop it with Ctrl+C and compare it with the command claude mcp get mnemoverse shows. If the two differ, the -- before npx was probably left out: remove the server and add it again. If npx is not recognized, or the error names Node.js, install Node.js 18 or later, open a new terminal, and try again.

  4. Remove the old entry before adding it again. Running claude mcp add with a name that already exists at the same scope fails with an "already exists" error. Remove it first, run the add command at the top of this page again, then restart the Claude Code session:

    bash
    claude mcp remove mnemoverse

    If remove reports that the name exists in multiple scopes, name the one to delete, for example claude mcp remove mnemoverse -s local.

  5. Check which scope wins. Claude Code resolves a server name once, local scope over project scope over user scope, and uses that entry whole. Run claude mcp get mnemoverse from the project directory: if Scope says local or project although you added the server at user scope, an older entry with the same name is shadowing yours, and a stale command path in it shows up only as ✘ Connection error. Remove that entry with claude mcp remove mnemoverse -s local (or -s project) and check again. Entries are keyed by project path, so a repository moved back to an old path brings an old entry back with it.

If you would rather not run anything on your machine, use the OAuth connector instead.

The server is connected but every memory call fails ​

The local server starts even when the key is missing or wrong, so a key problem does not show up as ✘ Failed to connect. With no key set, each memory tool returns an error saying that no API key is configured. With a key the API rejects, each call fails and the server prints one line to stderr at startup that begins Mnemoverse: API key rejected and names MNEMOVERSE_API_KEY. The direct way to see that line is to run the server yourself with the same key, as in step 3 above.

In bash:

bash
MNEMOVERSE_API_KEY=mk_live_YOUR_KEY npx -y @mnemoverse/mcp-memory-server@latest

In PowerShell:

powershell
$env:MNEMOVERSE_API_KEY = "mk_live_YOUR_KEY"; npx -y @mnemoverse/mcp-memory-server@latest

If PowerShell reports "running scripts is disabled on this system", use npx.cmd in place of npx, as in step 3: $env:MNEMOVERSE_API_KEY = "mk_live_YOUR_KEY"; npx.cmd -y @mnemoverse/mcp-memory-server@latest.

If the API rejects the key, the line appears in your terminal. Stop the server with Ctrl+C. Anthropic's troubleshooting guide also names claude --debug=mcp as the way to read a server's stderr, in the debug log at ~/.claude/debug/<session-id>.txt. Fix the key with the remove-and-add steps above; keys start with mk_live_ and come from console.mnemoverse.com.

Memory keeps disconnecting ​

There are two ways Claude reaches Mnemoverse, and they fail differently.

The OAuth connector (https://mcp.mnemoverse.com/mcp — added as a claude.ai connector, which Claude Code picks up automatically, or with claude mcp add -s user --transport http and signed in via /mcp) is held by the host app's sign-in. Signing out, switching accounts, or the app re-authenticating you typically drops it, and exactly what happens is up to the host; a token that fails to refresh looks the same from the outside. The memory tools quietly vanish until you sign in again (/mcp → Re-authenticate in the CLI, or the connector settings on claude.ai). If your memory "keeps falling off", this is the connection to suspect first. Your memories are untouched: see what an account switch does to your connection.

The local server (the claude mcp add command at the top of this page) is a process on your machine with its own API key. It does not depend on any claude.ai login: you can sign out, switch accounts, or relogin as often as you like and memory stays up. If the connector keeps dropping, switching to the local install is the durable fix — one command, and the same memories, provided the key comes from the Mnemoverse account you signed in with (see the next question): both paths resolve to that account, not to the key itself.

To check what you are running: claude mcp list shows each configured server with its health, the local one under its npx command; claude mcp get <name> prints its Scope and Type: stdio. One trap if you have tried both paths: any claude mcp add run without a scope flag registers the server in local scope, and local scope takes precedence over a user-scoped server of the same name in that directory. Remove it first with claude mcp remove <name> -s local. After adding the local server, restart the Claude Code session so the tools load.

I switched to the local server and my memories or rooms are gone ​

The API key decides which account you are. Memories and shared rooms live in the account that stored them, so a key created in a different console account lands you in a fresh, empty store: memory_stats reports zero and memory_list_rooms shows nothing, with no error anywhere (a first memory_read on such a store answers "Your long-term memory is empty — nothing has been saved yet"). If you previously connected through OAuth, make sure the key comes from the same account you signed in with, and for shared rooms, the account behind the key must itself be a member: an invite accepted under one identity does not follow the key of another.

The tools are configured but Claude never uses them ​

That is a different problem: Claude has the tools but no rules for when to use them. Run /mcp__mnemoverse__setup_memory to get the memory rules for CLAUDE.md, or copy them from Make Your Agent Use Memory.

Source & Distribution ​

npm versionMCP Registry

The MCP server is also listed on the Official MCP Registry. Source on GitHub under MIT.