Zabob Memgraph - Knowledge Graph Server

A Model Context Protocol (MCP) server for persistent knowledge graph storage with interactive web visualization. Part of the Zabob AI assistant ecosystem, designed for thread-safe multi-client support with Docker deployment.

📖 See DEPLOYMENT.md for comprehensive deployment options

📖 See USAGE_PATTERNS.md for usage examples

Imagine a future where each AI assistant not only can talk to you, but can remember important things, and can show you everything it remembers, even share it with the other agents on the team—instantly!

Zabob remembers this future! Give him your plans and dreams, and he will remember not just the dream, but the journey to get there, even through the darkest nullspace.

Features

Zabob Memgraph is designed from the ground up for sharing knowledge between simultaneous sessions/agents, and even across multiple physical systems.

Key features include:

• Shared knowledge bases/Multiple knowledge bases
• Built-in visualization tool, to monitor the agent's saved knowledge
• Full Text Search (by agent or by user via the visualization)
• Semantic search is coming soon
• Hybrid contextual search coming soon after
• Simple setup and usage
  • Multi-agent support requires no additional configuration
  • Separate knowledge bases is as simple as specifying a different location for the database.

Hybrid contextual search is designed to leverage the combined power of the knowledge graph and semantic search, to allow task-focused results in large knowledge graph spaces.

More details:

• **Zero-install options via uvx or docker
• MCP Protocol - Standard Model Context Protocol for AI assistant integration
• Multiple Transports - HTTP/SSE for server mode, stdio for Claude Desktop or VSCode
• Thread-safe SQLite backend - WAL mode for concurrent access without locking
• Interactive D3.js visualization - Real-time graph exploration via web UI
• Docker deployment - Multiple deployment patterns (HTTP server, stdio, local)
• Persistent storage - Database with automatic backups and rotation
• Full-text search - Search across entities, observations, and relations
• Modern tooling - esbuild bundler, Python type checking, comprehensive tests

Quick Start

Prebuilt docker image

To run it as a background process clients connect to:

docker pull bobkerns/zabob-memgraph:latest
uvx zabob-memgraph start --docker

Prebuilt without docker

This works the same as above, but without the isolation of a docker container.

uvx zabob-memgraph start

DIY: Docker Compose

# Clone repository
git clone https://github.com/BobKerns/zabob-memgraph.git
cd zabob-memgraph

# Start HTTP server with web UI
docker-compose up -d

# Access web UI at http://localhost:6789
# MCP endpoint at http://localhost:6789/mcp

DIY: development mode

# Clone repository
git clone https://github.com/BobKerns/zabob-memgraph.git
cd zabob-memgraph

uv sync
source .venv/bin/activate

zabob-memgraph start

Claude Desktop Integration

Add to your Claude Desktop MCP config:

stdio mode (local only):

{
  "mcpServers": {
    "zabob-memgraph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.zabob/memgraph:/data/.zabob/memgraph",
        "bobkerns/zabob-memgraph:latest",
        "run"
      ]
    }
  }
}

HTTP mode (shareable across systems):

# Start HTTP server
docker run -d --name zabob-memgraph \
  -p 6789:6789 \
  -v ${HOME}/.zabob/memgraph:/data/.zabob/memgraph \
  bobkerns/zabob-memgraph:latest \
  start --host 0.0.0.0 --port 6789

Then configure Claude Desktop to connect to http://localhost:6789/mcp

Visual Studio Code

Visual Studio Code is a hostile environment. If you have a lot of tools, it will randomly decide to stop presenting some to the agent. To combat this, include a reference to #zabob-memgraph in every message where it is of use. A /prompt may simplify this.

Visual Studio Code will also close your server if it's HTTP, so a running as a stdio is essential. Use the run subcommand, and it will automatically start in stdio mode if appropriate.

📖 See DEPLOYMENT.md for complete deployment options

Usage

Basic Commands

# Start the server (auto-assigns port)
zabob-memgraph start

# Start on specific port
zabob-memgraph start --port 6789

# Run in foreground (stdio mode or development)
zabob-memgraph run

# Run with auto-reload (development)
zabob-memgraph run --reload

# Check server status
zabob-memgraph status

# Monitor server health
zabob-memgraph monitor

# Test all endpoints
zabob-memgraph test

# Stop server
zabob-memgraph stop

Docker Commands

# Run in foreground (stdio mode)
docker run --rm -i \
  -v ${HOME}/.zabob/memgraph:/data/.zabob/memgraph \
  bobkerns/zabob-memgraph:latest \
  run

# Run as HTTP server (background)
docker run -d --name zabob-memgraph \
  -p 6789:6789 \
  -v ${HOME}/.zabob/memgraph:/data/.zabob/memgraph \
  bobkerns/zabob-memgraph:latest \
  start --host 0.0.0.0 --port 6789

# Run development commands in container
docker run --rm -it \
  -v $(pwd):/app \
  bobkerns/zabob-memgraph:latest \
  lint

Development Commands

The CLI automatically detects development environments and enables additional commands:

# Development commands (available when .git exists or dev dependencies installed)
zabob-memgraph run --reload  # Run with auto-reload
zabob-memgraph build         # Build Docker image
zabob-memgraph lint          # Run type checking and linting
zabob-memgraph format        # Format code with ruff
zabob-memgraph clean         # Clean build artifacts

# Production commands (always available)
zabob-memgraph start         # Start server in background
zabob-memgraph stop          # Stop server
zabob-memgraph restart       # Restart server
zabob-memgraph status        # Check server status
zabob-memgraph open          # Open browser to web UI
zabob-memgraph test          # Test all endpoints
zabob-memgraph monitor       # Monitor server health

Development Setup:

# Clone repository
git clone <repository-url>
cd zabob-memgraph

# Install dependencies (dev commands auto-enabled)
uv sync

# Build web UI
pnpm install && pnpm run build:web

# Run with auto-reload
zabob-memgraph run --reload

Configuration

Workspace Customization

The repository includes a zabob-memgraph.code-workspace file that you can customize for your personal preferences. This file is in .gitignore, so your changes won't be committed.

Customize your workspace:

1. Open the workspace file and uncomment/edit the settings you want
2. Set a custom workspace name with an emoji tag for easy identification:
   • "name": "🟢 Main" - Main branch
   • "name": "🔵 Release 0.1" - Release branch
   • "name": "🟣 Development" - Development work
3. Customize window title and color theme in the settings section
4. The default window title shows: 🧠 Memgraph <workspace-name> · <folder> · <file>

Example customizations:

"settings": {
    "workbench.colorTheme": "Default Dark+",
    "window.title": "🟣 DEV ${separator} ${activeEditorShort}",
    "workbench.colorCustomizations": {
        "titleBar.activeBackground": "#1a0033",
        "statusBar.background": "#1a0033"
    }
}

This allows you to visually distinguish different worktrees or branches without affecting other developers.

Data Directory

Configuration and data are stored in ~/.zabob/memgraph/:

~/.zabob/memgraph/
├── config.json           # Server configuration
├── server_info.json      # Current server status
├── memgraph.log          # Application logs
├── data/                 # Database files
│   └── knowledge_graph.db
└── backup/               # Automatic backups
    ├── knowledge_graph_1234567890.db
    └── ...

Configuration File

The config.json file supports these options (and more)

{
  "default_port": 6789,
  "default_host": "localhost",
  "log_level": "INFO",
  "backup_on_start": true,
  "max_backups": 5,
  "data_dir": "~/.zabob/memgraph/data",
  "database_file": "~/.zabob/memgraph/data/knowledge_base.db"
}

You can see its effective contents with:

zabob-memgraph config

Environment Variables

For Docker or advanced deployments:

export MEMGRAPH_HOST=0.0.0.0
export MEMGRAPH_PORT=6789
export MEMGRAPH_LOG_LEVEL=DEBUG
export MEMGRAPH_CONFIG_DIR=/custom/path

MCP Tools

Zabob Memgraph provides these MCP tools for AI assistants:

• create_entities - Create new entities with observations
• create_relations - Create relationships between entities
• add_observations - Add observations to existing entities
• read_graph - Read the complete knowledge graph
• search_nodes - Full-text search across entities and observations
• delete_entities - Remove entities and their relations
• delete_relations - Remove specific relationships
• get_stats - Get graph statistics

HTTP Endpoints

The embedded HTTP server provides:

• GET / - Web visualization interface
• POST /mcp - MCP protocol endpoint (SSE transport)
• GET /health - Health check

Using MCP Tools

MCP tools are called through the protocol. Example using the web UI:

1. Open http://localhost:6789
2. View entities and relations in the interactive graph
3. Search, zoom, and explore your knowledge graph

For Claude Desktop, VSCode, or other MCP client integration, tools are automatically available after configuration.

Architecture

Thread-Safe Design

The server uses SQLite with proper locking for concurrent access:

• WAL mode: Enables concurrent readers
• Proper transactions: Atomic operations prevent corruption
• Connection pooling: Efficient resource management
• Automatic retries: Handles temporary locking conflicts

Component Structure

zabob-memgraph/
├── zabob-memgraph-dev.py         # Development CLI
├── main.py                       # Server entrypoint
├── memgraph/                     # Core package
│   ├── service.py                # Unified ASGI service (MCP + HTTP)
│   ├── mcp_service.py            # FastMCP server implementation
│   ├── knowledge_live.py         # Knowledge graph data layer
│   ├── sqlite_backend.py         # Thread-safe SQLite backend
│   ├── web/                      # Static web assets
│   │   ├── index.html
│   │   ├── graph.bundle.js       # Bundled web UI (built)
│   │   └── style.css
│   └── web-src/                  # Web UI source
│       ├── mcp-client.js         # Browser MCP client
│       └── graph.js              # D3.js visualization
├── docker-compose.yml            # Docker Compose config
└── Dockerfile                    # Container definition

Development

Setting Up Development Environment

# Clone repository
git clone <repository-url>
cd zabob-memgraph

# Install dependencies (enables dev commands)
uv sync

# Build web UI
pnpm install && pnpm run build:web

# Run in development mode with auto-reload
zabob-memgraph run --reload --port 6789

# Run tests
zabob-memgraph test

# Lint code
zabob-memgraph lint

# Format code
zabob-memgraph format

Docker Development

# Build Docker image
zabob-memgraph build

# Run in Docker (if configured)
zabob-memgraph start --docker --detach

# Check status
zabob-memgraph status

# Stop services
zabob-memgraph stop

Troubleshooting

Common Issues

Server already running:

zabob-memgraph status
zabob-memgraph stop

Port conflicts:

zabob-memgraph start --port 8081

Docker issues:

# Check if image exists
docker images | grep zabob-memgraph

# Build if missing
./zabob-memgraph-dev.py build

Database issues:

# Check logs
tail -f ~/.zabob-memgraph/memgraph.log

# Test server endpoints
zabob-memgraph test

Logs and Debugging

# View real-time logs
tail -f ~/.zabob/memgraph/memgraph.log

# Monitor server health
zabob-memgraph monitor

# Test all endpoints
zabob-memgraph test

Performance Notes

• SQLite Performance: Excellent for read-heavy workloads with WAL mode
• Docker Deployment: Recommended for production with volume persistence
• Memory Usage: Low footprint suitable for resource-constrained environments
• Scaling: Scale horizontally with multiple instances on different ports

Part of the Zabob Ecosystem

Zabob Memgraph is designed to work with other Zabob AI tools:

• Zabob Core: Main AI assistant framework
• Zabob Memgraph: Knowledge graph persistence (this project)
• Zabob Tools: Additional MCP tools and utilities

The zabob- prefix helps identify tools in this ecosystem while maintaining distinct, memorable names.

Contributing

1. Fork the repository

2. Create a feature branch

3. Use the development tools:

   ./zabob-memgraph-dev.py install
   ./zabob-memgraph-dev.py test
   ./zabob-memgraph-dev.py lint
   

4. Submit a pull request

License

[License information]

---

Getting Started: zabob-memgraph start Need Help: zabob-memgraph --help Issues: GitHub Issues