BeeGridX

Name: BeeGridX
Rating: 3.5 (1 reviews)
Author: sonictx81

By sonictx81 👁 35 views ▲ 0 votes

Distributed Task Grid System - A hot-cold separation architecture based on Redis + PostgreSQL (OpenClaw Plugin)

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "load": {
      "paths": [
        "/path/to/BeeGridX"
      ]
    },
    "entries": {
      "beegridx": {
        "enabled": true,
        "redis": {
          "host": "<redis-host>",
          "port": 6379
        },
        "pg": {
          "url": "postgres://user:pass@localhost:5432/beegridx"
        },
        "watchdog": {
          "enabled": true
        }
      },
      "beegridx-channel": {
        "enabled": true
      }
    }
  }
}

README

# BeeGridX ⚡

A distributed task grid plugin for OpenClaw, featuring Boss-Worker architecture with Redis Pub/Sub for real-time task distribution and PostgreSQL for shared memory persistence.

## 🎯 Core Features

- **📤 Task Distribution** — Boss dispatches tasks via Redis channels, results return event-driven to original conversation
- **🧠 Intelligent Classification** — Auto-identifies task type (heavy/light/coding) to decide dispatch or local execution
- **💾 Shared Memory** — PostgreSQL stores project context with Chinese full-text search, automatically pulled by Workers
- **🐺 Dead Letter Compensation** — Watchdog monitors Redis keyspace events, automatically redistributes timeout tasks
- **⚙️ Unified Configuration** — Dual plugins share one config, centralized Redis/PG/Boss/Worker parameters

## 🏗️ Architecture

```
👑 Boss (Agent) → 🔀 Redis Pub/Sub → 🔧 Worker (Agent)
                        ↓                       ↓
                 🐘 PostgreSQL Shared Memory  📨 Result Event-Driven Return
```

## 🛠️ Tech Stack

- **🔴 Redis** — Task distribution, event subscriptions, distributed locks
- **🐘 PostgreSQL** — Shared memory, full-text search, task persistence
- **🧩 OpenClaw Plugin SDK** — Dual plugin architecture (Tool Plugin + Channel Plugin)

## 📋 Requirements

- OpenClaw 2026.4+
- Redis 6+
- PostgreSQL 14+
- Node.js 20+

## 🚀 Quick Start

### 1. Installation

BeeGridX uses a unified plugin architecture:

```bash
# Clone repositories
git clone https://github.com/sonictx81/BeeGridX.git

# Install dependencies
cd BeeGridX
npm install
```

### 2. Configuration

Edit `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "load": {
      "paths": [
        "/path/to/BeeGridX"
      ]
    },
    "entries": {
      "beegridx": {
        "enabled": true,
        "redis": {
          "host": "<redis-host>",
          "port": 6379
        },
        "pg": {
          "url": "postgres://user:pass@localhost:5432/beegridx"
        },
        "watchdog": {
          "enabled": true
        }
      },
      "beegridx-channel": {
        "enabled": true
      }
    }
  }
}
```

### 3. Initialize Database

```bash
cd BeeGridX
node init-db.js
```

### 4. Restart OpenClaw Gateway

```bash
openclaw gateway restart
```

## 📖 Usage

### Basic Task Dispatch

```javascript
// Boss session
await beegridx_dispatch_task({
  title: "Calculate Fibonacci",
  type: "exec",
  payload: { n: 10 }
});
```

### Auto Dispatch (Intelligent)

```javascript
// Automatically decides local vs. Worker execution
await beegridx_auto_dispatch("Analyze this project architecture");
```

### Worker Setup

```javascript
// In a separate session
await beegridx_pull_task({
  workerType: "exec"
});

// After completing the task
await beegridx_finish_task({
  taskId: "task-123",
  result: { fibonacci: 55 },
  status: "completed"
});
```

### Shared Memory

```javascript
// Store memory
await beegridx_store_memory({
  content: "Project uses TypeScript and Express",
  tags: ["category:tech", "importance:4"]
});

// Search memory
const results = await beegridx_search_memory({
  query: "TypeScript",
  limit: 10
});
```

## 📚 Documentation

- **[Architecture Guide](docs/BeeGridX_Architecture.md)** — System design and components
- **[Protocol Specification](docs/BEEGRIDX_PROTOCOL.md)** — Task flow and message formats
- **[Shared Memory](docs/SHARED_MEMORY.md)** — Memory storage and search
- **[Examples](docs/EXAMPLES.md)** — Usage examples and patterns
- **[API Reference](docs/API.md)** — Complete tool reference

## 🧪 Testing

```bash
# Run all tests
npm test

# Run with UI
npm run test:ui

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage
```

## 📊 Performance

- **Task dispatch latency**: < 10ms (Redis)
- **Memory search**: < 5ms (PostgreSQL with GIN index)
- **Hook overhead**: < 0.01ms
- **Batch insert**: ~10ms for 10 records

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 License

MIT License — see [LICENSE](LICENSE) for details.

## 🗺️ Roadmap

### v2.2.0 (Upcoming)
- [ ] Complete code cleanup for remaining files
- [ ] Enhanced documentation
- [ ] More usage examples
- [ ] Performance optimizations

### v3.0.0 (Future)
- [ ] TypeScript migration
- [ ] Plugin architecture upgrade
- [ ] Support for additional storage backends
- [ ] Task dependencies and cancellation

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/sonictx81/BeeGridX/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sonictx81/BeeGridX/discussions)

## 🌟 Credits

Built with ❤️ by the OpenClaw community

---

**Version**: 2.1.0 | **Last Updated**: 2026-05-03

tools