🐝 ClankerHive

Shared context store for OpenClaw multi-session coordination. Three primitives:

1. 1. Facts — key/value pairs with optional TTL (auto-expire)
2. Alerts — cross-session notification queue (producer/consumer)
3. Tasks — claim-based deduplication for in-flight work

All backed by a single SQLite database in WAL mode (safe for concurrent access).

Setup

No dependencies beyond Python 3 stdlib. The DB is created automatically on first use.

CODEBLOCK0

Resolve the script path relative to this skill directory:

CODEBLOCK1

Facts — Key/Value with TTL

Store short-lived coordination state. Expired facts are auto-pruned on every read.

CODEBLOCK2

Pattern: Skip-if-recent

Before doing expensive work, check if it was done recently:

CODEBLOCK3

Alerts — Cross-Session Queue

Cron jobs or sub-agents produce alerts; the main session consumes them.

CODEBLOCK4

Pattern: Cron → Main Session Handoff

Cron job detects something important:
CODEBLOCK5

Main session heartbeat checks for alerts:
CODEBLOCK6

Tasks — Deduplication

Prevent multiple sessions from doing the same work simultaneously.

CODEBLOCK7

Pattern: Idempotent Cron

CODEBLOCK8

Stats

Quick summary of the hive state:

CODEBLOCK9

Returns JSON with counts for facts, pending/claimed alerts, and claimed/done tasks.

Replacing heartbeat-state.json

Instead of maintaining a separate memory/heartbeat-state.json file, use ClankerHive facts:

CODEBLOCK10

Notes

• - DB path configurable via CLANKERHIVE_DB env var (default: ~/.openclaw/hive.db)
• WAL mode ensures safe concurrent reads/writes from multiple processes
• All list/query commands output JSON; scalar commands output plain text
• Exit code 0 = success, 1 = error (already-claimed, not-found, etc.)
• No external dependencies — pure Python stdlib

System Access

Reads: Nothing — no files, env vars, or network beyond the SQLite DB.

Writes: Only to the SQLite database file at $CLANKERHIVE_DB (default ~/.openclaw/hive.db). Creates parent directories if they don't exist. The default path (~/.openclaw/) is typically mode 700 on OpenClaw installs, meaning only the owning user can read the DB. If you change CLANKERHIVE_DB to a shared or world-readable location, restrict permissions manually: chmod 600 hive.db.

Network: None. No outbound connections of any kind.

Imports: argparse, json, os, sqlite3, sys, time, typing — all Python stdlib. No third-party packages, no subprocess calls, no eval/exec.

Source: