agent-comm-hub

🤖 Agent Communication Hub

Production-grade multi-agent communication infrastructure
Real-time messaging · Task scheduling · Shared memory · Evolution engine
Built on MCP + SSE protocol · 56 tools · Zero external dependencies

中文 · English

---

📖 The Problem

AI Agents (Claude Code, OpenClaw, WorkBuddy, etc.) are naturally isolated:

• ❌ No direct communication (requires fragile webhooks or shared databases)
• ❌ No cross-agent task scheduling
• ❌ No shared context (beyond single prompts)
• ❌ No collective evolution (learning from each other’s experience)

Agent Communication Hub provides a shared neural center for every MCP-compatible Agent — message bus, task queue, memory layer, and evolution engine.

---

🚀 Quick Start

# 1. Start the Hub (Docker, recommended)
docker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub:v2.5.1

# 2. Register an Agent
python3 -c "
from hub_client import SynergyHubClient
hub = SynergyHubClient('http://localhost:3100')
result = hub.register(invite_code='INVITE-001', name='my-agent')
print(f'Token: {result[\"api_token\"]}')
hub.set_token(result['api_token'])
"

# 3. Send a Message
python3 -c "
from hub_client import SynergyHubClient
hub = SynergyHubClient('http://localhost:3100')
hub.set_token('your-api-token')
hub.send_message(to='other-agent', content='Hello, Agent!')
"

Zero config. Zero external services. Ready locally.

---

✨ Features

Category	Tools	Description
🔐 Identity	6	Registration, heartbeat, RBAC, trust scoring
💬 Messaging	5	P2P / broadcast, FTS5 full-text search, dedup
📋 Task Scheduling	8	7-state machine, Pipeline, parallel groups, retry
🧠 Shared Memory	5	private / team / collective scopes
🔀 Orchestration	11	Dependency chains (DFS cycle detection), quality gates, handoff
📈 Evolution Engine	12	Experience sharing, 4-tier strategy approval, feedback loop
🛡️ Security & Audit	6	Token auth, 4-level RBAC, audit hash chain, CORS whitelist
📎 File Transfer	3	Upload / download / list, Base64 10MB limit
🔧 High Availability	3	DB split auto-detection + merge + watchdog self-heal

56 MCP tools · SQLite WAL (zero message loss) · SSE push latency < 50ms

📊 Stats Snapshot

Metric	Value
MCP tools	56
Python SDK methods	68
TypeScript SDK methods	35
Unit tests	159 ✅
Database tables	32
External dependencies	0
SSE push latency	< 50ms
Deployment	Docker / npm / SkillHub

---

🏗️ Architecture

┌──────────────┐    ┌──────────────────────────┐    ┌──────────────┐
│  Agent A     │SSE │   Agent Communication    │SSE │  Agent B     │
│ (Claude Code)│◄──►│       Hub v2.5           │◄──►│  (WorkBuddy) │
│              │MCP │    localhost:3100        │MCP │              │
└──────────────┘◄───►│                          │◄───►└──────────────┘
                     │  ┌────────────────────┐  │
                     │  │ Identity / RBAC    │  │
                     │  │ Message / Broadcast│  │
                     │  │ Task Scheduler     │  │
                     │  │ Memory (3 scopes)  │  │
                     │  │ Evolution Engine   │  │
                     │  │ Orchestrator       │  │
                     │  └────────┬───────────┘  │
                     └───────────┼──────────────┘
                                 │
                            SQLite (WAL)

Any MCP-compatible agent can connect: Claude Code, OpenClaw, WorkBuddy, custom agents, and more.

---

🔧 SDK Examples

Python (zero external dependencies)

from hub_client import SynergyHubClient

hub = SynergyHubClient(
    hub_url="http://localhost:3100",
    agent_id="my-agent"
)
hub.set_token("your-api-token")

# Send a message
hub.send_message(to="other-agent", content="Task complete, handing over.")

# Store shared memory
hub.store_memory(
    content="User prefers JSON responses",
    scope="collective"
)

# Create a task
task = hub.create_task(
    title="Review PR #42",
    assignee="claude-code",
    priority=2
)

# Share experience
hub.share_experience(
    title="DB lock timeout fix",
    content="...",
    category="fix"
)

# Real-time SSE listener (blocking)
hub.on_message = lambda msg: print(f"Received: {msg}")
hub.connect_sse()

TypeScript (zero external dependencies)

import { AgentClient } from "./client-sdk/agent-client.js";

const client = new AgentClient({
  agentId: "my-agent",
  hubUrl: "http://localhost:3100",
  token: "your-api-token",
  onMessage: async (msg) => { /* handle message */ },
  onTaskAssigned: async (task) => { /* handle task */ },
});

await client.start();
await client.sendMessage({ to: "other-agent", content: "Done!" });

---

📦 Deployment

Docker (recommended)

docker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub:v2.5.1

Docker Compose (with Prometheus + Grafana)

cd deploy/
docker compose up -d
# Hub:      http://localhost:3100
# Grafana:  http://localhost:3000 (admin/admin)
# Prometheus: http://localhost:9090

From Source

git clone https://github.com/liuboacean/agent-comm-hub.git
cd agent-comm-hub
npm install
npm run build

# Development (hot reload)
npm run dev

# Production
npm start

---

⚠️ Node Version Requirement (Important)

This project depends on the native module better-sqlite3, which is compiled against Node 22 (NODE_MODULE_VERSION 127). Therefore:

• 🔒 The Hub (dist/src/server.js or dist/src/stdio.js) MUST be started with Node 22. If you use Node 24 (or higher), it will immediately throw ERR_DLOPEN_FAILED due to ABI mismatch and crash on startup — it will not run at all.
• 🧪 Node 24 in CI is only used to run unit tests (and the smoke tests that involve stdio startup have been conditionally skipped). The engines.node declaration of >=24 in package.json is a legacy CI declaration that conflicts with the actual runtime constraint — please follow Node 22 as stated in this section.
• ✅ Recommended approach: pin Node 22 with a version manager (e.g. nvm use 22), or hard-code the absolute path to the Node 22 binary in your startup script / MCP configuration.

---

🔌 MCP Configuration

Method 1: stdio (recommended)

{
  "mcpServers": {
    "agent-comm-hub": {
      "command": "/path/to/node22/bin/node",
      "args": ["dist/src/stdio.js"],
      "env": {
        "HUB_AUTH_TOKEN": "your-connection-key",
        "DB_PATH": "/path/to/comm_hub.db"
      }
    }
  }
}

⚠️ You MUST start with the Node 22 binary (e.g. the absolute path /path/to/node22/bin/node), not Node 24. The native module better-sqlite3 is compiled against Node 22 (NODE_MODULE_VERSION 127), so launching dist/src/stdio.js / dist/src/server.js with Node 24 will immediately crash with ERR_DLOPEN_FAILED due to ABI mismatch.

Method 2: HTTP + SSE

{
  "mcpServers": {
    "agent-comm-hub": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

---

🛡️ Security

Feature	Description
RBAC	4 levels: public → member → group_admin → admin
Token Auth	SHA-256 hashed storage, raw token never persisted
Audit Hash Chain	prev_hash → record_hash, DB triggers ensure integrity
Trust Scoring	Automatic, influences strategy approval tier
CORS	Whitelist-based, denied by default
Security Headers	X-Frame-Options, CSP, HSTS, X-XSS-Protection
Request Tracing	Every request gets traceId + response header

---

📁 Project Structure

agent-comm-hub/
├── src/                    # Hub server (TypeScript)
│   ├── server.ts          # Express + SSE + MCP entry point
│   ├── stdio.ts           # stdio MCP entry point
│   ├── db.ts              # SQLite WAL schema & queries
│   ├── identity.ts        # Registration, heartbeat, RBAC
│   ├── memory.ts          # 3-scope memory + FTS5
│   ├── task.ts            # 7-state task scheduler
│   ├── orchestrator.ts    # Dependency chains, pipelines
│   ├── evolution.ts       # Strategy engine, trust scoring
│   └── security.ts        # Auth, token, RBAC, audit
├── client-sdk/
│   ├── hub_client.py      # Python SDK (zero deps, 68 methods)
│   ├── agent-client.ts    # TypeScript SDK (35 public methods)
│   └── package.json       # npm publish config
├── deploy/
│   ├── docker-compose.yml # Prometheus + Grafana
│   └── prometheus.yml     # Metrics collection
├── docs/
│   ├── API_REFERENCE.md           # All 56 tool signatures
│   ├── advanced-orchestration-guide.md
│   ├── evolution-engine-guide.md
│   ├── hermes-integration-guide.md
│   ├── README_EN.md               # This file
│   └── hub-db-split-three-layer-protection.md
├── scripts/                # Install, test, migration
├── tests/                  # Unit & integration tests
└── .github/workflows/
    ├── ci.yml              # CI pipeline
    └── docker.yml          # Docker build & publish

---

📚 Documentation

Document	Description
API Reference	All 56 tool signatures + examples
Orchestration Guide	Pipelines, parallel groups, quality gates
Evolution Engine	Trust scoring, strategy approval flow
Hermes Integration	Step-by-step Hermes Agent setup
DB Split Protection	Auto-detection, merge, watchdog

---

🤝 Contributing

See CONTRIBUTING.md for details.

---

🆕 Changelog / Update History

v2.5.1 (2026-07-08) — Stability fixes + Node 22 constraint lock

- 🐛 **`get_db_stats` fix** — ESM module misused `require("fs")` causing `require is not defined`; changed to `import * as fs` - 🔄 **DB path fallback** — `resolveDbPath` now auto-falls-back on empty DB, fixing the false "data reset" of the memory / evolution engine from connecting to an empty DB - 🔒 **Node 22 lock** — startup script pins Node 22 to match the `better-sqlite3` native module (Node 24 would ABI-crash) - 🧪 **Guard test** — added a contract test ensuring stdio / Hub must run on Node 22, preventing accidental revert to Node 24 - 🧹 **Test hygiene** — fixed unit tests leaking `undefined*` stray files in the repo root (`isValidDbPath` guard)

v2.5.0 (2026-07-07) — Web admin panel + backup module

- 🖥️ **Web admin panel** — zero-framework static HTML dashboard with 6 real-time pages - 🔄 **Online-status improvement** — binary label → last-active timestamp, no more flickering - 📦 **Backup module** — local + remote rsync backup status display - ⏱️ **Persistent uptime** — survives restarts - 📊 **New API** — `GET /api/agents` - 🔧 **`.gitignore` cleanup** — removed tracked build artifacts

v2.4.7 (2026-06-09) — Tag tokenization fix + full-chain logging

- 🔍 FTS5 tag tokenization fix (space-joined instead of JSON) - 📊 12 silently-swallowed exceptions → `logError` full-chain observability - 🔐 `authed()` unified auth middleware refactor

v2.4.6 (2026-06-09) — FTS5 index guard + externalized paths

- 🔒 FTS5 index auto-verified after every store - 🛣️ Supports `HUB_ROOT` environment variable - 📨 New `generate_invite` invite-code tool - 🧪 Added 19 test cases

---

📄 License

MIT — Free for personal and commercial use.

---

Built with the MCP protocol + SSE. No external services. No vendor lock-in.

This site is open source. Improve this page.