Memory Graph

See [CLAUDE.md Examples](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/examples/CLAUDE_MD_EXAMPLES.md) for more configuration templates.

## Supported MCP Clients

MemoryGraph works with any MCP-compliant AI coding tool:

| Client | Type | Quick Start |
|--------|------|-------------|
| **Claude Code** | CLI/IDE | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/CLAUDE_CODE_SETUP.md) |
| **Claude Desktop** | Desktop App | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/CLAUDE_DESKTOP.md) |
| **ChatGPT Desktop** | Desktop App | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/CHATGPT_DESKTOP.md) |
| **Cursor AI** | IDE | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/CURSOR_SETUP.md) |
| **Windsurf** | IDE | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/WINDSURF_SETUP.md) |
| **VS Code + Copilot** | IDE (1.102+) | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/VSCODE_COPILOT_SETUP.md) |
| **Continue.dev** | VS Code/JetBrains | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/CONTINUE_SETUP.md) |
| **Cline** | VS Code | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/CLINE_SETUP.md) |
| **Gemini CLI** | CLI | [Setup Guide](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/quickstart/GEMINI_CLI_SETUP.md) |

See [CONFIGURATION.md](https://github.com/gregorydickson/memory-graph/blob/HEAD/docs/CONFIGURATION.md) for detailed compatibility info.

---

## Why MemoryGraph?

### Graph Relationships Make the Difference

Research shows that naive vector search degrades on long-horizon and temporal tasks. Benchmarks such as Deep Memory Retrieval (DMR) and LongMemEval were introduced precisely because graph-based systems excel at temporal queries ("what did the user decide last week"), cross-session reasoning, and multi-hop questions requiring explicit relational paths.

Graph memory captures entities, relationships, and temporal markers that traditional vector stores miss. For example: `Alice COMPLETED authentication_service`, `Bob BLOCKED_BY schema_conflicts` with timeline information about when events occurred.

**Flat storage** (CLAUDE.md, vector stores):

No connection between these - search finds them separately. Best for static rules and prime directives.

**Graph storage** (MemoryGraph):

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 rules, prime directives | 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 | 12 tools |
| Relationships | Yes | Yes |
| Session Briefings | Yes | Yes |
| Database Stats | - | Yes |
| Complex Queries | - | Yes |
| Contextual Search | - | Yes |
| Backend | SQLite | SQLite |
| Setup Time | 30 sec | 30 sec |

```bash
memorygraph                    # Core (default, 9 tools)
memorygraph --profile extended # Extended (12 tools)

# Enable extended mode in Claude Code
claude mcp add --scope user memorygraph -- memorygraph --profile extended

# From memorygraph repo
cp -r examples/claude-code-hooks/.claude /path/to/your/project/

# Commit to your repo
cd /path/to/your/project
git add .claude/
git commit -m "Add MemoryGraph auto-install hooks"

This helps Claude use the optimal tool for memory recall.

---

## Memory Best Practices

### Why Memories Aren't Automatic

MemoryGraph is an MCP tool provider, not an autonomous agent. This means:
- **Claude needs to be prompted** to use the memory tools
- **You control what gets stored** - nothing is saved without explicit instruction
- **Configuration is key** - Add memory protocols to your CLAUDE.md for consistent behavior

This design gives you full control over your memory graph, but requires setup to work effectively.

### How to Encourage Memory Creation

#### 1. Configure CLAUDE.md (Recommended)

Add a memory protocol to `~/.claude/CLAUDE.md` for persistent behavior across all sessions:

```markdown

## Memory Protocol

### REQUIRED: Before Starting Work
You MUST use `recall_memories` before any task. Query by project, tech, or task type.

### REQUIRED: Automatic Storage Triggers
Store memories on ANY of:
- **Git commit** → what was fixed/added
- **Bug fix** → problem + solution
- **Version release** → summarize changes
- **Architecture decision** → choice + rationale
- **Pattern discovered** → reusable approach

### Timing Mode (default: on-commit)
`memory_mode: immediate | on-commit | session-end`

### Memory Fields
- **Type**: solution | problem | code_pattern | fix | error | workflow
- **Title**: Specific, searchable (not generic)
- **Content**: Accomplishment, decisions, patterns
- **Tags**: project, tech, category (REQUIRED)
- **Importance**: 0.8+ critical, 0.5-0.7 standard, 0.3-0.4 minor
- **Relationships**: Link related memories when they exist

Do NOT wait to be asked. Memory storage is automatic.

You: "What do you remember about the authentication system?"
Claude: [Uses recall_memories to find relevant context]

You: "We fixed the Redis timeout by increasing the connection pool to 50. Store this solution."
Claude: [Uses store_memory, then create_relationship to link to the problem]

You: "Store a summary of what we accomplished today"
Claude: [Creates a task-type memory with summary and links]

## Project Memory Protocol

This project uses MemoryGraph for team knowledge sharing.

### When to Store
- Solutions to project-specific problems
- Architecture decisions and rationale
- Deployment procedures and gotchas
- Performance optimizations
- Bug fixes and root causes

### Tagging Convention
Always include these tags:
- Project name: "my-app"
- Component: "auth", "api", "database", etc.
- Type: "fix", "feature", "optimization", etc.

### Example
When fixing a bug:
1. Store the problem (type: problem)
2. Store the solution (type: solution)
3. Link them: solution SOLVES problem
4. Tag both with component and "bug-fix"

# Causal relationships
problem --CAUSES--> error
change --TRIGGERS--> bug

# Solution relationships
solution --SOLVES--> problem
fix --ADDRESSES--> error
pattern --IMPROVES--> code

# Context relationships
pattern --APPLIES_TO--> project
solution --REQUIRES--> dependency
pattern --WORKS_WITH--> technology

# Learning relationships
new_approach --BUILDS_ON--> old_approach
finding --CONTRADICTS--> assumption
result --CONFIRMS--> hypothesis

1. Encounter error → Store as type: error
2. Find root cause → Store as type: problem, link: error TRIGGERS problem
3. Implement fix → Store as type: solution, link: solution SOLVES problem
4. Result: Complete chain for future reference

1. Start: "Recall any patterns for user authentication"
2. Implement: [Work on feature]
3. Store: "Store this authentication pattern" → type: code_pattern
4. Link: pattern APPLIES_TO project
5. End: "Store summary of authentication implementation"

1. Identify issue → Store as type: problem
2. Test solutions → Store each as type: solution
3. Compare → Link: best_solution IMPROVES other_solutions
4. Document → Store decision with rationale

# Migrate existing database to multi-tenant mode
memorygraph migrate-to-multitenant --tenant-id="acme-corp" --dry-run

# Enable multi-tenant mode
export MEMORY_MULTI_TENANT_MODE=true
memorygraph

memorygraph/
├── src/memorygraph/     # Main source
│   ├── server.py        # MCP server (11 tools)
│   ├── backends/        # SQLite, Neo4j, Memgraph, FalkorDB, Turso, Cloud
│   ├── migration/       # Backend-to-backend migration
│   └── tools/           # Tool implementations
├── tests/               # 1,068 tests
└── docs/                # Documentation

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

pip install memorygraphsdk[all]  # All integrations

from memorygraphsdk import MemoryGraphClient

client = MemoryGraphClient(api_key="mg_...")
memory = client.create_memory(
    type="solution",
    title="Fixed Redis timeout",
    content="Used exponential backoff",
    tags=["redis", "fix"]
)

# Enable cloud backend
claude mcp add --scope user memorygraph \
  --env MEMORYGRAPH_API_KEY=mg_your_key_here \
  -- memorygraph --backend cloud

# Query what solutions existed in March 2024
march_2024 = datetime(2024, 3, 1, tzinfo=timezone.utc)
relationships = await db.get_related_memories("error_id", as_of=march_2024)

# Get full history of how understanding evolved
history = await db.get_relationship_history("problem_id")

# See what changed in the last week
changes = await db.what_changed(since=one_week_ago)

# Migrate from SQLite to FalkorDB
memorygraph migrate --from sqlite --to falkordb --to-uri redis://localhost:6379

# Test migration first
memorygraph migrate --from sqlite --to neo4j --dry-run

memorygraph export --format json --output backup.json
memorygraph import --format json --input backup.json --skip-duplicates

# 1. Install (will use default SQLite database)
pipx install memorygraphMCP

# 1b. Optionally, you can specify a backend
pipx install "memorygraphMCP[falkordblite]"

# 2. Add to Claude Code (see docs/quickstart/ for other coding agents)
claude mcp add --scope user memorygraph -- memorygraph

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

claude mcp list  # Should show memorygraph with "Connected"

## Installation Options

### pipx (Recommended)

```bash
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[ladybugdb]"         # With LadybugDB backend (embedded)
pipx install "memorygraphMCP[falkordb]"          # With FalkorDB backend (client-server)

pip install --user memorygraphMCP

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

uvx memorygraph --version  # No install needed

# 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

# Cloud backend (multi-device sync, zero setup)
claude mcp add --scope user memorygraph \
  --env MEMORYGRAPH_API_KEY=mg_your_key_here \
  -- memorygraph --backend cloud

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

## Usage

### Store Memories

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

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

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

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

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

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

# Option A: Use full path to avoid venv conflicts (recommended)
claude mcp add memorygraph -- ~/.local/bin/memorygraph

# Option B: Create symlink for cleaner config (requires sudo once)
sudo ln -s ~/.local/bin/memorygraph /usr/local/bin/memorygraph
# Then use simple command
claude mcp add memorygraph -- memorygraph