refactor: Reorganize Docker Compose files by database type

- Rename docker-compose.yml to docker-compose-neo4j.yml for Neo4j setup
- Rename docker-compose-kuzu.yml to docker-compose.yml (making KuzuDB default)
- Create docker-compose-falkordb.yml for FalkorDB deployment
- Add dedicated config files for each database type:
  - config-docker-neo4j.yaml for Neo4j
  - config-docker-falkordb.yaml for FalkorDB
  - config-docker-kuzu.yaml for KuzuDB
- Create comprehensive Docker README with database comparison
- Update all compose files to use their respective config files

KuzuDB is now the default database for Docker deployments due to:
- No external dependencies required
- Lower resource usage
- Instant startup time
- Simpler deployment

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

mcp_server/config/config-docker-falkordb.yaml

@@ -0,0 +1,90 @@
+# Graphiti MCP Server Configuration for Docker with FalkorDB
+# This configuration is optimized for running with docker-compose-falkordb.yml
+
+server:
+  transport: "sse"  # SSE for HTTP access from Docker
+  host: "0.0.0.0"
+  port: 8000
+  
+llm:
+  provider: "openai"  # Options: openai, azure_openai, anthropic, gemini, groq
+  model: "gpt-4o"
+  temperature: 0.0
+  max_tokens: 4096
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    anthropic:
+      api_key: ${ANTHROPIC_API_KEY}
+      api_url: ${ANTHROPIC_API_URL:https://api.anthropic.com}
+      max_retries: 3
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    groq:
+      api_key: ${GROQ_API_KEY}
+      api_url: ${GROQ_API_URL:https://api.groq.com/openai/v1}
+
+embedder:
+  provider: "openai"  # Options: openai, azure_openai, gemini, voyage
+  model: "text-embedding-ada-002"
+  dimensions: 1536
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    voyage:
+      api_key: ${VOYAGE_API_KEY}
+      api_url: ${VOYAGE_API_URL:https://api.voyageai.com/v1}
+      model: "voyage-3"
+
+database:
+  provider: "falkordb"  # Using FalkorDB for this configuration
+  
+  providers:
+    falkordb:
+      # Use environment variable if set, otherwise use Docker service hostname
+      uri: ${FALKORDB_URI:redis://falkordb:6379}
+      password: ${FALKORDB_PASSWORD:}
+      database: ${FALKORDB_DATABASE:default_db}
+
+graphiti:
+  group_id: ${GRAPHITI_GROUP_ID:main}
+  episode_id_prefix: ${EPISODE_ID_PREFIX:}
+  user_id: ${USER_ID:mcp_user}
+  entity_types:
+    - name: "Requirement"
+      description: "Represents a requirement"
+    - name: "Preference"
+      description: "User preferences and settings"
+    - name: "Procedure"
+      description: "Standard operating procedures"

mcp_server/config/config-docker-neo4j.yaml

@@ -0,0 +1,92 @@
+# Graphiti MCP Server Configuration for Docker with Neo4j
+# This configuration is optimized for running with docker-compose-neo4j.yml
+
+server:
+  transport: "sse"  # SSE for HTTP access from Docker
+  host: "0.0.0.0"
+  port: 8000
+  
+llm:
+  provider: "openai"  # Options: openai, azure_openai, anthropic, gemini, groq
+  model: "gpt-4o"
+  temperature: 0.0
+  max_tokens: 4096
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    anthropic:
+      api_key: ${ANTHROPIC_API_KEY}
+      api_url: ${ANTHROPIC_API_URL:https://api.anthropic.com}
+      max_retries: 3
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    groq:
+      api_key: ${GROQ_API_KEY}
+      api_url: ${GROQ_API_URL:https://api.groq.com/openai/v1}
+
+embedder:
+  provider: "openai"  # Options: openai, azure_openai, gemini, voyage
+  model: "text-embedding-ada-002"
+  dimensions: 1536
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    voyage:
+      api_key: ${VOYAGE_API_KEY}
+      api_url: ${VOYAGE_API_URL:https://api.voyageai.com/v1}
+      model: "voyage-3"
+
+database:
+  provider: "neo4j"  # Using Neo4j for this configuration
+  
+  providers:
+    neo4j:
+      # Use environment variable if set, otherwise use Docker service hostname
+      uri: ${NEO4J_URI:bolt://neo4j:7687}
+      username: ${NEO4J_USER:neo4j}
+      password: ${NEO4J_PASSWORD:demodemo}
+      database: ${NEO4J_DATABASE:neo4j}
+      use_parallel_runtime: ${USE_PARALLEL_RUNTIME:false}
+
+graphiti:
+  group_id: ${GRAPHITI_GROUP_ID:main}
+  episode_id_prefix: ${EPISODE_ID_PREFIX:}
+  user_id: ${USER_ID:mcp_user}
+  entity_types:
+    - name: "Requirement"
+      description: "Represents a requirement"
+    - name: "Preference"
+      description: "User preferences and settings"
+    - name: "Procedure"
+      description: "Standard operating procedures"

mcp_server/docker/README.md

@@ -0,0 +1,173 @@
+# Docker Deployment for Graphiti MCP Server
+
+This directory contains Docker Compose configurations for running the Graphiti MCP server with different database backends.
+
+## Quick Start
+
+The default configuration uses **KuzuDB** (embedded, no external dependencies):
+
+```bash
+docker-compose up
+```
+
+## Database Options
+
+### KuzuDB (Default) - Recommended
+**File:** `docker-compose.yml`
+
+Embedded graph database with persistent storage, no external dependencies.
+
+```bash
+docker-compose up
+```
+
+**Pros:**
+- No external database required
+- Fast startup
+- Low resource usage
+- Single file persistence
+
+**Cons:**
+- Less mature than Neo4j
+- Limited tooling
+
+### Neo4j
+**File:** `docker-compose-neo4j.yml`
+
+Full-featured graph database with web interface.
+
+```bash
+docker-compose -f docker-compose-neo4j.yml up
+```
+
+**Pros:**
+- Mature, battle-tested
+- Rich query language (Cypher)
+- Web UI at http://localhost:7474
+- Extensive tooling
+
+**Cons:**
+- Requires separate database container
+- Higher resource usage (512MB+ RAM)
+- Slower startup (30+ seconds)
+
+### FalkorDB
+**File:** `docker-compose-falkordb.yml`
+
+Redis-based graph database with high performance.
+
+```bash
+docker-compose -f docker-compose-falkordb.yml up
+```
+
+**Pros:**
+- Fast performance
+- Redis-compatible
+- Good for high throughput
+
+**Cons:**
+- Requires separate database container
+- Less tooling than Neo4j
+
+## Environment Variables
+
+Create a `.env` file in this directory:
+
+```bash
+# Required for all configurations
+OPENAI_API_KEY=your-api-key-here
+
+# Optional
+GRAPHITI_GROUP_ID=main
+SEMAPHORE_LIMIT=10
+
+# Database-specific (if using non-default values)
+NEO4J_PASSWORD=yourpassword
+FALKORDB_PASSWORD=yourpassword
+```
+
+## Switching Between Databases
+
+To switch from one database to another:
+
+1. Stop the current setup:
+   ```bash
+   docker-compose down  # or docker-compose -f docker-compose-[db].yml down
+   ```
+
+2. Start with the new database:
+   ```bash
+   docker-compose -f docker-compose-[neo4j|falkordb].yml up
+   ```
+
+Note: Data is not automatically migrated between different database types.
+
+## Data Persistence
+
+All configurations use Docker volumes for data persistence:
+
+- **KuzuDB**: `kuzu_data` volume
+- **Neo4j**: `neo4j_data` and `neo4j_logs` volumes  
+- **FalkorDB**: `falkordb_data` volume
+
+### Backup and Restore
+
+**Backup:**
+```bash
+# Replace [volume_name] with the appropriate volume
+docker run --rm -v [volume_name]:/data -v $(pwd):/backup alpine \
+  tar czf /backup/backup.tar.gz -C /data .
+```
+
+**Restore:**
+```bash
+docker run --rm -v [volume_name]:/data -v $(pwd):/backup alpine \
+  tar xzf /backup/backup.tar.gz -C /data
+```
+
+### Clear Data
+
+To completely reset a database:
+
+```bash
+# Stop containers
+docker-compose -f docker-compose-[db].yml down
+
+# Remove volume
+docker volume rm docker_[volume_name]
+
+# Restart (creates fresh volume)
+docker-compose -f docker-compose-[db].yml up
+```
+
+## Performance Comparison
+
+| Database | Startup Time | Memory Usage | External Container | Best For |
+|----------|-------------|--------------|-------------------|----------|
+| KuzuDB | Instant | ~100MB | No | Development, embedded use |
+| Neo4j | 30+ sec | ~512MB+ | Yes | Production, complex queries |
+| FalkorDB | ~5 sec | ~200MB | Yes | High throughput, caching |
+
+## Troubleshooting
+
+### Port Conflicts
+If port 8000 is already in use:
+```bash
+lsof -i :8000  # Find what's using the port
+```
+
+### Database Connection Issues
+- **KuzuDB**: Check volume permissions
+- **Neo4j**: Wait for health check, check logs
+- **FalkorDB**: Ensure Redis is responding
+
+### API Key Issues
+Verify your `.env` file contains valid API keys:
+```bash
+cat .env | grep API_KEY
+```
+
+## Additional Documentation
+
+- [KuzuDB Setup Guide](README-kuzu.md)
+- [Main MCP Server Documentation](../docs/README.md)

mcp_server/docker/docker-compose-falkordb.yml

@@ -1,4 +1,19 @@
 services:
+  falkordb:
+    image: falkordb/falkordb:latest
+    ports:
+      - "6379:6379" # Redis/FalkorDB port
+    environment:
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+    volumes:
+      - falkordb_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
   graphiti-mcp:
     image: zepai/knowledge-graph-mcp:latest
     build:
@@ -7,10 +22,14 @@ services:
     env_file:
       - path: .env
         required: false # Makes the file optional. Default value is 'true'
+    depends_on:
+      falkordb:
+        condition: service_healthy
     environment:
-      # Database configuration for KuzuDB - using persistent storage
+      # Database configuration
-      - KUZU_DB=${KUZU_DB:-/data/graphiti.kuzu}
+      - FALKORDB_URI=${FALKORDB_URI:-redis://falkordb:6379}
-      - KUZU_MAX_CONCURRENT_QUERIES=${KUZU_MAX_CONCURRENT_QUERIES:-10}
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+      - FALKORDB_DATABASE=${FALKORDB_DATABASE:-default_db}
       # LLM provider configurations
       - OPENAI_API_KEY=${OPENAI_API_KEY}
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
@@ -29,14 +48,11 @@ services:
       - CONFIG_PATH=/app/config/config.yaml
       - PATH=/root/.local/bin:${PATH}
     volumes:
-      - ../config/config-docker-kuzu.yaml:/app/config/config.yaml:ro
+      - ../config/config-docker-falkordb.yaml:/app/config/config.yaml:ro
-      # Persistent KuzuDB data storage
-      - kuzu_data:/data
     ports:
       - "8000:8000" # Expose the MCP server via HTTP for SSE transport
     command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]
 
-# Volume for persistent KuzuDB storage
 volumes:
-  kuzu_data:
+  falkordb_data:
     driver: local

mcp_server/docker/docker-compose-neo4j.yml

@@ -0,0 +1,64 @@
+services:
+  neo4j:
+    image: neo4j:5.26.0
+    ports:
+      - "7474:7474" # HTTP
+      - "7687:7687" # Bolt
+    environment:
+      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-demodemo}
+      - NEO4J_server_memory_heap_initial__size=512m
+      - NEO4J_server_memory_heap_max__size=1G
+      - NEO4J_server_memory_pagecache_size=512m
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+    healthcheck:
+      test: ["CMD", "wget", "-O", "/dev/null", "http://localhost:7474"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  graphiti-mcp:
+    image: zepai/knowledge-graph-mcp:latest
+    build:
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - path: .env
+        required: false # Makes the file optional. Default value is 'true'
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    environment:
+      # Database configuration
+      - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
+      - NEO4J_USER=${NEO4J_USER:-neo4j}
+      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
+      - NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j}
+      # LLM provider configurations
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+      - GROQ_API_KEY=${GROQ_API_KEY}
+      - AZURE_OPENAI_API_KEY=${AZURE_OPENAI_API_KEY}
+      - AZURE_OPENAI_ENDPOINT=${AZURE_OPENAI_ENDPOINT}
+      - AZURE_OPENAI_DEPLOYMENT=${AZURE_OPENAI_DEPLOYMENT}
+      # Embedder provider configurations
+      - VOYAGE_API_KEY=${VOYAGE_API_KEY}
+      - AZURE_OPENAI_EMBEDDINGS_ENDPOINT=${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      - AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      # Application configuration
+      - GRAPHITI_GROUP_ID=${GRAPHITI_GROUP_ID:-main}
+      - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10}
+      - CONFIG_PATH=/app/config/config.yaml
+      - PATH=/root/.local/bin:${PATH}
+    volumes:
+      - ../config/config-docker-neo4j.yaml:/app/config/config.yaml:ro
+    ports:
+      - "8000:8000" # Expose the MCP server via HTTP for SSE transport
+    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]
+
+volumes:
+  neo4j_data:
+  neo4j_logs:

mcp_server/docker/docker-compose.yml

@@ -1,24 +1,4 @@
 services:
-  neo4j:
-    image: neo4j:5.26.0
-    ports:
-      - "7474:7474" # HTTP
-      - "7687:7687" # Bolt
-    environment:
-      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-demodemo}
-      - NEO4J_server_memory_heap_initial__size=512m
-      - NEO4J_server_memory_heap_max__size=1G
-      - NEO4J_server_memory_pagecache_size=512m
-    volumes:
-      - neo4j_data:/data
-      - neo4j_logs:/logs
-    healthcheck:
-      test: ["CMD", "wget", "-O", "/dev/null", "http://localhost:7474"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-
   graphiti-mcp:
     image: zepai/knowledge-graph-mcp:latest
     build:
@@ -27,15 +7,10 @@ services:
     env_file:
       - path: .env
         required: false # Makes the file optional. Default value is 'true'
-    depends_on:
-      neo4j:
-        condition: service_healthy
     environment:
-      # Database configuration
+      # Database configuration for KuzuDB - using persistent storage
-      - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
+      - KUZU_DB=${KUZU_DB:-/data/graphiti.kuzu}
-      - NEO4J_USER=${NEO4J_USER:-neo4j}
+      - KUZU_MAX_CONCURRENT_QUERIES=${KUZU_MAX_CONCURRENT_QUERIES:-10}
-      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
-      - NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j}
       # LLM provider configurations
       - OPENAI_API_KEY=${OPENAI_API_KEY}
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
@@ -54,11 +29,14 @@ services:
       - CONFIG_PATH=/app/config/config.yaml
       - PATH=/root/.local/bin:${PATH}
     volumes:
-      - ./config.yaml:/app/config/config.yaml:ro
+      - ../config/config-docker-kuzu.yaml:/app/config/config.yaml:ro
+      # Persistent KuzuDB data storage
+      - kuzu_data:/data
     ports:
       - "8000:8000" # Expose the MCP server via HTTP for SSE transport
     command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]
 
+# Volume for persistent KuzuDB storage
 volumes:
-  neo4j_data:
+  kuzu_data:
-  neo4j_logs:
+    driver: local