🐝⚡ Spark for Buzz

Give your hive a memory. A bridge agent that connects a Buzz workspace to the Memco Spark collective knowledge network — so every lesson any agent or human learns compounds for the whole team.

Buzz makes agents first-class workspace members. But out of the box, what an agent learns in a session dies with the session — buzz mem is per-agent scratch space, not team knowledge. Spark is the missing organ: a validated, model-portable knowledge network. This bridge wires them together.

Every buzz CLI invocation and workflow definition in this package is verified against the block/buzz source (crates/buzz-cli, crates/buzz-workflow); the workflow YAML files parse clean through Buzz's own WorkflowEngine::parse_yaml.

What it does

| In Buzz | The bridge does | In Spark | |---|---|---| | @spark how do we fix X? in any channel | queries the network, replies in-thread with ranked lessons + confidence | spark query | | /spark capture [event-id] | distills that thread (problem → path → resolution) into a lesson, confirms with 🐝 | spark share-task | | 👍 / 👎 reactions on a bridge answer | polls buzz reactions get on its answers and rates the recommendations they contained | spark feedback | | ✅ / 📌 reactions, error: messages | native Buzz workflows drive the above (see below) | — |

The bridge is a regular workspace member with its own keypair — no privileged bot API, no webhook backdoor. It authenticates like any agent (the CLI signs with BUZZ_PRIVATE_KEY; BUZZ_AUTH_TAG carries NIP-OA owner-authorized identity), every action it takes is in the signed, audit-logged event stream, and admins scope it by channel membership exactly like a human teammate.

Workflows (validated against Buzz's parser)

Three drop-in workflows in workflows/, written against the real buzz-workflow schema — triggers reaction_added / message_posted, actions send_message / add_reaction / request_approval, evalexpr filters, and {{trigger.*}} templates:

• capture-on-checkmark.yaml — react ✅ on any message and the workflow posts /spark capture {{trigger.message_id}}; the bridge distills that thread into a lesson.
• capture-approval-gate.yaml — 📌 asks a knowledge steward via Buzz's native request_approval gate before anything is shared to Spark. Governance as a signed event.
• auto-answer-errors.yaml — any message containing error: is reposted as @spark re:{{trigger.message_id}} …; the re: marker makes the bridge thread its answer onto the original message. A filter guard prevents the workflow from re-triggering on its own repost.

Architecture

┌────────────── Buzz relay (yours) ──────────────┐
│  channels · threads · reactions · workflows    │
└──────────────────┬─────────────────────────────┘
                   │ buzz CLI (JSON in/out, signed requests)
           ┌───────┴────────┐
           │ spark-for-buzz │   state in `buzz mem` (cursors,
           │  bridge agent  │   answer→session index) — audit-logged,
           └───────┬────────┘   survives redeploys
                   │ spark CLI (JSON out, API-key auth)
┌──────────────────┴─────────────────────────────┐
│        Spark knowledge network (Memco)         │
│  validated lessons · tags · feedback ratings   │
└────────────────────────────────────────────────┘

Both products expose agent-first CLIs, so the bridge composes them instead of reimplementing either protocol. Your relay stays yours; only distilled problem/solution text ever reaches Spark — never raw channel history, never code, and captures only happen when a human (or an approved workflow) asks.

Install

# Prereqs: buzz CLI on PATH, Node 20+
npm install -g @memco/spark-for-buzz

# Buzz identity — the bridge is a workspace member with its own keys
export BUZZ_RELAY_URL=https://relay.your-community.dev
export BUZZ_PRIVATE_KEY=<hex or nsec>
# export BUZZ_AUTH_TAG='<NIP-OA auth tag JSON>'   # owner-authorized agents

# Spark — teams MCP endpoint + API key from spark.memco.ai/dashboard
export SPARK_MCP_URL=https://spark.memco.ai/mcp-pro
export SPARK_API_KEY=sk_...

# Run
spark-for-buzz

Configuration (env)

| Variable | Default | Meaning | |---|---|---| | SPARK_MCP_URL | (none) | Spark teams MCP endpoint: https://spark.memco.ai/mcp-pro. When unset, the bridge falls back to the spark CLI on PATH | | SPARK_API_KEY | (none) | API key for the Spark MCP endpoint | | SPARK_BUZZ_HANDLE | @spark | mention that triggers an answer | | SPARK_BUZZ_CHANNELS | (all joined) | comma-separated channel names/UUIDs to watch | | SPARK_BUZZ_POLL_INTERVAL | 15 | seconds between relay polls | | SPARK_BUZZ_MAX_RECS | 3 | recommendations per answer | | SPARK_BUZZ_TAGS | (none) | base tags for every query/share, e.g. project:acme,domain:web | | SPARK_BUZZ_CAPTURE_COMMAND | /spark capture | thread command that captures a lesson | | SPARK_BUZZ_FEEDBACK_TTL_HOURS | 48 | how long answers are polled for reaction feedback | | SPARK_BUZZ_DRY_RUN | off | 1 = log instead of posting/sharing |

For the agents in your workspace

skills/spark-hive/SKILL.md — drop into your agents' skill set (Claude Code, Goose, Codex via buzz-acp) so every agent queries the hive before starting work and shares lessons when done.

Develop

npm install
npm run build       # tsc → dist/
SPARK_BUZZ_DRY_RUN=1 node dist/index.js

To re-validate the workflow YAML against Buzz's parser:

git clone --depth 1 https://github.com/block/buzz.git /tmp/buzz
# drop a test in crates/buzz-workflow/tests/ that calls
# WorkflowEngine::parse_yaml on each file in workflows/, then:
cd /tmp/buzz && ./bin/cargo test -p buzz-workflow

License

MIT