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. Claude Code now ships with built-in file-based memory of its own; Memory MCP complements it with a structured, queryable knowledge graph you control.

Updated November 4, 2026: Fixed the setup. Claude Code has no --scope global (use --scope user); user- and local-scope servers are stored in ~/.claude.json, not ~/.claude/.mcp.json; and every MEMORY_FILE_PATH is now absolute, because the server resolves a relative path against its own package directory rather than your project.

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)

# This project only (local scope, stored in ~/.claude.json).
# Run it from the project root: the shell expands $PWD to an absolute path.
claude mcp add \
  --scope local \
  memory \
  -e MEMORY_FILE_PATH="$PWD/.claude/memory.jsonl" \
  -- npx -y @modelcontextprotocol/server-memory

# All your projects (user scope)
claude mcp add \
  --scope user \
  memory \
  -e MEMORY_FILE_PATH="$HOME/.claude/memory.jsonl" \
  -- npx -y @modelcontextprotocol/server-memory

The server needs Node.js 24 or later when it runs through npx.

Use an absolute MEMORY_FILE_PATH. The server resolves a relative path against its own package directory (with npx, a folder in the npm cache), not against your project. A leading ~/ works with current releases (v1.0.0 from October 2026 onward), which expand it themselves; the older date-numbered releases, up to 2026.8.31, treated it as a relative path. Don’t rely on the shell for ~: JSON config never passes through a shell, and zsh (the macOS default) and POSIX sh leave -e KEY=~/... as typed. "$HOME/..." and "$PWD/..." expand in bash and zsh alike.

The project command uses local scope so that machine-specific path stays in your own ~/.claude.json; --scope project would write it into the shared .mcp.json.

Method 2: Manual Configuration

Edit .mcp.json in the project root (project scope). User- and local-scope servers are stored in ~/.claude.json, which Claude Code manages for you, so add those with claude mcp add instead:

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

Storage Location Recommendations

• Project memory: <project>/.claude/memory.jsonl, written as an absolute path (project-specific knowledge)
• Global memory: ~/.claude/memory.jsonl (cross-project knowledge)
• Separate memories: Use different absolute 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 (from the project root)
   cat ./.claude/memory.jsonl | 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": "/Users/you/projects/web-app/.claude/memory.jsonl" }
  },
  "memory-mobile-app": {
    "env": { "MEMORY_FILE_PATH": "/Users/you/projects/mobile-app/.claude/memory.jsonl" }
  }
}

Use case: Separate memories for different projects

Strategy 2: Global Shared Memory

{
  "memory": {
    "env": { "MEMORY_FILE_PATH": "/Users/you/.claude/global-memory.jsonl" }
  }
}

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

Strategy 3: Hybrid Approach

{
  "memory-global": {
    "env": { "MEMORY_FILE_PATH": "/Users/you/.claude/global-memory.jsonl" }
  },
  "memory-project": {
    "env": { "MEMORY_FILE_PATH": "/Users/you/projects/web-app/.claude/project-memory.jsonl" }
  }
}

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 that MEMORY_FILE_PATH is set to an absolute path (a relative one resolves inside the server’s package directory)
• 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.jsonl 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 adds a structured, queryable knowledge graph alongside Claude Code’s built-in file-based memory, giving Claude persistent context awareness you can traverse and query. 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 (from the project root): claude mcp add memory -e MEMORY_FILE_PATH="$PWD/.claude/memory.jsonl" -- 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