![Zabob Memgraph - Knowledge Graph Server](docs/images/zabob-holodeck-text.jpg)

# 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](DEPLOYMENT.md) for comprehensive deployment options**

**📖 See [USAGE_PATTERNS.md](docs/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](docs/images/zabob-faviicon.png) 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.

![alt text](docs/images/screenshot.png)

## 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:

```bash
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.

```bash
uvx zabob-memgraph start
```

### DIY: Docker Compose

```bash
# 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

```bash

# 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)**:

```json
{
  "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)**:

```bash
# 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](DEPLOYMENT.md) for complete deployment options**

## Usage

### Basic Commands

```bash
# 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

```bash
# 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:

```bash
# 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**:

```bash
# 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:**

```jsonc
"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/`:

```text
~/.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)

```json
{
  "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:

```bash
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

```text
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

```bash
# 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

```bash
# 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**:

```bash
zabob-memgraph status
zabob-memgraph stop
```

**Port conflicts**:

```bash
zabob-memgraph start --port 8081
```

**Docker issues**:

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

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

**Database issues**:

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

# Test server endpoints
zabob-memgraph test
```

### Logs and Debugging

```bash
# 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:

   ```bash
   ./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](https://github.com/your-username/zabob-memgraph/issues)
