Skip to content
Wenlan

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.

Qi-Xuan LuUpdated 8 min read

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.

One entity in the memory graph
{
  "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.
Claude Code and Codex
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-memory

04

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.

Cursor or Claude Desktop JSON
{
  "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.

ServerHow it stores and searchesRunsGood for
Official memory serverKnowledge graph in one JSONL file; text searchLocalA simple start and learning how MCP memory works
Mem0 (about 67,000 stars)Memory platform with semantic search; hosted MCP serverHosted, or self-host Mem0Apps and agents that need managed memory
Basic Memory (about 4,100 stars)Markdown files you can open and edit, for example in ObsidianLocal, with an optional cloud versionNotes you want to read and edit yourself
mcp-memory-service (about 2,000 stars)Semantic search over stored memories; SQLite locally or CloudflareLocal or cloudSemantic recall shared across agents and frameworks
codebase-memory-mcp (about 46,000 stars)Indexes your code into a knowledge graphLocalCode structure, not decisions or preferences
WenlanLocal memories plus wiki pages that cite their sources and flag when a source changesLocalProject knowledge you want to read, check, and share across tools
Compare Wenlan with mcp-memory-service

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.

See how memories become source-backed wiki pages

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.

Connect MCP clients to Wenlan
npx -y wenlan setup
~/.wenlan/bin/wenlan connect claude-code
~/.wenlan/bin/wenlan connect cursor
~/.wenlan/bin/wenlan connect codex
# also: claude-desktop, vscode, gemini

Read all MCP client setup paths

09

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.
Gemini CLI and VS Code setup
~/.wenlan/bin/wenlan connect gemini
gemini mcp list
~/.wenlan/bin/wenlan connect vscode --dry-run

11

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.
Daemon and MCP checks
~/.wenlan/bin/wenlan status
~/.wenlan/bin/wenlan doctor
~/.wenlan/bin/wenlan connect codex --dry-run
lsof -nP -iTCP:7878 -sTCP:LISTEN

Use 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

What is an MCP memory server?+
A server that stores memories and exposes them as MCP tools, so AI clients such as Claude Code, Cursor, and Codex can save and recall information across sessions.
Where does the MCP memory server store data?+
The official server writes one JSONL file. By default it is memory.jsonl in the server's folder; set MEMORY_FILE_PATH to choose the location.
Can Claude Code and Cursor share one MCP memory server?+
Yes, they can use the same MEMORY_FILE_PATH for sequential access. Separate local stdio server processes do not coordinate concurrent writes, so avoid simultaneous writers or use one coordinated service if both clients need to write at the same time. Both clients can also connect to the same Wenlan install.
Is an MCP memory server the same as RAG?+
No. MCP is how the client talks to the server. RAG is one way a server can search. Some memory servers use semantic search; the official one uses plain text matching.
Can I change Wenlan's daemon port?+
Yes for development, but the daemon port, bind address, CLI target, and MCP connector target are separate settings. Update the daemon and connector together, usually with an isolated data directory. For example, point the connector elsewhere with wenlan-mcp --origin-url http://127.0.0.1:7879.
Does Claude Code need an MCP memory server?+
Not always. Claude Code has CLAUDE.md and auto memory built in. Add an MCP memory server when you want the same memory in other tools or need more control over what is stored.

Share this guide