Memory MCP: Persistent Knowledge Graph for AI

Have you ever wished your AI assistant could remember information across conversations? Like remembering your project structure, coding preferences, or important context that you don’t want to repeat every time?

Memory MCP provides exactly that - a persistent knowledge graph that allows Claude to remember information across chat sessions.

What is Memory MCP?

Memory MCP (also known as Knowledge Graph Memory Server) is an official Anthropic MCP server that provides persistent memory for Claude using a local knowledge graph stored as a JSONL file.

Core Concept: Knowledge Graph

The system uses three core components:

1. Entities - Primary nodes in the knowledge graph (people, projects, concepts)
2. Relations - Directed connections between entities (stored in active voice)
3. Observations - Discrete pieces of information about an entity

Key Features

1. Persistent Memory 🧠

   • Information survives across chat sessions
   • Stored locally in a JSONL file
   • No data sent to external servers

2. Structured Knowledge 🕸️

   • Knowledge graph with entities and relations
   • Semantic relationships between concepts
   • Easy to query and traverse

3. Privacy-First 🔒

   • All data stored locally
   • Full control over your data
   • No cloud dependencies

4. Cross-Session Context 🔄

   • Claude remembers previous conversations
   • Build on past discussions
   • No need to repeat context

Installation & Setup

Method 1: Official CLI (Recommended)

# Install for project
claude mcp add \
  --scope project \
  memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

# Install globally
claude mcp add \
  --scope global \
  memory \
  -e MEMORY_FILE_PATH=~/.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

Method 2: Manual Configuration

Edit .mcp.json (project) or ~/.claude/.mcp.json (global):

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

Storage Location Recommendations

• Project memory: ./.claude/memory.json (project-specific knowledge)
• Global memory: ~/.claude/memory.json (cross-project knowledge)
• Separate memories: Use different paths for different contexts

Real-World Examples

Example 1: Remember Project Architecture

You: "Remember: This project uses a microservices architecture with 5 services:
auth, api, database, cache, and queue"

Memory MCP creates:
- Entity: "project-architecture" (type: architecture)
- Observation: "Uses microservices architecture"
- Entity: "auth-service" (type: service)
- Entity: "api-service" (type: service)
- Relations: project-architecture -> contains -> auth-service
- Relations: project-architecture -> contains -> api-service
...

Next session:
You: "What's our project architecture?"
Claude: "Your project uses a microservices architecture with 5 services..."

Example 2: Remember Coding Preferences

You: "I prefer using const over let, and arrow functions over function declarations"

Memory MCP creates:
- Entity: "coding-preferences" (type: preferences)
- Observation: "Prefers const over let"
- Observation: "Prefers arrow functions over function declarations"

Later:
Claude automatically applies these preferences when writing code

Example 3: Track Project Dependencies

You: "We're using React 18.2, Next.js 14, and Tailwind CSS 3.4"

Memory MCP creates:
- Entity: "React" (type: dependency, version: 18.2)
- Entity: "Next.js" (type: dependency, version: 14)
- Entity: "Tailwind CSS" (type: dependency, version: 3.4)
- Relations: project -> uses -> React
- Relations: project -> uses -> Next.js

Result: Claude always uses correct versions when suggesting code

Available Tools

1. create_entities

Create multiple entities with observations.

create_entities([
  {
    name: "user-authentication",
    entityType: "feature",
    observations: [
      "Uses JWT for authentication",
      "Implements refresh token rotation",
      "Supports OAuth 2.0"
    ]
  }
])

2. create_relations

Create directed relations between entities.

create_relations([
  {
    from: "auth-service",
    to: "database",
    relationType: "connects-to"
  },
  {
    from: "api-service",
    to: "auth-service",
    relationType: "depends-on"
  }
])

3. add_observations

Add new observations to existing entities.

add_observations([
  {
    entityName: "user-authentication",
    contents: [
      "Added MFA support in v2.0",
      "Migrated to bcrypt for password hashing"
    ]
  }
])

4. search_nodes

Search for entities and observations.

search_nodes("authentication")
// Returns all entities and observations related to authentication

5. open_nodes

Retrieve specific entities by name.

open_nodes(["user-authentication", "database"])
// Returns full details of these entities

6. delete_entities

Remove entities and their relations.

delete_entities(["deprecated-feature"])

7. delete_observations

Remove specific observations from entities.

delete_observations([
  {
    entityName: "user-authentication",
    observations: ["Old observation to remove"]
  }
])

8. read_graph

Read the entire knowledge graph.

read_graph()
// Returns complete graph structure

Best Practices

✅ Recommended

1. Structured Entity Names

   ✅ Good: "user-authentication-feature"
   ❌ Bad: "that auth thing"

2. Clear Entity Types

   Use consistent types: feature, service, dependency, preference, person, etc.

3. Active Voice Relations

   ✅ Good: "depends-on", "connects-to", "implements"
   ❌ Bad: "is-depended-on-by" (passive voice)

4. Granular Observations

   ✅ Good: "Uses JWT for authentication"
   ❌ Bad: "Uses JWT and also bcrypt and has OAuth and..."

5. Regular Memory Audits

   # Periodically review your memory graph
   cat ./.claude/memory.json | jq '.'

❌ Avoid

1. Storing Sensitive Data - Never store passwords, API keys, or PII
2. Duplicate Entities - Check if entity exists before creating
3. Vague Observations - Be specific and actionable
4. Circular References - Can cause confusion in graph traversal

Memory Scope Strategies

Strategy 1: Project-Specific Memory

{
  "memory-web-app": {
    "env": { "MEMORY_FILE_PATH": "./projects/web-app/.claude/memory.json" }
  },
  "memory-mobile-app": {
    "env": { "MEMORY_FILE_PATH": "./projects/mobile-app/.claude/memory.json" }
  }
}

Use case: Separate memories for different projects

Strategy 2: Global Shared Memory

{
  "memory": {
    "env": { "MEMORY_FILE_PATH": "~/.claude/global-memory.json" }
  }
}

Use case: Share knowledge across all projects (e.g., coding preferences)

Strategy 3: Hybrid Approach

{
  "memory-global": {
    "env": { "MEMORY_FILE_PATH": "~/.claude/global-memory.json" }
  },
  "memory-project": {
    "env": { "MEMORY_FILE_PATH": "./.claude/project-memory.json" }
  }
}

Use case: Global preferences + project-specific knowledge

Integration with Other MCPs

Memory + Filesystem MCP

Workflow:
1. Filesystem explores project structure
2. Memory stores architecture decisions
3. Future refactorings respect stored patterns

Memory + Context7 MCP

Workflow:
1. Context7 fetches latest docs
2. Claude implements feature
3. Memory stores implementation patterns
4. Future features follow stored patterns

Troubleshooting

Issue 1: Memory Not Persisting

Error: Changes not saved across sessions

Solution:

• Check MEMORY_FILE_PATH is correctly set
• Ensure write permissions for the file
• Verify file is not corrupted

Issue 2: Duplicate Entities

Warning: Multiple entities with similar names

Solution:

• Use search_nodes before creating
• Implement consistent naming conventions
• Use delete_entities to remove duplicates

Issue 3: Memory File Too Large

Warning: memory.json is >10MB

Solution:

• Remove obsolete entities
• Archive old memories
• Split into multiple memory files

Memory File Format

The memory is stored as JSONL (JSON Lines):

{"type":"entity","name":"user-auth","entityType":"feature","observations":["Uses JWT"]}
{"type":"relation","from":"api","to":"user-auth","relationType":"uses"}
{"type":"entity","name":"api","entityType":"service","observations":["REST API"]}

Note: Do not manually edit unless you know what you’re doing.

Conclusion

Memory MCP transforms Claude from a stateless assistant into one with persistent context awareness. It enables:

• ✅ Cross-session continuity
• ✅ Project knowledge accumulation
• ✅ Personalized AI assistance
• ✅ Reduced context repetition

Is It Right for You?

Use Case	Recommendation
Long-term projects	⭐⭐⭐⭐⭐
Multiple related projects	⭐⭐⭐⭐⭐
Team knowledge sharing	⭐⭐⭐⭐
Personal coding preferences	⭐⭐⭐⭐⭐
One-off tasks	⭐⭐

Get Started Now

1. Install: claude mcp add --scope project memory -e MEMORY_FILE_PATH=./.claude/memory.json -- npx -y @modelcontextprotocol/server-memory
2. Start building your knowledge graph
3. Enjoy persistent AI memory

Further Reading

• Memory MCP GitHub Repository
• Memory MCP npm Package
• Knowledge Graph Best Practices