Memory MCP Server: Install, Tools and Limits

The Memory MCP server is the official reference server for persistent agent memory. It stores a knowledge graph of entities, relations and observations in a local JSONL file, and exposes nine tools plus one resource to read and change it. It runs over stdio with npx -y @modelcontextprotocol/server-memory and needs Node 24 or later. We checked it on 31 October 2026.

Quick facts

What it does

Agents forget. A chat ends and the next one starts blank. The Memory server gives the agent a small database it can write to and read from, so it can carry facts forward: your preferred test runner, the name of a client, the reason a decision was made.

It is a graph, not a pile of notes. That shape is worth understanding because it decides how the agent should write to it.

The README asks for atomic observations: one fact each. That makes them easy to delete or replace one at a time. A long paragraph stuffed into one observation is hard to correct later.

The nine tools

The resource memory://knowledge-graph returns the same data as read_graph, as JSON. The six mutation tools send an update notification for that URI, so a client that subscribed sees changes live.

A detail that trips people up

create_entities does not merge. If John_Smith already exists, the call skips him and drops the new observations. The structured result lists the skipped names, and a second text item says which were skipped. The README points you to add_observations for extending an entity. An agent that always calls create_entities will silently lose new facts, so say so in your prompt.

Search is plain text matching

search_nodes looks across names, types and observation content for your query. The README does not describe embeddings, ranking or fuzzy matching. In the source, search_nodes lowercases the query and checks whether it appears inside an entity name, type or observation, so it is a case-insensitive substring match. If you want semantic recall across thousands of notes, this is the wrong tool; see the alternatives below.

Install it

The README documents Claude Desktop (npx and Docker) and VS Code. Lines for other agents are our adaptation from each agent's MCP docs. See MCP clients for field names.

Quick test:

npx -y @modelcontextprotocol/server-memory

It prints at most a startup line and then waits, which is normal for a stdio server. To browse its tools, use the Inspector:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-memory

Install it in each agent

Claude Code

Our adaptation, with a fixed file location so memory does not depend on where npx puts the package:

claude mcp add memory -e MEMORY_FILE_PATH="$HOME/.agent-memory/memory.jsonl" \
  -- npx -y @modelcontextprotocol/server-memory

Make the folder first with mkdir -p ~/.agent-memory. The README says the directory must be writable, because the server saves atomically and takes a lock file beside the data file.

Codex

Our adaptation, in ~/.codex/config.toml:

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

[mcp_servers.memory.env]
MEMORY_FILE_PATH = "/Users/you/.agent-memory/memory.jsonl"

Cursor

Our adaptation, in .cursor/mcp.json or the global file, using the README's Claude Desktop shape:

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

Antigravity

Our adaptation. Put the same entry under mcpServers in ~/.gemini/config/mcp_config.json. The server is stdio only, so use command and args, not serverUrl. Gemini CLI is now for Code Assist enterprise customers only, so we cover Antigravity instead.

OpenCode

Our adaptation, in opencode.json:

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-memory"],
      "environment": { "MEMORY_FILE_PATH": "/Users/you/.agent-memory/memory.jsonl" }
    }
  }
}

Docker and VS Code

The README's Docker entry keeps the graph in a named volume:

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

For VS Code, the README gives .vscode/mcp.json entries for npx and Docker, or you can use the user configuration through the Command Palette. On Windows, wrap npx with cmd /c, as the README shows.

Telling the agent how to use it

The server stores memory. It does not decide when to. The README says so directly: the system prompt controls the frequency and type of memories created. Without instructions, many agents will call the tools rarely or never.

The README's sample prompt, meant for the Custom Instructions field of a Claude.ai Project, has a clear structure:

1. Identify the user. Assume a default user and try to confirm it.
2. Retrieve first. Start each chat by retrieving relevant information from the graph, and refer to it as "memory".
3. Watch for new information in five groups: basic identity, behaviours, preferences, goals and relationships up to three degrees out.
4. Update when you learn something. Create entities for recurring people, organisations and events, connect them with relations, and store facts as observations.

For a coding agent, adapt this. Put a short version in the project's instruction file, such as CLAUDE.md or AGENTS.md, and narrow it to what a developer wants remembered:

## Memory
At the start of a task, call search_nodes with the repo name and the task topic.
Store only: decisions and the reason, user preferences about code style,
and recurring commands. One fact per observation.
Use add_observations for existing entities. Never store secrets or tokens.

That last line matters. See the security notes.

What a graph looks like in practice

These are our examples, built from the README's data model. We did not run them. Say you tell a coding agent that your team prefers Vitest over Jest on the billing-api repo, and that you chose it because the Jest run took too long in CI. A tidy agent would create one entity per thing that recurs and hang facts off it:

{
  "entities": [
    { "name": "billing-api", "entityType": "repository",
      "observations": ["Test runner is Vitest", "Moved from Jest because CI runs were slow"] },
    { "name": "Vitest", "entityType": "tool", "observations": ["Preferred test runner"] }
  ],
  "relations": [
    { "from": "billing-api", "to": "Vitest", "relationType": "uses" }
  ]
}

Next week, a new chat starts with a search_nodes call for "billing-api" and the agent already knows the runner and the reason. If you later switch runners, the agent should call delete_observations on the old line and add_observations with the new one. If it calls create_entities again for billing-api, nothing changes, which is the trap described above.

Entity names are the only identifier, so pick a naming habit and tell the agent. billing-api and Billing API would be two separate nodes, and searches may miss one of them. Lower-case with hyphens for repositories, and First_Last for people, as the README's example does, is a fair starting rule.

Sharing one file between clients

Each client starts its own server process. So Claude Code and Cursor, pointed at the same MEMORY_FILE_PATH, are two processes writing one file. The README describes how this is handled:

• Every write tool takes an exclusive lock file, <memory file>.lock, while it reads, changes and saves the graph. Writes from different processes take turns.
• A lock left by a crashed server is removed automatically: at once if the process is known to have exited on the same machine, otherwise after 30 seconds without a refresh. A live server refreshes its lock every 15 seconds.
• A write that cannot get the lock in 60 seconds fails with a tool error instead of overwriting the file.
• The lock needs exclusive file creation. A network filesystem that does not honour it cannot be shared this way.

Read from the other direction: do not put the file on a flaky network drive and point three machines at it.

There is also a migration detail. If MEMORY_FILE_PATH is not set and the server directory holds an old memory.json but no memory.jsonl, the server renames it to .jsonl at startup, and exits with an error if the rename fails.

Security and privacy notes

1. It stores what the agent writes. If the agent saves a token, a customer name or a private note, it sits in plain text in the JSONL file. The server has no encryption and no redaction.
2. Tell it what never to store. Put "never store secrets, keys or personal data about third parties" in your instructions.
3. Treat recalled memory as untrusted input. Whatever got written once comes back into every later chat. If a web page or a file once tricked the agent into saving a hostile instruction as an observation, that instruction returns later as "memory". Review the graph now and then with read_graph or by opening the file.
4. Back up and review the file. It is a plain text file you own. You can read it, diff it in git, or delete it.
5. Scope per project. One global graph mixes work for different clients. Use a separate MEMORY_FILE_PATH per project if that matters.
6. No auth, local only. It opens no port. The risk is the file, not the network.
7. Reference status. The monorepo README says its servers are examples and not production-ready.

Limits and known issues

• No semantic search. See above.
• Whole-graph reads. read_graph returns everything. A graph with thousands of entities would fill an agent's context. Prefer search_nodes and open_nodes.
• No built-in expiry. Nothing ages out. Stale facts stay until someone deletes them.
• No update-in-place tool. To change a fact, delete the observation and add a new one.
• Node 24 or later. An older Node on your machine will fail. Docker avoids the requirement.
• Licence in transition. The LICENSE text now covers MIT and Apache-2.0, so GitHub shows no SPDX id.
• Open issues. The servers repository showed 34 open issues when we checked, across all reference servers. We did not read them.

Alternatives

For a wider list, see our best MCP servers page.

Our take

We did not run this server for this page. This comes from the README and the repo data.

It is a clean teaching example and a usable personal notepad. The graph model is simple enough to read by eye, and the lock-file handling is more careful than we expected from a reference server. For one developer on one machine, with a prompt that says what to store, it works as a lightweight memory.

It is not a knowledge base. There is no semantic search, no expiry and no access control, and the agent decides what to write. If your agent already loads a project instruction file each session, you may find that file does the same job with less machinery. Reach for the Memory server when you want the agent itself to add and retrieve facts across tools, such as Claude Code and Cursor sharing one file.

A short setup checklist

1. Make a folder for the memory file and set MEMORY_FILE_PATH.
2. Add the server to one agent first.
3. Add a short memory section to the project instructions, including what never to store.
4. Ask the agent to remember one test fact, then open the JSONL file and confirm it is there.
5. Start a new chat and ask the agent to recall it.
6. Review the file after a week and delete anything you would not want read back.

Frequently asked questions

What does the Memory MCP server do?

It keeps a knowledge graph of entities, relations and observations in a local file, and gives the agent tools to add, search and delete them, so facts survive between chats.

Where is the memory stored?

In a JSONL file. By default it is memory.jsonl in the server directory. Set MEMORY_FILE_PATH to choose a location.

Does the agent save memories by itself?

Only if you tell it to. The README says the system prompt decides how often and what kinds of memory the model creates, and gives a sample prompt.

Can two agents share one memory file?

Yes on a local disk. Write tools take a lock file so writes from different processes take turns. A network filesystem that ignores exclusive file creation is not safe.

What Node version does it need?

Node.js 24 or later when run through npx or from source.