memorygraphMCP 0.8.0

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. Store patterns, track relationships, retrieve knowledge across sessions.

---

Quick Start

Claude Code CLI (30 seconds)

# 1. Install
pipx install memorygraphMCP

# 2. Add to Claude Code
claude mcp add --scope user memorygraph -- memorygraph

# 3. Restart Claude Code (exit and run 'claude' again)

Verify it works:

claude mcp list  # Should show memorygraph with "Connected"

Then in Claude Code: "Store this for later: Use pytest for Python testing"

Other MCP clients? See Supported Clients below.

Need pipx? pip install --user pipx && pipx ensurepath

Command not found? Run pipx ensurepath and restart your terminal.

Tip: Add this to your CLAUDE.md or AGENTS.md to encourage use:

## Memory Tools
When recalling past work, always start with `recall_memories` tool

Supported MCP Clients

MemoryGraph works with any MCP-compliant AI coding tool:

Client	Type	Quick Start
Claude Code	CLI/IDE	Setup Guide
Cursor AI	IDE	Setup Guide
Windsurf	IDE	Setup Guide
VS Code + Copilot	IDE (1.102+)	Setup Guide
Continue.dev	VS Code/JetBrains	Setup Guide
Cline	VS Code	Setup Guide
Gemini CLI	CLI	Setup Guide

See MCP_CLIENT_COMPATIBILITY.md for detailed compatibility info.

---

Why MemoryGraph?

Graph Relationships Make the Difference

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.

When to Use What

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"
Static instructions	Dynamic learnings with relationships

Relationship Types

MemoryGraph tracks 7 categories of relationships:

• Causal: CAUSES, TRIGGERS, LEADS_TO, PREVENTS
• Solution: SOLVES, ADDRESSES, ALTERNATIVE_TO, IMPROVES
• Context: OCCURS_IN, APPLIES_TO, WORKS_WITH, REQUIRES
• Learning: BUILDS_ON, CONTRADICTS, CONFIRMS
• Similarity: SIMILAR_TO, VARIANT_OF, RELATED_TO
• Workflow: FOLLOWS, DEPENDS_ON, ENABLES, BLOCKS
• Quality: EFFECTIVE_FOR, PREFERRED_OVER, DEPRECATED_BY

---

Choose Your Mode

Feature	Core (Default)	Extended
Memory Storage	9 tools	11 tools
Relationships	Yes	Yes
Session Briefings	Yes	Yes
Database Stats	-	Yes
Complex Queries	-	Yes
Backend	SQLite	SQLite
Setup Time	30 sec	30 sec

memorygraph                    # Core (default, 9 tools)
memorygraph --profile extended # Extended (11 tools)

Core mode provides all essential tools for daily use and works for 95% of users. Extended mode adds database statistics and complex relationship queries for power users.

See TOOL_PROFILES.md for complete tool list and details.

---

Installation Options

pipx (Recommended)

pipx install memorygraphMCP                      # Core mode (default, SQLite)
pipx install "memorygraphMCP[neo4j]"             # With Neo4j backend support
pipx install "memorygraphMCP[falkordblite]"      # With FalkorDBLite backend (embedded)
pipx install "memorygraphMCP[falkordb]"          # With FalkorDB backend (client-server)

pip

pip install --user memorygraphMCP

Docker

docker compose up -d                           # SQLite
docker compose -f docker-compose.neo4j.yml up -d  # Neo4j

uvx (Quick Test)

uvx memorygraph --version  # No install needed

Method	Best For	Persistence
pipx	Most users	Yes
pip	PATH already configured	Yes
Docker	Teams, production	Yes
uvx	Quick testing	No

See DEPLOYMENT.md for detailed options.

---

Configuration

Claude Code CLI

# Core mode (default)
claude mcp add --scope user memorygraph -- memorygraph

# Extended mode
claude mcp add --scope user memorygraph -- memorygraph --profile extended

# Extended mode with Neo4j backend
claude mcp add --scope user memorygraph \
  --env MEMORY_NEO4J_URI=bolt://localhost:7687 \
  --env MEMORY_NEO4J_USER=neo4j \
  --env MEMORY_NEO4J_PASSWORD=password \
  -- memorygraph --profile extended --backend neo4j

Other MCP Clients

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

See CONFIGURATION.md for all options.

Recommended: Add to CLAUDE.md

For best results, add this to your CLAUDE.md or project instructions:

## Memory Tools
When recalling past work or learnings, always start with `recall_memories`
before using `search_memories`. The recall tool has optimized defaults
for natural language queries (fuzzy matching, relationship context included).

This helps Claude use the optimal tool for memory recall.

---

Usage

Store Memories

{
  "tool": "store_memory",
  "content": "Use bcrypt for password hashing",
  "memory_type": "CodePattern",
  "tags": ["security", "authentication"]
}

Recall Memories (Recommended)

{
  "tool": "recall_memories",
  "query": "authentication security"
}

Returns fuzzy-matched results with relationship context and match quality hints.

Search Memories (Advanced)

{
  "tool": "search_memories",
  "query": "authentication",
  "search_tolerance": "strict",
  "limit": 5
}

Use when you need exact matching or advanced filtering.

Create Relationships

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

See docs/examples/ for more use cases.

---

Backends

MemoryGraph supports 5 backend options to fit your deployment needs:

Backend	Type	Config	Native Graph	Zero-Config	Best For
sqlite	Embedded	File path	No (simulated)	✅	Default, simple use
falkordblite	Embedded	File path	✅ Cypher	✅	Graph queries without server
falkordb	Client-server	Host:port	✅ Cypher	❌	High-performance production
neo4j	Client-server	URI	✅ Cypher	❌	Enterprise features
memgraph	Client-server	Host:port	✅ Cypher	❌	Real-time analytics

New: FalkorDB Options

• FalkorDBLite: Zero-config embedded database with native Cypher support, perfect upgrade from SQLite
• FalkorDB: Redis-based graph DB with 500x faster p99 than Neo4j (docs)

See DEPLOYMENT.md for setup details.

---

Architecture

Memory Types

• Task - Development tasks and patterns
• CodePattern - Reusable solutions
• Problem - Issues encountered
• Solution - How problems were resolved
• Project - Codebase context
• Technology - Framework/tool knowledge

Project Structure

memorygraph/
├── src/memorygraph/     # Main source
│   ├── server.py        # MCP server (11 tools)
│   ├── backends/        # SQLite, Neo4j, Memgraph
│   └── tools/           # Tool implementations
├── tests/               # 409 tests, 93% coverage
└── docs/                # Documentation

See schema.md for complete data model.

---

Troubleshooting

Command not found?

pipx ensurepath && source ~/.bashrc  # or ~/.zshrc

MCP connection failed?

memorygraph --version    # Check installation
claude mcp list          # Check connection status

Multiple version conflict?

# Use full path to avoid venv conflicts
claude mcp add memorygraph -- ~/.local/bin/memorygraph

See TROUBLESHOOTING.md for more solutions.

---

Development

git clone https://github.com/gregorydickson/memorygraph.git
cd memorygraph
pip install -e ".[dev]"
pytest tests/ -v --cov=memorygraph

---

Roadmap

Current (v0.7.1+)

• SQLite default backend
• Two-tier profiles (core/extended)
• 11 fully implemented MCP tools
• 93% test coverage
• PyPI + Docker

Planned (v1.0+)

• Web visualization dashboard
• PostgreSQL backend
• Enhanced embeddings

See PRODUCT_ROADMAP.md for details.

---

Contributing

See CONTRIBUTING.md for guidelines.

---

License

MIT License - see LICENSE.

---

Links

• Documentation
• GitHub Issues
• Discussions

---

Made for the Claude Code community

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