memorygraphMCP 0.5.8

Graph-based MCP memory server for AI coding agents with intelligent relationship tracking and multi-backend support

MemoryGraph

MCP Memory Server for AI Coding Agents

A graph-based Model Context Protocol (MCP) server that gives AI coding agents persistent memory. Originally built for Claude Code, MemoryGraph works with any MCP-enabled coding agent. Store development patterns, track relationships, and retrieve contextual knowledge across sessions and projects.

---

Quick Start

For Claude Code CLI (30 seconds)

Super simple - just 3 commands:

# 1. Install the package
pip install memorygraphMCP

# 2. Add to Claude Code CLI
claude mcp add --transport stdio memorygraph -- memorygraph

# 3. Restart Claude Code CLI
# Exit your current Claude Code session (Ctrl+C or type 'exit')
# Then start a new session by running 'claude' again

Verify Installation:

# Check that memorygraph command is available
which memorygraph

# Verify version
memorygraph --version

# Check MCP server status
claude mcp list
# You should see "memorygraph" with ✓ Connected

If you see "command not found", the memorygraph command may not be in your PATH. Find it with:

python3 -c "import memorygraph; print(memorygraph.__file__)"
# Or check pip installation location
python3 -m pip show memorygraphMCP | grep Location

Then either:

• Add the Python bin directory to your PATH, or
• Use the full path when configuring: claude mcp add --transport stdio memorygraph -- /full/path/to/memorygraph

That's it! Memory is now available.

First Steps with MemoryGraph

Try storing your first memory:

In Claude Code:

Store this for later: Use pytest for testing Python projects

Verify it was stored:

Search for memories about testing

Check your memory database:

ls -la ~/.memorygraph/
# You should see memory.db

Default Configuration:

• Mode: Lite (8 core tools), SQLite backend
• Storage: ~/.memorygraph/memory.db
• Scope: Local to current project (use --scope user for all projects)

Note: These instructions are for Claude Code CLI (command-line interface). For other Claude Code interfaces (VS Code extension, Desktop app, Web), see CLAUDE_CODE_SETUP.md for interface-specific instructions.

Want more features? Click to expand

# Pattern recognition (15 tools)
claude mcp add --transport stdio memorygraph -- memorygraph --profile standard

# All features (44 tools) with Neo4j
claude mcp add --transport stdio memorygraph \
  --env MEMORY_NEO4J_URI=bolt://localhost:7687 \
  --env MEMORY_NEO4J_USER=neo4j \
  --env MEMORY_NEO4J_PASSWORD=your-password \
  -- memorygraph --profile full --backend neo4j

# Project-specific (creates .mcp.json in project root)
claude mcp add --transport stdio memorygraph --scope project -- memorygraph

Configuration File Guide:

File	Purpose	What Goes Here
.mcp.json	Project MCP servers	Created by claude mcp add --scope project
~/.claude.json	Global MCP servers (legacy)	Managed by claude mcp add
settings.json	Permissions & behavior	enabledMcpjsonServers, env vars

Key Takeaways:

• ✅ Use claude mcp add (official method)
• ✅ Let the CLI manage config files
• ❌ Don't manually edit config files
• ❌ Don't put MCP servers in settings.json - won't work

See CLAUDE_CODE_SETUP.md for advanced configuration and other Claude Code interfaces.

---

For Other MCP Clients (Cursor, Continue, etc.)

# 1. Install the package
pip install memorygraphMCP

# 2. Add to your client's MCP configuration

Example configuration (location varies by client):

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph"
    }
  }
}

3. Restart your coding agent

Follow your MCP client's documentation for exact configuration steps.

Start Using It

Ask your AI coding agent in any conversation:

• "Store this pattern for later"
• "What similar problems have we solved?"
• "Remember this approach works well for authentication"
• "Show me all memories related to database migrations"

See CLAUDE_CODE_SETUP.md for Claude Code integration guide and advanced configurations.

---

What is This?

MemoryGraph is a universal MCP server implementation that provides persistent memory for AI coding agents, built on the Model Context Protocol (MCP).

Understanding the Architecture

• MCP is an open specification that allows AI assistants to connect to external data sources and tools
• MemoryGraph is an MCP server implementation that provides memory capabilities via graph database backends
• AI coding agents (Claude Code, Cursor, Continue, etc.) are MCP clients that can connect to any MCP-compliant server

Think of it this way:

• MCP Specification = HTTP specification
• MemoryGraph = A web server (like nginx or Apache)
• Coding Agents = Web browsers that can connect to any HTTP server

This implementation is not the only way to provide memory to coding agents. Anyone can build their own MCP server with different memory approaches. MemoryGraph offers:

• Graph-based knowledge representation
• Multiple backend options (SQLite, Neo4j, Memgraph)
• Progressive complexity model (lite → standard → full)
• 44 specialized memory tools

Why build on MCP? It's an open standard. Your memory data isn't locked into proprietary formats. You can migrate to other MCP servers, build your own, or integrate multiple memory systems simultaneously.

Originally Built For Claude Code: While MemoryGraph works with any MCP client, it was specifically designed and optimized for Claude Code workflows.

---

Understanding Memory Options

Most AI coding agents offer multiple ways to maintain persistent context across sessions. Here's how they compare (using Claude Code as example):

Memory Option Comparison

Feature	CLAUDE.md Files	Anthropic Memory Tool (API)	MCP Memory Servers
Setup	Zero config	API integration required	MCP server config
Storage	Markdown files	Your implementation	Server's backend
Automatic	✅ Always loaded	✅ Claude checks automatically	⚡ On-demand via tools
Relationships	❌ Flat text	❌ Flat files	✅ Depends on server
Searchable	❌ No search	✅ File-based	✅ Semantic/graph search
Best For	Instructions, preferences	Long-running agents	Knowledge graphs, patterns

Option 1: CLAUDE.md Files (Built-in)

What it is: Claude Code's native memory system using hierarchical Markdown files.

How it works:

• Files are automatically loaded into context when Claude Code launches
• Hierarchical: Enterprise → Project → User → Local
• You manage the content manually or via # quick-add

Best For:

• Coding conventions and style guides
• Project architecture documentation
• Team-shared instructions
• Personal preferences

Limitations:

• Everything loads into context (token cost)
• No search or retrieval - Claude sees all or nothing
• No relationships between concepts
• Manual maintenance required

Option 2: Anthropic Memory Tool (API Beta)

What it is: A beta feature in the Anthropic API for building custom memory backends.

How it works:

• Claude makes tool calls to read/write files in a /memories directory
• You implement the storage backend (file system, database, cloud)
• Uses BetaAbstractMemoryTool (Python) or betaMemoryTool (TypeScript)

Best For:

• Custom applications calling Anthropic API
• Long-running agentic workflows
• Workflows that need context editing

Not For:

• Claude Code users (different architecture)
• MCP server implementations

Option 3: MCP Memory Servers

What it is: External servers that provide memory tools via Model Context Protocol.

How it works:

• Claude Code connects to MCP server via stdio/HTTP
• Server exposes tools like store_memory, search_memories, get_related
• Storage backend varies by implementation (SQLite, Neo4j, vector stores)

Popular Implementations:

Server	Storage	Key Feature
mcp-memory-keeper	SQLite	Channels, checkpoints, git integration
mcp-memory-service	SQLite + Cloudflare	Hybrid sync, semantic search
memorygraph	Neo4j/Memgraph/SQLite	Graph relationships, pattern recognition

---

Why memorygraph?

Graph Relationships Make the Difference

memorygraph uses graph database relationships to capture how concepts connect - something flat file systems and vector stores cannot do.

Flat storage (CLAUDE.md, vector stores):

Memory 1: "Fixed timeout by adding retry logic"
Memory 2: "Retry logic caused memory leak"
Memory 3: "Fixed memory leak with connection pooling"

No connection between these - search finds them separately.

Graph storage (memorygraph):

[timeout_fix] --CAUSES--> [memory_leak] --SOLVED_BY--> [connection_pooling]
     |                                                        |
     +------------------SUPERSEDED_BY------------------------+

Query: "What happened with retry logic?" → Returns the full causal chain.

Relationship Categories

We track seven categories of relationships that CLAUDE.md files cannot represent:

1. Causal: CAUSES, TRIGGERS, LEADS_TO, PREVENTS
2. Solution: SOLVES, ADDRESSES, ALTERNATIVE_TO, IMPROVES
3. Context: OCCURS_IN, APPLIES_TO, WORKS_WITH, REQUIRES
4. Learning: BUILDS_ON, CONTRADICTS, CONFIRMS
5. Similarity: SIMILAR_TO, VARIANT_OF, RELATED_TO
6. Workflow: FOLLOWS, DEPENDS_ON, ENABLES, BLOCKS
7. Quality: EFFECTIVE_FOR, PREFERRED_OVER, DEPRECATED_BY

Complementary Usage

memorygraph complements CLAUDE.md files - it doesn't replace them:

Use CLAUDE.md For	Use memorygraph For
"Always use 2-space indentation"	"Last time we used 4-space, it broke the linter"
"Run tests before committing"	"The auth tests failed because of X, fixed by Y"
"API uses JWT authentication"	"JWT refresh logic caused issues; switched to session tokens"
Static instructions	Dynamic learnings
What to do	What happened and why

Decision Guide

┌─────────────────────────────────────────────────────────────────┐
│                     Decision Guide                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  "I need Claude to follow project conventions"                   │
│       → Use CLAUDE.md files                                      │
│                                                                  │
│  "I need Claude to remember what we discussed"                   │
│       → Use MCP memory server (any)                              │
│                                                                  │
│  "I need Claude to understand WHY a solution worked"             │
│       → Use memorygraph (graph relationships)             │
│                                                                  │
│  "I need Claude to find similar past problems"                   │
│       → Use memorygraph (pattern recognition)             │
│                                                                  │
│  "I'm building a custom app with Anthropic API"                  │
│       → Use Anthropic Memory Tool (BetaAbstractMemoryTool)       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Choose Your Mode

Start simple, upgrade when needed:

Feature	Lite (Default)	Standard	Full
Memory Storage	✅	✅	✅
Relationships	✅ Basic	✅ Basic	✅ Advanced
Pattern Recognition	❌	✅	✅
Session Briefings	❌	✅	✅
Graph Analytics	❌	❌	✅
Project Integration	❌	❌	✅
Workflow Automation	❌	❌	✅
Backend	SQLite	SQLite	SQLite/Neo4j/Memgraph
Tools Available	8	15	44
Setup Time	30 sec	30 sec	5 min

# Default (lite mode)
memorygraph

# Standard mode (pattern recognition)
memorygraph --profile standard

# Full power (all 44 tools)
memorygraph --profile full --backend neo4j

---

Features

Core Memory Operations (All Modes)

• Store & Retrieve - Persistent memory across sessions
• Smart Search - Find memories by content, context, or relationships
• Relationship Tracking - Link related concepts, solutions, and patterns
• Project Context - Organize memories by project and technology

Intelligence Features (Standard & Full)

• Pattern Recognition - Automatically identify reusable patterns
• Solution Suggestions - Find similar solutions from past work
• Context Awareness - Smart context retrieval with token limiting
• Session Briefings - Get AI-generated summaries of your work

Advanced Analytics (Full Mode Only)

• Graph Analytics - Cluster analysis, bridging nodes, path finding
• Workflow Automation - Track and optimize development workflows
• Project Integration - Codebase scanning and pattern detection
• Proactive Suggestions - AI-powered recommendations and issue detection

See TOOL_PROFILES.md for complete tool list.

---

Installation

Option 1: pip (Recommended)

# Basic installation (SQLite, lite mode)
pip install memorygraphMCP

# With intelligence features (standard mode)
pip install "memorygraphMCP[intelligence]"

# Full power with Neo4j
pip install "memorygraphMCP[neo4j,intelligence]"

Option 2: Docker

# SQLite mode (default)
docker compose up -d

# Neo4j mode (full power)
docker compose -f docker-compose.neo4j.yml up -d

Option 3: uvx (Quick Test / No Install)

Try memorygraph without installation using uvx:

# Install uv (if not already installed)
pip install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Run directly from PyPI
uvx memorygraph --version
uvx memorygraph --show-config

# Run as MCP server (ephemeral)
uvx memorygraph --backend sqlite --profile lite

Note: uvx is great for quick testing and CI/CD, but pip install is recommended for daily use as a persistent MCP server. See DEPLOYMENT.md for limitations and use cases.

Installation Method Comparison

Method	Setup Time	Use Case	Persistence	Recommended For
pip install	30 sec	Daily use, MCP server	Yes	Most users
Docker	5 min	Team/production	Yes	Power users, teams
uvx	10 sec*	Quick test, CI/CD	No**	Testing, automation

* First run slower (downloads package), subsequent runs cached ** Requires explicit database path for persistent data (MEMORY_SQLITE_PATH)

See DEPLOYMENT.md for detailed installation options.

---

Configuration Examples

Basic Configuration (Lite Mode - Default)

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph"
    }
  }
}

Standard Mode (Pattern Recognition)

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--profile", "standard"]
    }
  }
}

Full Mode with SQLite

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--profile", "full"],
      "env": {
        "MEMORY_TOOL_PROFILE": "full",
        "MEMORY_SQLITE_PATH": "/Users/yourname/.memorygraph/memory.db"
      }
    }
  }
}

Full Mode with Neo4j

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--backend", "neo4j", "--profile", "full"],
      "env": {
        "MEMORY_BACKEND": "neo4j",
        "MEMORY_NEO4J_URI": "bolt://localhost:7687",
        "MEMORY_NEO4J_USER": "neo4j",
        "MEMORY_NEO4J_PASSWORD": "your-password",
        "MEMORY_TOOL_PROFILE": "full"
      }
    }
  }
}

Full Mode with Memgraph

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--backend", "memgraph", "--profile", "full"],
      "env": {
        "MEMORY_BACKEND": "memgraph",
        "MEMORY_MEMGRAPH_URI": "bolt://localhost:7687",
        "MEMORY_MEMGRAPH_USER": "memgraph",
        "MEMORY_MEMGRAPH_PASSWORD": "memgraph",
        "MEMORY_TOOL_PROFILE": "full"
      }
    }
  }
}

Docker-based Configuration

{
  "mcpServers": {
    "memorygraph": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "memorygraph-server",
        "python",
        "-m",
        "memorygraph.server"
      ],
      "env": {
        "MEMORY_BACKEND": "neo4j",
        "MEMORY_NEO4J_URI": "bolt://neo4j:7687",
        "MEMORY_NEO4J_USER": "neo4j",
        "MEMORY_NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Custom Database Path

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--profile", "standard"],
      "env": {
        "MEMORY_SQLITE_PATH": "/path/to/your/project/.memory/memory.db",
        "MEMORY_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Multiple Memory Servers (Project-Specific)

{
  "mcpServers": {
    "memory-personal": {
      "command": "memorygraph",
      "env": {
        "MEMORY_SQLITE_PATH": "/Users/yourname/.memorygraph/personal.db"
      }
    },
    "memory-work": {
      "command": "memorygraph",
      "args": ["--profile", "full", "--backend", "neo4j"],
      "env": {
        "MEMORY_NEO4J_URI": "bolt://work-server:7687",
        "MEMORY_NEO4J_USER": "neo4j",
        "MEMORY_NEO4J_PASSWORD": "work-password"
      }
    }
  }
}

See CLAUDE_CODE_SETUP.md for more configuration examples and best practices.

---

Usage Examples

Basic Memory Storage

{
  "tool": "store_memory",
  "content": "Use bcrypt for password hashing in this project",
  "memory_type": "CodePattern",
  "project": "my-app",
  "tags": ["security", "authentication"]
}

Find Related Memories

{
  "tool": "search_memories",
  "query": "authentication",
  "memory_type": "CodePattern",
  "limit": 5
}

Create Relationships

{
  "tool": "create_relationship",
  "from_memory_id": "mem_123",
  "to_memory_id": "mem_456",
  "relationship_type": "SOLVES"
}

Pattern Recognition (Standard/Full)

{
  "tool": "find_similar_solutions",
  "problem_description": "need to validate user input",
  "limit": 3
}

See examples in docs/examples/ for more use cases.

---

Architecture

Memory Types

• Task - Development tasks and execution patterns
• CodePattern - Reusable code solutions and architectural decisions
• Problem - Issues encountered and their context
• Solution - How problems were resolved and effectiveness
• Project - Codebase context and project-specific knowledge
• Technology - Framework, language, and tool-specific knowledge

Relationship Categories (7 types, 35+ relationships)

1. Causal - CAUSES, TRIGGERS, LEADS_TO, PREVENTS, BREAKS
2. Solution - SOLVES, ADDRESSES, ALTERNATIVE_TO, IMPROVES, REPLACES
3. Context - OCCURS_IN, APPLIES_TO, WORKS_WITH, REQUIRES, USED_IN
4. Learning - BUILDS_ON, CONTRADICTS, CONFIRMS, GENERALIZES, SPECIALIZES
5. Similarity - SIMILAR_TO, VARIANT_OF, RELATED_TO, ANALOGY_TO, OPPOSITE_OF
6. Workflow - FOLLOWS, DEPENDS_ON, ENABLES, BLOCKS, PARALLEL_TO
7. Quality - EFFECTIVE_FOR, INEFFECTIVE_FOR, PREFERRED_OVER, DEPRECATED_BY, VALIDATED_BY

See schema.md for complete data model.

---

Backends

SQLite (Default)

• Use for: Getting started, personal projects, <10k memories
• Pros: Zero config, no dependencies, portable, fast for most use cases
• Cons: Graph queries slower at scale, no concurrent writes
• Backend: --backend sqlite (default)

Neo4j

• Use for: Production, team use, complex graph analytics
• Pros: Industry-standard graph DB, rich query language, excellent tooling
• Cons: Requires setup, resource intensive
• Backend: --backend neo4j

Memgraph

• Use for: High-performance analytics, real-time queries
• Pros: Fastest graph analytics, in-memory processing, compatible with Neo4j
• Cons: Requires setup, less mature ecosystem
• Backend: --backend memgraph

See FULL_MODE.md for backend setup guides.

---

Environment Variables

# Backend selection
export MEMORY_BACKEND=sqlite          # sqlite (default) | neo4j | memgraph

# Tool profile
export MEMORY_TOOL_PROFILE=lite       # lite (default) | standard | full

# SQLite configuration (default backend)
export MEMORY_SQLITE_PATH=~/.memorygraph/memory.db

# Neo4j configuration (if using neo4j backend)
export MEMORY_NEO4J_URI=bolt://localhost:7687
export MEMORY_NEO4J_USER=neo4j
export MEMORY_NEO4J_PASSWORD=your-password

# Memgraph configuration (if using memgraph backend)
export MEMORY_MEMGRAPH_URI=bolt://localhost:7687
export MEMORY_MEMGRAPH_USER=memgraph
export MEMORY_MEMGRAPH_PASSWORD=your-password

# Logging
export MEMORY_LOG_LEVEL=INFO          # DEBUG | INFO | WARNING | ERROR

CLI Options

# Show help
memorygraph --help

# Show current configuration
memorygraph --show-config

# Show version
memorygraph --version

# Run with custom settings
memorygraph --backend neo4j --profile full --log-level DEBUG

See DEPLOYMENT.md for complete configuration reference.

---

Development

Project Structure

memorygraph/
├── src/memorygraph/            # Main source code
│   ├── server.py               # MCP server (44 tools)
│   ├── backends/               # SQLite, Neo4j, Memgraph
│   ├── tools/                  # Tool implementations
│   ├── models.py               # Data models
│   └── cli.py                  # Command-line interface
├── tests/                      # 409 tests, 93% coverage
├── docs/                       # Documentation
└── pyproject.toml             # Package configuration

Development Setup

# Clone repository
git clone https://github.com/gregorydickson/memorygraph.git
cd memorygraph

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --cov=memorygraph

# Type checking
mypy src/

# Format code
black src/ tests/
ruff --fix src/ tests/

Test Suite

# All tests
pytest

# With coverage
pytest --cov=memorygraph --cov-report=html

# Specific backend
pytest tests/backends/test_sqlite_backend.py

# Integration tests
pytest tests/integration/

Current Status: 401/409 tests passing, 93% coverage

---

Upgrading

From Lite to Standard

No changes needed - just add the flag:

memorygraph --profile standard

From SQLite to Neo4j

1. Export SQLite data: memorygraph --export backup.json
2. Set up Neo4j (see FULL_MODE.md)
3. Import data: memorygraph --backend neo4j --import backup.json
4. Update MCP config to use --backend neo4j

See DEPLOYMENT.md for detailed migration guide.

---

Troubleshooting

Common Issues

Command not found: memorygraph

# Find where memorygraph was installed
python3 -m pip show memorygraphMCP | grep Location

# Check if it's in PATH
which memorygraph

# If not found, add Python bin directory to PATH
# For bash users, add to ~/.bashrc:
export PATH="$PATH:/path/to/python/bin"

# For zsh users, add to ~/.zshrc:
export PATH="$PATH:/path/to/python/bin"

# Or use full path in MCP configuration
claude mcp add --transport stdio memorygraph -- /full/path/to/memorygraph

Server won't start

# Check configuration
memorygraph --show-config

# Verify database connection
memorygraph --health

SQLite database locked

# Check for running processes
ps aux | grep memorygraph

# Remove lock file (if safe)
rm ~/.memorygraph/memory.db-lock

Neo4j connection refused

# Verify Neo4j is running
docker ps | grep neo4j

# Check credentials
memorygraph --backend neo4j --show-config

See DEPLOYMENT.md for more solutions.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Workflow

1. Check GitHub Issues
2. Fork the repository and create a feature branch
3. Make changes following our coding standards (Black, Ruff, mypy)
4. Add tests for new functionality (maintain 90%+ coverage)
5. Submit a pull request with clear description

---

Roadmap

v1.0 (Current) ✅

• ✅ SQLite default backend
• ✅ Three-tier complexity (lite/standard/full)
• ✅ 44 MCP tools
• ✅ CLI with memorygraph command
• ✅ PyPI publication
• ✅ Docker support

v1.1 (Planned)

• Web visualization dashboard
• Enhanced embedding support
• PostgreSQL backend (pg_graph)
• Advanced analytics UI
• Workflow automation templates

v2.0 (Future)

• Multi-user support
• Team memory sharing
• Cloud-hosted options
• Advanced AI features

---

Performance

Benchmarks (SQLite)

• 1,000 memories: <50ms query time
• 10,000 memories: <100ms query time
• 100,000 memories: <500ms query time
• Relationship traversal: <100ms for 3-hop queries

Benchmarks (Neo4j)

• 10x faster graph traversals at scale
• 100x faster complex analytics queries
• Handles millions of memories efficiently

See FULL_MODE.md for detailed benchmarks.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

• Documentation - Guides, references, examples
• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community support

---

Acknowledgments

• Model Context Protocol - Protocol specification
• Neo4j - Graph database platform
• Memgraph - High-performance graph platform
• Claude Code - AI-powered development environment

---

Made with ❤️ for the Claude Code community

Start simple. Upgrade when needed. Never lose context again.