Memory

Memory is one of the official MCP reference servers from Anthropic. It gives any MCP-compatible agent a persistent knowledge graph backed by a plain JSON file. No database to configure, no cloud account to create. Entities, observations, and the relationships between them all live in a local file that survives between sessions.

Most AI agents are amnesiac by default. You tell Claude something important in one session and it's gone by the next. This isn't a model limitation, it's an architecture limitation. Models don't store state between API calls. If you want continuity, you have to build it.

The Memory MCP server is the simplest possible solution to that problem. It's a TypeScript server, officially maintained by Anthropic, that gives any MCP-compatible agent a persistent knowledge graph stored in a local JSON file. Five tools, no database, runs in one command. If you've been looking for the easiest path to an agent that remembers things across sessions, this is it.

What Memory MCP actually does

The server implements a knowledge graph, which sounds more complex than it is. Think of it as a collection of named entities with two types of attachments: observations (facts about an entity) and relations (how one entity connects to another).

A concrete example: you might have an entity called "ProjectAlpha" with observations like "uses PostgreSQL 16", "deployed on AWS us-east-1", "release target is Q3 2026", and a relation connecting it to another entity called "TeamLead-Khalid". Next session, the agent can search for "ProjectAlpha" and get back all of that context immediately, without you repeating yourself.

The five tools the server exposes are:

• create_entities: Register one or more named entities in the graph, with an entity type and initial observations.
• add_observations: Attach new facts to an existing entity at any point. This is how the graph grows over time.
• create_relations: Define a typed relationship between two entities, like "ProjectAlpha uses Database-Postgres" or "TeamLead-Khalid owns ProjectAlpha."
• search_nodes: Query the graph by keyword. The search hits entity names, types, and the text of observations.
• read_graph: Pull the entire graph as structured JSON. Useful for giving an agent full context at the start of a session.

That's the whole surface area. There's no hidden complexity, no background sync process, no ML-powered embeddings. The graph is read and written as JSON, and search_nodes does basic text matching rather than semantic similarity search. That simplicity is a feature, not a limitation, as long as you know what you're signing up for.

Setup in under five minutes

The server is published to npm as @modelcontextprotocol/server-memory. The quickest way to try it is with npx, which means no global install required:

npx -y @modelcontextprotocol/server-memory

For a persistent setup in Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

By default the JSON file lands in your home directory. If you want to put it somewhere specific, set MEMORY_FILE_PATH in the env block:

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

Same pattern works in Claude Code if you prefer using the terminal agent. Add the server block to your Claude Code MCP config, restart, and the five tools appear. Claude Code is particularly good at using the memory tools deliberately, since you can instruct it in your CLAUDE.md to write entities for every project it touches.

That's it. Restart your client, start a session, and ask the agent to remember something. It'll call create_entities and add_observations on its own.

When a JSON file is enough

The honest answer is: for personal use and small experiments, a JSON file is completely fine.

The Memory MCP server was built to demonstrate the MCP memory pattern cleanly. It does that well. For a single developer who wants their agent to remember which projects they're working on, which tools they prefer, what context is relevant to their current work, the JSON file approach is durable, inspectable, and easy to back up. You can open the file in any text editor, read it, edit it by hand if needed, copy it to another machine.

The graph structure also happens to be the right shape for a lot of personal agent memory. Entities with typed relations map cleanly onto things like "projects and their dependencies," "people and their roles," "preferences and their contexts." You don't need a vector database to store the fact that you prefer TypeScript over JavaScript for new projects.

Where it starts to strain is when you need semantic search rather than keyword search. If you want the agent to find "the thing I told it about authentication last month" without knowing the exact words you used, text matching won't cut it. That's the point where you look at a vector-backed solution or a full memory framework.

It also strains under any kind of multi-user or multi-process scenario. The file is not protected by any locking mechanism. Two agents writing simultaneously can corrupt it. For a single-user personal setup that's not a real concern, but it rules out server deployments.

Memory MCP vs building something real

When Memory MCP is not enough, the next step depends on what you actually need.

If you want semantic similarity search on top of a persistent store, you're looking at adding a vector database like Chroma or Qdrant and using a different MCP server or building a custom integration. The graph structure of Memory MCP doesn't help here since it has no embedding layer.

If you need production-grade memory management with tiered storage, automatic context distillation, and support for multiple agents sharing a memory space, Letta is the serious option. Letta (formerly MemGPT) was built from the ground up to solve the long-term memory problem for agents. It's significantly more complex to set up and operate, but it's doing a fundamentally different job. Memory MCP stores what you tell it to store. Letta actively manages what to keep, what to compress, and what to surface based on relevance.

For most people reading this page, Memory MCP is enough. The 80% case for agent memory is "remember things I've told you about my projects and preferences." A flat knowledge graph with keyword search handles that without any infrastructure overhead. Don't add complexity you don't need yet.

Practical patterns that work well

A few usage patterns make Memory MCP meaningfully more useful than a naive "remember this" prompt:

Structured entity types. When you create entities, use consistent types. "project", "person", "tool", "preference", "task" as entity types makes search_nodes much more useful since you can scope queries to a type. An agent that creates everything as type "thing" is harder to query.

Verbose observations over sparse ones. Add enough context to each observation that it makes sense without the surrounding conversation. "Uses PostgreSQL" is less useful than "Uses PostgreSQL 16.2, hosted on RDS, connection pool size is 10." When the agent reads this back three weeks later, the detail is what makes it actionable.

A session-start read. Instruct your agent (via system prompt or CLAUDE.md if using Claude Code) to call read_graph at the start of each session and summarize what it finds. This front-loads the memory retrieval rather than hoping the agent will search at the right moment.

Relations for navigation. The create_relations tool is underused. Connecting "ProjectAlpha" to "Tech-PostgreSQL" and "Tech-AWS" means a query for "PostgreSQL" pulls back connected projects, not just entities with PostgreSQL in their observations. It's a small thing that makes the graph much more navigable as it grows.

The case for starting here

If you're looking at memory options for an agent you're building or configuring, the right move is almost always to start with Memory MCP. The cost of a wrong choice here is low because the JSON file is portable and readable. You can migrate its contents to a more sophisticated system later, or you might find you never need to.

More sophisticated memory systems carry real setup and maintenance cost. A Chroma instance requires a running process. Letta requires understanding its agent framework before you can use the memory layer. Memory MCP requires one npx command and a JSON config block. If you're at the stage of figuring out whether persistent memory even solves your problem, you want the lowest-friction experiment possible.

The MCP server directory has other options if your needs outgrow this one. The best AI agent for coding page also covers how memory fits into broader agentic workflows if you're trying to understand where this piece sits in a larger architecture.

Limitations worth knowing before you commit

The text search is case-insensitive substring matching. It is not fuzzy, not semantic, and not ranked by relevance. If your graph grows to hundreds of entities, queries that return many results become harder to work with.

There's no versioning or change history on the graph. If the agent writes something incorrect, you can't roll back to an earlier state without a manual backup. For anything where the integrity of stored facts matters, keep a backup copy of the JSON file.

The server also has no authentication layer. Whoever can connect to the MCP server can read and write the full graph. In a local personal setup this is irrelevant. In any networked deployment it's a real security consideration.

None of these are dealbreakers for the use case the server is designed for. They're limits to understand upfront so you're not surprised by them later.

Bottom line

Memory MCP is exactly what it says it is: a simple, persistent knowledge graph for agents, with no dependencies beyond a JSON file. For personal use, prototyping, and the common case of an agent that needs to remember project context and preferences across sessions, it does the job without any friction.

When you outgrow it, the upgrade path to tools like Letta is clear. But a lot of agent setups never need to go there. A plain knowledge graph in a local file, five tools, one npx command. That covers more ground than people expect.

Features

• Create and update named entities in a knowledge graph
• Attach observations to entities across multiple sessions
• Define typed relations between entities
• Search the graph by keyword or entity name
• Read the full graph as structured JSON
• Single JSON file storage with no external dependencies

How to set up the Memory MCP server

1. Run npx -y @modelcontextprotocol/server-memory to try it without installing
2. Or install with npm install -g @modelcontextprotocol/server-memory
3. Add the server block to your Claude Desktop or Claude Code MCP config
4. Optionally set MEMORY_FILE_PATH to control where the JSON file is written
5. Restart your MCP client and the memory tools appear automatically