MCP Memory Server - Persistent Context for AI Assistants

What Is the Memory MCP Server?

The Memory MCP server gives AI assistants the ability to remember information across conversations. By default, AI chat sessions are stateless - when you close a conversation and start a new one, the AI has no memory of what you discussed. The Memory server solves this by providing a persistent knowledge graph that the AI can read from and write to.

Built on the official @modelcontextprotocol/server-memory package, it stores entities, relationships, and observations in a local JSON file. This means your data stays on your machine - nothing is sent to external servers. The AI can create entities (like "Project X uses React and TypeScript"), add observations to them, and query them in future conversations.

This guide covers setup, how persistence works under the hood, practical use cases, and comparisons with other memory approaches.

Setting Up the Memory Server

Claude Desktop Setup

Add the Memory server to your Claude Desktop configuration:

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

The MEMORY_FILE_PATH environment variable controls where the knowledge graph is stored. If omitted, it defaults to a file in the server's working directory. We strongly recommend setting an explicit path so your memory persists across npx updates.

Cursor Setup

Add the server to your Cursor MCP configuration at .cursor/mcp.json:

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

Using a project-relative path (like ./memory/project-memory.json) is ideal for Cursor because each project gets its own memory. Add the memory directory to your .gitignore if the memory contains sensitive information.

Verifying the Setup

After restarting your client, ask the AI: "What tools do you have for memory?" It should list tools like create_entities, add_observations, search_nodes, and open_nodes. If these don't appear, check the tools not showing troubleshooting guide.

How Persistence Works

The Memory server uses a simple but effective file-based storage system. All data is stored as a JSON file on disk with this structure:

{
  "entities": [
    {
      "name": "ProjectAlpha",
      "entityType": "project",
      "observations": [
        "Uses React 19 with TypeScript",
        "Deployed on Vercel",
        "Database is PostgreSQL on Supabase",
        "Has 3 team members: Alice, Bob, Charlie"
      ]
    },
    {
      "name": "Alice",
      "entityType": "person",
      "observations": [
        "Frontend lead on ProjectAlpha",
        "Prefers functional components",
        "Timezone: PST"
      ]
    }
  ],
  "relations": [
    {
      "from": "Alice",
      "to": "ProjectAlpha",
      "relationType": "works_on"
    }
  ]
}

Every time the AI creates an entity or adds an observation, the entire JSON file is rewritten. This is simple and reliable for typical usage (hundreds of entities), but may become slow with thousands of entries. The file is human-readable, so you can also edit it manually.

Important: The Memory server reads from and writes to this file on every operation. If you delete the file, all memory is lost. Back up important memory files regularly.

Use Cases

1. Project Context

The most common use case is storing project details so the AI remembers your tech stack, architecture decisions, and team conventions across sessions. Instead of re-explaining your project every time, you tell the AI once and it remembers.

You: "Remember that our project uses Next.js 15 with App Router,
      Tailwind CSS, and Drizzle ORM with PostgreSQL."

AI: [Creates entity "CurrentProject" with these observations]

--- Next conversation ---

You: "Add a new API route for user profiles."

AI: [Checks memory, sees Next.js 15 + App Router + Drizzle]
    "I'll create a route handler at app/api/profiles/route.ts
     using Drizzle ORM for the database queries..."

2. Conversation Memory

Store key decisions and action items from previous conversations. The AI can track what you discussed, what was decided, and what's still pending.

3. Knowledge Graphs

Build structured knowledge about your codebase, team, or domain. The Memory server's entity-relationship model is essentially a simple knowledge graph. Entities can represent anything - people, projects, services, APIs, bugs - and relationships connect them.

4. Personal Preferences

Store coding preferences so the AI adapts to your style: "I prefer single quotes in TypeScript", "Always use named exports", "Use early returns instead of nested if-else". Once stored, the AI applies these preferences automatically.

5. Meeting Notes and Action Items

After meetings, ask the AI to store key decisions and action items. In the next session, ask "What action items do we have?" and the AI retrieves them from memory.

Comparison with Other Memory Approaches

Approach	Persistence	Privacy	Best For
MCP Memory Server	Local file (permanent)	Fully local	Structured knowledge, project context
Claude Projects	Cloud (per project)	Anthropic servers	Document-heavy context
CLAUDE.md files	File in repo	Fully local	Codebase conventions, team-shared
System prompts	Per session	Varies	Fixed instructions
RAG / Vector DB	Database	Self-hosted or cloud	Large document collections

The MCP Memory server is the best choice when you want structured, queryable, fully local memory that works across any MCP-compatible client. It's lightweight, requires no infrastructure, and gives the AI granular control over what to remember and retrieve.

Tips for Effective Memory Usage

• Be explicit: Tell the AI "Remember this" or "Save this to memory" - it won't automatically save things unless instructed.
• Use entity types: Categorize entities as "project", "person", "decision", "preference" for better organization.
• Clean up periodically: Over time, memory accumulates outdated information. Periodically ask the AI to review and prune old entries.
• Separate memories per project: Use different MEMORY_FILE_PATH values for different projects to keep memories focused and relevant.
• Back up memory files: The memory file is just JSON - include it in your backup strategy. You can even version control it (minus sensitive data).

Persistence File Locations

Where the memory file is stored depends on how you configure the MEMORY_FILE_PATH environment variable. Here are the recommended locations for each platform and use case:

Use Case	macOS Path	Linux Path	Windows Path
Global memory (all projects)	/Users/you/.mcp/memory.json	/home/you/.mcp/memory.json	C:/Users/you/.mcp/memory.json
Per-project memory	./memory/project-memory.json (relative to project root, add to .gitignore)
Shared team memory	Network drive or synced folder (Dropbox, iCloud, OneDrive)

If you do not set MEMORY_FILE_PATH, the file is created in the server's working directory, which varies depending on how npx resolves the package. This makes it unreliable across restarts - always set an explicit path. Create the parent directory if it does not exist: mkdir -p ~/.mcp (macOS/Linux) or mkdir C:\Users\you\.mcp (Windows).

Knowledge Graph Patterns

The Memory server's entity-relationship model is a lightweight knowledge graph. To get the most out of it, use consistent patterns for entity types and relationship naming:

// Entity types to use consistently
"entityType": "project"     // Projects, applications, repositories
"entityType": "person"      // Team members, stakeholders, contacts
"entityType": "decision"    // Architecture decisions, design choices
"entityType": "preference"  // Coding style, tool preferences
"entityType": "service"     // APIs, databases, infrastructure
"entityType": "bug"         // Known issues, workarounds
"entityType": "meeting"     // Meeting summaries, action items

// Relationship types
"relationType": "works_on"        // person -> project
"relationType": "depends_on"      // service -> service
"relationType": "decided_in"      // decision -> meeting
"relationType": "blocked_by"      // bug -> service
"relationType": "owns"            // person -> service
"relationType": "uses"            // project -> service

When adding observations to entities, be specific and factual rather than vague. Instead of "uses modern stack," write "Uses Next.js 15 with App Router, Tailwind CSS v4, and Drizzle ORM." Specific observations are more useful for the AI when generating code or making recommendations.

Cross-Session Context

The primary value of the Memory server is providing context that persists across AI conversation sessions. Here is how to maximize this cross-session context:

• Start conversations with a memory check: Begin each session by asking the AI "What do you remember about this project?" This prompts it to query the knowledge graph and load relevant context.
• Store decisions immediately: When you make an important decision during a conversation, ask the AI to save it to memory before the conversation ends. "Remember that we decided to use Redis for session storage instead of JWT."
• Use observations for context, not full documents: The Memory server is designed for structured facts, not storing entire files or long documents. Store key takeaways, not raw content.
• Review and prune periodically: Ask the AI "Review all entities in memory and flag any that seem outdated." Remove stale information to keep the knowledge graph accurate.
• Separate personal preferences from project facts: Use the preference entity type for personal style choices. These apply globally, while project facts only matter in project context.

You can also configure multiple Memory servers pointing to different files. Use one for global preferences and another for project-specific context:

{
  "mcpServers": {
    "global-memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/you/.mcp/global-memory.json"
      }
    },
    "project-memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./memory/project-memory.json"
      }
    }
  }
}

MCP Memory Server vs RAG (Retrieval-Augmented Generation)

The Memory server is sometimes compared to RAG systems (which use vector databases and embedding search). These serve different purposes and have different trade-offs:

Aspect	MCP Memory Server	RAG / Vector Database
Data model	Structured entities + relationships	Unstructured text chunks + embeddings
Search type	Exact name/keyword matching	Semantic similarity search
Infrastructure	Single JSON file, zero dependencies	Vector DB (Pinecone, Weaviate, Chroma)
Scale	Hundreds of entities	Millions of documents
AI control	AI creates, updates, and queries data	Typically pre-loaded by developers
Best for	Project context, preferences, decisions	Large documentation, codebases, knowledge bases
Setup complexity	Add one server to MCP config	Embedding pipeline + vector DB + retrieval logic

Use the Memory server when you want lightweight, structured, AI-controlled memory for daily workflows. Use RAG when you need to search through thousands of documents or code files by semantic meaning. They are complementary - you can run both simultaneously. The Memory server handles "what does the AI need to remember about my preferences and project," while RAG handles "search through 10,000 documentation pages to find relevant context."

Advanced: Custom Memory Servers

If the default Memory server does not meet your needs, you can build a custom memory server. Common customizations include:

• SQLite backend: Replace JSON file storage with SQLite for better performance with large datasets. SQLite handles concurrent reads, supports indexing, and does not rewrite the entire file on every operation.
• Vector search: Add embedding-based search so the AI can find relevant memories by semantic similarity, not just exact name matches. Use an embedding model to vectorize observations and store them alongside the text.
• Expiring memories: Add TTL (time-to-live) to observations so outdated information is automatically cleaned up. Useful for temporary context like "currently working on feature X."
• Shared team memory: Store the knowledge graph in a shared location (network drive, S3, database) so team members share a common context about the project. Be cautious about write conflicts if multiple people access the memory simultaneously.
• Encryption at rest: Encrypt the memory file if it contains sensitive information. Decrypt on server startup and encrypt on shutdown.

For a deeper dive into building custom servers, see our Claude integration tutorial. For configuring the Memory server alongside other servers, see the multiple server configuration guide.