# Configuration Reference
Complete configuration examples for MemoryGraph with various MCP clients and backends.
## Claude Code CLI (Recommended Method)
Use `claude mcp add` to configure MemoryGraph:
```bash
# Core mode (default, 9 tools)
claude mcp add --scope user memorygraph -- memorygraph
# Extended mode (11 tools)
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=your-password \
-- memorygraph --profile extended --backend neo4j
# FalkorDBLite backend (embedded, like SQLite with Cypher)
claude mcp add --scope user memorygraph \
--env MEMORY_FALKORDBLITE_PATH=~/.memorygraph/falkordblite.db \
-- memorygraph --backend falkordblite
# FalkorDB backend (client-server)
claude mcp add --scope user memorygraph \
--env MEMORY_FALKORDB_HOST=localhost \
--env MEMORY_FALKORDB_PORT=6379 \
--env MEMORY_FALKORDB_PASSWORD=your-password \
-- memorygraph --backend falkordb
# Project-specific (creates .mcp.json in project root)
claude mcp add --scope project memorygraph -- memorygraph
```
## JSON Configuration Examples
### Basic Configuration (Core Mode - Default)
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph"
}
}
}
```
This uses the default core profile with 9 essential tools.
### Extended Mode (11 Tools)
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--profile", "extended"]
}
}
}
```
Adds database statistics and complex relationship queries to the core tools.
### Extended Mode with SQLite (Custom Path)
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--profile", "extended"],
"env": {
"MEMORY_TOOL_PROFILE": "extended",
"MEMORY_SQLITE_PATH": "/Users/yourname/.memorygraph/memory.db"
}
}
}
}
```
### Extended Mode with Neo4j
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--backend", "neo4j", "--profile", "extended"],
"env": {
"MEMORY_BACKEND": "neo4j",
"MEMORY_NEO4J_URI": "bolt://localhost:7687",
"MEMORY_NEO4J_USER": "neo4j",
"MEMORY_NEO4J_PASSWORD": "your-password",
"MEMORY_TOOL_PROFILE": "extended"
}
}
}
}
```
### Extended Mode with Memgraph
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--backend", "memgraph", "--profile", "extended"],
"env": {
"MEMORY_BACKEND": "memgraph",
"MEMORY_MEMGRAPH_URI": "bolt://localhost:7687",
"MEMORY_MEMGRAPH_USER": "memgraph",
"MEMORY_MEMGRAPH_PASSWORD": "memgraph",
"MEMORY_TOOL_PROFILE": "extended"
}
}
}
}
```
### FalkorDBLite Backend (Embedded with Cypher)
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--backend", "falkordblite"],
"env": {
"MEMORY_BACKEND": "falkordblite",
"MEMORY_FALKORDBLITE_PATH": "/Users/yourname/.memorygraph/falkordblite.db"
}
}
}
}
```
### FalkorDB Backend (Client-Server)
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--backend", "falkordb", "--profile", "extended"],
"env": {
"MEMORY_BACKEND": "falkordb",
"MEMORY_FALKORDB_HOST": "localhost",
"MEMORY_FALKORDB_PORT": "6379",
"MEMORY_FALKORDB_PASSWORD": "your-password",
"MEMORY_TOOL_PROFILE": "extended"
}
}
}
}
```
### Docker-based Configuration
```json
{
"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
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--profile", "extended"],
"env": {
"MEMORY_SQLITE_PATH": "/path/to/your/project/.memory/memory.db",
"MEMORY_LOG_LEVEL": "DEBUG"
}
}
}
}
```
### Multiple Memory Servers
```json
{
"mcpServers": {
"memory-personal": {
"command": "memorygraph",
"env": {
"MEMORY_SQLITE_PATH": "/Users/yourname/.memorygraph/personal.db"
}
},
"memory-work": {
"command": "memorygraph",
"args": ["--profile", "extended", "--backend", "neo4j"],
"env": {
"MEMORY_NEO4J_URI": "bolt://work-server:7687",
"MEMORY_NEO4J_USER": "neo4j",
"MEMORY_NEO4J_PASSWORD": "work-password"
}
}
}
}
```
### Using Full Path (Prevents Version Conflicts)
```json
{
"mcpServers": {
"memorygraph": {
"type": "stdio",
"command": "/Users/yourname/.local/bin/memorygraph",
"args": [],
"env": {}
}
}
}
```
## Environment Variables
```bash
# Backend selection
export MEMORY_BACKEND=sqlite # sqlite (default) | falkordblite | falkordb | neo4j | memgraph
# Tool profile
export MEMORY_TOOL_PROFILE=core # core (default) | extended
# SQLite configuration (default backend)
export MEMORY_SQLITE_PATH=~/.memorygraph/memory.db
# FalkorDBLite configuration (embedded with Cypher)
export MEMORY_FALKORDBLITE_PATH=~/.memorygraph/falkordblite.db
# FalkorDB configuration (client-server)
export MEMORY_FALKORDB_HOST=localhost
export MEMORY_FALKORDB_PORT=6379
export MEMORY_FALKORDB_PASSWORD=your-password
# 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=memgraph
# Relationship configuration (v0.9.0+)
export MEMORY_ALLOW_CYCLES=false # true | false (default) - Allow circular relationships
# Multi-tenancy configuration (v0.9.6+, Phase 1)
export MEMORY_MULTI_TENANT_MODE=false # true | false (default) - Enable multi-tenant features
export MEMORY_DEFAULT_TENANT=default # Default tenant ID for single-tenant mode
export MEMORY_REQUIRE_AUTH=false # true | false (default) - Require authentication (future)
# Logging
export MEMORY_LOG_LEVEL=INFO # DEBUG | INFO | WARNING | ERROR
```
### New in v0.9.0
**Cycle Detection Configuration**:
- `MEMORY_ALLOW_CYCLES` - Controls whether circular relationships are permitted
- `false` (default): Prevents cycles using DFS algorithm, raises error if cycle detected
- `true`: Allows circular relationships (use with caution)
- Example use case: Allowing mutually-dependent patterns or bidirectional workflows
**Health Check Options**:
- Use `memorygraph --health` to check backend connection and statistics
- Use `memorygraph --health-json` for JSON output (useful for monitoring/CI)
- Use `memorygraph --health-timeout 10.0` to set timeout in seconds (default: 5.0)
### New in v0.9.6 - Multi-Tenancy (Phase 1)
**Multi-Tenant Configuration**:
- `MEMORY_MULTI_TENANT_MODE` - Enable multi-tenant features (default: `false`)
- `false` (default): Single-tenant mode, 100% backward compatible with existing deployments
- `true`: Multi-tenant mode with tenant isolation and access control
- `MEMORY_DEFAULT_TENANT` - Default tenant ID for single-tenant mode (default: `"default"`)
- Used when migrating existing single-tenant databases to multi-tenant mode
- `MEMORY_REQUIRE_AUTH` - Require authentication for operations (default: `false`)
- Phase 1: Not yet implemented, reserved for future use
- Will be used in Phase 3 (Authentication Integration)
**Migration to Multi-Tenant Mode**:
```bash
# Check what would be changed (dry-run)
memorygraph migrate-to-multitenant --tenant-id="acme-corp" --dry-run
# Migrate existing database to multi-tenant mode
memorygraph migrate-to-multitenant --tenant-id="acme-corp" --visibility=team
# Enable multi-tenant mode in environment
export MEMORY_MULTI_TENANT_MODE=true
# Restart server to enable multi-tenant indexes
memorygraph
# Rollback if needed
memorygraph migrate-to-multitenant --rollback
```
**Multi-Tenant Configuration Example**:
```json
{
"mcpServers": {
"memorygraph": {
"command": "memorygraph",
"args": ["--profile", "extended"],
"env": {
"MEMORY_MULTI_TENANT_MODE": "true",
"MEMORY_DEFAULT_TENANT": "acme-corp"
}
}
}
}
```
See [MULTI_TENANCY.md](MULTI_TENANCY.md) for detailed multi-tenancy configuration and usage guide.
## CLI Options
```bash
# Show help
memorygraph --help
# Show current configuration
memorygraph --show-config
# Show version
memorygraph --version
# Run with custom settings
memorygraph --backend neo4j --profile extended --log-level DEBUG
```
## Configuration File Locations
| File | Purpose | Created By |
|------|---------|------------|
| `.mcp.json` | Project MCP servers | `claude mcp add --scope project` |
| `~/.claude.json` | Global MCP servers | `claude mcp add --scope user` |
| `settings.json` | Permissions & behavior | Claude Code settings |
## Backend Platform Support
| Backend | Linux | macOS | Windows |
|---------|-------|-------|---------|
| SQLite | ✅ | ✅ | ✅ |
| Neo4j | ✅ | ✅ | ✅ |
| Memgraph | ✅ | ✅ | ✅ |
| FalkorDB | ✅ | ✅ | ✅ |
| FalkorDBLite | ✅ | ⚠️* | ❌ |
*FalkorDBLite on macOS requires specific versions - see details below.
### FalkorDBLite Platform Requirements
FalkorDBLite officially supports macOS (x86_64 and ARM64) and Linux. However, there are version-specific requirements:
| Platform | Minimum Version | Python | Status |
|----------|-----------------|--------|--------|
| Linux x86_64 | Any | 3.12+ | ✅ Full support |
| macOS x86_64 | 10.13+ | 3.12+ | ✅ Full support |
| macOS ARM64 | **15.0+** (Sequoia) | 3.12+ | ✅ Full support |
| macOS ARM64 | 14.x (Sonoma) | 3.12+ | ⚠️ See note below |
| Windows | - | - | ❌ Not supported |
**macOS ARM64 on Sonoma (14.x) or earlier**: The pre-built wheels require macOS 15.0+. On older versions, pip falls back to building from source, which bundles Linux binaries and won't work. Options:
1. Upgrade to macOS 15.0 (Sequoia) or later
2. Use SQLite (default), FalkorDB (client-server), or Neo4j instead
3. Use FalkorDB with Docker: `docker run -p 6379:6379 falkordb/falkordb:latest`
### macOS Runtime Requirement
**Important**: On macOS, FalkorDBLite requires the OpenMP runtime library (`libomp`). If you encounter:
```
Library not loaded: /opt/homebrew/opt/libomp/lib/libomp.dylib
```
Install it using Homebrew:
```bash
brew install libomp
```
## Best Practices
1. **Use `claude mcp add`** - Let the CLI manage configuration files
2. **Use `--scope user`** - For global installation across all projects
3. **Use full paths** - Prevents version conflicts with project venvs
4. **Start with core mode** - Upgrade to extended when needed
5. **Don't manually edit** - Config files are managed by `claude mcp`
6. **Configure memory protocols** - Add memory storage guidelines to your CLAUDE.md
## Encouraging Memory Creation
MemoryGraph provides the tools, but Claude won't automatically use them. To enable proactive memory creation:
### Add to ~/.claude/CLAUDE.md
```markdown
## Memory Protocol
After completing significant tasks, store a memory using `store_memory`:
- Type: solution, problem, code_pattern, decision, etc.
- Title: Brief description
- Content: What was accomplished, key decisions, patterns discovered
- Tags: Relevant keywords for future recall
- Relationships: Link to related memories
Before starting work, use `recall_memories` to check for relevant past learnings.
At session end, store a summary with type=task.
```
### Use Trigger Phrases
- **Store**: "Store this for later...", "Remember that...", "Save this pattern..."
- **Recall**: "What do you remember about...?", "Have we solved this before?"
- **Session**: "Summarize and store what we accomplished today"
See [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md#configuring-proactive-memory-creation) for comprehensive configuration examples and workflows.
