How to set up the Memory MCP server in Claude Code, Claude Desktop, Cursor, VS Code and Codex

Quick answer

1. Install Node.js 24 or later. The server needs it when it runs through npx.
2. Create a folder for the memory file, for example ~/.mcp-memory. The server creates the file but not the folder.
3. Add the server with npx -y @modelcontextprotocol/server-memory and set MEMORY_FILE_PATH to an absolute path such as ~/.mcp-memory/memory.jsonl. In Claude Code: claude mcp add memory --scope user --env MEMORY_FILE_PATH=$HOME/.mcp-memory/memory.jsonl -- npx -y @modelcontextprotocol/server-memory.
4. Tell the assistant when to save and recall memories (a short instruction is enough), then restart the client.

Skipping MEMORY_FILE_PATH is the classic mistake. The default file sits inside npm's package cache, so an update or a cleared npx cache can delete everything the assistant has remembered.

What the Memory server does

The server stores a knowledge graph with three kinds of data:

• Entities: named things with a type, such as a person, a project or an organization.
• Relations: directed links between entities, written in active voice, such as works_at.
• Observations: short facts attached to an entity, one fact each, such as "Prefers morning meetings".

The assistant reads and writes the graph through MCP tools. Nothing is stored in the cloud by the server itself: the graph lives in one local file in JSON Lines format. It is "memory" in a basic sense. The assistant has to decide to save something and to look it up again, which is why the instruction in step 4 matters. For a shorter overview, see the Memory MCP Server listing.

Before you start: choose where the memory file lives

MEMORY_FILE_PATH sets the file. If you leave it out, the server uses memory.jsonl in its own package directory. Under npx or an npm install, that directory is inside a node_modules tree that npm manages, so reinstalling or updating the server, or clearing the npx cache, can delete the file. A relative path has the same problem, because it resolves against that same directory.

• Use an absolute path in a folder you own. A leading ~ expands to your home directory, so ~/.mcp-memory/memory.jsonl works in the JSON and TOML configs below.
• Create the folder first: mkdir -p ~/.mcp-memory on macOS or Linux. The server creates the file, not the folders above it.
• If the server finds its memory file inside node_modules, it prints a warning on stderr at startup naming the file. Most clients show this in the server's log.
• Already have a graph in the default location? Move the file to the new path when you set the variable, or the server starts with an empty graph.

Claude Code

mkdir -p ~/.mcp-memory
claude mcp add memory --scope user --env MEMORY_FILE_PATH=$HOME/.mcp-memory/memory.jsonl \
  -- npx -y @modelcontextprotocol/server-memory

--scope user makes the server available in every project. Leave it out to add it to the current project only. Everything after -- is the command that starts the server. Your shell fills in $HOME when you run the command, so the saved config has the full path. Run claude mcp get memory to check the command and path, then /mcp inside Claude Code to see it connected. More on Claude Code: the best MCP servers for Claude Code.

Claude Desktop

Add this to claude_desktop_config.json, then fully quit and reopen Claude Desktop. If you haven't edited that file before, see how to add an MCP server to Claude Desktop for where it is.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "~/.mcp-memory/memory.jsonl"
      }
    }
  }
}

On Windows, the README launches npx through cmd /c. In JSON, backslashes in the path must be doubled:

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "C:\\Users\\you\\.mcp-memory\\memory.jsonl"
      }
    }
  }
}

Cursor

Cursor uses the same mcpServers block. Put it in ~/.cursor/mcp.json to use memory in all projects, or .cursor/mcp.json in one project, then restart Cursor and check the server is switched on under Customize > MCPs. Details: how to add an MCP server to Cursor.

VS Code

The server's README gives this block for VS Code's own format (top-level servers), in your user mcp.json (Command Palette > MCP: Open User Configuration) or .vscode/mcp.json in a workspace:

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "~/.mcp-memory/memory.jsonl"
      }
    }
  }
}

VS Code also reads the portable mcpServers format, and the two don't mix in one file. See how to add an MCP server to VS Code for which file uses which key.

Codex

codex mcp add memory --env MEMORY_FILE_PATH=$HOME/.mcp-memory/memory.jsonl -- npx -y @modelcontextprotocol/server-memory

Or add it to ~/.codex/config.toml yourself:

[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]

[mcp_servers.memory.env]
MEMORY_FILE_PATH = "~/.mcp-memory/memory.jsonl"

More on Codex config: how to add an MCP server to Codex.

Docker

The README's Docker setup mounts a named volume over the image's code directory, /app/dist, so the graph survives restarts:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

The catch: that volume also holds the server's code, and Docker only copies an image's files into a named volume while it is empty. After the first run, pulling a newer image does not update the server in the volume. The README's alternative keeps the graph in a volume of its own, so a new image takes effect with no extra step:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory-data:/data", "-e", "MEMORY_FILE_PATH=/data/memory.jsonl", "--rm", "mcp/memory"]
    }
  }
}

To move an existing graph from the old volume to the new one, quit the clients that start the server, then run:

docker run --rm -v claude-memory:/old -v claude-memory-data:/data \
  --entrypoint cp mcp/memory /old/memory.jsonl /data/memory.jsonl

If you stay on the original setup, the README has an upgrade command that replaces the code in the volume and keeps memory.jsonl (see Troubleshooting below for the EACCES error it also fixes).

Tell the assistant when to use memory

The server only provides the tools. How often the assistant saves and recalls things depends on your instructions. The README's example is written for chat personalization and goes in a Claude.ai Project's custom instructions. For a coding agent, a few lines in the place it reads standing instructions (such as CLAUDE.md or AGENTS.md) do the same job. A short version:

At the start of a task, search your memory for anything relevant to this project.
When I tell you a lasting preference or a fact about this project, save it to memory
as an observation on the right entity. Keep each observation to one fact.

Not sure which instructions file your tool reads? See Cursor rules vs AGENTS.md.

The tools it adds

• create_entities: add entities. Names that already exist are skipped (their observations are not added), and the result lists what was skipped.
• create_relations: link two existing entities. Duplicates are skipped; it fails if either entity doesn't exist.
• add_observations: add facts to existing entities.
• delete_entities: remove entities and every relation that touches them.
• delete_observations and delete_relations: remove single facts or links. A relation is only deleted when from, to and relationType all match exactly.
• read_graph: read the whole graph. observationLimit: 0 returns names, types and counts only, which is a cheap overview of a large graph. entityTypes filters by type.
• search_nodes: search names, types and observation text. Optional limit and observationLimit.
• open_nodes: read specific entities by name.

The whole graph is also available as an MCP resource, memory://knowledge-graph, and the write tools send update notifications for it to clients that subscribe.

Using one memory file from several clients

Each client starts its own server process, so Claude Desktop and Claude Code pointed at the same MEMORY_FILE_PATH are two processes writing one file. The write tools take a lock file (<memory file>.lock) next to the memory file, so writes take turns instead of overwriting each other. Saves are atomic, so a server killed mid-save leaves the previous graph intact.

• The folder holding the memory file must be writable, because the lock file and the temporary save file go there.
• A write that can't get the lock within 60 seconds fails with a tool error rather than overwriting the file.
• The lock relies on local-filesystem behavior. Don't share one memory file over a network drive.

Check that it works

1. Restart the client and check the memory server is connected (/mcp in Claude Code, the MCP list in Cursor or VS Code).
2. Ask: "Remember that my main project uses Next.js and Supabase." The assistant should call create_entities or add_observations.
3. Open the file at your MEMORY_FILE_PATH and check the new entry is there.
4. Start a new chat and ask: "What do you remember about my main project?" It should call search_nodes or open_nodes and answer from memory.

Troubleshooting

• The memory was gone after an update: the file was in the default location inside node_modules. Set MEMORY_FILE_PATH to an absolute path outside it. Check the server log for the startup warning that names the file it is using.
• The server won't start: check node --version. The current version needs Node.js 24 or later when it runs through npx. Also check that the folder in MEMORY_FILE_PATH exists.
• `spawn npx ENOENT` on Windows: use the cmd /c config above, or see fix spawn npx ENOENT.
• "Connection closed" (MCP error -32000): this usually means the server process exited at startup. Run the command from your config in a terminal to see the real error, and see fix MCP error -32000.
• It exits with an error naming `memory.json` and `memory.jsonl`: with no MEMORY_FILE_PATH, the server renames an old memory.json to memory.jsonl at startup, and stops if that fails rather than starting on an empty graph. Fix the cause (often permissions) and restart, or set MEMORY_FILE_PATH.
• A write fails after about a minute: another server process held the lock for 60 seconds. A lock left by a crashed server is removed automatically (at once if its process is known to have exited on the same machine, otherwise after 30 seconds without a refresh). Check that the file isn't on a network drive.
• `delete_relations` deletes nothing: the relationType must match the stored one exactly. Read it with open_nodes first.
• Docker save fails with `EACCES`: the image runs as the unprivileged node user, and a volume created by an older image is owned by root. The README's upgrade command fixes ownership and replaces the code: docker run --rm -v claude-memory:/volume --user root --entrypoint sh mcp/memory -c 'rm -f /volume/*.js && cp /app/dist/*.js /volume/ && chown -R node:node /volume'.

FAQ

Is the Memory MCP server local and free?

Yes. It runs on your machine and stores the graph in a local file, with no account or API key. Anything the assistant reads from memory becomes part of the conversation it sends to your model provider, so keep secrets out of it.

Where is memory.jsonl stored by default?

In the server's own package directory, which under npx is inside npm's cache. That is why setting MEMORY_FILE_PATH is worth the extra line.

Can I edit or back up the memory file?

It's a plain file at the path you chose, so you can copy it like any other file. To change the graph, the safest route is to ask the assistant to use the delete and add tools, which take the write lock.

Does it work with Claude Desktop and Claude Code at the same time?

Yes, if both point at the same absolute MEMORY_FILE_PATH. The lock file keeps their writes from overwriting each other.