Protocol
MCP Memory Server: How It Works, Setup for Claude Code and Cursor, and Which One to Use
What an MCP memory server is, how to set up the official memory server in Claude Code, Codex, Cursor, and VS Code, where it stores data, and how the popular options compare.
01
An MCP memory server stores what your AI should remember and lets any MCP client read and write it.
02
The official server is a small knowledge graph saved to one JSONL file. Set MEMORY_FILE_PATH so the file doesn't get lost.
03
Pick a server by where memory lives, how it searches, and whether you need to read and check what it remembers.
01
Quick answer
An MCP memory server is a program that stores memories and exposes them as tools through the Model Context Protocol (MCP). Claude Code, Cursor, Codex, VS Code, Claude Desktop, and other MCP clients can call those tools to save something and look it up later, so memory outlasts one chat and can be shared between tools.
The best-known one is Anthropic's Knowledge Graph Memory Server (@modelcontextprotocol/server-memory) in the official MCP servers repository. It is a good place to start; other servers add semantic search, Markdown notes, hosting, or source tracking.
02
How the official memory server works
The official server stores a knowledge graph with three parts. Entities are things such as a person, a project, or a tool. Relations connect two entities, such as "Alice works_at Acme". Observations are single facts attached to an entity, such as "prefers pnpm".
It gives the AI nine tools: create_entities, create_relations, add_observations, delete_entities, delete_observations, delete_relations, read_graph, search_nodes, and open_nodes. search_nodes matches text in names, types, and observations; it is not semantic search.
{
"name": "wenlan-site",
"entityType": "project",
"observations": ["Uses pnpm", "Deployed on Vercel"]
}03
Add the memory server to Claude Code, Codex, Cursor, or VS Code
Each client needs the same command, npx -y @modelcontextprotocol/server-memory, plus a MEMORY_FILE_PATH that points to a file you control. Create the file's parent directory before starting the server; this also applies when you set the path in a client's JSON config. Restart the client or start a new session after adding it.
- Cursor: add a "memory" entry under mcpServers in ~/.cursor/mcp.json, or .cursor/mcp.json for one project.
- VS Code: add it under servers in .vscode/mcp.json, or use the install button in the server's README.
- Claude Desktop: add it under mcpServers in claude_desktop_config.json.
- Docker: the README also shows a docker run command using the mcp/memory image and a named volume.
mkdir -p "$HOME/.mcp-memory"
claude mcp add memory -e MEMORY_FILE_PATH=$HOME/.mcp-memory/memory.jsonl \
-- npx -y @modelcontextprotocol/server-memory
codex mcp add memory --env MEMORY_FILE_PATH="$HOME/.mcp-memory/memory.jsonl" \
-- npx -y @modelcontextprotocol/server-memory04
Where the MCP memory server stores data
Everything lives in one JSONL file. If you don't set MEMORY_FILE_PATH, the file is memory.jsonl in the server's own folder. With npx, that folder is inside the npm cache, which can be cleared or replaced on update. Set MEMORY_FILE_PATH to a path you back up.
Because it's one file per path, clients can reuse the same MEMORY_FILE_PATH sequentially. In local stdio setups, each client usually starts its own server process, and each process has its own mutation queue; writes from separate processes are not coordinated. Avoid simultaneous writes to the same file, or route clients through one coordinated service. Give each project its own path if you don't want memories to mix.
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": { "MEMORY_FILE_PATH": "/Users/you/.mcp-memory/memory.jsonl" }
}
}
}05
Make the AI actually use it
Adding the server only makes the tools available. The AI decides when to call them, and many sessions never do. Tell it when to read and write memory in your instructions file: CLAUDE.md for Claude Code, AGENTS.md for Codex, or Cursor rules.
- At the start of a task, search memory for the project name before asking me for context.
- When I state a preference or we make a decision, save it as an observation.
- Keep one fact per observation, and don't save secrets.
06
MCP memory servers compared
The servers differ mostly in where memory lives and how they find it. GitHub star counts are from October 2026.
| Server | How it stores and searches | Runs | Good for |
|---|---|---|---|
| Official memory server | Knowledge graph in one JSONL file; text search | Local | A simple start and learning how MCP memory works |
| Mem0 (about 67,000 stars) | Memory platform with semantic search; hosted MCP server | Hosted, or self-host Mem0 | Apps and agents that need managed memory |
| Basic Memory (about 4,100 stars) | Markdown files you can open and edit, for example in Obsidian | Local, with an optional cloud version | Notes you want to read and edit yourself |
| mcp-memory-service (about 2,000 stars) | Semantic search over stored memories; SQLite locally or Cloudflare | Local or cloud | Semantic recall shared across agents and frameworks |
| codebase-memory-mcp (about 46,000 stars) | Indexes your code into a knowledge graph | Local | Code structure, not decisions or preferences |
| Wenlan | Local memories plus wiki pages that cite their sources and flag when a source changes | Local | Project knowledge you want to read, check, and share across tools |
07
MCP memory server vs knowledge base
A memory server keeps small facts: preferences, decisions, names. That works until you need to know where a fact came from, or the document it was based on changes. Then you want a knowledge base: memories linked to their sources, organized into pages you can read, with a way to spot outdated answers.
Wenlan is built for that second case. It keeps short memories for recall, groups related memories and documents into wiki pages that cite their sources, and marks pages for review when a source changes instead of silently overwriting them.
08
Add Wenlan as your MCP memory server
Wenlan is an open-source desktop app with a local MCP server. Install it, then connect each client you use. They all read the same local memory and pages.
Claude Code and Codex also have Wenlan plugins with commands such as /brief, /capture, /recall, and /handoff.
npx -y wenlan setup
~/.wenlan/bin/wenlan connect claude-code
~/.wenlan/bin/wenlan connect cursor
~/.wenlan/bin/wenlan connect codex
# also: claude-desktop, vscode, gemini09
Check that memory works
A configured server isn't proof that memory works. Run a small round trip before you rely on it.
- List the server tools from one MCP client and confirm the memory tools appear.
- Ask the AI to save one harmless fact, then open a new session and ask for it.
- Ask the same question from a second client to confirm they share memory.
- For a knowledge base, query one harmless source and inspect the citation, then change the source and check that the answer is flagged or updated.
10
Connect Gemini CLI and VS Code to Wenlan
Both clients use the same Wenlan daemon through MCP, so they share memory with your other tools. For terminal work, capture the conclusion and the command that proved it, not raw output.
- Gemini CLI: run ~/.wenlan/bin/wenlan connect gemini, then verify with gemini mcp list, or /mcp list inside Gemini CLI. Wenlan uses Gemini's user-scope MCP setup. Then ask Gemini to use Wenlan's brief, recall, or capture tools.
- VS Code: from the workspace root, run ~/.wenlan/bin/wenlan connect vscode. It writes .vscode/mcp.json with a servers.wenlan entry. Add --dry-run to preview the config first.
- In VS Code, confirm MCP server trust, use MCP: List Servers to start or restart the server, and enable the Wenlan tools in Chat or Agent mode.
- VS Code Remote and Dev Containers run MCP servers where they are configured. Install or configure Wenlan in the remote environment, or handle localhost forwarding on purpose.
~/.wenlan/bin/wenlan connect gemini
gemini mcp list
~/.wenlan/bin/wenlan connect vscode --dry-run11
What's running on localhost:7878? Troubleshoot Wenlan's daemon
Wenlan's daemon listens on 127.0.0.1:7878 by default. MCP clients don't talk to the database directly: they launch wenlan-mcp, and wenlan-mcp talks to the local daemon. When a tool is missing or a connection fails, check the daemon before changing every client. If something answers on 127.0.0.1:7878 and you don't use Wenlan, it's another local program (the Rust Book's example web server uses the same port); the lsof command below shows which process owns it.
- Run wenlan status, then wenlan doctor for a fuller setup report.
- Run wenlan connect <client> --dry-run to see the wenlan-mcp command the client should launch.
- Run lsof to see which process owns port 7878, and make sure another development daemon isn't using the wrong data directory.
- Restart the MCP client after config changes.
- Loopback avoids LAN exposure, but the port is still sensitive access to a memory API. Don't bind the daemon to a non-loopback address unless you are deliberately developing or self-hosting, and redact memory contents from diagnostics.
~/.wenlan/bin/wenlan status
~/.wenlan/bin/wenlan doctor
~/.wenlan/bin/wenlan connect codex --dry-run
lsof -nP -iTCP:7878 -sTCP:LISTENUse one local memory server for all your AI tools
Install Wenlan, connect one MCP client, and test a save-and-recall round trip before connecting the rest.
FAQ